esoul-sdk 0.17.0 → 0.19.0

package/api-reference.md

@@ -7,11 +7,11 @@ the complete list it teaches from. In a Forge workbench the source itself is rea
 Regenerate: `npm run docs:api`.
 
 ==============================================================================
-## `esoul-sdk` — 185 exports
+## `esoul-sdk` — 196 exports
 
 Manifest, events, tools, ops, bindings, contracts, charts, access words — what app.tsx and the shared modules import.
 
-### Functions and values (109)
+### Functions and values (115)
 
 #### `ASSET_APP_MAX_BYTES` — const · src/assets.ts
 
@@ -189,6 +189,14 @@ Every declared attribute a grant carries, typed; an undeclared or ill-typed one
 function coerceAttrs(types: Record<string, AttrType>, raw: Record<string, unknown> | undefined | null): Record<string, AttrValue>
 ```
 
+#### `COMMAND_NAME_RE` — const · src/machine/commands.ts
+
+What a command name may look like: lowercase, starts with a letter, up to 40 characters.
+
+```ts
+const COMMAND_NAME_RE: RegExp
+```
+
 #### `compareFileNames` — function · src/files.ts
 
 Natural name order: "frame_2" before "frame_10".
@@ -245,6 +253,14 @@ What a mounted editor should do with the value the store now holds for the item
 function decideReconcile<T>(args: { incoming: T; /** What the editor last knew the server to hold (its merge base). */ base: T | undefined; /** What the editor shows right now. */ current: T; equal: (a: T, b: T) => boolean; /** A local save is scheduled and not yet dispatched. */ pending: boolean; /** The user is in the middle of editing (focus, an open field). */ editing: boolean; /** isOlderOwnWrite(...) for the incoming state. */ olderOwn: boolean; /** The editor supplies a three-way merge. */ canMerge: boolean; /** May a merge be applied while the person is editing? Default true. An editor that can only apply by * replacing its whole surface (an input in progress would be lost) sets false: it merges once idle. */ mergeWhileEditing?: boolean; }): ReconcileDecision
 ```
 
+#### `DEFAULT_TIMEOUT_SECONDS` — const · src/machine/commands.ts
+
+A command's time limit when it declares none: one hour.
+
+```ts
+const DEFAULT_TIMEOUT_SECONDS: 3600
+```
+
 #### `defineBindingEvent` — function · src/bindings.ts
 
 The event definition for one app's slots. `knownSlots` comes from the manifest, so an event naming a slot the app never declared is ignored rather than inventing one.
@@ -277,6 +293,22 @@ Refold-stable id from event payload — the ONLY way a processor may mint an id
 function deterministicReducerId(prefix: string, seed: unknown): string
 ```
 
+#### `deviceBlockProblems` — function · src/machine/commands.ts
+
+Every problem with a `device` block, in words an author can act on. Empty = valid.
+
+```ts
+function deviceBlockProblems(block: unknown): string[]
+```
+
+#### `DeviceCommandError` — class · src/machine/commands.ts
+
+Why a command was refused: `unknown_command` (not declared), `bad_param` (missing, extra or ill-typed), `bad_spec`. The message says which, in words.
+
+```ts
+class DeviceCommandError extends Error { … }
+```
+
 #### `fenceMetaOf` — function · src/editor-sync.ts
 
 The fence record of `itemKey` in an app state (`__itemRevs`), if any.
@@ -509,6 +541,14 @@ Does an entry pass these listing options? The one rule every provider's listing
 function matchesListOptions(entry: Pick<FileEntry, "name" | "kind">, opts?: FileListOptions | null): boolean
 ```
 
+#### `MAX_TIMEOUT_SECONDS` — const · src/machine/commands.ts
+
+The longest time limit a command may declare: seven days.
+
+```ts
+const MAX_TIMEOUT_SECONDS: number
+```
+
 #### `mergeFields` — function · src/editor-sync.ts
 
 Three-way merge of a flat record of fields (a form: to/cc/subject/body; a node's config). A field changed differently on both sides is a conflict → `null`.
@@ -714,7 +754,7 @@ const PluginConnectionSchema: z.ZodEffects<z.ZodObject<{ key: z.ZodString; kind:
 The zod schema `plugin.json` must satisfy — the sync and `check_app` refuse a manifest that fails it, with the path.
 
 ```ts
-const PluginManifestSchema: z.ZodObject<{ manifestVersion: z.ZodLiteral<1>; id: z.ZodString; name: z.ZodString; version: z.ZodString; description: z.ZodString; applicationType: z.ZodString; entry: z.ZodString; icon: z.ZodOptional<z.ZodString>; author: z.ZodOptional<z.ZodObject<{ name: z.ZodString; email: z.ZodOptional<z.ZodString>; url: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { name?: string; email?: string; url?: string; }, { name?: string; email?: string; url?: string; }>>; kickableTasks: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{ access: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["write", "read", "public", "token"]>, z.ZodArray<z.ZodString, "many">]>>>; requires: z.ZodOptional<z.ZodLiteral<"account">>; }, "strict", z.ZodTypeAny, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>>]>>>; webhooks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; ops: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{ access: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["write", "read", "public", "token"]>, z.ZodArray<z.ZodString, "many">]>>>; requires: z.ZodOptional<z.ZodLiteral<"account">>; }, "strict", z.ZodTypeAny, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>>]>>>; routes: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{ access: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["write", "read", "public", "token"]>, z.ZodArray<z.ZodString, "many">]>>>; requires: z.ZodOptional<z.ZodLiteral<"account">>; }, "strict", z.ZodTypeAny, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>>]>>>; pollTasks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{ task: z.ZodString; everyMinutes: z.ZodNumber; }, "strip", z.ZodTypeAny, { task?: string; everyMinutes?: number; }, { task?: string; everyMinutes?: number; }>, "many">>>; platformApi: z.ZodOptional<z.ZodObject<{ min: z.ZodString; max: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { min?: string; max?: string; }, { min?: string; max?: string; }>>; scopes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; roles: z.ZodOptional<z.ZodEffects<z.ZodObject<{ vocabulary: z.ZodArray<z.ZodString, "many">; default: z.ZodDefault<z.ZodOptional<z.ZodObject<{ owner: z.ZodOptional<z.ZodString>; "member-edit": z.ZodOptional<z.ZodString>; "member-readonly": z.ZodOptional<z.ZodString>; visitor: z.ZodOptional<z.ZodString>; anonymous: z.ZodOptional<z.ZodString>; agent: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }, { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }>>>; describe: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>; attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["string", "int", "boolean"]>>>; custom: z.ZodOptional<z.ZodObject<{ attributes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ where: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; hide: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; update: z.ZodOptional<z.ZodObject<{ fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; transitions: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { fields?: string[]; transitions?: string; }, { fields?: string[]; transitions?: string; }>>; }, "strict", z.ZodTypeAny, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>>>; ops: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }, { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }>>; }, "strict", z.ZodTypeAny, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }>, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }>>; workspaceTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; connections: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{ key: z.ZodString; kind: z.ZodEnum<["oauth2", "apiKey"]>; label: z.ZodString; description: z.ZodOptional<z.ZodString>; authorizeUrl: z.ZodOptional<z.ZodString>; tokenUrl: z.ZodOptional<z.ZodString>; oauthScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; clientIdEnv: z.ZodOptional<z.ZodString>; clientSecretEnv: z.ZodOptional<z.ZodString>; headerNames: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }>, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }>, "many">>>; fileSources: z.ZodOptional<z.ZodEffects<z.ZodObject<{ workspace: z.ZodOptional<z.ZodEnum<["read", "readwrite"]>>; providers: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; write: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }>, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }>>; fileProviders: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{ key: z.ZodString; connectionKey: z.ZodString; label: z.ZodString; }, "strict", z.ZodTypeAny, { key?: string; label?: string; connectionKey?: string; }, { key?: string; label?: string; connectionKey?: string; }>, "many">>>; uses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ contract: z.ZodString; label: z.ZodOptional<z.ZodString>; optional: z.ZodOptional<z.ZodBoolean>; }, "strict", z.ZodTypeAny, { label?: string; contract?: string; optional?: boolean; }, { label?: string; contract?: string; optional?: boolean; }>>>; provides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; events: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; models: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { models?: string[]; tools?: string[]; events?: string[]; }, { models?: string[]; tools?: string[]; events?: string[]; }>>>; channel: z.ZodOptional<z.ZodObject<{ topics: z.ZodRecord<z.ZodString, z.ZodObject<{ audience: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"all">, z.ZodLiteral<"viewer">, z.ZodString]>>; mayAddress: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; description: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { description?: string; audience?: string; mayAddress?: string[]; }, { description?: string; audience?: string; mayAddress?: string[]; }>>; }, "strict", z.ZodTypeAny, { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }, { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }>>; db: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ scope: z.ZodOptional<z.ZodEnum<["instance", "workspace", "user"]>>; owner: z.ZodOptional<z.ZodLiteral<"creator">>; fields: z.ZodRecord<z.ZodString, z.ZodString>; sealed: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; unique: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">>; indexes: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodObject<{ fields: z.ZodArray<z.ZodString, "many">; kind: z.ZodOptional<z.ZodEnum<["btree", "contains", "text"]>>; }, "strict", z.ZodTypeAny, { kind?: "btree" | "contains" | "text"; fields?: string[]; }, { kind?: "btree" | "contains" | "text"; fields?: string[]; }>]>, "many">>; rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strict", z.ZodTypeAny, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "btree" | "contains" | "text"; fields?: string[]; })[]; rules?: Record<string, unknown>; }, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "btree" | "contains" | "text"; fields?: string[]; })[]; rules?: Record<string, unknown>; }>>>; }, "strict", z.ZodTypeAny, { roles?: { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }; description?: string; manifestVersion?: 1; id?: string; name?: string; version?: string; applicationType?: string; entry?: string; icon?: string; author?: { name?: string; email?: string; url?: string; }; kickableTasks?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; webhooks?: string[]; ops?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; routes?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; pollTasks?: { task?: string; everyMinutes?: number; }[]; platformApi?: { min?: string; max?: string; }; scopes?: string[]; workspaceTools?: string[]; connections?: { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }[]; fileSources?: { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }; fileProviders?: { key?: string; label?: string; connectionKey?: string; }[]; uses?: Record<string, { label?: string; contract?: string; optional?: boolean; }>; provides?: Record<string, { models?: string[]; tools?: string[]; events?: string[]; }>; channel?: { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }; db?: Record<string, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "btree" | "contains" | "text"; fields?: string[]; })[]; rules?: Record<string, unknown>; }>; }, { roles?: { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }; description?: string; manifestVersion?: 1; id?: string; name?: string; version?: string; applicationType?: string; entry?: string; icon?: string; author?: { name?: string; email?: string; url?: string; }; kickableTasks?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; webhooks?: string[]; ops?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; routes?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; pollTasks?: { task?: string; everyMinutes?: number; }[]; platformApi?: { min?: string; max?: string; }; scopes?: string[]; workspaceTools?: string[]; connections?: { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }[]; fileSources?: { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }; fileProviders?: { key?: string; label?: string; connectionKey?: string; }[]; uses?: Record<string, { label?: string; contract?: string; optional?: boolean; }>; provides?: Record<string, { models?: string[]; tools?: string[]; events?: string[]; }>; channel?: { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }; db?: Record<string, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "btree" | "contains" | "text"; fields?: string[]; })[]; rules?: Record<string, unknown>; }>; }>
+const PluginManifestSchema: z.ZodObject<{ manifestVersion: z.ZodLiteral<1>; id: z.ZodString; name: z.ZodString; version: z.ZodString; description: z.ZodString; applicationType: z.ZodString; entry: z.ZodString; icon: z.ZodOptional<z.ZodString>; author: z.ZodOptional<z.ZodObject<{ name: z.ZodString; email: z.ZodOptional<z.ZodString>; url: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { name?: string; email?: string; url?: string; }, { name?: string; email?: string; url?: string; }>>; kickableTasks: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{ access: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["write", "read", "public", "token"]>, z.ZodArray<z.ZodString, "many">]>>>; requires: z.ZodOptional<z.ZodLiteral<"account">>; }, "strict", z.ZodTypeAny, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>>]>>>; webhooks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; ops: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{ access: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["write", "read", "public", "token"]>, z.ZodArray<z.ZodString, "many">]>>>; requires: z.ZodOptional<z.ZodLiteral<"account">>; }, "strict", z.ZodTypeAny, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>>]>>>; routes: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{ access: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["write", "read", "public", "token"]>, z.ZodArray<z.ZodString, "many">]>>>; requires: z.ZodOptional<z.ZodLiteral<"account">>; }, "strict", z.ZodTypeAny, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>>]>>>; pollTasks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{ task: z.ZodString; everyMinutes: z.ZodNumber; }, "strip", z.ZodTypeAny, { task?: string; everyMinutes?: number; }, { task?: string; everyMinutes?: number; }>, "many">>>; platformApi: z.ZodOptional<z.ZodObject<{ min: z.ZodString; max: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { min?: string; max?: string; }, { min?: string; max?: string; }>>; scopes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; roles: z.ZodOptional<z.ZodEffects<z.ZodObject<{ vocabulary: z.ZodArray<z.ZodString, "many">; default: z.ZodDefault<z.ZodOptional<z.ZodObject<{ owner: z.ZodOptional<z.ZodString>; "member-edit": z.ZodOptional<z.ZodString>; "member-readonly": z.ZodOptional<z.ZodString>; visitor: z.ZodOptional<z.ZodString>; anonymous: z.ZodOptional<z.ZodString>; agent: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }, { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }>>>; describe: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>; attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["string", "int", "boolean"]>>>; custom: z.ZodOptional<z.ZodObject<{ attributes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ where: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; hide: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; update: z.ZodOptional<z.ZodObject<{ fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; transitions: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { fields?: string[]; transitions?: string; }, { fields?: string[]; transitions?: string; }>>; }, "strict", z.ZodTypeAny, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>>>; ops: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }, { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }>>; }, "strict", z.ZodTypeAny, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }>, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }>>; workspaceTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; device: z.ZodOptional<z.ZodEffects<z.ZodObject<{ commands: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{ argv: z.ZodArray<z.ZodString, "many">; params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodEnum<["int", "number", "bool", "string"]>, z.ZodObject<{ type: z.ZodEnum<["int", "number"]>; min: z.ZodOptional<z.ZodNumber>; max: z.ZodOptional<z.ZodNumber>; describe: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { type?: "number" | "int"; min?: number; max?: number; describe?: string; }, { type?: "number" | "int"; min?: number; max?: number; describe?: string; }>, z.ZodObject<{ type: z.ZodLiteral<"string">; pattern: z.ZodOptional<z.ZodString>; maxLength: z.ZodOptional<z.ZodNumber>; allowDash: z.ZodOptional<z.ZodBoolean>; describe: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { type?: "string"; maxLength?: number; describe?: string; pattern?: string; allowDash?: boolean; }, { type?: "string"; maxLength?: number; describe?: string; pattern?: string; allowDash?: boolean; }>, z.ZodObject<{ type: z.ZodLiteral<"enum">; values: z.ZodArray<z.ZodString, "many">; describe: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { values?: string[]; type?: "enum"; describe?: string; }, { values?: string[]; type?: "enum"; describe?: string; }>, z.ZodObject<{ type: z.ZodLiteral<"bool">; describe: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { type?: "bool"; describe?: string; }, { type?: "bool"; describe?: string; }>]>>>; cwd: z.ZodOptional<z.ZodString>; env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>; config: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; timeoutSeconds: z.ZodOptional<z.ZodNumber>; onRestart: z.ZodOptional<z.ZodEnum<["report", "rerun"]>>; output: z.ZodOptional<z.ZodObject<{ mode: z.ZodOptional<z.ZodEnum<["live", "batched", "final"]>>; flushMs: z.ZodOptional<z.ZodNumber>; maxChunkKb: z.ZodOptional<z.ZodNumber>; keep: z.ZodOptional<z.ZodEnum<["head", "tail", "both"]>>; maxKb: z.ZodOptional<z.ZodNumber>; }, "strict", z.ZodTypeAny, { mode?: "live" | "batched" | "final"; flushMs?: number; maxChunkKb?: number; keep?: "head" | "tail" | "both"; maxKb?: number; }, { mode?: "live" | "batched" | "final"; flushMs?: number; maxChunkKb?: number; keep?: "head" | "tail" | "both"; maxKb?: number; }>>; result: z.ZodOptional<z.ZodEnum<["text", "json"]>>; describe: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { params?: Record<string, "string" | "number" | "int" | "bool" | { type?: "number" | "int"; min?: number; max?: number; describe?: string; } | { type?: "string"; maxLength?: number; describe?: string; pattern?: string; allowDash?: boolean; } | { values?: string[]; type?: "enum"; describe?: string; } | { type?: "bool"; describe?: string; }>; describe?: string; argv?: string[]; cwd?: string; env?: Record<string, string>; config?: string[]; timeoutSeconds?: number; onRestart?: "report" | "rerun"; output?: { mode?: "live" | "batched" | "final"; flushMs?: number; maxChunkKb?: number; keep?: "head" | "tail" | "both"; maxKb?: number; }; result?: "text" | "json"; }, { params?: Record<string, "string" | "number" | "int" | "bool" | { type?: "number" | "int"; min?: number; max?: number; describe?: string; } | { type?: "string"; maxLength?: number; describe?: string; pattern?: string; allowDash?: boolean; } | { values?: string[]; type?: "enum"; describe?: string; } | { type?: "bool"; describe?: string; }>; describe?: string; argv?: string[]; cwd?: string; env?: Record<string, string>; config?: string[]; timeoutSeconds?: number; onRestart?: "report" | "rerun"; output?: { mode?: "live" | "batched" | "final"; flushMs?: number; maxChunkKb?: number; keep?: "head" | "tail" | "both"; maxKb?: number; }; result?: "text" | "json"; }>>>; program: z.ZodOptional<z.ZodObject<{ main: z.ZodString; resident: z.ZodOptional<z.ZodBoolean>; setup: z.ZodOptional<z.ZodArray<z.ZodObject<{ id: z.ZodString; describe: z.ZodString; run: z.ZodArray<z.ZodString, "many">; inputs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; timeoutSeconds: z.ZodOptional<z.ZodNumber>; }, "strict", z.ZodTypeAny, { id?: string; describe?: string; timeoutSeconds?: number; run?: string[]; inputs?: string[]; }, { id?: string; describe?: string; timeoutSeconds?: number; run?: string[]; inputs?: string[]; }>, "many">>; selfTest: z.ZodOptional<z.ZodObject<{ run: z.ZodArray<z.ZodString, "many">; timeoutSeconds: z.ZodOptional<z.ZodNumber>; }, "strict", z.ZodTypeAny, { timeoutSeconds?: number; run?: string[]; }, { timeoutSeconds?: number; run?: string[]; }>>; }, "strict", z.ZodTypeAny, { main?: string; resident?: boolean; setup?: { id?: string; describe?: string; timeoutSeconds?: number; run?: string[]; inputs?: string[]; }[]; selfTest?: { timeoutSeconds?: number; run?: string[]; }; }, { main?: string; resident?: boolean; setup?: { id?: string; describe?: string; timeoutSeconds?: number; run?: string[]; inputs?: string[]; }[]; selfTest?: { timeoutSeconds?: number; run?: string[]; }; }>>; config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ secret: z.ZodOptional<z.ZodBoolean>; required: z.ZodOptional<z.ZodBoolean>; describe: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { required?: boolean; describe?: string; secret?: boolean; }, { required?: boolean; describe?: string; secret?: boolean; }>>>; redact: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; onAppDeleted: z.ZodOptional<z.ZodEnum<["kill", "finish"]>>; }, "strict", z.ZodTypeAny, { config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; commands?: Record<string, { params?: Record<string, "string" | "number" | "int" | "bool" | { type?: "number" | "int"; min?: number; max?: number; describe?: string; } | { type?: "string"; maxLength?: number; describe?: string; pattern?: string; allowDash?: boolean; } | { values?: string[]; type?: "enum"; describe?: string; } | { type?: "bool"; describe?: string; }>; describe?: string; argv?: string[]; cwd?: string; env?: Record<string, string>; config?: string[]; timeoutSeconds?: number; onRestart?: "report" | "rerun"; output?: { mode?: "live" | "batched" | "final"; flushMs?: number; maxChunkKb?: number; keep?: "head" | "tail" | "both"; maxKb?: number; }; result?: "text" | "json"; }>; program?: { main?: string; resident?: boolean; setup?: { id?: string; describe?: string; timeoutSeconds?: number; run?: string[]; inputs?: string[]; }[]; selfTest?: { timeoutSeconds?: number; run?: string[]; }; }; redact?: string[]; onAppDeleted?: "kill" | "finish"; }, { config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; commands?: Record<string, { params?: Record<string, "string" | "number" | "int" | "bool" | { type?: "number" | "int"; min?: number; max?: number; describe?: string; } | { type?: "string"; maxLength?: number; describe?: string; pattern?: string; allowDash?: boolean; } | { values?: string[]; type?: "enum"; describe?: string; } | { type?: "bool"; describe?: string; }>; describe?: string; argv?: string[]; cwd?: string; env?: Record<string, string>; config?: string[]; timeoutSeconds?: number; onRestart?: "report" | "rerun"; output?: { mode?: "live" | "batched" | "final"; flushMs?: number; maxChunkKb?: number; keep?: "head" | "tail" | "both"; maxKb?: number; }; result?: "text" | "json"; }>; program?: { main?: string; resident?: boolean; setup?: { id?: string; describe?: string; timeoutSeconds?: number; run?: string[]; inputs?: string[]; }[]; selfTest?: { timeoutSeconds?: number; run?: string[]; }; }; redact?: string[]; onAppDeleted?: "kill" | "finish"; }>, { config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; commands?: Record<string, { params?: Record<string, "string" | "number" | "int" | "bool" | { type?: "number" | "int"; min?: number; max?: number; describe?: string; } | { type?: "string"; maxLength?: number; describe?: string; pattern?: string; allowDash?: boolean; } | { values?: string[]; type?: "enum"; describe?: string; } | { type?: "bool"; describe?: string; }>; describe?: string; argv?: string[]; cwd?: string; env?: Record<string, string>; config?: string[]; timeoutSeconds?: number; onRestart?: "report" | "rerun"; output?: { mode?: "live" | "batched" | "final"; flushMs?: number; maxChunkKb?: number; keep?: "head" | "tail" | "both"; maxKb?: number; }; result?: "text" | "json"; }>; program?: { main?: string; resident?: boolean; setup?: { id?: string; describe?: string; timeoutSeconds?: number; run?: string[]; inputs?: string[]; }[]; selfTest?: { timeoutSeconds?: number; run?: string[]; }; }; redact?: string[]; onAppDeleted?: "kill" | "finish"; }, { config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; commands?: Record<string, { params?: Record<string, "string" | "number" | "int" | "bool" | { type?: "number" | "int"; min?: number; max?: number; describe?: string; } | { type?: "string"; maxLength?: number; describe?: string; pattern?: string; allowDash?: boolean; } | { values?: string[]; type?: "enum"; describe?: string; } | { type?: "bool"; describe?: string; }>; describe?: string; argv?: string[]; cwd?: string; env?: Record<string, string>; config?: string[]; timeoutSeconds?: number; onRestart?: "report" | "rerun"; output?: { mode?: "live" | "batched" | "final"; flushMs?: number; maxChunkKb?: number; keep?: "head" | "tail" | "both"; maxKb?: number; }; result?: "text" | "json"; }>; program?: { main?: string; resident?: boolean; setup?: { id?: string; describe?: string; timeoutSeconds?: number; run?: string[]; inputs?: string[]; }[]; selfTest?: { timeoutSeconds?: number; run?: string[]; }; }; redact?: string[]; onAppDeleted?: "kill" | "finish"; }>>; connections: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{ key: z.ZodString; kind: z.ZodEnum<["oauth2", "apiKey"]>; label: z.ZodString; description: z.ZodOptional<z.ZodString>; authorizeUrl: z.ZodOptional<z.ZodString>; tokenUrl: z.ZodOptional<z.ZodString>; oauthScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; clientIdEnv: z.ZodOptional<z.ZodString>; clientSecretEnv: z.ZodOptional<z.ZodString>; headerNames: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }>, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }>, "many">>>; fileSources: z.ZodOptional<z.ZodEffects<z.ZodObject<{ workspace: z.ZodOptional<z.ZodEnum<["read", "readwrite"]>>; providers: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; write: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }>, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }>>; fileProviders: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{ key: z.ZodString; connectionKey: z.ZodString; label: z.ZodString; }, "strict", z.ZodTypeAny, { key?: string; label?: string; connectionKey?: string; }, { key?: string; label?: string; connectionKey?: string; }>, "many">>>; uses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ contract: z.ZodString; label: z.ZodOptional<z.ZodString>; optional: z.ZodOptional<z.ZodBoolean>; }, "strict", z.ZodTypeAny, { label?: string; contract?: string; optional?: boolean; }, { label?: string; contract?: string; optional?: boolean; }>>>; provides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; events: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; models: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { models?: string[]; tools?: string[]; events?: string[]; }, { models?: string[]; tools?: string[]; events?: string[]; }>>>; channel: z.ZodOptional<z.ZodObject<{ topics: z.ZodRecord<z.ZodString, z.ZodObject<{ audience: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"all">, z.ZodLiteral<"viewer">, z.ZodString]>>; mayAddress: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; description: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { description?: string; audience?: string; mayAddress?: string[]; }, { description?: string; audience?: string; mayAddress?: string[]; }>>; }, "strict", z.ZodTypeAny, { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }, { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }>>; db: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ scope: z.ZodOptional<z.ZodEnum<["instance", "workspace", "user"]>>; owner: z.ZodOptional<z.ZodLiteral<"creator">>; fields: z.ZodRecord<z.ZodString, z.ZodString>; sealed: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; unique: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">>; indexes: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodObject<{ fields: z.ZodArray<z.ZodString, "many">; kind: z.ZodOptional<z.ZodEnum<["btree", "contains", "text"]>>; }, "strict", z.ZodTypeAny, { kind?: "text" | "btree" | "contains"; fields?: string[]; }, { kind?: "text" | "btree" | "contains"; fields?: string[]; }>]>, "many">>; rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strict", z.ZodTypeAny, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "text" | "btree" | "contains"; fields?: string[]; })[]; rules?: Record<string, unknown>; }, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "text" | "btree" | "contains"; fields?: string[]; })[]; rules?: Record<string, unknown>; }>>>; }, "strict", z.ZodTypeAny, { roles?: { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }; description?: string; manifestVersion?: 1; id?: string; name?: string; version?: string; applicationType?: string; entry?: string; icon?: string; author?: { name?: string; email?: string; url?: string; }; kickableTasks?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; webhooks?: string[]; ops?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; routes?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; pollTasks?: { task?: string; everyMinutes?: number; }[]; platformApi?: { min?: string; max?: string; }; scopes?: string[]; workspaceTools?: string[]; device?: { config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; commands?: Record<string, { params?: Record<string, "string" | "number" | "int" | "bool" | { type?: "number" | "int"; min?: number; max?: number; describe?: string; } | { type?: "string"; maxLength?: number; describe?: string; pattern?: string; allowDash?: boolean; } | { values?: string[]; type?: "enum"; describe?: string; } | { type?: "bool"; describe?: string; }>; describe?: string; argv?: string[]; cwd?: string; env?: Record<string, string>; config?: string[]; timeoutSeconds?: number; onRestart?: "report" | "rerun"; output?: { mode?: "live" | "batched" | "final"; flushMs?: number; maxChunkKb?: number; keep?: "head" | "tail" | "both"; maxKb?: number; }; result?: "text" | "json"; }>; program?: { main?: string; resident?: boolean; setup?: { id?: string; describe?: string; timeoutSeconds?: number; run?: string[]; inputs?: string[]; }[]; selfTest?: { timeoutSeconds?: number; run?: string[]; }; }; redact?: string[]; onAppDeleted?: "kill" | "finish"; }; connections?: { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }[]; fileSources?: { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }; fileProviders?: { key?: string; label?: string; connectionKey?: string; }[]; uses?: Record<string, { label?: string; contract?: string; optional?: boolean; }>; provides?: Record<string, { models?: string[]; tools?: string[]; events?: string[]; }>; channel?: { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }; db?: Record<string, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "text" | "btree" | "contains"; fields?: string[]; })[]; rules?: Record<string, unknown>; }>; }, { roles?: { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }; description?: string; manifestVersion?: 1; id?: string; name?: string; version?: string; applicationType?: string; entry?: string; icon?: string; author?: { name?: string; email?: string; url?: string; }; kickableTasks?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; webhooks?: string[]; ops?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; routes?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; pollTasks?: { task?: string; everyMinutes?: number; }[]; platformApi?: { min?: string; max?: string; }; scopes?: string[]; workspaceTools?: string[]; device?: { config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; commands?: Record<string, { params?: Record<string, "string" | "number" | "int" | "bool" | { type?: "number" | "int"; min?: number; max?: number; describe?: string; } | { type?: "string"; maxLength?: number; describe?: string; pattern?: string; allowDash?: boolean; } | { values?: string[]; type?: "enum"; describe?: string; } | { type?: "bool"; describe?: string; }>; describe?: string; argv?: string[]; cwd?: string; env?: Record<string, string>; config?: string[]; timeoutSeconds?: number; onRestart?: "report" | "rerun"; output?: { mode?: "live" | "batched" | "final"; flushMs?: number; maxChunkKb?: number; keep?: "head" | "tail" | "both"; maxKb?: number; }; result?: "text" | "json"; }>; program?: { main?: string; resident?: boolean; setup?: { id?: string; describe?: string; timeoutSeconds?: number; run?: string[]; inputs?: string[]; }[]; selfTest?: { timeoutSeconds?: number; run?: string[]; }; }; redact?: string[]; onAppDeleted?: "kill" | "finish"; }; connections?: { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }[]; fileSources?: { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }; fileProviders?: { key?: string; label?: string; connectionKey?: string; }[]; uses?: Record<string, { label?: string; contract?: string; optional?: boolean; }>; provides?: Record<string, { models?: string[]; tools?: string[]; events?: string[]; }>; channel?: { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }; db?: Record<string, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "text" | "btree" | "contains"; fields?: string[]; })[]; rules?: Record<string, unknown>; }>; }>
 ```
 
 #### `PluginRolesSchema` — const · src/manifest.ts
@@ -765,6 +805,14 @@ The reducer behind `plugin/binding_set`. Deterministic: setting a slot replaces
 function reduceBinding( current: BindingMap, event: { slot?: unknown; nodeId?: unknown; applicationType?: unknown; via?: unknown; at?: unknown }, knownSlots: readonly string[], ): BindingMap
 ```
 
+#### `renderCommand` — function · src/machine/commands.ts
+
+Render one declared command. Throws `DeviceCommandError` with a sentence for anything undeclared or ill-typed.
+
+```ts
+function renderCommand(block: DeviceBlock, name: string, params: Record<string, unknown> = {}): RenderedCommand
+```
+
 #### `resolveAppRole` — function · src/roles.ts
 
 The app's word for this caller.
@@ -885,7 +933,7 @@ A manifest with one entry removed (the bytes stay; they may be shared). Pure.
 function withoutAsset(assets: AssetsManifest | null | undefined, pluginId: string, name: string): AssetsManifest
 ```
 
-### Types (76)
+### Types (81)
 
 #### `AgentRunToolContext` — interface · src/types.ts
 
@@ -1191,6 +1239,23 @@ interface CollapsibleConfig {
 }
 ```
 
+#### `CommandSpec` — interface · src/machine/commands.ts
+
+```ts
+interface CommandSpec {
+  argv: string[];
+  params?: Record<string, ParamSpec>;
+  cwd?: string;
+  env?: Record<string, string>;
+  config?: string[];
+  timeoutSeconds?: number;
+  onRestart?: "report" | "rerun";
+  output?: OutputSpec;
+  result?: "text" | "json";
+  describe?: string;
+}
+```
+
 #### `CompiledCustomRole` — interface · src/db/custom-roles.ts
 
 ```ts
@@ -1211,6 +1276,16 @@ interface CompiledCustomRole {
 }
 ```
 
+#### `ConfigKeySpec` — interface · src/machine/commands.ts
+
+```ts
+interface ConfigKeySpec {
+  secret?: boolean;
+  required?: boolean;
+  describe?: string;
+}
+```
+
 #### `ContractDef` — interface · src/bindings.ts
 
 What a contract REQUIRES of whoever claims it. The platform ships these; an app may publish its own.
@@ -1321,6 +1396,18 @@ interface DerivedTool extends ApplicationTools {
 }
 ```
 
+#### `DeviceBlock` — interface · src/machine/commands.ts
+
+```ts
+interface DeviceBlock {
+  commands: Record<string, CommandSpec>;
+  program?: ProgramSpec;
+  config?: Record<string, ConfigKeySpec>;
+  redact?: string[];
+  onAppDeleted?: "kill" | "finish";
+}
+```
+
 #### `EventData` — interface · src/types.ts
 
 ```ts
@@ -1635,6 +1722,22 @@ interface OpToolConfig<S extends OpInput, R> {
 }
 ```
 
+#### `ParamSpec` — type · src/machine/commands.ts
+
+DECLARED COMMANDS — the wall between an app and the person's computer.
+
+```ts
+type ParamSpec =
+  | "int"
+  | "number"
+  | "bool"
+  | "string"
+  | { type: "int" | "number"; min?: number; max?: number; describe?: string }
+  | { type: "string"; pattern?: string; maxLength?: number; allowDash?: boolean; describe?: string }
+  | { type: "enum"; values: string[]; describe?: string }
+  | { type: "bool"; describe?: string };
+```
+
 #### `ParsedSourceId` — type · src/files.ts
 
 ```ts
@@ -1733,6 +1836,20 @@ type ReconcileDecision =
   | { kind: "adopt" };
 ```
 
+#### `RenderedCommand` — interface · src/machine/commands.ts
+
+```ts
+interface RenderedCommand {
+  name: string;
+  argv: string[];
+  cwd?: string;
+  env: Record<string, string>;
+  config: string[];
+  timeoutSeconds: number;
+  onRestart: "report" | "rerun";
+}
+```
+
 #### `RequiredStateShape` — interface · src/helpers.ts
 
 Fields whose ABSENCE means "did not load" (they are seeded at genesis).
@@ -1810,11 +1927,11 @@ interface UsesDecl {
 ```
 
 ==============================================================================
-## `esoul-sdk/server` — 67 exports
+## `esoul-sdk/server` — 79 exports
 
 Server code only (server.ts, ops, routes, tasks): the viewer, the app's database, files, connections, machines, charts, route tokens.
 
-### Functions and values (27)
+### Functions and values (29)
 
 #### `APPROVAL_WAIT` — const · src/computer.ts
 
@@ -1848,6 +1965,22 @@ COMPOSE A ROLE, as the owner: a name of its own, a base word from the vocabulary
 function defineAppRole( _ctx: { pluginId: string; workspaceId: string; nodeId: string; viewer: PluginViewer }, _definition: CustomRoleDefinitionRaw, ): Promise<{ ok: boolean; name?: string; error?: string }>
 ```
 
+#### `DEVICE_RUN_TERMINAL` — const · src/device.ts
+
+The statuses a run ends in: done, expired, cancelled, lost.
+
+```ts
+const DEVICE_RUN_TERMINAL: readonly DeviceRunStatus[]
+```
+
+#### `devices` — function · src/server.ts
+
+PARTS OF THE APP THAT RUN ON THE PERSON'S COMPUTER (plugin-device-arm.md). The app declares its commands in plugin.json `device.commands`; the owner connects a computer with <ConnectComputer/> (esoul-sdk/react) and approves that list; then server code runs a declared command by name:
+
+```ts
+function devices(_ctx: { pluginId: string; nodeId: string; viewer?: { canWrite: boolean; kind: string; userId: string | null } }): Devices
+```
+
 #### `emitPluginAppEvent` — function · src/server.ts
 
 Cross-app events: dispatch the TARGET app's own events through the platform spine (target's dataCreator mints; triggers fire; every event is actor-stamped `{kind:"plugin", pluginId, sourceNodeId}`). Same-workspace only. HOST-ONLY.
@@ -2032,7 +2165,7 @@ WHO IS THIS, IN WORDS. The caller's own name and email, for an app with a reason
 function viewerProfile(_viewer: PluginViewer): Promise<ViewerProfile | null>
 ```
 
-### Types (40)
+### Types (50)
 
 #### `AppRolePerson` — interface · src/server.ts
 
@@ -2263,6 +2396,98 @@ interface CustomRolesEnvelope {
 }
 ```
 
+#### `DeviceRunOptions` — interface · src/device.ts
+
+```ts
+interface DeviceRunOptions {
+  linkId?: string;
+  expiresInSeconds?: number;
+}
+```
+
+#### `DeviceRunStarted` — interface · src/device.ts
+
+```ts
+interface DeviceRunStarted {
+  commandId: string;
+  status: DeviceRunStatus;
+  machineOnline: boolean;
+  expiresAt: number;
+}
+```
+
+#### `DeviceRunStatus` — type · src/device.ts
+
+```ts
+type DeviceRunStatus = "queued" | "claimed" | "running" | "done" | "expired" | "cancelled" | "lost";
+```
+
+#### `DeviceRunView` — interface · src/device.ts
+
+```ts
+interface DeviceRunView {
+  commandId: string;
+  linkId: string;
+  machineId: string;
+  capability?: string;
+  agent?: string | null;
+  name: string;
+  params: Record<string, unknown>;
+  argv: string[];
+  status: DeviceRunStatus;
+  exitCode: number | null;
+  signal: string | null;
+  reason: string | null;
+  output?: string;
+  tail?: string;
+  result?: unknown;
+  resultError?: string | null;
+  outputMode?: "live" | "batched" | "final";
+  outputBytes: number;
+  outputSeq: number;
+  truncated: boolean;
+  createdAt: number;
+  startedAt: number | null;
+  endedAt: number | null;
+  expiresAt: number;
+}
+```
+
+#### `Devices` — interface · src/device.ts
+
+```ts
+interface Devices {
+  list(): Promise<DeviceSummary[]>;
+  run(name: string, params?: Record<string, unknown>, opts?: DeviceRunOptions): Promise<DeviceRunStarted>;
+  get(commandId: string): Promise<DeviceRunView>;
+  wait(commandId: string, opts?: { timeoutSeconds?: number }): Promise<DeviceRunView>;
+  cancel(commandId: string): Promise<{ status: string }>;
+  sh(line: string, opts: { agent: string; stdin?: string; linkId?: string; waitSeconds?: number }): Promise<ShellResult & { commandId: string; status: DeviceRunStatus }>;
+  program(linkId: string): {
+    send(topic: string, data?: unknown, opts?: { waitSeconds?: number }): Promise<{ commandId: string; status: DeviceRunStatus; ok: boolean; result: unknown; error: string | null }>;
+    state(): Promise<ProgramState | null>;
+  };
+}
+```
+
+#### `DeviceSummary` — interface · src/device.ts
+
+One computer connected to this app instance.
+
+```ts
+interface DeviceSummary {
+  linkId: string;
+  status: "active" | "suspended";
+  reason: string | null;
+  commands: string[];
+  pendingApproval: { added: string[]; changed: string[] };
+  machine: { machineId: string; hostname: string; os: string; arch: string | null; runtimeVersion: string | null; lastSeenAt: number | null; online: boolean } | null;
+  workspace?: WorkspaceGrant | null;
+  program?: boolean;
+  programState?: ProgramState | null;
+}
+```
+
 #### `EmitPluginAppEventArgs` — interface · src/server.ts
 
 ```ts
@@ -2500,7 +2725,8 @@ interface PluginViewer {
   attrs?: Record<string, AttrValue>;
   canWrite: boolean;
   shareId: string | null;
-  agent?: { runId?: string; onBehalfOf: Omit<PluginViewer, "agent"> };
+  agent?: { runId?: string; onBehalfOf: Omit<PluginViewer, "agent"> };  
+  device?: { machineId: string; linkId: string; hostname: string };
 }
 ```
 
@@ -2541,6 +2767,38 @@ type PluginWebhookHandler = (
 ) => Promise<Response>;
 ```
 
+#### `ProgramState` — interface · src/machine/program-api.ts
+
+Where an app's program stands on one computer — what the runtime reports and the app's Computers card renders. `phase` moves forward installing → setup → self-test → running (or ready, for a program started by its first message); `failed` and `refused` say why in `error`.
+
+```ts
+interface ProgramState {
+  digest: string;
+  phase: "installing" | "setup" | "self-test" | "ready" | "starting" | "running" | "stopped" | "failed" | "refused";
+  steps: ProgramStepState[];
+  status?: { text: string; progress?: number; ready?: boolean; at: number } | null;
+  error?: string | null;
+  logTail?: string[];
+  restarts: number;
+  updatedAt: number;
+}
+```
+
+#### `ProgramStepState` — interface · src/machine/program-api.ts
+
+One setup step, as the Computers card shows it.
+
+```ts
+interface ProgramStepState {
+  id: string;
+  describe: string;
+  state: "pending" | "running" | "done" | "cached" | "failed";
+  startedAt?: number;
+  endedAt?: number;
+  detail?: string;
+}
+```
+
 #### `RouteTokenGrant` — interface · src/server.ts
 
 ```ts
@@ -2561,6 +2819,22 @@ interface RunOptions {
 }
 ```
 
+#### `ShellResult` — interface · src/device.ts
+
+One line of the shared command line, answered (esoul-sdk/machine shell.ts): `text` is what a terminal would print (what an agent reads), `data` the same answer structured, `opId` the journal entry to `undo`.
+
+```ts
+interface ShellResult {
+  ok: boolean;
+  text: string;
+  data?: unknown;
+  exitCode?: number | null;
+  error?: string;
+  opId?: string;
+  cwd: string;
+}
+```
+
 #### `ToEndOptions` — interface · src/computer.ts
 
 ```ts
@@ -2582,12 +2856,28 @@ interface ViewerProfile {
 }
 ```
 
+#### `WorkspaceGrant` — type · src/device.ts
+
+What an app's agents may reach on a computer through the shared command line.
+
+```ts
+type WorkspaceGrant = { scope: "folder"; root: string } | { scope: "computer" };
+```
+
 ==============================================================================
-## `esoul-sdk/react` — 52 exports
+## `esoul-sdk/react` — 64 exports
 
 The app's UI: hooks for the viewer, the app's state, realtime, workspace files and tools.
 
-### Functions and values (27)
+### Functions and values (33)
+
+#### `ConnectComputer` — function · src/react.ts
+
+The connect panel for an app's config page: the computers already connected (online, last seen, Disconnect, Approve new commands) and "Connect a computer" — one command to paste in a terminal, the code the computer shows, Approve. Linux and macOS, Node 22+.
+
+```ts
+function ConnectComputer(_props: { workspaceId: string; nodeId: string; title?: string; className?: string }): any
+```
 
 #### `describeFailure` — function · src/failed-requests.ts
 
@@ -2693,6 +2983,30 @@ True when the current viewer may mutate this workspace.
 function useAppCanEdit(): boolean
 ```
 
+#### `useDeviceActions` — function · src/react.ts
+
+The owner's buttons from the UI: run a declared command, stop a run, disconnect a computer, approve an update's new commands. Needs edit access.
+
+```ts
+function useDeviceActions(_where: { nodeId: string }): { run(name: string, params?: Record<string, unknown>, opts?: { linkId?: string; expiresInSeconds?: number }): Promise<DeviceRunStarted>; cancel(commandId: string): Promise<{ status: string }>; disconnect(linkId: string): Promise<{ ok: boolean }>; approveUpdate(linkId: string): Promise<unknown>; recent(limit?: number): Promise<{ commands: DeviceRunView[] }>; /** What the app's agents may reach on that computer: none, its folder, or the whole computer. */ setWorkspace(linkId: string, workspace: "none" | "folder" | "computer"): Promise<unknown>; /** One line of the shared command line as a named agent; `result` is the answer once it ends. */ sh(line: string, opts: { agent: string; stdin?: string; linkId?: string; waitSeconds?: number }): Promise<DeviceRunView & { result?: import("./device.js").ShellResult }>; }
+```
+
+#### `useDeviceRun` — function · src/react.ts
+
+One run, live: status as it changes, output as it streams. `finished` once it ended.
+
+```ts
+function useDeviceRun(_where: { workspaceId: string; nodeId: string; commandId: string | null | undefined }): { run: DeviceRunView | null; error: string | null; refetch: () => Promise<void>; finished: boolean }
+```
+
+#### `useDevices` — function · src/react.ts
+
+The computers connected to this app instance, live (presence refreshes every 20 s).
+
+```ts
+function useDevices(_where: { workspaceId: string; nodeId: string }): { devices: DeviceSummary[] | null; error: string | null; refresh: () => Promise<void> }
+```
+
 #### `useFileSourceEntries` — function · src/react.ts
 
 One folder's listing; a failing source reports error/errorKind, never []. `opts` narrows AT THE SOURCE — `{ only: "folder" }`, `{ nameContains }`, `{ orderBy: "name", pageSize: 1000 }` — and `loadMore()` appends the next page.
@@ -2725,6 +3039,14 @@ A folder box with autocomplete: give it the text being typed ("sheets/quality_da
 function useFolderAutocomplete(_workspaceId: string | null, _sourceId: string | null, _text: string): FolderAutocompleteState
 ```
 
+#### `useMyComputers` — function · src/react.ts
+
+The account's computers (computers belong to the person, not to an app; an app gets one by assignment). `assign(machineId, nodeId)` gives a computer to an app (approving its declared commands); `disconnect(machineId)` removes a computer from the account entirely.
+
+```ts
+function useMyComputers(): { computers: MyComputer[] | null; error: string | null; refresh: () => Promise<void>; assign(machineId: string, nodeId: string): Promise<{ linkId: string }>; disconnect(machineId: string): Promise<{ ok: boolean }> }
+```
+
 #### `usePluginCurrentChatId` — function · src/react.ts
 
 Current open chat id, for `chatIdSource` attribution.
@@ -2805,7 +3127,75 @@ Invoke tools of OTHER apps in the workspace (append a spreadsheet row, add a cal
 function useWorkspaceTools(_identity: { workspaceId: string; nodeId: string }): WorkspaceTools
 ```
 
-### Types (25)
+#### `YourComputers` — function · src/react.ts
+
+The account's computers as a panel: online, the apps each serves, Disconnect.
+
+```ts
+function YourComputers(_props: { className?: string }): any
+```
+
+### Types (31)
+
+#### `DeviceRunStarted` — interface · src/device.ts
+
+```ts
+interface DeviceRunStarted {
+  commandId: string;
+  status: DeviceRunStatus;
+  machineOnline: boolean;
+  expiresAt: number;
+}
+```
+
+#### `DeviceRunView` — interface · src/device.ts
+
+```ts
+interface DeviceRunView {
+  commandId: string;
+  linkId: string;
+  machineId: string;
+  capability?: string;
+  agent?: string | null;
+  name: string;
+  params: Record<string, unknown>;
+  argv: string[];
+  status: DeviceRunStatus;
+  exitCode: number | null;
+  signal: string | null;
+  reason: string | null;
+  output?: string;
+  tail?: string;
+  result?: unknown;
+  resultError?: string | null;
+  outputMode?: "live" | "batched" | "final";
+  outputBytes: number;
+  outputSeq: number;
+  truncated: boolean;
+  createdAt: number;
+  startedAt: number | null;
+  endedAt: number | null;
+  expiresAt: number;
+}
+```
+
+#### `DeviceSummary` — interface · src/device.ts
+
+One computer connected to this app instance.
+
+```ts
+interface DeviceSummary {
+  linkId: string;
+  status: "active" | "suspended";
+  reason: string | null;
+  commands: string[];
+  pendingApproval: { added: string[]; changed: string[] };
+  machine: { machineId: string; hostname: string; os: string; arch: string | null; runtimeVersion: string | null; lastSeenAt: number | null; online: boolean } | null;
+  workspace?: WorkspaceGrant | null;
+  program?: boolean;
+  programState?: ProgramState | null;
+}
+```
 
 #### `FailedRequest` — interface · src/failed-requests.ts
 
@@ -2923,6 +3313,23 @@ interface LabelClass {
 }
 ```
 
+#### `MyComputer` — interface · src/react.ts
+
+One computer connected to the signed-in account, and the apps it is assigned to.
+
+```ts
+interface MyComputer {
+  machineId: string;
+  hostname: string;
+  os: string;
+  arch: string | null;
+  runtimeVersion: string | null;
+  lastSeenAt: number | null;
+  online: boolean;
+  apps: { linkId: string; nodeId: string; workspaceId: string; status: string; appName: string | null }[];
+}
+```
+
 #### `PluginRealtime` — interface · src/react.ts
 
 ```ts
@@ -3068,6 +3475,22 @@ interface ResolvedFilePath {
 }
 ```
 
+#### `ShellResult` — interface · src/device.ts
+
+One line of the shared command line, answered (esoul-sdk/machine shell.ts): `text` is what a terminal would print (what an agent reads), `data` the same answer structured, `opId` the journal entry to `undo`.
+
+```ts
+interface ShellResult {
+  ok: boolean;
+  text: string;
+  data?: unknown;
+  exitCode?: number | null;
+  error?: string;
+  opId?: string;
+  cwd: string;
+}
+```
+
 #### `SignInWall` — interface · src/react.ts
 
 ```ts
@@ -3091,6 +3514,14 @@ interface WorkspaceAppSummary {
 }
 ```
 
+#### `WorkspaceGrant` — type · src/device.ts
+
+What an app's agents may reach on a computer through the shared command line.
+
+```ts
+type WorkspaceGrant = { scope: "folder"; root: string } | { scope: "computer" };
+```
+
 #### `WorkspaceNav` — interface · src/react.ts
 
 ```ts
@@ -3344,3 +3775,990 @@ interface TestManifest {
 ```ts
 type ViewerKind = RuleViewer["kind"];
 ```
+
+==============================================================================
+## `esoul-sdk/machine` — 102 exports
+
+The side of an app that runs on the person's computer: the signed door protocol, the declared-command rules, the runtime behind the `esoul-device` command. Node built-ins only.
+
+### Functions and values (62)
+
+#### `AGENT_NAME_RE` — const · src/machine/shell.ts
+
+What an agent may be called: lowercase letters, digits, - and _, up to 32, starting with a letter.
+
+```ts
+const AGENT_NAME_RE: RegExp
+```
+
+#### `announce` — function · src/machine/capabilities.ts
+
+What the hello announces: ["commands@1", "workspace@1"].
+
+```ts
+function announce(reg: Map<string, Capability>): string[]
+```
+
+#### `applyEdits` — function · src/machine/files.ts
+
+Find-and-replace edits, applied in order; each must match exactly once (unless `all`). All or nothing.
+
+```ts
+function applyEdits(text: string, edits: Edit[]): { text: string; applied: number }
+```
+
+#### `applyPatch` — function · src/machine/files.ts
+
+Apply a unified diff with context. Each hunk's old lines (context + removed) are located exactly, preferring the line the diff names and searching outward, so a file that moved on still takes a hunk whose context is intact. A hunk whose context is gone is reported, never forced. All-or-nothing unless `partial`.
+
+```ts
+function applyPatch(text: string, diff: string, opts: { partial?: boolean } = {}): { text: string; results: HunkResult[] }
+```
+
+#### `approvedCommandNames` — function · src/machine/digest.ts
+
+The command names an approval covers (without the program's entry).
+
+```ts
+function approvedCommandNames(approved: Record<string, string>): string[]
+```
+
+#### `builtInCapabilities` — function · src/machine/capabilities.ts
+
+The capabilities this runtime is built with, as one registry (the supervisor dispatches through it).
+
+```ts
+function builtInCapabilities(startRun: (job: Job, redact: string[], env: Record<string, string>) => Promise<void>, programs: ProgramDelivery | null = null): Map<string, Capability>
+```
+
+#### `canonical` — function · src/machine/protocol.ts
+
+The exact bytes that are signed. Path INCLUDES the query string.
+
+```ts
+function canonical(method: string, pathAndQuery: string, ts: number | string, body: string | Uint8Array): string
+```
+
+#### `COMMAND_NAME_RE` — const · src/machine/commands.ts
+
+What a command name may look like: lowercase, starts with a letter, up to 40 characters.
+
+```ts
+const COMMAND_NAME_RE: RegExp
+```
+
+#### `commandDigest` — function · src/machine/digest.ts
+
+Stable digest of one command's spec — what the owner approved.
+
+```ts
+function commandDigest(spec: CommandSpec): string
+```
+
+#### `commandDigests` — function · src/machine/digest.ts
+
+Every declared command's digest, by name, and the program's under `@program` — what an approval records.
+
+```ts
+function commandDigests(block: DeviceBlock): Record<string, string>
+```
+
+#### `commandsCapability` — function · src/machine/capabilities.ts
+
+The app's declared commands; the detached runner owns and reports each run.
+
+```ts
+function commandsCapability(deps: { startRun: (job: Job, redact: string[], env: Record<string, string>) => Promise<void> }): Capability
+```
+
+#### `confinedArgv` — function · src/machine/shell.ts
+
+argv that runs `line` in `cwd` under the scope's confinement.
+
+```ts
+function confinedArgv(ws: Workspace, cwd: string, line: string): string[]
+```
+
+#### `connect` — function · src/machine/supervisor.ts
+
+Answer a connect link from the app's page with this computer's key: print the code and the commands, wait for the owner's approval.
+
+```ts
+async function connect(opts: ConnectOptions): Promise<ConnectResult>
+```
+
+#### `connectCode` — function · src/machine/protocol.ts
+
+The short code both the machine and the connect page show, so the owner can see the request on screen is the one from the machine in front of them. Derived from the machine's public key + the offer, so neither side invents it.
+
+```ts
+function connectCode(publicKey: string, offerId: string): string
+```
+
+#### `createProgramManager` — function · src/machine/program-manager.ts
+
+The runtime's keeper of app programs: `reconcile(links)` after each hello brings every approved program to its approved digest (download, verify, setup, self-test, start) and stops the rest; `deliver` hands a program the app's message and resolves with its answer.
+
+```ts
+function createProgramManager(opts: ProgramManagerOptions)
+```
+
+#### `DEFAULT_TIMEOUT_SECONDS` — const · src/machine/commands.ts
+
+A command's time limit when it declares none: one hour.
+
+```ts
+const DEFAULT_TIMEOUT_SECONDS: 3600
+```
+
+#### `defineProgram` — function · src/machine/program-api.ts
+
+Identity helper for a program written in plain JavaScript (TypeScript can use `satisfies Program`).
+
+```ts
+function defineProgram(program: Program): Program
+```
+
+#### `describeGrant` — function · src/machine/grant.ts
+
+A grant in words: "the folder /home/me/proj", "the whole computer", or "no workspace access".
+
+```ts
+function describeGrant(g: WorkspaceGrant | null): string
+```
+
+#### `deviceBlockProblems` — function · src/machine/commands.ts
+
+Every problem with a `device` block, in words an author can act on. Empty = valid.
+
+```ts
+function deviceBlockProblems(block: unknown): string[]
+```
+
+#### `DeviceCommandError` — class · src/machine/commands.ts
+
+Why a command was refused: `unknown_command` (not declared), `bad_param` (missing, extra or ill-typed), `bad_spec`. The message says which, in words.
+
+```ts
+class DeviceCommandError extends Error { … }
+```
+
+#### `deviceHome` — function · src/machine/state.ts
+
+The runtime's folder on this computer: `explicit`, else ESOUL_DEVICE_HOME, else ~/.esoul-device.
+
+```ts
+function deviceHome(explicit?: string): string
+```
+
+#### `DoorError` — class · src/machine/client.ts
+
+A door call that failed: `status` 0 means the door never answered (network); otherwise the door's own `code` and message.
+
+```ts
+class DoorError extends Error { … }
+```
+
+#### `effectiveGrant` — function · src/machine/grant.ts
+
+What the runtime actually allows: the grant, if it fits inside the ceiling. A folder grant inside a folder ceiling keeps the grant's (narrower) root; a computer grant needs a computer ceiling.
+
+```ts
+function effectiveGrant(grant: WorkspaceGrant | null, ceiling: WorkspaceGrant | null): { ok: true; grant: WorkspaceGrant; why?: undefined } | { ok: false; why: string; grant?: undefined }
+```
+
+#### `execute` — function · src/machine/shell.ts
+
+Run one line of the shared command line as a named agent in a workspace; never throws — failures come back as `ok: false` with an `error` code.
+
+```ts
+async function execute(call: ShellCall): Promise<ShellResult>
+```
+
+#### `FileError` — class · src/machine/files.ts
+
+Why a file operation was refused: outside_scope, not_found, changed, hard_link, edit_failed, patch_failed, … — with a sentence and details.
+
+```ts
+class FileError extends Error { … }
+```
+
+#### `generateDeviceKey` — function · src/machine/protocol.ts
+
+A new Ed25519 keypair for a computer: the public key in base64url, the private key as PKCS#8 PEM (it never leaves the computer).
+
+```ts
+function generateDeviceKey(): DeviceKeyPair
+```
+
+#### `grantFromChoice` — function · src/machine/grant.ts
+
+The owner's choice turned into a grant under this computer's ceiling, or why it cannot be.
+
+```ts
+function grantFromChoice(choice: WorkspaceChoice, ceiling: WorkspaceGrant | null): { ok: true; grant: WorkspaceGrant | null; why?: undefined } | { ok: false; why: string; grant?: undefined }
+```
+
+#### `H` — const · src/machine/protocol.ts
+
+Request headers. `key` names the signer: a machine id, or `connect:<id>` before approval.
+
+```ts
+const H: { readonly key: "x-esoul-key"; readonly ts: "x-esoul-ts"; readonly sig: "x-esoul-sig"; readonly runtime: "x-esoul-runtime"; }
+```
+
+#### `isPublicKey` — function · src/machine/protocol.ts
+
+Whether `s` is a base64url Ed25519 public key (43 characters).
+
+```ts
+function isPublicKey(s: unknown): s is string
+```
+
+#### `isTransient` — function · src/machine/client.ts
+
+Transient = worth retrying later without telling anyone.
+
+```ts
+function isTransient(e: unknown): boolean
+```
+
+#### `Journal` — class · src/machine/files.ts
+
+The undo journal of one workspace: previous contents (content-addressed), directory snapshots, and the append-only log of operations.
+
+```ts
+class Journal { … }
+```
+
+#### `machineFingerprint` — function · src/machine/state.ts
+
+This computer, stably: the OS machine id (Linux /etc/machine-id, macOS the platform UUID), the user, and the runtime home. Sent when connecting, so the platform RECOGNISES a reconnect (a reinstall, a new key) instead of listing a second entry for the same computer. A different home is deliberately a different computer (a second runtime, a test run).
+
+```ts
+function machineFingerprint(home: string): string
+```
+
+#### `makeClient` — function · src/machine/client.ts
+
+A signed door client for one key: every call carries the signature, retries only what the door never answered.
+
+```ts
+function makeClient(args: { base: string; keyId: string; privateKeyPem: string; runtimeVersion: string; fetch?: FetchLike; onTiming?: (t: CallTiming) => void }): DoorClient
+```
+
+#### `MAX_SKEW_MS` — const · src/machine/protocol.ts
+
+How far a request's clock may be from the server's. Laptops drift; five minutes is generous and still bounds a replay.
+
+```ts
+const MAX_SKEW_MS: number
+```
+
+#### `MAX_TIMEOUT_SECONDS` — const · src/machine/commands.ts
+
+The longest time limit a command may declare: seven days.
+
+```ts
+const MAX_TIMEOUT_SECONDS: number
+```
+
+#### `newAuthority` — function · src/machine/digest.ts
+
+What an app update asks of the owner. Removing a command, or leaving one untouched, needs nothing; ADDING a command or CHANGING one is new authority and waits for a fresh approval.
+
+```ts
+function newAuthority(approved: Record<string, string>, current: DeviceBlock): { added: string[]; changed: string[] }
+```
+
+#### `openWorkspace` — function · src/machine/shell.ts
+
+Open (or create) the workspace for a scope under the runtime's home.
+
+```ts
+function openWorkspace(home: string, id: string, scope: Scope): Workspace
+```
+
+#### `OUTPUT_LIMITS` — const · src/machine/commands.ts
+
+The ceilings of the output options: chunk 3 MB, stored head 8 MB, gather 60 s, tail 64 KB.
+
+```ts
+const OUTPUT_LIMITS: { readonly maxChunkKb: 3072; readonly maxKb: 8192; readonly flushMs: 60000; readonly tailChars: number; }
+```
+
+#### `OutputUploader` — class · src/machine/capabilities.ts
+
+Ordered, batched, retried upload of one job's output (the run directory is the outbox for detached runs; inline jobs hold theirs here). `finish` drains the output, then reports the end with the result.
+
+```ts
+class OutputUploader { … }
+```
+
+#### `parseGrant` — function · src/machine/grant.ts
+
+A grant from untrusted JSON, or null. Roots must be absolute and plain.
+
+```ts
+function parseGrant(v: unknown): WorkspaceGrant | null
+```
+
+#### `parseUnifiedDiff` — function · src/machine/files.ts
+
+The hunks of a unified diff (`@@ -a,b +c,d
+
+```ts
+function parseUnifiedDiff(diff: string): Hunk[]
+```
+
+#### `PROGRAM_KEY` — const · src/machine/digest.ts
+
+Where an approval records the program's digest, beside the commands' (no command name can start with "@").
+
+```ts
+const PROGRAM_KEY: "@program"
+```
+
+#### `PROGRAM_MAX_BYTES` — const · src/machine/commands.ts
+
+A program's files: at most this many bytes in all (setup steps download the heavy things).
+
+```ts
+const PROGRAM_MAX_BYTES: number
+```
+
+#### `PROGRAM_MAX_FILES` — const · src/machine/commands.ts
+
+A program's files: at most this many.
+
+```ts
+const PROGRAM_MAX_FILES: 200
+```
+
+#### `programCapability` — function · src/machine/capabilities.ts
+
+A message from the app to its program on this computer; the program's answer is the job's result.
+
+```ts
+function programCapability(programs: ProgramDelivery | null): Capability
+```
+
+#### `programDigest` — function · src/machine/digest.ts
+
+The digest of a program: its spec (without the computed fields) and every file, sorted by path. Two builds of the same files give the same digest.
+
+```ts
+function programDigest(spec: Omit<ProgramSpec, "digest" | "size">, files: { path: string; content: Buffer | Uint8Array | string }[]): string
+```
+
+#### `programEnv` — function · src/machine/program-manager.ts
+
+The environment an app's program and its setup steps get: scrubbed (the runtime's own settings never reach app code), the runtime's Node FIRST on PATH — on a computer whose only Node is the one the bootstrap brought (showrack), `node` in a setup step must be it — and HOME its own data folder, or the person's real home when the whole computer was granted (unconfined).
+
+```ts
+function programEnv(env: Record<string, string | undefined>, nodePath: string, dataDir: string, opts: { unconfined?: boolean } = {}): Record<string, string>
+```
+
+#### `programPaths` — function · src/machine/program-manager.ts
+
+Where an app's program lives in the runtime's folder: its version folder, its own data folder, setup markers and logs.
+
+```ts
+function programPaths(home: string, linkId: string, digest?: string)
+```
+
+#### `programProblems` — function · src/machine/commands.ts
+
+What is wrong with a program spec, in words (the platform's build adds `digest` and `size`).
+
+```ts
+function programProblems(p: unknown): string[]
+```
+
+#### `PROTOCOL` — const · src/machine/protocol.ts
+
+The protocol version, the first line of every signed request.
+
+```ts
+const PROTOCOL: "esoul-device/1"
+```
+
+#### `registry` — function · src/machine/capabilities.ts
+
+The capability table the runtime dispatches jobs through, by name.
+
+```ts
+function registry(caps: Capability[]): Map<string, Capability>
+```
+
+#### `renderCommand` — function · src/machine/commands.ts
+
+Render one declared command. Throws `DeviceCommandError` with a sentence for anything undeclared or ill-typed.
+
+```ts
+function renderCommand(block: DeviceBlock, name: string, params: Record<string, unknown> = {}): RenderedCommand
+```
+
+#### `resolveInScope` — function · src/machine/files.ts
+
+A path as the agent wrote it → an absolute path the scope allows. `cwd` is the agent's current directory (absolute, inside the scope). `~` means the home directory, and is allowed only when the scope contains it.
+
+```ts
+function resolveInScope(scope: Scope, cwd: string, p: string): string
+```
+
+#### `resolveOutput` — function · src/machine/commands.ts
+
+The spec's output choice with its defaults filled in — what the runtime and the door both use.
+
+```ts
+function resolveOutput(spec: OutputSpec | undefined): ResolvedOutput
+```
+
+#### `RUNTIME_CAPABILITIES` — const · src/machine/capabilities.ts
+
+What this runtime can do, said at CONNECT as well as in every hello, so the platform knows it from the approval on: work asked for before the runtime's first hello waits in the queue instead of being refused.
+
+```ts
+const RUNTIME_CAPABILITIES: string[]
+```
+
+#### `sandboxFor` — function · src/machine/shell.ts
+
+How `run` and `term` are confined. The computer scope runs processes as they are. A folder scope needs an OS sandbox — bubblewrap on Linux, Seatbelt on macOS — or processes are REFUSED (a path check cannot keep a shell in a folder; `cd ..` would do).
+
+```ts
+function sandboxFor(scope: Scope): Sandbox
+```
+
+#### `sha256Hex` — function · src/machine/protocol.ts
+
+Hex SHA-256 of a request body, as signed.
+
+```ts
+function sha256Hex(body: string | Uint8Array): string
+```
+
+#### `signRequest` — function · src/machine/protocol.ts
+
+Sign one request (method, path with query, body) now; returns the `x-esoul-ts` and `x-esoul-sig` header values.
+
+```ts
+function signRequest( privateKeyPem: string, method: string, pathAndQuery: string, body: string | Uint8Array, now: number = Date.now(), ): { ts: string; sig: string }
+```
+
+#### `startSupervisor` — function · src/machine/supervisor.ts
+
+The runtime: one per computer, for every connected app — hello, wake, claim, re-render and run, report, and the app's lifecycle.
+
+```ts
+function startSupervisor(opts: SupervisorOptions)
+```
+
+#### `tokenize` — function · src/machine/shell.ts
+
+Shell-like words: quotes ('…' literal, "…" with \" escapes), backslash escapes, whitespace separation.
+
+```ts
+function tokenize(line: string): string[]
+```
+
+#### `verifyRequest` — function · src/machine/protocol.ts
+
+Pure verification. `publicKey` comes from the platform's row for `x-esoul-key`, never from the request.
+
+```ts
+function verifyRequest(args: { publicKey: string; method: string; pathAndQuery: string; body: string | Uint8Array; ts: string | null | undefined; sig: string | null | undefined; now?: number; }): { ok: true } | { ok: false; reason: VerifyFailure }
+```
+
+#### `workspaceCapability` — function · src/machine/capabilities.ts
+
+The shared command line, under grant ∩ ceiling, one working directory per named agent.
+
+```ts
+function workspaceCapability(): Capability
+```
+
+### Types (40)
+
+#### `CallTiming` — interface · src/machine/client.ts
+
+```ts
+interface CallTiming {
+  method: string;
+  path: string;
+  status: number;
+  ms: number;
+  server: string | null;
+}
+```
+
+#### `Capability` — interface · src/machine/capabilities.ts
+
+```ts
+interface Capability {
+  name: string;
+  version: number;
+  refuse(job: Job, ctx: JobContext): string | null;
+  start(job: Job, ctx: JobContext): Promise<void>;
+}
+```
+
+#### `CommandSpec` — interface · src/machine/commands.ts
+
+```ts
+interface CommandSpec {
+  argv: string[];
+  params?: Record<string, ParamSpec>;
+  cwd?: string;
+  env?: Record<string, string>;
+  config?: string[];
+  timeoutSeconds?: number;
+  onRestart?: "report" | "rerun";
+  output?: OutputSpec;
+  result?: "text" | "json";
+  describe?: string;
+}
+```
+
+#### `ConfigKeySpec` — interface · src/machine/commands.ts
+
+```ts
+interface ConfigKeySpec {
+  secret?: boolean;
+  required?: boolean;
+  describe?: string;
+}
+```
+
+#### `ConnectOptions` — interface · src/machine/supervisor.ts
+
+```ts
+interface ConnectOptions {
+  url: string;
+  home?: string;
+  runtimeVersion: string;
+  fetch?: FetchLike;
+  pollMs?: number;
+  print?: (line: string) => void;
+  fingerprint?: string;
+  ceiling?: WorkspaceGrant | null;
+}
+```
+
+#### `ConnectResult` — interface · src/machine/supervisor.ts
+
+```ts
+interface ConnectResult {
+  machineId: string;
+  linkId: string | null;
+  base: string;
+  appName: string | null;
+}
+```
+
+#### `DeviceBlock` — interface · src/machine/commands.ts
+
+```ts
+interface DeviceBlock {
+  commands: Record<string, CommandSpec>;
+  program?: ProgramSpec;
+  config?: Record<string, ConfigKeySpec>;
+  redact?: string[];
+  onAppDeleted?: "kill" | "finish";
+}
+```
+
+#### `DeviceKeyPair` — interface · src/machine/protocol.ts
+
+```ts
+interface DeviceKeyPair {
+  publicKey: string;
+  privateKeyPem: string;
+}
+```
+
+#### `DoorClient` — interface · src/machine/client.ts
+
+```ts
+interface DoorClient {
+  call<T = Record<string, unknown>>(method: "GET" | "POST", path: string, body?: unknown, opts?: { timeoutMs?: number; tries?: number }): Promise<T>;
+  base: string;
+}
+```
+
+#### `Edit` — interface · src/machine/files.ts
+
+```ts
+interface Edit {
+  find: string;
+  replace: string;
+  all?: boolean;
+}
+```
+
+#### `FetchLike` — type · src/machine/client.ts
+
+```ts
+type FetchLike = (input: string, init: { method: string; headers: Record<string, string>; body?: string; signal?: AbortSignal }) => Promise<{ status: number; text(): Promise<string>; headers?: { get(name: string): string | null } }>;
+```
+
+#### `HunkResult` — interface · src/machine/files.ts
+
+```ts
+interface HunkResult {
+  hunk: number;
+  applied: boolean;
+  at?: number;
+  offset?: number;
+  reason?: string;
+}
+```
+
+#### `Job` — interface · src/machine/capabilities.ts
+
+```ts
+interface Job extends ClaimedCommand {
+  capability: string;
+  agent: string | null;
+}
+```
+
+#### `JobContext` — interface · src/machine/capabilities.ts
+
+```ts
+interface JobContext {
+  home: string;
+  link: LocalLink;
+  ceiling: WorkspaceGrant | null;
+  client: DoorClient;
+  signal: AbortSignal;
+  log: (s: string) => void;
+}
+```
+
+#### `JobOutcome` — interface · src/machine/capabilities.ts
+
+```ts
+interface JobOutcome {
+  exitCode: number | null;
+  reason?: string | null;
+  signal?: string | null;
+  result?: unknown;
+}
+```
+
+#### `JournalEntry` — interface · src/machine/files.ts
+
+```ts
+interface JournalEntry {
+  opId: string;
+  at: number;
+  agent: string;
+  op: "write" | "edit" | "patch" | "rm" | "mv" | "mkdir" | "undo";
+  path: string;
+  to?: string;
+  before: string | null;
+  after: string | null;
+  dirSnapshot?: string;
+}
+```
+
+#### `LocalLink` — interface · src/machine/state.ts
+
+```ts
+interface LocalLink {
+  linkId: string;
+  nodeId: string;
+  workspaceId: string;
+  pluginId: string;
+  appName: string | null;
+  status: "active" | "suspended" | "revoked";
+  reason: string | null;
+  commands: DeviceBlock | null;
+  grants?: Record<string, unknown> | null;
+}
+```
+
+#### `LocalState` — interface · src/machine/state.ts
+
+```ts
+interface LocalState {
+  base: string;
+  machineId: string;
+  links: Record<string, LocalLink>;
+  ceiling?: { scope: "folder"; root: string } | { scope: "computer" } | null;
+}
+```
+
+#### `MachineShellResult` — interface · src/machine/shell.ts
+
+```ts
+interface ShellResult {
+  ok: boolean;
+  text: string;
+  data?: unknown;
+  exitCode?: number | null;
+  error?: string;
+  opId?: string;
+  cwd: string;
+}
+```
+
+#### `OutputSpec` — interface · src/machine/commands.ts
+
+The delivery tradeoff, chosen per command (esoul-sdk docs/18 §4):
+
+```ts
+interface OutputSpec {
+  mode?: "live" | "batched" | "final";
+  flushMs?: number;
+  maxChunkKb?: number;
+  keep?: "head" | "tail" | "both";
+  maxKb?: number;
+}
+```
+
+#### `ParamSpec` — type · src/machine/commands.ts
+
+DECLARED COMMANDS — the wall between an app and the person's computer.
+
+```ts
+type ParamSpec =
+  | "int"
+  | "number"
+  | "bool"
+  | "string"
+  | { type: "int" | "number"; min?: number; max?: number; describe?: string }
+  | { type: "string"; pattern?: string; maxLength?: number; allowDash?: boolean; describe?: string }
+  | { type: "enum"; values: string[]; describe?: string }
+  | { type: "bool"; describe?: string };
+```
+
+#### `Program` — interface · src/machine/program-api.ts
+
+An app's program: `start` is called once per process; `stop` before the process ends, when it ends cleanly.
+
+```ts
+interface Program {
+  start(p: ProgramApi): void | Promise<void>;
+  stop?(): void | Promise<void>;
+}
+```
+
+#### `ProgramApi` — interface · src/machine/program-api.ts
+
+The program's handle on the computer and on its app.
+
+```ts
+interface ProgramApi {
+  readonly computer: { readonly hostname: string; readonly platform: string; readonly arch: string; readonly cpus: number; readonly memoryGb: number };
+  readonly appName: string | null;
+  readonly programDir: string;
+  readonly dataDir: string;
+  readonly workspaceRoot: string | null;
+  readonly config: Readonly<Record<string, string>>;
+  status(text: string, extra?: { progress?: number; ready?: boolean }): void;
+  op<T = unknown>(name: string, args?: unknown, opts?: { key?: string }): Promise<T>;
+  on(topic: string, handler: (data: unknown) => unknown | Promise<unknown>): void;
+  every(ms: number, fn: () => unknown | Promise<unknown>): () => void;
+  log(...args: unknown[]): void;
+}
+```
+
+#### `ProgramDelivery` — interface · src/machine/capabilities.ts
+
+The part of the program manager a message job needs (program-manager.ts).
+
+```ts
+interface ProgramDelivery {
+  has(linkId: string): boolean;
+  deliver(linkId: string, topic: string, data: unknown, signal?: AbortSignal): Promise<{ ok: boolean; result?: unknown; error?: string }>;
+}
+```
+
+#### `ProgramManager` — type · src/machine/program-manager.ts
+
+The program manager's handle (see createProgramManager).
+
+```ts
+type ProgramManager = ReturnType<typeof createProgramManager>;
+```
+
+#### `ProgramManagerOptions` — interface · src/machine/program-manager.ts
+
+What the program manager needs from the runtime.
+
+```ts
+interface ProgramManagerOptions {
+  home: string;
+  client: DoorClient;
+  hostScript: string;
+  nodePath?: string;
+  log: (line: string) => void;
+  ceiling: () => WorkspaceGrant | null;
+  sandbox?: Sandbox;
+}
+```
+
+#### `ProgramSpec` — interface · src/machine/commands.ts
+
+The app's own program on the computer (`computer-apps.md` §4.1): the files of `device/` shipped per app version, set up once, then started — at approval when `resident`, or when the app first sends it a message.
+
+```ts
+interface ProgramSpec {
+  main: string;
+  resident?: boolean;
+  setup?: SetupStepSpec[];
+  selfTest?: { run: string[]; timeoutSeconds?: number };
+  digest?: string;
+  size?: number;
+}
+```
+
+#### `ProgramState` — interface · src/machine/program-api.ts
+
+Where an app's program stands on one computer — what the runtime reports and the app's Computers card renders. `phase` moves forward installing → setup → self-test → running (or ready, for a program started by its first message); `failed` and `refused` say why in `error`.
+
+```ts
+interface ProgramState {
+  digest: string;
+  phase: "installing" | "setup" | "self-test" | "ready" | "starting" | "running" | "stopped" | "failed" | "refused";
+  steps: ProgramStepState[];
+  status?: { text: string; progress?: number; ready?: boolean; at: number } | null;
+  error?: string | null;
+  logTail?: string[];
+  restarts: number;
+  updatedAt: number;
+}
+```
+
+#### `ProgramStepState` — interface · src/machine/program-api.ts
+
+One setup step, as the Computers card shows it.
+
+```ts
+interface ProgramStepState {
+  id: string;
+  describe: string;
+  state: "pending" | "running" | "done" | "cached" | "failed";
+  startedAt?: number;
+  endedAt?: number;
+  detail?: string;
+}
+```
+
+#### `RenderedCommand` — interface · src/machine/commands.ts
+
+```ts
+interface RenderedCommand {
+  name: string;
+  argv: string[];
+  cwd?: string;
+  env: Record<string, string>;
+  config: string[];
+  timeoutSeconds: number;
+  onRestart: "report" | "rerun";
+}
+```
+
+#### `ResolvedOutput` — interface · src/machine/commands.ts
+
+```ts
+interface ResolvedOutput {
+  mode: "live" | "batched" | "final";
+  flushMs: number;
+  maxChunkBytes: number;
+  headMaxBytes: number;
+  tailMaxChars: number;
+}
+```
+
+#### `Sandbox` — type · src/machine/shell.ts
+
+```ts
+type Sandbox = { kind: "none" } | { kind: "bwrap"; bin: string } | { kind: "seatbelt" } | { kind: "unavailable"; why: string };
+```
+
+#### `Scope` — type · src/machine/files.ts
+
+```ts
+type Scope = { kind: "folder"; root: string } | { kind: "computer" };
+```
+
+#### `SetupStepSpec` — interface · src/machine/commands.ts
+
+One setup step of a program: argv (never a shell line), run once per program digest and declared inputs.
+
+```ts
+interface SetupStepSpec {
+  id: string;
+  describe: string;
+  run: string[];
+  inputs?: string[];
+  timeoutSeconds?: number;
+}
+```
+
+#### `ShellCall` — interface · src/machine/shell.ts
+
+```ts
+interface ShellCall {
+  ws: Workspace;
+  agent: string;
+  line: string;
+  stdin?: string;
+  onOutput?: (chunk: string) => void;
+  signal?: AbortSignal;
+}
+```
+
+#### `SupervisorOptions` — interface · src/machine/supervisor.ts
+
+```ts
+interface SupervisorOptions {
+  home?: string;
+  runtimeVersion: string;
+  execScript: string;
+  nodePath?: string;
+  fetch?: FetchLike;
+  wake?: boolean;
+  pollSeconds?: number;
+  flushMs?: number;
+  helloEveryMs?: number;
+  log?: (line: string) => void;
+  onEmpty?: (why: string) => void | Promise<void>;
+}
+```
+
+#### `VerifyFailure` — type · src/machine/protocol.ts
+
+```ts
+type VerifyFailure = "missing" | "bad_key" | "skew" | "bad_signature";
+```
+
+#### `Workspace` — interface · src/machine/shell.ts
+
+```ts
+interface Workspace {
+  id: string;
+  scope: Scope;
+  journal: Journal;
+  stateDir: string;
+  sandbox: Sandbox;
+}
+```
+
+#### `WorkspaceChoice` — type · src/machine/grant.ts
+
+```ts
+type WorkspaceChoice = "none" | "folder" | "computer";
+```
+
+#### `WorkspaceGrant` — type · src/machine/grant.ts
+
+WORKSPACE GRANTS (plugin-device-arm.md §15): what an app's agents may reach on a computer through the shared command line — one FOLDER, or the whole COMPUTER. Two parties must agree:
+
+```ts
+type WorkspaceGrant = { scope: "folder"; root: string } | { scope: "computer" };
+```