# System Miniapp APIs

> Permission-gated miniapp lifecycle and platform settings APIs, and the controls reserved for system miniapps.

Source: https://docs.dev.glassly.ai/app-devs/reference/system-apis/

`session.miniapps` (listing, starting, and stopping other miniapps by package)
needs the `MANAGE_MINIAPPS` manifest permission, and `session.settings` needs
`PLATFORM_SETTINGS`. Neither shows an OS prompt; both appear in the Store
listing. Without the permission, requests reject with
`{code: "PERMISSION_NOT_DECLARED", message, permission}`, and a
`session.settings.onChange` subscription is rejected at subscribe time with the
same code. System miniapps pass without declaring. Only the Wi-Fi ADB control
and actions declared `visibility: "system"` are reserved for **system
miniapps** and reject other callers with `NOT_PERMITTED`. Setting
`type: "dashboard"` or `alwaysOn: true` does not grant any of these.
`session.actions.invoke` and `session.actions.list` are **not** gated: see
[Actions](https://docs.dev.glassly.ai/app-devs/core-concepts/miniapp-interop.md).

Miniapps that declare `MANAGE_MINIAPPS` can discover other miniapps and control
their lifecycle, miniapps that declare `PLATFORM_SETTINGS` can read and write
host settings, and system miniapps can use a small set of privileged device
controls. Invoking the actions other miniapps
expose is open to every miniapp and documented here because the error surface is
shared.

## Discover and control miniapps

`session.miniapps` lists installed miniapps and starts or stops them. It needs
`MANAGE_MINIAPPS`. `session.miniapps.hasPermission` is true when the manifest
declares it.

```ts
// Compatible miniapps only by default; each action can carry input and output schemas.
const apps = await session.miniapps.list();
const all = await session.miniapps.list({ includeIncompatible: true });

// start() runs a miniapp in the BACKGROUND: it spawns the background context and
// reports as running, without changing phone navigation or foregrounding anything
// (the WebView mounts only if the user opens it).
await session.miniapps.start("com.glassly.todo");
await session.miniapps.stop("com.glassly.todo");
```

| Method | Returns | Notes |
|---|---|---|
| `list(options?)` | `Promise<MiniappInfo[]>` | `options.includeIncompatible` and `options.includeIcons` default to `false`. Each entry carries its declared `actions`. |
| `start(packageName)` | `Promise<void>` | Background-spawn; no foreground change. |
| `stop(packageName)` | `Promise<void>` | Stop a running miniapp. |

`session.miniapps.stopSelf()` is not permission-gated. Any miniapp can call it to
stop itself; the host tears the background context down shortly after. It's
fire-and-forget with no reply, so flush any pending work first.

Each list entry can include `hidden?: boolean` and `system?: boolean`. Leave
out entries with either set when building a glasses menu: `hidden` means the
wearer took the miniapp off the home grid, and `system` marks the host's
built-in phone pages (Store, Settings, Glasses Mirror and the like) and
dashboards. Older hosts omit both.

Pass `{includeIcons: true}` to draw miniapp icons on the glasses: each entry
then carries `icon`, a 32×32 PNG thumbnail of the installed icon as raw base64,
ready for an [`image` element](https://docs.dev.glassly.ai/app-devs/core-concepts/display/layouts.md)'s
`data`. Entries whose icon is missing or unreadable, and older hosts, omit it,
so keep a fallback.

## Platform settings

`session.settings` reads and writes an allowlisted subset of the host's
settings. It needs `PLATFORM_SETTINGS`; `session.settings.hasPermission` is true
when the manifest declares it. Writes go through the same persistence, server sync, and applicable
Bluetooth sync as the Glassly App's settings screens. For your own miniapp's
preferences, use [storage](https://docs.dev.glassly.ai/app-devs/core-concepts/storage.md).

```typescript
const values = await session.settings.getAll(["notifications_enabled", "menu_apps"]);
const off = session.settings.onChange(({key, value}) => {
  console.log(key, value);
});
await session.settings.set("notifications_popups", true);
// later
off();
```

| Method | Returns | Notes |
|---|---|---|
| `get<T>(key)` | `Promise<T \| undefined>` | Unknown keys return `undefined`. |
| `getAll(keys?)` | `Promise<Record<string, unknown>>` | Omit `keys` for all available keys. Unknown keys are omitted. |
| `set(key, value)` | `Promise<void>` | Writable keys only; values use the host's JSON shapes. |
| `onChange(handler)` | Unsubscribe function | Replays every available key's current value, then sends `{key, value}` changes. |

Writable keys are `head_up_angle`, `dashboard_depth`, `dashboard_height`,
`menu_apps`, and the notification
enable/popup/filter settings. The depth and height steps the connected glasses
accept are in `session.capabilities.display.positionRange` (`{height, depth}`,
each `{min, max}` inclusive). `custom_dashboard_enabled` and
`notification_seen_apps` are read-only. A dashboard keeps its own settings (its
look, head-up opening, a 12-hour clock override) in `session.storage`.
The bridge also supplies read-only derived values: `phone_active` and
`foreground_app_on_screen` (booleans) and `controllers`, one entry per paired
controller (R1 ring, Meta Neural Band) in pairing order:

```typescript
type Controllers = Array<{
  id: string;          // controller id, stable while paired
  model: string;       // "Even Realities R1", "Meta Neural Band"
  name: string;        // display name
  connected: boolean;  // false while the controller is idle
  battery: {level: number; charging: boolean}; // level -1 when unknown
  input2d: boolean;    // swipes sideways as well as up and down (the Neural Band)
}>;
```

A 2D controller is connected when
`controllers.some((c) => c.connected && c.input2d)`. The key replaces
`ring_battery` and `input_2d`.

`set` rejects unknown keys or missing values with `INVALID_ARGUMENT`,
read-only keys with `NOT_PERMITTED`, and failed store writes with `INTERNAL`.
Handle missing keys on older hosts; the generic on `get<T>` does not validate
the value at runtime.

## Notification app discovery

`session.phone.notifications.installedApps()` returns
`Promise<NotificationAppInfo[]>` for building a notification filter UI. Each
entry is `{packageName: string, appName: string, icon: string | null}`.
Android lists installed apps with base64 PNG icons. iOS cannot enumerate
installed apps, so it returns a seeded catalog plus apps the glasses reported
posting notifications, without icons. This request needs `READ_NOTIFICATIONS`.

## Invoke an action

`session.actions.invoke` calls an action another miniapp exposed via
`session.actions.handle`. It headless-wakes the target if it's stopped, runs the
handler, and returns the result. Any miniapp can call it; only actions the target
declared with `visibility: "system"` are restricted to system callers.

```ts
const res = await session.actions.invoke(
  "com.glassly.todo",
  "add_todo",
  { text: "milk" },
  { timeoutMs: 30000 }, // default 30s, max 120s
);
```

`invoke()` rejects with `{ code, message }` where `code` is one of:

| Code | Meaning |
|---|---|
| `NOT_PERMITTED` | The action is declared `visibility: "system"` and the caller isn't a system miniapp. |
| `APP_NOT_FOUND` | No miniapp with that package name. |
| `APP_NOT_COMPATIBLE` | The target can't run on the connected glasses. |
| `ACTION_NOT_FOUND` | The target doesn't declare that action. |
| `NO_ACTION_HANDLER` | The action is declared but no handler is registered. |
| `WAKE_FAILED` | The target couldn't be headless-woken. |
| `ACTION_TIMEOUT` | The handler didn't resolve within `timeoutMs`. |
| `PAYLOAD_TOO_LARGE` | Params or result exceeded 256 KB. |

A thrown handler in the target surfaces its own error message to the caller.
The action descriptor returned by `session.miniapps.list()` includes an optional
`outputSchema`, which describes the structured result for result-aware callers.

## Privileged device controls

### Wi-Fi ADB (Mentra Live)

`session.glasses.setWifiAdbState` toggles wireless debugging on Mentra Live.
The preference is persisted on the glasses and reapplied at boot (default
**off**). Non-system callers get `NOT_PERMITTED`.

```ts
await session.glasses.setWifiAdbState(true);  // enable
await session.glasses.setWifiAdbState(false); // disable
```

| Method | Returns | Notes |
|---|---|---|
| `setWifiAdbState(enabled)` | `Promise<void>` | Mentra Live only; other models no-op. SYSTEM-only. |
