esoul-sdk 0.16.0 → 0.18.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.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"; }>>; 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, { 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"; }>; config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; redact?: string[]; onAppDeleted?: "kill" | "finish"; }, { 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"; }>; config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; redact?: string[]; onAppDeleted?: "kill" | "finish"; }>, { 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"; }>; config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; redact?: string[]; onAppDeleted?: "kill" | "finish"; }, { 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"; }>; config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; 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?: { 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"; }>; config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; 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?: { 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"; }>; config?: Record<string, { required?: boolean; describe?: string; secret?: boolean; }>; 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,17 @@ interface DerivedTool extends ApplicationTools {
 }
 ```
 
+#### `DeviceBlock` — interface · src/machine/commands.ts
+
+```ts
+interface DeviceBlock {
+  commands: Record<string, CommandSpec>;
+  config?: Record<string, ConfigKeySpec>;
+  redact?: string[];
+  onAppDeleted?: "kill" | "finish";
+}
+```
+
 #### `EventData` — interface · src/types.ts
 
 ```ts
@@ -1635,6 +1721,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 +1835,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 +1926,11 @@ interface UsesDecl {
 ```
 
 ==============================================================================
-## `esoul-sdk/server` — 67 exports
+## `esoul-sdk/server` — 77 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 +1964,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 +2164,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 (48)
 
 #### `AppRolePerson` — interface · src/server.ts
 
@@ -2263,6 +2395,94 @@ 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
+
+Types for `devices(ctx)` — parts of an app that run on the person's own computer (plugin-device-arm.md §10–§11). The functions live in server.ts (host-only); the hooks and <ConnectComputer/> in react.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 }>;
+}
+```
+
+#### `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;
+}
+```
+
 #### `EmitPluginAppEventArgs` — interface · src/server.ts
 
 ```ts
@@ -2561,6 +2781,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 +2818,44 @@ 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` — 46 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 (22)
+### 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
+
+Words and retryability for a thrown request: `PluginCallError` carries status + code; a fetch that never reached the server throws a TypeError.
+
+```ts
+function describeFailure(error: unknown): { why: string; retryable: boolean }
+```
+
+#### `dismissFailedRequest` — function · src/failed-requests.ts
+
+Take a request off the banner — it landed after all, or the person dismissed it.
+
+```ts
+function dismissFailedRequest(key: string): void
+```
 
 #### `FilesBrowseError` — class · src/react.ts
 
@@ -2605,6 +2873,14 @@ A polygon labeller for one image — the Explorer's mask editor as a component:
 function ImageLabeler(_props: ImageLabelerProps): any
 ```
 
+#### `isRetryableFailure` — function · src/failed-requests.ts
+
+Is this failure worth a Try again? A lost connection, a timeout, a server error or a rate limit — yes. A refusal (the server read the request and said no, with a reason) — retrying sends the same no; the app shows the reason instead.
+
+```ts
+function isRetryableFailure(r: { reason?: string; status?: number }): boolean
+```
+
 #### `listFileEntries` — function · src/react.ts
 
 One page of a folder, as a plain call (no hook).
@@ -2629,6 +2905,14 @@ Folders matching what is being typed: names that START with it, then names that
 function rankFolderSuggestions(entries: FileEntry[], partial: string, limit = 50): FileEntry[]
 ```
 
+#### `reportFailedRequest` — function · src/failed-requests.ts
+
+Report a request that failed after the screen already showed it; the banner names it (and offers Try again when `retry` is given). The same `key` replaces, never stacks.
+
+```ts
+function reportFailedRequest(r: Omit<FailedRequest, "at" | "retrying"> & { at?: number }): void
+```
+
 #### `resolveFilePath` — function · src/react.ts
 
 Walk "a/b/c" from the source's root by exact names, as a plain call.
@@ -2637,6 +2921,14 @@ Walk "a/b/c" from the source's root by exact names, as a plain call.
 function resolveFilePath(_workspaceId: string, _sourceId: string, _path: string): Promise<ResolvedFilePath>
 ```
 
+#### `runOptimistic` — function · src/failed-requests.ts
+
+The optimistic-UI rule in one call. `apply` puts the result on screen at once; `send` does the work; on success any earlier failure of the same `key` clears. On failure `revert` puts the screen back and the request is reported: a connection loss, timeout or server error gets Try again (which runs the whole thing again, apply included), a refusal shows its reason only — retrying would send the same no.
+
+```ts
+async function runOptimistic<T>(r: { key: string; what: string; apply?: () => void; revert?: () => void; send: () => Promise<T>; }): Promise<{ ok: true; result: T } | { ok: false; error: unknown }>
+```
+
 #### `splitTypedPath` — function · src/react.ts
 
 "sheets/quality/Ty" → `{ parentPath: "sheets/quality", partial: "Ty" }`; a trailing "/" means "inside it". Pure.
@@ -2653,6 +2945,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.
@@ -2685,6 +3001,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.
@@ -2765,7 +3089,88 @@ Invoke tools of OTHER apps in the workspace (append a spreadsheet row, add a cal
 function useWorkspaceTools(_identity: { workspaceId: string; nodeId: string }): WorkspaceTools
 ```
 
-### Types (24)
+#### `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;
+}
+```
+
+#### `FailedRequest` — interface · src/failed-requests.ts
+
+The platform's list of requests that failed after the UI already showed their result (the optimistic-UI rule, app-style-guide.md "Interaction"): an app updates the screen at once, and when the request behind it fails the app puts the screen back and reports here — `<FailedRequestBanner/>` then names the request and offers Try again, in the same place and style as the "new version is available" pill. Pure and framework-free, so any app (built-in or Forge) and any test can use it. A Forge app imports it from `esoul-sdk/react`; the platform's `src/lib/failed-requests.ts` re-exports this very module, so both reach one list.
+
+```ts
+interface FailedRequest {
+  key: string;
+  what: string;
+  why?: string;
+  retry?: () => Promise<boolean> | boolean;
+  at: number;
+  retrying?: boolean;
+}
+```
 
 #### `FileEntriesState` — interface · src/react.ts
 
@@ -2868,6 +3273,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
@@ -3013,6 +3435,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
@@ -3036,6 +3474,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
@@ -3289,3 +3735,774 @@ interface TestManifest {
 ```ts
 type ViewerKind = RuleViewer["kind"];
 ```
+
+==============================================================================
+## `esoul-sdk/machine` — 82 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 (51)
+
+#### `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[] }
+```
+
+#### `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>): 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 — 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
+```
+
+#### `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
+```
+
+#### `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[]
+```
+
+#### `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 (31)
+
+#### `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>;
+  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 };
+```
+
+#### `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" };
+```
+
+#### `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" };
+```