@immediately-run/sdk 0.57.1 → 0.57.4

package/dist/onFsChange.d.ts

@@ -1,3 +1,10 @@
+/** One server-side change in a mount batch: the path (mount-relative, leading
+ *  slash) and its kind — the Node `watch` event mapping is `add`/`remove` →
+ *  `rename`, `change` → `change`. (R3-409.) */
+interface MountChange {
+    path: string;
+    kind: 'add' | 'change' | 'remove';
+}
 /** One working-tree change batch the host pushes: the changed paths plus an epoch. */
 interface FsChange {
     /** Repo-relative paths (leading slash, e.g. `/src/App.tsx`) that just changed. */
@@ -8,6 +15,19 @@ interface FsChange {
      * deduplicated away). `0` is the pre-first-event initial.
      */
     epoch: number;
+    /**
+     * R3-409 — a SPACE mount's server-side change batch (another tab's/member's
+     * writes), anchored at the mount path the frame holds. The `fs.watch` events
+     * themselves are delivered by the sandbox's fs shim (no SDK surface needed);
+     * this field is DECLARED so the wire shape has one written-down type on this
+     * side too (the R3-274e lesson), and so an SDK consumer that wants the raw
+     * per-mount batches can read them. Absent on the working-tree leg.
+     */
+    mount?: {
+        /** The sandbox mount root the `changes[].path`s are relative to (e.g. `/mnt/{hash}`). */
+        path: string;
+        changes: MountChange[];
+    };
 }
 /** The most recent working-tree change batch (the empty initial until the first). */
 declare const getFsChange: () => FsChange;
@@ -20,4 +40,4 @@ declare const onFsChange: (listener: (change: FsChange) => void) => (() => void)
 /** React hook: the current working-tree change batch, re-rendering on every push. */
 declare const useFsChange: () => FsChange;
 
-export { type FsChange, getFsChange, onFsChange, useFsChange };
+export { type FsChange, type MountChange, getFsChange, onFsChange, useFsChange };

package/dist/onFsChange.js

@@ -2,10 +2,22 @@ import "./chunk-VHAA22YE.js";
 import { createPushChannel } from "./pushChannel";
 import { FS_CHANGE } from "./generated/protocol";
 const isStringArray = (v) => Array.isArray(v) && v.every((p) => typeof p === "string");
+const isMountBatch = (v) => {
+  if (typeof v !== "object" || v === null) return false;
+  const m = v;
+  if (typeof m.path !== "string" || !Array.isArray(m.changes)) return false;
+  return m.changes.every(
+    (c) => typeof c === "object" && c !== null && typeof c.path === "string" && ["add", "change", "remove"].includes(c.kind)
+  );
+};
 const channel = createPushChannel({
   pushType: FS_CHANGE,
   initial: { paths: [], epoch: 0 },
-  parse: (msg) => isStringArray(msg.paths) && typeof msg.epoch === "number" ? { paths: msg.paths, epoch: msg.epoch } : void 0
+  parse: (msg) => isStringArray(msg.paths) && typeof msg.epoch === "number" ? {
+    paths: msg.paths,
+    epoch: msg.epoch,
+    ...isMountBatch(msg.mount) ? { mount: msg.mount } : {}
+  } : void 0
 });
 const getFsChange = () => channel.get();
 const onFsChange = (listener) => channel.onChange(listener);

package/dist/onFsChange.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/onFsChange.ts"],"sourcesContent":["// Working-tree change stream (EDITOR_AS_APP_SPEC §4.2). The host pushes the\n// repo-relative paths that just changed in the working tree — from ANY writer: an\n// agent's port write, a host `editor:write` action (create/delete/rename), or the\n// preview's own copy-on-write. A working-tree observer (the editor app, the file\n// explorer) reacts by re-reading the affected files instead of polling.\n//\n// Elevated `editor:read` — a previewed app holds no `editor:read`, so it never sees\n// the stream (the host channel ACL withholds it). Push-only: there is no past-event\n// state worth polling, so the empty initial stands until the first write.\n//\n// Origin-exclusion is the CONSUMER's responsibility: the editor must ignore the\n// echo of its OWN write (a debounced write lags the buffer, so re-reading it as\n// \"external\" would surface a false conflict). Compare the changed file's bytes to\n// what you last wrote; if they match, it is your echo, not an external change.\nimport { createPushChannel } from './pushChannel';\nimport { FS_CHANGE } from './generated/protocol';\n\n/** One working-tree change batch the host pushes: the changed paths plus an epoch. */\nexport interface FsChange {\n  /** Repo-relative paths (leading slash, e.g. `/src/App.tsx`) that just changed. */\n  paths: string[];\n  /**\n   * Monotonic batch id — bumps on every change even if the path set repeats, so a\n   * subscriber re-fires for a second edit to the same file (the value is never\n   * deduplicated away). `0` is the pre-first-event initial.\n   */\n  epoch: number;\n}\n\nconst isStringArray = (v: unknown): v is string[] => Array.isArray(v) && v.every((p) => typeof p === 'string');\n\nconst channel = createPushChannel<FsChange>({\n  pushType: FS_CHANGE,\n  initial: { paths: [], epoch: 0 },\n  parse: (msg) =>\n    isStringArray(msg.paths) && typeof msg.epoch === 'number' ? { paths: msg.paths, epoch: msg.epoch } : undefined,\n});\n\n/** The most recent working-tree change batch (the empty initial until the first). */\nexport const getFsChange = (): FsChange => channel.get();\n\n/**\n * Subscribe to working-tree changes. The listener fires immediately with the\n * current batch, then on every host push. Returns an unsubscribe fn. The common\n * use: re-read an open file when its path appears in `change.paths`.\n */\nexport const onFsChange = (listener: (change: FsChange) => void): (() => void) => channel.onChange(listener);\n\n/** React hook: the current working-tree change batch, re-rendering on every push. */\nexport const useFsChange = (): FsChange => channel.use();\n"],"mappings":";AAcA,SAAS,yBAAyB;AAClC,SAAS,iBAAiB;AAc1B,MAAM,gBAAgB,CAAC,MAA8B,MAAM,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ;AAE7G,MAAM,UAAU,kBAA4B;AAAA,EAC1C,UAAU;AAAA,EACV,SAAS,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE;AAAA,EAC/B,OAAO,CAAC,QACN,cAAc,IAAI,KAAK,KAAK,OAAO,IAAI,UAAU,WAAW,EAAE,OAAO,IAAI,OAAO,OAAO,IAAI,MAAM,IAAI;AACzG,CAAC;AAGM,MAAM,cAAc,MAAgB,QAAQ,IAAI;AAOhD,MAAM,aAAa,CAAC,aAAuD,QAAQ,SAAS,QAAQ;AAGpG,MAAM,cAAc,MAAgB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/onFsChange.ts"],"sourcesContent":["// Working-tree change stream (EDITOR_AS_APP_SPEC §4.2). The host pushes the\n// repo-relative paths that just changed in the working tree — from ANY writer: an\n// agent's port write, a host `editor:write` action (create/delete/rename), or the\n// preview's own copy-on-write. A working-tree observer (the editor app, the file\n// explorer) reacts by re-reading the affected files instead of polling.\n//\n// Elevated `editor:read` — a previewed app holds no `editor:read`, so it never sees\n// the stream (the host channel ACL withholds it). Push-only: there is no past-event\n// state worth polling, so the empty initial stands until the first write.\n//\n// Origin-exclusion is the CONSUMER's responsibility: the editor must ignore the\n// echo of its OWN write (a debounced write lags the buffer, so re-reading it as\n// \"external\" would surface a false conflict). Compare the changed file's bytes to\n// what you last wrote; if they match, it is your echo, not an external change.\nimport { createPushChannel } from './pushChannel';\nimport { FS_CHANGE } from './generated/protocol';\n\n/** One server-side change in a mount batch: the path (mount-relative, leading\n *  slash) and its kind — the Node `watch` event mapping is `add`/`remove` →\n *  `rename`, `change` → `change`. (R3-409.) */\nexport interface MountChange {\n  path: string;\n  kind: 'add' | 'change' | 'remove';\n}\n\n/** One working-tree change batch the host pushes: the changed paths plus an epoch. */\nexport interface FsChange {\n  /** Repo-relative paths (leading slash, e.g. `/src/App.tsx`) that just changed. */\n  paths: string[];\n  /**\n   * Monotonic batch id — bumps on every change even if the path set repeats, so a\n   * subscriber re-fires for a second edit to the same file (the value is never\n   * deduplicated away). `0` is the pre-first-event initial.\n   */\n  epoch: number;\n  /**\n   * R3-409 — a SPACE mount's server-side change batch (another tab's/member's\n   * writes), anchored at the mount path the frame holds. The `fs.watch` events\n   * themselves are delivered by the sandbox's fs shim (no SDK surface needed);\n   * this field is DECLARED so the wire shape has one written-down type on this\n   * side too (the R3-274e lesson), and so an SDK consumer that wants the raw\n   * per-mount batches can read them. Absent on the working-tree leg.\n   */\n  mount?: {\n    /** The sandbox mount root the `changes[].path`s are relative to (e.g. `/mnt/{hash}`). */\n    path: string;\n    changes: MountChange[];\n  };\n}\n\nconst isStringArray = (v: unknown): v is string[] => Array.isArray(v) && v.every((p) => typeof p === 'string');\n\nconst isMountBatch = (v: unknown): v is FsChange['mount'] => {\n  if (typeof v !== 'object' || v === null) return false;\n  const m = v as { path?: unknown; changes?: unknown };\n  if (typeof m.path !== 'string' || !Array.isArray(m.changes)) return false;\n  return m.changes.every(\n    (c) =>\n      typeof c === 'object' &&\n      c !== null &&\n      typeof (c as { path?: unknown }).path === 'string' &&\n      ['add', 'change', 'remove'].includes((c as { kind?: unknown }).kind as string),\n  );\n};\n\nconst channel = createPushChannel<FsChange>({\n  pushType: FS_CHANGE,\n  initial: { paths: [], epoch: 0 },\n  parse: (msg) =>\n    isStringArray(msg.paths) && typeof msg.epoch === 'number'\n      ? {\n          paths: msg.paths,\n          epoch: msg.epoch,\n          ...(isMountBatch(msg.mount) ? { mount: msg.mount } : {}),\n        }\n      : undefined,\n});\n\n/** The most recent working-tree change batch (the empty initial until the first). */\nexport const getFsChange = (): FsChange => channel.get();\n\n/**\n * Subscribe to working-tree changes. The listener fires immediately with the\n * current batch, then on every host push. Returns an unsubscribe fn. The common\n * use: re-read an open file when its path appears in `change.paths`.\n */\nexport const onFsChange = (listener: (change: FsChange) => void): (() => void) => channel.onChange(listener);\n\n/** React hook: the current working-tree change batch, re-rendering on every push. */\nexport const useFsChange = (): FsChange => channel.use();\n"],"mappings":";AAcA,SAAS,yBAAyB;AAClC,SAAS,iBAAiB;AAmC1B,MAAM,gBAAgB,CAAC,MAA8B,MAAM,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ;AAE7G,MAAM,eAAe,CAAC,MAAuC;AAC3D,MAAI,OAAO,MAAM,YAAY,MAAM,KAAM,QAAO;AAChD,QAAM,IAAI;AACV,MAAI,OAAO,EAAE,SAAS,YAAY,CAAC,MAAM,QAAQ,EAAE,OAAO,EAAG,QAAO;AACpE,SAAO,EAAE,QAAQ;AAAA,IACf,CAAC,MACC,OAAO,MAAM,YACb,MAAM,QACN,OAAQ,EAAyB,SAAS,YAC1C,CAAC,OAAO,UAAU,QAAQ,EAAE,SAAU,EAAyB,IAAc;AAAA,EACjF;AACF;AAEA,MAAM,UAAU,kBAA4B;AAAA,EAC1C,UAAU;AAAA,EACV,SAAS,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE;AAAA,EAC/B,OAAO,CAAC,QACN,cAAc,IAAI,KAAK,KAAK,OAAO,IAAI,UAAU,WAC7C;AAAA,IACE,OAAO,IAAI;AAAA,IACX,OAAO,IAAI;AAAA,IACX,GAAI,aAAa,IAAI,KAAK,IAAI,EAAE,OAAO,IAAI,MAAM,IAAI,CAAC;AAAA,EACxD,IACA;AACR,CAAC;AAGM,MAAM,cAAc,MAAgB,QAAQ,IAAI;AAOhD,MAAM,aAAa,CAAC,aAAuD,QAAQ,SAAS,QAAQ;AAGpG,MAAM,cAAc,MAAgB,QAAQ,IAAI;","names":[]}

package/dist/protocolSchemes.cjs

@@ -34,6 +34,7 @@ const SCHEMES = {
   [import_protocol.PROTOCOL_IPC]: schemeOf(import_protocol.PROTOCOL_IPC),
   [import_protocol.PROTOCOL_LAUNCH]: schemeOf(import_protocol.PROTOCOL_LAUNCH),
   [import_protocol.PROTOCOL_LLM]: schemeOf(import_protocol.PROTOCOL_LLM),
+  [import_protocol.PROTOCOL_RECENTS]: schemeOf(import_protocol.PROTOCOL_RECENTS),
   [import_protocol.PROTOCOL_SECRETS]: schemeOf(import_protocol.PROTOCOL_SECRETS),
   [import_protocol.PROTOCOL_SETTINGS]: schemeOf(import_protocol.PROTOCOL_SETTINGS),
   [import_protocol.PROTOCOL_SPACES]: schemeOf(import_protocol.PROTOCOL_SPACES),

package/dist/protocolSchemes.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocolSchemes.ts"],"sourcesContent":["// The `protocol-<scheme>` SCHEMES, derived from the wire names.\n//\n// `protocolRequest(scheme, method, params)` takes the scheme — `'theme'` — while the\n// wire name the frame dispatches on is `'protocol-theme'`; the frame adds the prefix.\n// So the typed service wrappers cannot pass the published `PROTOCOL_*` constant\n// directly, and spelling the scheme inline would put a second, unguarded copy of the\n// name back in the tree — exactly what R3-274c removes.\n//\n// Instead the schemes are *derived* from the wire names, keyed BY the wire name:\n//\n//   protocolRequest(SCHEMES[PROTOCOL_THEME], 'set', [{ theme }])\n//\n// Keying by the constant is what makes the derivation unfalsifiable — there is no\n// second place to name the family, so there is no pair to get wrong. `schemeOf`\n// returns a template-literal conditional, so each value has a literal type (`'theme'`),\n// which buys two more things:\n//\n//   - a wire name that stops matching `protocol-*` stops compiling here, rather than\n//     silently producing an empty scheme at runtime;\n//   - `check-protocol-snapshot.mjs` resolves `SCHEMES[PROTOCOL_THEME]` through the type\n//     checker exactly like a plain literal, so the call sites stay visible to the gate.\n//\n// One export, deliberately: `./*` is a public subpath, so every name added here is\n// public API forever (ways_of_working §6, additive-only).\n//\n// This module is NOT generated — the derivation is the content — so it lives outside\n// `src/generated/`.\nimport {\n  PROTOCOL_ANALYTICS,\n  PROTOCOL_CONTRIBUTE,\n  PROTOCOL_DND,\n  PROTOCOL_EDITOR,\n  PROTOCOL_FEED,\n  PROTOCOL_FETCH,\n  PROTOCOL_IPC,\n  PROTOCOL_LAUNCH,\n  PROTOCOL_LLM,\n  PROTOCOL_SECRETS,\n  PROTOCOL_SETTINGS,\n  PROTOCOL_SPACES,\n  PROTOCOL_TASK,\n  PROTOCOL_THEME,\n  PROTOCOL_VCS,\n} from './generated/protocol';\n\nconst PREFIX = 'protocol-';\n\n/** The scheme half of a `protocol-<scheme>` wire name. */\ntype SchemeOf<N extends string> = N extends `${typeof PREFIX}${infer S}` ? S : never;\n\n/**\n * `'protocol-theme'` → `'theme'`, as a literal type.\n *\n * The cast is the only place the derivation is asserted rather than computed; the\n * `N extends \\`protocol-${string}\\`` bound is what makes it sound — a wire name that is\n * not scheme-shaped is a compile error at the call, not a `never` at runtime.\n */\nconst schemeOf = <N extends `${typeof PREFIX}${string}`>(name: N): SchemeOf<N> =>\n  name.slice(PREFIX.length) as SchemeOf<N>;\n\n/** Every `protocol-*` scheme the SDK speaks, keyed by its wire name. */\nexport const SCHEMES = {\n  [PROTOCOL_ANALYTICS]: schemeOf(PROTOCOL_ANALYTICS),\n  [PROTOCOL_CONTRIBUTE]: schemeOf(PROTOCOL_CONTRIBUTE),\n  [PROTOCOL_DND]: schemeOf(PROTOCOL_DND),\n  [PROTOCOL_EDITOR]: schemeOf(PROTOCOL_EDITOR),\n  [PROTOCOL_FEED]: schemeOf(PROTOCOL_FEED),\n  [PROTOCOL_FETCH]: schemeOf(PROTOCOL_FETCH),\n  [PROTOCOL_IPC]: schemeOf(PROTOCOL_IPC),\n  [PROTOCOL_LAUNCH]: schemeOf(PROTOCOL_LAUNCH),\n  [PROTOCOL_LLM]: schemeOf(PROTOCOL_LLM),\n  [PROTOCOL_SECRETS]: schemeOf(PROTOCOL_SECRETS),\n  [PROTOCOL_SETTINGS]: schemeOf(PROTOCOL_SETTINGS),\n  [PROTOCOL_SPACES]: schemeOf(PROTOCOL_SPACES),\n  [PROTOCOL_TASK]: schemeOf(PROTOCOL_TASK),\n  [PROTOCOL_THEME]: schemeOf(PROTOCOL_THEME),\n  [PROTOCOL_VCS]: schemeOf(PROTOCOL_VCS),\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BA,sBAgBO;AAEP,MAAM,SAAS;AAYf,MAAM,WAAW,CAAwC,SACvD,KAAK,MAAM,OAAO,MAAM;AAGnB,MAAM,UAAU;AAAA,EACrB,CAAC,kCAAkB,GAAG,SAAS,kCAAkB;AAAA,EACjD,CAAC,mCAAmB,GAAG,SAAS,mCAAmB;AAAA,EACnD,CAAC,4BAAY,GAAG,SAAS,4BAAY;AAAA,EACrC,CAAC,+BAAe,GAAG,SAAS,+BAAe;AAAA,EAC3C,CAAC,6BAAa,GAAG,SAAS,6BAAa;AAAA,EACvC,CAAC,8BAAc,GAAG,SAAS,8BAAc;AAAA,EACzC,CAAC,4BAAY,GAAG,SAAS,4BAAY;AAAA,EACrC,CAAC,+BAAe,GAAG,SAAS,+BAAe;AAAA,EAC3C,CAAC,4BAAY,GAAG,SAAS,4BAAY;AAAA,EACrC,CAAC,gCAAgB,GAAG,SAAS,gCAAgB;AAAA,EAC7C,CAAC,iCAAiB,GAAG,SAAS,iCAAiB;AAAA,EAC/C,CAAC,+BAAe,GAAG,SAAS,+BAAe;AAAA,EAC3C,CAAC,6BAAa,GAAG,SAAS,6BAAa;AAAA,EACvC,CAAC,8BAAc,GAAG,SAAS,8BAAc;AAAA,EACzC,CAAC,4BAAY,GAAG,SAAS,4BAAY;AACvC;","names":[]}
+{"version":3,"sources":["../src/protocolSchemes.ts"],"sourcesContent":["// The `protocol-<scheme>` SCHEMES, derived from the wire names.\n//\n// `protocolRequest(scheme, method, params)` takes the scheme — `'theme'` — while the\n// wire name the frame dispatches on is `'protocol-theme'`; the frame adds the prefix.\n// So the typed service wrappers cannot pass the published `PROTOCOL_*` constant\n// directly, and spelling the scheme inline would put a second, unguarded copy of the\n// name back in the tree — exactly what R3-274c removes.\n//\n// Instead the schemes are *derived* from the wire names, keyed BY the wire name:\n//\n//   protocolRequest(SCHEMES[PROTOCOL_THEME], 'set', [{ theme }])\n//\n// Keying by the constant is what makes the derivation unfalsifiable — there is no\n// second place to name the family, so there is no pair to get wrong. `schemeOf`\n// returns a template-literal conditional, so each value has a literal type (`'theme'`),\n// which buys two more things:\n//\n//   - a wire name that stops matching `protocol-*` stops compiling here, rather than\n//     silently producing an empty scheme at runtime;\n//   - `check-protocol-snapshot.mjs` resolves `SCHEMES[PROTOCOL_THEME]` through the type\n//     checker exactly like a plain literal, so the call sites stay visible to the gate.\n//\n// One export, deliberately: `./*` is a public subpath, so every name added here is\n// public API forever (ways_of_working §6, additive-only).\n//\n// This module is NOT generated — the derivation is the content — so it lives outside\n// `src/generated/`.\nimport {\n  PROTOCOL_ANALYTICS,\n  PROTOCOL_CONTRIBUTE,\n  PROTOCOL_DND,\n  PROTOCOL_EDITOR,\n  PROTOCOL_FEED,\n  PROTOCOL_FETCH,\n  PROTOCOL_IPC,\n  PROTOCOL_LAUNCH,\n  PROTOCOL_LLM,\n  PROTOCOL_RECENTS,\n  PROTOCOL_SECRETS,\n  PROTOCOL_SETTINGS,\n  PROTOCOL_SPACES,\n  PROTOCOL_TASK,\n  PROTOCOL_THEME,\n  PROTOCOL_VCS,\n} from './generated/protocol';\n\nconst PREFIX = 'protocol-';\n\n/** The scheme half of a `protocol-<scheme>` wire name. */\ntype SchemeOf<N extends string> = N extends `${typeof PREFIX}${infer S}` ? S : never;\n\n/**\n * `'protocol-theme'` → `'theme'`, as a literal type.\n *\n * The cast is the only place the derivation is asserted rather than computed; the\n * `N extends \\`protocol-${string}\\`` bound is what makes it sound — a wire name that is\n * not scheme-shaped is a compile error at the call, not a `never` at runtime.\n */\nconst schemeOf = <N extends `${typeof PREFIX}${string}`>(name: N): SchemeOf<N> =>\n  name.slice(PREFIX.length) as SchemeOf<N>;\n\n/** Every `protocol-*` scheme the SDK speaks, keyed by its wire name. */\nexport const SCHEMES = {\n  [PROTOCOL_ANALYTICS]: schemeOf(PROTOCOL_ANALYTICS),\n  [PROTOCOL_CONTRIBUTE]: schemeOf(PROTOCOL_CONTRIBUTE),\n  [PROTOCOL_DND]: schemeOf(PROTOCOL_DND),\n  [PROTOCOL_EDITOR]: schemeOf(PROTOCOL_EDITOR),\n  [PROTOCOL_FEED]: schemeOf(PROTOCOL_FEED),\n  [PROTOCOL_FETCH]: schemeOf(PROTOCOL_FETCH),\n  [PROTOCOL_IPC]: schemeOf(PROTOCOL_IPC),\n  [PROTOCOL_LAUNCH]: schemeOf(PROTOCOL_LAUNCH),\n  [PROTOCOL_LLM]: schemeOf(PROTOCOL_LLM),\n  [PROTOCOL_RECENTS]: schemeOf(PROTOCOL_RECENTS),\n  [PROTOCOL_SECRETS]: schemeOf(PROTOCOL_SECRETS),\n  [PROTOCOL_SETTINGS]: schemeOf(PROTOCOL_SETTINGS),\n  [PROTOCOL_SPACES]: schemeOf(PROTOCOL_SPACES),\n  [PROTOCOL_TASK]: schemeOf(PROTOCOL_TASK),\n  [PROTOCOL_THEME]: schemeOf(PROTOCOL_THEME),\n  [PROTOCOL_VCS]: schemeOf(PROTOCOL_VCS),\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BA,sBAiBO;AAEP,MAAM,SAAS;AAYf,MAAM,WAAW,CAAwC,SACvD,KAAK,MAAM,OAAO,MAAM;AAGnB,MAAM,UAAU;AAAA,EACrB,CAAC,kCAAkB,GAAG,SAAS,kCAAkB;AAAA,EACjD,CAAC,mCAAmB,GAAG,SAAS,mCAAmB;AAAA,EACnD,CAAC,4BAAY,GAAG,SAAS,4BAAY;AAAA,EACrC,CAAC,+BAAe,GAAG,SAAS,+BAAe;AAAA,EAC3C,CAAC,6BAAa,GAAG,SAAS,6BAAa;AAAA,EACvC,CAAC,8BAAc,GAAG,SAAS,8BAAc;AAAA,EACzC,CAAC,4BAAY,GAAG,SAAS,4BAAY;AAAA,EACrC,CAAC,+BAAe,GAAG,SAAS,+BAAe;AAAA,EAC3C,CAAC,4BAAY,GAAG,SAAS,4BAAY;AAAA,EACrC,CAAC,gCAAgB,GAAG,SAAS,gCAAgB;AAAA,EAC7C,CAAC,gCAAgB,GAAG,SAAS,gCAAgB;AAAA,EAC7C,CAAC,iCAAiB,GAAG,SAAS,iCAAiB;AAAA,EAC/C,CAAC,+BAAe,GAAG,SAAS,+BAAe;AAAA,EAC3C,CAAC,6BAAa,GAAG,SAAS,6BAAa;AAAA,EACvC,CAAC,8BAAc,GAAG,SAAS,8BAAc;AAAA,EACzC,CAAC,4BAAY,GAAG,SAAS,4BAAY;AACvC;","names":[]}

package/dist/protocolSchemes.d.cts

@@ -9,6 +9,7 @@ declare const SCHEMES: {
     readonly "protocol-ipc": "ipc";
     readonly "protocol-launch": "launch";
     readonly "protocol-llm": "llm";
+    readonly "protocol-recents": "recents";
     readonly "protocol-secrets": "secrets";
     readonly "protocol-settings": "settings";
     readonly "protocol-spaces": "spaces";

package/dist/protocolSchemes.d.ts

@@ -9,6 +9,7 @@ declare const SCHEMES: {
     readonly "protocol-ipc": "ipc";
     readonly "protocol-launch": "launch";
     readonly "protocol-llm": "llm";
+    readonly "protocol-recents": "recents";
     readonly "protocol-secrets": "secrets";
     readonly "protocol-settings": "settings";
     readonly "protocol-spaces": "spaces";

package/dist/protocolSchemes.js

@@ -9,6 +9,7 @@ import {
   PROTOCOL_IPC,
   PROTOCOL_LAUNCH,
   PROTOCOL_LLM,
+  PROTOCOL_RECENTS,
   PROTOCOL_SECRETS,
   PROTOCOL_SETTINGS,
   PROTOCOL_SPACES,
@@ -28,6 +29,7 @@ const SCHEMES = {
   [PROTOCOL_IPC]: schemeOf(PROTOCOL_IPC),
   [PROTOCOL_LAUNCH]: schemeOf(PROTOCOL_LAUNCH),
   [PROTOCOL_LLM]: schemeOf(PROTOCOL_LLM),
+  [PROTOCOL_RECENTS]: schemeOf(PROTOCOL_RECENTS),
   [PROTOCOL_SECRETS]: schemeOf(PROTOCOL_SECRETS),
   [PROTOCOL_SETTINGS]: schemeOf(PROTOCOL_SETTINGS),
   [PROTOCOL_SPACES]: schemeOf(PROTOCOL_SPACES),

package/dist/protocolSchemes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocolSchemes.ts"],"sourcesContent":["// The `protocol-<scheme>` SCHEMES, derived from the wire names.\n//\n// `protocolRequest(scheme, method, params)` takes the scheme — `'theme'` — while the\n// wire name the frame dispatches on is `'protocol-theme'`; the frame adds the prefix.\n// So the typed service wrappers cannot pass the published `PROTOCOL_*` constant\n// directly, and spelling the scheme inline would put a second, unguarded copy of the\n// name back in the tree — exactly what R3-274c removes.\n//\n// Instead the schemes are *derived* from the wire names, keyed BY the wire name:\n//\n//   protocolRequest(SCHEMES[PROTOCOL_THEME], 'set', [{ theme }])\n//\n// Keying by the constant is what makes the derivation unfalsifiable — there is no\n// second place to name the family, so there is no pair to get wrong. `schemeOf`\n// returns a template-literal conditional, so each value has a literal type (`'theme'`),\n// which buys two more things:\n//\n//   - a wire name that stops matching `protocol-*` stops compiling here, rather than\n//     silently producing an empty scheme at runtime;\n//   - `check-protocol-snapshot.mjs` resolves `SCHEMES[PROTOCOL_THEME]` through the type\n//     checker exactly like a plain literal, so the call sites stay visible to the gate.\n//\n// One export, deliberately: `./*` is a public subpath, so every name added here is\n// public API forever (ways_of_working §6, additive-only).\n//\n// This module is NOT generated — the derivation is the content — so it lives outside\n// `src/generated/`.\nimport {\n  PROTOCOL_ANALYTICS,\n  PROTOCOL_CONTRIBUTE,\n  PROTOCOL_DND,\n  PROTOCOL_EDITOR,\n  PROTOCOL_FEED,\n  PROTOCOL_FETCH,\n  PROTOCOL_IPC,\n  PROTOCOL_LAUNCH,\n  PROTOCOL_LLM,\n  PROTOCOL_SECRETS,\n  PROTOCOL_SETTINGS,\n  PROTOCOL_SPACES,\n  PROTOCOL_TASK,\n  PROTOCOL_THEME,\n  PROTOCOL_VCS,\n} from './generated/protocol';\n\nconst PREFIX = 'protocol-';\n\n/** The scheme half of a `protocol-<scheme>` wire name. */\ntype SchemeOf<N extends string> = N extends `${typeof PREFIX}${infer S}` ? S : never;\n\n/**\n * `'protocol-theme'` → `'theme'`, as a literal type.\n *\n * The cast is the only place the derivation is asserted rather than computed; the\n * `N extends \\`protocol-${string}\\`` bound is what makes it sound — a wire name that is\n * not scheme-shaped is a compile error at the call, not a `never` at runtime.\n */\nconst schemeOf = <N extends `${typeof PREFIX}${string}`>(name: N): SchemeOf<N> =>\n  name.slice(PREFIX.length) as SchemeOf<N>;\n\n/** Every `protocol-*` scheme the SDK speaks, keyed by its wire name. */\nexport const SCHEMES = {\n  [PROTOCOL_ANALYTICS]: schemeOf(PROTOCOL_ANALYTICS),\n  [PROTOCOL_CONTRIBUTE]: schemeOf(PROTOCOL_CONTRIBUTE),\n  [PROTOCOL_DND]: schemeOf(PROTOCOL_DND),\n  [PROTOCOL_EDITOR]: schemeOf(PROTOCOL_EDITOR),\n  [PROTOCOL_FEED]: schemeOf(PROTOCOL_FEED),\n  [PROTOCOL_FETCH]: schemeOf(PROTOCOL_FETCH),\n  [PROTOCOL_IPC]: schemeOf(PROTOCOL_IPC),\n  [PROTOCOL_LAUNCH]: schemeOf(PROTOCOL_LAUNCH),\n  [PROTOCOL_LLM]: schemeOf(PROTOCOL_LLM),\n  [PROTOCOL_SECRETS]: schemeOf(PROTOCOL_SECRETS),\n  [PROTOCOL_SETTINGS]: schemeOf(PROTOCOL_SETTINGS),\n  [PROTOCOL_SPACES]: schemeOf(PROTOCOL_SPACES),\n  [PROTOCOL_TASK]: schemeOf(PROTOCOL_TASK),\n  [PROTOCOL_THEME]: schemeOf(PROTOCOL_THEME),\n  [PROTOCOL_VCS]: schemeOf(PROTOCOL_VCS),\n} as const;\n"],"mappings":";AA2BA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,MAAM,SAAS;AAYf,MAAM,WAAW,CAAwC,SACvD,KAAK,MAAM,OAAO,MAAM;AAGnB,MAAM,UAAU;AAAA,EACrB,CAAC,kBAAkB,GAAG,SAAS,kBAAkB;AAAA,EACjD,CAAC,mBAAmB,GAAG,SAAS,mBAAmB;AAAA,EACnD,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,aAAa,GAAG,SAAS,aAAa;AAAA,EACvC,CAAC,cAAc,GAAG,SAAS,cAAc;AAAA,EACzC,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,gBAAgB,GAAG,SAAS,gBAAgB;AAAA,EAC7C,CAAC,iBAAiB,GAAG,SAAS,iBAAiB;AAAA,EAC/C,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,aAAa,GAAG,SAAS,aAAa;AAAA,EACvC,CAAC,cAAc,GAAG,SAAS,cAAc;AAAA,EACzC,CAAC,YAAY,GAAG,SAAS,YAAY;AACvC;","names":[]}
+{"version":3,"sources":["../src/protocolSchemes.ts"],"sourcesContent":["// The `protocol-<scheme>` SCHEMES, derived from the wire names.\n//\n// `protocolRequest(scheme, method, params)` takes the scheme — `'theme'` — while the\n// wire name the frame dispatches on is `'protocol-theme'`; the frame adds the prefix.\n// So the typed service wrappers cannot pass the published `PROTOCOL_*` constant\n// directly, and spelling the scheme inline would put a second, unguarded copy of the\n// name back in the tree — exactly what R3-274c removes.\n//\n// Instead the schemes are *derived* from the wire names, keyed BY the wire name:\n//\n//   protocolRequest(SCHEMES[PROTOCOL_THEME], 'set', [{ theme }])\n//\n// Keying by the constant is what makes the derivation unfalsifiable — there is no\n// second place to name the family, so there is no pair to get wrong. `schemeOf`\n// returns a template-literal conditional, so each value has a literal type (`'theme'`),\n// which buys two more things:\n//\n//   - a wire name that stops matching `protocol-*` stops compiling here, rather than\n//     silently producing an empty scheme at runtime;\n//   - `check-protocol-snapshot.mjs` resolves `SCHEMES[PROTOCOL_THEME]` through the type\n//     checker exactly like a plain literal, so the call sites stay visible to the gate.\n//\n// One export, deliberately: `./*` is a public subpath, so every name added here is\n// public API forever (ways_of_working §6, additive-only).\n//\n// This module is NOT generated — the derivation is the content — so it lives outside\n// `src/generated/`.\nimport {\n  PROTOCOL_ANALYTICS,\n  PROTOCOL_CONTRIBUTE,\n  PROTOCOL_DND,\n  PROTOCOL_EDITOR,\n  PROTOCOL_FEED,\n  PROTOCOL_FETCH,\n  PROTOCOL_IPC,\n  PROTOCOL_LAUNCH,\n  PROTOCOL_LLM,\n  PROTOCOL_RECENTS,\n  PROTOCOL_SECRETS,\n  PROTOCOL_SETTINGS,\n  PROTOCOL_SPACES,\n  PROTOCOL_TASK,\n  PROTOCOL_THEME,\n  PROTOCOL_VCS,\n} from './generated/protocol';\n\nconst PREFIX = 'protocol-';\n\n/** The scheme half of a `protocol-<scheme>` wire name. */\ntype SchemeOf<N extends string> = N extends `${typeof PREFIX}${infer S}` ? S : never;\n\n/**\n * `'protocol-theme'` → `'theme'`, as a literal type.\n *\n * The cast is the only place the derivation is asserted rather than computed; the\n * `N extends \\`protocol-${string}\\`` bound is what makes it sound — a wire name that is\n * not scheme-shaped is a compile error at the call, not a `never` at runtime.\n */\nconst schemeOf = <N extends `${typeof PREFIX}${string}`>(name: N): SchemeOf<N> =>\n  name.slice(PREFIX.length) as SchemeOf<N>;\n\n/** Every `protocol-*` scheme the SDK speaks, keyed by its wire name. */\nexport const SCHEMES = {\n  [PROTOCOL_ANALYTICS]: schemeOf(PROTOCOL_ANALYTICS),\n  [PROTOCOL_CONTRIBUTE]: schemeOf(PROTOCOL_CONTRIBUTE),\n  [PROTOCOL_DND]: schemeOf(PROTOCOL_DND),\n  [PROTOCOL_EDITOR]: schemeOf(PROTOCOL_EDITOR),\n  [PROTOCOL_FEED]: schemeOf(PROTOCOL_FEED),\n  [PROTOCOL_FETCH]: schemeOf(PROTOCOL_FETCH),\n  [PROTOCOL_IPC]: schemeOf(PROTOCOL_IPC),\n  [PROTOCOL_LAUNCH]: schemeOf(PROTOCOL_LAUNCH),\n  [PROTOCOL_LLM]: schemeOf(PROTOCOL_LLM),\n  [PROTOCOL_RECENTS]: schemeOf(PROTOCOL_RECENTS),\n  [PROTOCOL_SECRETS]: schemeOf(PROTOCOL_SECRETS),\n  [PROTOCOL_SETTINGS]: schemeOf(PROTOCOL_SETTINGS),\n  [PROTOCOL_SPACES]: schemeOf(PROTOCOL_SPACES),\n  [PROTOCOL_TASK]: schemeOf(PROTOCOL_TASK),\n  [PROTOCOL_THEME]: schemeOf(PROTOCOL_THEME),\n  [PROTOCOL_VCS]: schemeOf(PROTOCOL_VCS),\n} as const;\n"],"mappings":";AA2BA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,MAAM,SAAS;AAYf,MAAM,WAAW,CAAwC,SACvD,KAAK,MAAM,OAAO,MAAM;AAGnB,MAAM,UAAU;AAAA,EACrB,CAAC,kBAAkB,GAAG,SAAS,kBAAkB;AAAA,EACjD,CAAC,mBAAmB,GAAG,SAAS,mBAAmB;AAAA,EACnD,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,aAAa,GAAG,SAAS,aAAa;AAAA,EACvC,CAAC,cAAc,GAAG,SAAS,cAAc;AAAA,EACzC,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,gBAAgB,GAAG,SAAS,gBAAgB;AAAA,EAC7C,CAAC,gBAAgB,GAAG,SAAS,gBAAgB;AAAA,EAC7C,CAAC,iBAAiB,GAAG,SAAS,iBAAiB;AAAA,EAC/C,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,aAAa,GAAG,SAAS,aAAa;AAAA,EACvC,CAAC,cAAc,GAAG,SAAS,cAAc;AAAA,EACzC,CAAC,YAAY,GAAG,SAAS,YAAY;AACvC;","names":[]}

package/dist/recents.cjs

@@ -0,0 +1,41 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var recents_exports = {};
+__export(recents_exports, {
+  clearRecentProjects: () => clearRecentProjects,
+  listRecentProjects: () => listRecentProjects
+});
+module.exports = __toCommonJS(recents_exports);
+var import_sandboxUtils = require("./sandboxUtils");
+var import_protocol = require("./generated/protocol");
+var import_protocolSchemes = require("./protocolSchemes");
+const recentsRequest = (params) => (0, import_sandboxUtils.protocolRequest)(import_protocolSchemes.SCHEMES[import_protocol.PROTOCOL_RECENTS], "list", [params]);
+async function listRecentProjects() {
+  const res = await recentsRequest({});
+  return res.projects ?? null;
+}
+async function clearRecentProjects() {
+  await recentsRequest({ clear: true });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearRecentProjects,
+  listRecentProjects
+});
+//# sourceMappingURL=recents.cjs.map

package/dist/recents.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recents.ts"],"sourcesContent":["// The recent-projects record — app-facing surface (R3-485, OSO §4.3).\n//\n// `listRecentProjects()` reads the HOST-OWNED record through the one elevated,\n// app-scoped `recents:read` capability. Two gates stand between an app and the\n// record, and both must pass: the §8.4 capability grant (declared as\n// `requests: { 'recents:read': {} }` and consented per (app, principal)), and the\n// handler's structural binding — the read is granted only to the app bound at\n// `page.home`. For every other app the call resolves to a refusal, whatever it\n// declared.\n//\n// A project entry is COORDINATES (provider/namespace/repository/ref + when) — a\n// location the user already navigated to under their own authority, never an\n// in-repo path. Opening one runs the ordinary load path with the ordinary\n// consent: the record confers nothing (R-OSO-22).\nimport { protocolRequest } from './sandboxUtils';\nimport { PROTOCOL_RECENTS } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/** One recently opened project — repository coordinates, never an in-repo path. */\nexport interface RecentProject {\n  provider: string;\n  namespace: string;\n  repository: string;\n  /** The ref the user opened (`main`, a sha). */\n  ref: string;\n  /** When the user last opened it (epoch ms). */\n  ts: number;\n}\n\ninterface RecentsReply {\n  /** Newest-first; `null` when the record is empty or the user cleared it. */\n  projects: RecentProject[] | null;\n}\n\n/**\n * The one call shape the SDK speaks under `protocol-recents` — read, or clear\n * (same gated surface). A single typed call site keeps the wire contract exact:\n * the snapshot gate reads THIS shape, and the host handler accepts the same.\n */\nconst recentsRequest = (params: { clear?: boolean }): Promise<RecentsReply> =>\n  protocolRequest(SCHEMES[PROTOCOL_RECENTS], 'list', [params]) as Promise<RecentsReply>;\n\n/**\n * The user's recently opened projects, newest-first, or `null` when the record is\n * absent (R-OSO-22: cleared is absent, never an empty list). Refuses for any app\n * that is not the `page.home` binding.\n */\nexport async function listRecentProjects(): Promise<RecentProject[] | null> {\n  const res = await recentsRequest({});\n  return res.projects ?? null;\n}\n\n/**\n * Clear the user's recent-projects record (the surface afterwards is absent, not\n * empty). Rides the same page.home binding gate as the read.\n */\nexport async function clearRecentProjects(): Promise<void> {\n  await recentsRequest({ clear: true });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAcA,0BAAgC;AAChC,sBAAiC;AACjC,6BAAwB;AAuBxB,MAAM,iBAAiB,CAAC,eACtB,qCAAgB,+BAAQ,gCAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC;AAO7D,eAAsB,qBAAsD;AAC1E,QAAM,MAAM,MAAM,eAAe,CAAC,CAAC;AACnC,SAAO,IAAI,YAAY;AACzB;AAMA,eAAsB,sBAAqC;AACzD,QAAM,eAAe,EAAE,OAAO,KAAK,CAAC;AACtC;","names":[]}

package/dist/recents.d.cts

@@ -0,0 +1,23 @@
+/** One recently opened project — repository coordinates, never an in-repo path. */
+interface RecentProject {
+    provider: string;
+    namespace: string;
+    repository: string;
+    /** The ref the user opened (`main`, a sha). */
+    ref: string;
+    /** When the user last opened it (epoch ms). */
+    ts: number;
+}
+/**
+ * The user's recently opened projects, newest-first, or `null` when the record is
+ * absent (R-OSO-22: cleared is absent, never an empty list). Refuses for any app
+ * that is not the `page.home` binding.
+ */
+declare function listRecentProjects(): Promise<RecentProject[] | null>;
+/**
+ * Clear the user's recent-projects record (the surface afterwards is absent, not
+ * empty). Rides the same page.home binding gate as the read.
+ */
+declare function clearRecentProjects(): Promise<void>;
+
+export { type RecentProject, clearRecentProjects, listRecentProjects };

package/dist/recents.d.ts

@@ -0,0 +1,23 @@
+/** One recently opened project — repository coordinates, never an in-repo path. */
+interface RecentProject {
+    provider: string;
+    namespace: string;
+    repository: string;
+    /** The ref the user opened (`main`, a sha). */
+    ref: string;
+    /** When the user last opened it (epoch ms). */
+    ts: number;
+}
+/**
+ * The user's recently opened projects, newest-first, or `null` when the record is
+ * absent (R-OSO-22: cleared is absent, never an empty list). Refuses for any app
+ * that is not the `page.home` binding.
+ */
+declare function listRecentProjects(): Promise<RecentProject[] | null>;
+/**
+ * Clear the user's recent-projects record (the surface afterwards is absent, not
+ * empty). Rides the same page.home binding gate as the read.
+ */
+declare function clearRecentProjects(): Promise<void>;
+
+export { type RecentProject, clearRecentProjects, listRecentProjects };

package/dist/recents.js

@@ -0,0 +1,17 @@
+import "./chunk-VHAA22YE.js";
+import { protocolRequest } from "./sandboxUtils";
+import { PROTOCOL_RECENTS } from "./generated/protocol";
+import { SCHEMES } from "./protocolSchemes";
+const recentsRequest = (params) => protocolRequest(SCHEMES[PROTOCOL_RECENTS], "list", [params]);
+async function listRecentProjects() {
+  const res = await recentsRequest({});
+  return res.projects ?? null;
+}
+async function clearRecentProjects() {
+  await recentsRequest({ clear: true });
+}
+export {
+  clearRecentProjects,
+  listRecentProjects
+};
+//# sourceMappingURL=recents.js.map

package/dist/recents.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recents.ts"],"sourcesContent":["// The recent-projects record — app-facing surface (R3-485, OSO §4.3).\n//\n// `listRecentProjects()` reads the HOST-OWNED record through the one elevated,\n// app-scoped `recents:read` capability. Two gates stand between an app and the\n// record, and both must pass: the §8.4 capability grant (declared as\n// `requests: { 'recents:read': {} }` and consented per (app, principal)), and the\n// handler's structural binding — the read is granted only to the app bound at\n// `page.home`. For every other app the call resolves to a refusal, whatever it\n// declared.\n//\n// A project entry is COORDINATES (provider/namespace/repository/ref + when) — a\n// location the user already navigated to under their own authority, never an\n// in-repo path. Opening one runs the ordinary load path with the ordinary\n// consent: the record confers nothing (R-OSO-22).\nimport { protocolRequest } from './sandboxUtils';\nimport { PROTOCOL_RECENTS } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/** One recently opened project — repository coordinates, never an in-repo path. */\nexport interface RecentProject {\n  provider: string;\n  namespace: string;\n  repository: string;\n  /** The ref the user opened (`main`, a sha). */\n  ref: string;\n  /** When the user last opened it (epoch ms). */\n  ts: number;\n}\n\ninterface RecentsReply {\n  /** Newest-first; `null` when the record is empty or the user cleared it. */\n  projects: RecentProject[] | null;\n}\n\n/**\n * The one call shape the SDK speaks under `protocol-recents` — read, or clear\n * (same gated surface). A single typed call site keeps the wire contract exact:\n * the snapshot gate reads THIS shape, and the host handler accepts the same.\n */\nconst recentsRequest = (params: { clear?: boolean }): Promise<RecentsReply> =>\n  protocolRequest(SCHEMES[PROTOCOL_RECENTS], 'list', [params]) as Promise<RecentsReply>;\n\n/**\n * The user's recently opened projects, newest-first, or `null` when the record is\n * absent (R-OSO-22: cleared is absent, never an empty list). Refuses for any app\n * that is not the `page.home` binding.\n */\nexport async function listRecentProjects(): Promise<RecentProject[] | null> {\n  const res = await recentsRequest({});\n  return res.projects ?? null;\n}\n\n/**\n * Clear the user's recent-projects record (the surface afterwards is absent, not\n * empty). Rides the same page.home binding gate as the read.\n */\nexport async function clearRecentProjects(): Promise<void> {\n  await recentsRequest({ clear: true });\n}\n"],"mappings":";AAcA,SAAS,uBAAuB;AAChC,SAAS,wBAAwB;AACjC,SAAS,eAAe;AAuBxB,MAAM,iBAAiB,CAAC,WACtB,gBAAgB,QAAQ,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC;AAO7D,eAAsB,qBAAsD;AAC1E,QAAM,MAAM,MAAM,eAAe,CAAC,CAAC;AACnC,SAAO,IAAI,YAAY;AACzB;AAMA,eAAsB,sBAAqC;AACzD,QAAM,eAAe,EAAE,OAAO,KAAK,CAAC;AACtC;","names":[]}

package/dist/tasks.cjs

@@ -21,6 +21,8 @@ __export(tasks_exports, {
   cancelTask: () => cancelTask,
   capDir: () => capDir,
   capFile: () => capFile,
+  captureAudio: () => captureAudio,
+  capturePhoto: () => capturePhoto,
   completeTask: () => completeTask,
   getTaskInput: () => getTaskInput,
   invokeTask: () => invokeTask,
@@ -29,6 +31,7 @@ __export(tasks_exports, {
 module.exports = __toCommonJS(tasks_exports);
 var import_react = require("react");
 var import_sandboxUtils = require("./sandboxUtils");
+var import_hostTransport = require("./hostTransport");
 var import_protocol = require("./generated/protocol");
 var import_protocolSchemes = require("./protocolSchemes");
 const capFile = (ref, opts) => ({
@@ -52,15 +55,44 @@ const invokeTask = async (task, params = {}) => {
   }
   return res.data;
 };
+const capturePhoto = (options = {}) => invokeTask("capture-photo", { ...options });
+const captureAudio = (options = {}) => invokeTask("capture-audio", { ...options });
 let latestInput = null;
 const inputListeners = /* @__PURE__ */ new Set();
-(0, import_sandboxUtils.addListener)(import_protocol.TASK_INPUT, (m) => {
-  latestInput = { task: m.task, params: m.params ?? {} };
-  inputListeners.forEach((l) => l(latestInput));
-});
-const getTaskInput = () => latestInput;
-const completeTask = (result) => (0, import_sandboxUtils.sendMessage)(import_protocol.TASK_COMPLETE, { result });
-const cancelTask = () => (0, import_sandboxUtils.sendMessage)(import_protocol.TASK_CANCEL, {});
+let inputListenerRegistered = false;
+const ensureInputListener = () => {
+  if (inputListenerRegistered) return;
+  try {
+    (0, import_sandboxUtils.addListener)(import_protocol.TASK_INPUT, (m) => {
+      latestInput = { task: m.task, params: m.params ?? {} };
+      inputListeners.forEach((l) => l(latestInput));
+    });
+  } catch {
+    return;
+  }
+  inputListenerRegistered = true;
+};
+ensureInputListener();
+const getTaskInput = () => {
+  ensureInputListener();
+  return latestInput;
+};
+const hostReachable = () => {
+  try {
+    (0, import_hostTransport.transport)();
+    return true;
+  } catch {
+    return false;
+  }
+};
+const completeTask = (result) => {
+  if (!hostReachable()) return;
+  (0, import_sandboxUtils.sendMessage)(import_protocol.TASK_COMPLETE, { result });
+};
+const cancelTask = () => {
+  if (!hostReachable()) return;
+  (0, import_sandboxUtils.sendMessage)(import_protocol.TASK_CANCEL, {});
+};
 const useTaskInput = () => {
   const [input, setInput] = (0, import_react.useState)(getTaskInput);
   (0, import_react.useEffect)(() => {
@@ -78,6 +110,8 @@ const useTaskInput = () => {
   cancelTask,
   capDir,
   capFile,
+  captureAudio,
+  capturePhoto,
   completeTask,
   getTaskInput,
   invokeTask,

package/dist/tasks.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tasks.ts"],"sourcesContent":["// Task invocation — apps invoking apps (UI_AS_APPS_SPEC §5.7). The\n// `startActivityForResult` pattern: one app invokes another by TASK CONTRACT\n// (never by app name — the user's override picks the bound app), passes typed\n// params, and awaits a typed result. The callee runs in a host-owned overlay\n// under ITS OWN grants — data crosses, your authority does not (§5.7).\n//\n// Two roles:\n//  - CALLER: `invokeTask(task, params)` (Recipe B — a deferred reply the host\n//    holds open until the callee finishes). Delegate a file with `capFile(...)`:\n//    the host resolves it against YOUR grants and mints an attenuated chroot.\n//  - CALLEE: read `useTaskInput()`, then `completeTask(result)` / `cancelTask()`.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport { PROTOCOL_TASK, TASK_CANCEL, TASK_COMPLETE, TASK_INPUT } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n// ── caller side ─────────────────────────────────────────────────────────────\n\n/** A delegated FILE capability marker for a task param (§5.7). */\nexport interface FileCap {\n  $cap: 'file';\n  mountId: string;\n  relPath: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Build a delegated file reference for a task param. The host resolves it against\n * YOUR OWN grants and mints an attenuated, task-scoped chroot for the callee — you\n * can only delegate a path you already hold (attenuation only, never escalation).\n *\n *   file: capFile({ mountId: 'space:abc', relPath: 'photos/cat.jpg' }, { mode: 'rw' })\n */\nexport const capFile = (ref: { mountId: string; relPath: string }, opts: { mode: 'ro' | 'rw' }): FileCap => ({\n  $cap: 'file',\n  mountId: ref.mountId,\n  relPath: ref.relPath,\n  mode: opts.mode,\n});\n\n/** A delegated DIRECTORY capability marker for a task param (D2). Like {@link FileCap}\n *  but `relPath` names a DIRECTORY: the host chroots the callee AT that directory\n *  (the whole subtree). Used for the `pick-file` `roots` — one chroot per root. */\nexport interface DirCap {\n  $cap: 'dir';\n  mountId: string;\n  relPath: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Build a delegated DIRECTORY reference for a task param (the directory analogue of\n * {@link capFile}). The host resolves it against YOUR OWN grants and mints an\n * attenuated, task-scoped chroot of that directory for the callee — you can only\n * delegate a directory you already hold (attenuation only, never escalation):\n *\n *   roots: [capDir({ mountId: 'space:abc', relPath: 'boards' }, { mode: 'rw' })]\n */\nexport const capDir = (ref: { mountId: string; relPath: string }, opts: { mode: 'ro' | 'rw' }): DirCap => ({\n  $cap: 'dir',\n  mountId: ref.mountId,\n  relPath: ref.relPath,\n  mode: opts.mode,\n});\n\n/**\n * Invoke another app via a task contract and await its typed result (Recipe B).\n * Rejects with a machine `.code` on refusal: `cancelled` (user dismissed the\n * overlay), `timeout` (§5.7.1 liveness), `forbidden` (undeclared task or a file\n * delegation you don't hold), `no-such-task`, `task-cycle`/`task-depth-exceeded`/\n * `task-version-mismatch`, or `invalid-params` (result failed the contract schema).\n */\nexport const invokeTask = async <R = unknown>(task: string, params: Record<string, unknown> = {}): Promise<R> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_TASK], 'invoke', [{ task, params }])) as\n    | { ok: true; data: R }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `task '${task}' failed`) as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n  return res.data;\n};\n\n// ── callee side ─────────────────────────────────────────────────────────────\n\n/** The params this app was invoked with as a task callee. */\nexport interface TaskInput {\n  task: string;\n  params: Record<string, unknown>;\n}\n\nlet latestInput: TaskInput | null = null;\nconst inputListeners = new Set<(i: TaskInput) => void>();\n\n// The host delivers a `task-input` message to the callee's iframe right after it\n// mounts the overlay (the §5.7 \"params via the region's mount event\").\naddListener(TASK_INPUT, (m: { task: string; params?: Record<string, unknown> }) => {\n  latestInput = { task: m.task, params: m.params ?? {} };\n  inputListeners.forEach((l) => l(latestInput!));\n});\n\n/** The task params this app was invoked with, or null if it isn't a task callee. */\nexport const getTaskInput = (): TaskInput | null => latestInput;\n\n/**\n * Finish the task, returning a result to the caller. The host validates it against\n * the contract's result schema before resolving the caller (`invalid-params` on\n * violation), then tears down this overlay.\n */\nexport const completeTask = (result: unknown): void => sendMessage(TASK_COMPLETE, { result });\n\n/** Abort the task; the caller's `invokeTask` rejects with `cancelled`. */\nexport const cancelTask = (): void => sendMessage(TASK_CANCEL, {});\n\n/** React hook: the task input for this callee, re-rendering when it arrives. */\nexport const useTaskInput = (): TaskInput | null => {\n  const [input, setInput] = useState<TaskInput | null>(getTaskInput);\n  useEffect(() => {\n    const l = (i: TaskInput) => setInput(i);\n    inputListeners.add(l);\n    if (latestInput) setInput(latestInput);\n    return () => {\n      inputListeners.delete(l);\n    };\n  }, []);\n  return input;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,mBAAoC;AACpC,0BAA0D;AAC1D,sBAAsE;AACtE,6BAAwB;AAmBjB,MAAM,UAAU,CAAC,KAA2C,UAA0C;AAAA,EAC3G,MAAM;AAAA,EACN,SAAS,IAAI;AAAA,EACb,SAAS,IAAI;AAAA,EACb,MAAM,KAAK;AACb;AAoBO,MAAM,SAAS,CAAC,KAA2C,UAAyC;AAAA,EACzG,MAAM;AAAA,EACN,SAAS,IAAI;AAAA,EACb,SAAS,IAAI;AAAA,EACb,MAAM,KAAK;AACb;AASO,MAAM,aAAa,OAAoB,MAAc,SAAkC,CAAC,MAAkB;AAC/G,QAAM,MAAO,UAAM,qCAAgB,+BAAQ,6BAAa,GAAG,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC;AAIvF,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,SAAS,IAAI,UAAU;AAC7D,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAUA,IAAI,cAAgC;AACpC,MAAM,iBAAiB,oBAAI,IAA4B;AAAA,IAIvD,iCAAY,4BAAY,CAAC,MAA0D;AACjF,gBAAc,EAAE,MAAM,EAAE,MAAM,QAAQ,EAAE,UAAU,CAAC,EAAE;AACrD,iBAAe,QAAQ,CAAC,MAAM,EAAE,WAAY,CAAC;AAC/C,CAAC;AAGM,MAAM,eAAe,MAAwB;AAO7C,MAAM,eAAe,CAAC,eAA0B,iCAAY,+BAAe,EAAE,OAAO,CAAC;AAGrF,MAAM,aAAa,UAAY,iCAAY,6BAAa,CAAC,CAAC;AAG1D,MAAM,eAAe,MAAwB;AAClD,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAA2B,YAAY;AACjE,8BAAU,MAAM;AACd,UAAM,IAAI,CAAC,MAAiB,SAAS,CAAC;AACtC,mBAAe,IAAI,CAAC;AACpB,QAAI,YAAa,UAAS,WAAW;AACrC,WAAO,MAAM;AACX,qBAAe,OAAO,CAAC;AAAA,IACzB;AAAA,EACF,GAAG,CAAC,CAAC;AACL,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/tasks.ts"],"sourcesContent":["// Task invocation — apps invoking apps (UI_AS_APPS_SPEC §5.7). The\n// `startActivityForResult` pattern: one app invokes another by TASK CONTRACT\n// (never by app name — the user's override picks the bound app), passes typed\n// params, and awaits a typed result. The callee runs in a host-owned overlay\n// under ITS OWN grants — data crosses, your authority does not (§5.7).\n//\n// Two roles:\n//  - CALLER: `invokeTask(task, params)` (Recipe B — a deferred reply the host\n//    holds open until the callee finishes). Delegate a file with `capFile(...)`:\n//    the host resolves it against YOUR grants and mints an attenuated chroot.\n//  - CALLEE: read `useTaskInput()`, then `completeTask(result)` / `cancelTask()`.\n//\n// OFF-HOST (plain `vite dev`, node/jsdom tests — no sandbox, no host transport):\n// importing this module is always safe (R3-421 — no subpath may throw at import\n// time), and the surface degrades instead of crashing: `getTaskInput()` /\n// `useTaskInput()` stay `null` forever (you are never a task callee without a\n// host), `completeTask` / `cancelTask` are no-ops, and `invokeTask` rejects with\n// a \"no host transport\" error. Under the @immediately-run/dev-fs substrate the\n// transport resolves but no task ever arrives — same observable behaviour.\n// The no-op is scoped to the ABSENCE of a host: when there IS one, a failed send\n// throws instead of leaving the caller to hang out its deadline.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport { transport } from './hostTransport';\nimport { PROTOCOL_TASK, TASK_CANCEL, TASK_COMPLETE, TASK_INPUT } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n// ── caller side ─────────────────────────────────────────────────────────────\n\n/** A delegated FILE capability marker for a task param (§5.7). */\nexport interface FileCap {\n  $cap: 'file';\n  mountId: string;\n  relPath: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Build a delegated file reference for a task param. The host resolves it against\n * YOUR OWN grants and mints an attenuated, task-scoped chroot for the callee — you\n * can only delegate a path you already hold (attenuation only, never escalation).\n *\n *   file: capFile({ mountId: 'space:abc', relPath: 'photos/cat.jpg' }, { mode: 'rw' })\n */\nexport const capFile = (ref: { mountId: string; relPath: string }, opts: { mode: 'ro' | 'rw' }): FileCap => ({\n  $cap: 'file',\n  mountId: ref.mountId,\n  relPath: ref.relPath,\n  mode: opts.mode,\n});\n\n/** A delegated DIRECTORY capability marker for a task param (D2). Like {@link FileCap}\n *  but `relPath` names a DIRECTORY: the host chroots the callee AT that directory\n *  (the whole subtree). Used for the `pick-file` `roots` — one chroot per root. */\nexport interface DirCap {\n  $cap: 'dir';\n  mountId: string;\n  relPath: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Build a delegated DIRECTORY reference for a task param (the directory analogue of\n * {@link capFile}). The host resolves it against YOUR OWN grants and mints an\n * attenuated, task-scoped chroot of that directory for the callee — you can only\n * delegate a directory you already hold (attenuation only, never escalation):\n *\n *   roots: [capDir({ mountId: 'space:abc', relPath: 'boards' }, { mode: 'rw' })]\n */\nexport const capDir = (ref: { mountId: string; relPath: string }, opts: { mode: 'ro' | 'rw' }): DirCap => ({\n  $cap: 'dir',\n  mountId: ref.mountId,\n  relPath: ref.relPath,\n  mode: opts.mode,\n});\n\n/**\n * Invoke another app via a task contract and await its typed result (Recipe B).\n * Rejects with a machine `.code` on refusal: `cancelled` (user dismissed the\n * overlay), `timeout` (§5.7.1 liveness), `forbidden` (missing `task:invoke`, or a\n * file delegation you don't hold), `not-declared` (the task is missing from your\n * `immediately.run.invokes`), `no-such-task` (no app is bound to that contract),\n * `task-cycle`/`task-depth-exceeded`/`task-version-mismatch`, or `invalid-params`\n * (result failed the contract schema). **Read `err.message`** — since R3-418 the host\n * says which capability, which declaration or which param was at fault; the code alone\n * does not distinguish them.\n *\n * Two things must BOTH be true before any invoke is admitted, and they are separate:\n *  1. your `package.json` `immediately.run.invokes` lists the task (else `not-declared`);\n *  2. your app holds the `task:invoke` capability — declare it in\n *     `immediately.run.capabilities` so the user can grant it (else `forbidden`).\n * Declaring the invoke does not imply the capability.\n *\n * ── `pick-file`: `roots` is required (SPACES_UI_SPEC §4.1) ───────────────────\n * ```ts\n * import { invokeTask, capDir, requestMount } from '@immediately-run/sdk';\n *\n * const mount = await requestMount();                    // the user picks a space\n * // `invokeTask` returns `unknown` — name the result type, or the destructuring\n * // below does not compile.\n * const { root, path } = await invokeTask<{ root: number; path: string }>('pick-file', {\n *   // `SandboxMount.id` is optional (absent on the primary repo mount) — fall back to\n *   // `path`, which is always present and is what the host resolves against.\n *   roots: [capDir({ mountId: mount.id ?? mount.path, relPath: 'boards' }, { mode: 'ro' })],\n * });\n * ```\n * - `roots` is a NON-EMPTY `DirCap[]` of directories you **already hold**. The result\n *   names its target as `{ root, path }` where `root` INDEXES `params.roots`, so\n *   `invokeTask('pick-file', {})` can never produce a valid result and is rejected.\n *   There is no rootless \"pick from any of my spaces\" mode by design: enumerating the\n *   user's spaces is the host's powerbox (`requestMount()`), and composing the two —\n *   as above — is that flow. See SPACES_UI_SPEC R-SPACES-5/R-SPACES-12.\n * - Each `capDir` is attenuated against your own grant. **`{ mode: 'rw' }` over a space\n *   the user granted `ro` is refused `forbidden`** — the commonest failure, because the\n *   mount *was* granted and the path *is* inside it. Pass the mode you actually hold;\n *   `ro` is right for a plain pick.\n * - The `requestMount()` grant is DURABLE and survives a cancelled pick: the user\n *   consented to the mount in host chrome, separately from the pick (SPACES_UI_SPEC §4.1).\n *   Reuse it for later picks rather than re-requesting.\n *\n * Off-host (plain `vite dev` — no host transport) it rejects with a plain\n * \"no host transport\" error: there is no host to resolve the task binding.\n */\nexport const invokeTask = async <R = unknown>(task: string, params: Record<string, unknown> = {}): Promise<R> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_TASK], 'invoke', [{ task, params }])) as\n    | { ok: true; data: R }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `task '${task}' failed`) as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n  return res.data;\n};\n\n// ── the host-provided CAPTURE contracts (R3-425) ────────────────────────────\n\n/** Bytes captured by the host, as `capturePhoto()` / `captureAudio()` return them.\n *  `bytes` is a transferable `ArrayBuffer` — write it to a space, decode it, upload\n *  it. You never receive a `MediaStream` or a `MediaStreamTrack`, and that is not an\n *  omission: a track cannot be transferred into an app frame at all\n *  (`DataCloneError`), and the frame's opaque origin cannot open a device itself\n *  (`getUserMedia` throws `SecurityError: Invalid security origin`). */\nexport interface CaptureResult {\n  bytes: ArrayBuffer;\n  /** e.g. `image/jpeg`, `audio/webm`. Chosen by the HOST, not by you. */\n  mimeType: string;\n  /** How long the device was open, in ms. */\n  durationMs: number;\n}\n\n/** Optional hints for a capture. They deliberately name NOTHING — no device id, no\n *  camera index — because the host chooses everything about how the capture is\n *  performed. That is what lets the grant be a plain on/off instead of a per-call\n *  target list the way `net:fetch` needs. */\nexport interface CaptureOptions {\n  /** Which way the camera should face, if the device has a choice. A HINT: the host\n   *  may ignore it. Ignored for audio. */\n  facing?: 'user' | 'environment';\n}\n\n/**\n * Take one photo, or record one audio clip, through the HOST's capture UI\n * (`BROWSER_CAPABILITIES_SPEC` §3 grade 1).\n *\n * The host opens the device at its own origin, draws the viewfinder, and hands you\n * the bytes when the user presses Done. **You are never in the loop while the device\n * is live** — that is the point of the design, not a limitation of it:\n *\n * - The capture UI is drawn by the host, so a user can trust it the way they trust\n *   the sign-in dialog. Do not build a lookalike; imitating host chrome is spoofing.\n * - While the device is open the host shows a persistent \"camera on\" / \"microphone\n *   on\" indicator in its own chrome, for the whole session. You cannot hide it and\n *   should not try to.\n * - If the user cancels, this rejects `cancelled` and **nothing was recorded**. There\n *   is no partial result — do not write error handling that hopes for one.\n *\n * ```ts\n * import { capturePhoto, requestMount, openFs } from '@immediately-run/sdk';\n *\n * try {\n *   const { bytes, mimeType } = await capturePhoto({ facing: 'environment' });\n *   const mount = await requestMount();          // the user picks a space to save into\n *   const fs = openFs(mount);                    // writeFile is a METHOD on the MountFs\n *   await fs.mkdir('photos', { recursive: true }); // writeFile does not create parents\n *   await fs.writeFile(`photos/latest.${mimeType === 'image/png' ? 'png' : 'jpg'}`, new Uint8Array(bytes));\n * } catch (e) {\n *   if ((e as { code?: string }).code === 'cancelled') return; // the user said no\n *   throw e;\n * }\n * ```\n * (The extension follows `mimeType` because the HOST chooses the format — do not assume\n * JPEG. `openAppFs()` is the variant that writes to your own app space with no pick.)\n *\n * Two things must BOTH be true, exactly as for any other task:\n *  1. `immediately.run.invokes` lists `capture-photo` (or `capture-audio`);\n *  2. your app holds `task:invoke` **and** `device:camera` (or `device:microphone`)\n *     — declare them in `immediately.run.capabilities` so the user can grant them.\n *\n * Rejects with `.code`: `cancelled` (the user dismissed the capture — nothing was\n * recorded), `forbidden` (you lack the capability; `message: 'browser-denied'` means\n * the BROWSER refused immediately.run itself, which your consent cannot fix),\n * `unavailable` (no such device on this machine, or it would not start),\n * `unsupported` (this host cannot capture), `not-declared`, `timeout`.\n *\n * *Zero-platform alternative, still worth knowing:* `<input type=\"file\"\n * accept=\"image/*\" capture=\"environment\">` opens the OS camera from inside the\n * sandbox (file choosers are not permission-gated). It needs no capability and no\n * host support; it also gives you no indicator and no host-drawn surface.\n */\nexport const capturePhoto = (options: CaptureOptions = {}): Promise<CaptureResult> =>\n  invokeTask<CaptureResult>('capture-photo', { ...options });\n\n/** Record one audio clip through the host's capture UI. See {@link capturePhoto} —\n *  every rule there applies verbatim, with `device:microphone` and `capture-audio`. */\nexport const captureAudio = (options: CaptureOptions = {}): Promise<CaptureResult> =>\n  invokeTask<CaptureResult>('capture-audio', { ...options });\n\n// ── callee side ─────────────────────────────────────────────────────────────\n\n/** The params this app was invoked with as a task callee. */\nexport interface TaskInput {\n  task: string;\n  params: Record<string, unknown>;\n}\n\nlet latestInput: TaskInput | null = null;\nconst inputListeners = new Set<(i: TaskInput) => void>();\nlet inputListenerRegistered = false;\n\n// Register the `task-input` listener IF a host transport is reachable; otherwise do\n// nothing (and let the next call retry — the same pattern as pushChannel's `start`).\n// Split out so both the module-eval attempt below and the first-use call sites share\n// one idempotent path.\nconst ensureInputListener = (): void => {\n  if (inputListenerRegistered) return;\n  try {\n    addListener(TASK_INPUT, (m: { task: string; params?: Record<string, unknown> }) => {\n      latestInput = { task: m.task, params: m.params ?? {} };\n      inputListeners.forEach((l) => l(latestInput!));\n    });\n  } catch {\n    return; // off-host: the transport resolver threw — no host to listen on\n  }\n  inputListenerRegistered = true;\n};\n\n// The host delivers a `task-input` message to the callee's iframe right after it\n// mounts the overlay (the §5.7 \"params via the region's mount event\"). That wire\n// message is a plain one-shot host→app message with NO replay/poll counterpart —\n// the contract (`@immediately-run/sandbox-protocol/sdk`) marks replayable state as\n// \"push … polled with request-*\" (mounts, theme, auth-state, …) and `task-input`\n// is not one of them — so a listener registered only on first use could miss an\n// input delivered between module evaluation and the app's first render. Hence:\n// register EAGERLY when a host transport is already present at module eval\n// (on-host, byte-for-byte the pre-R3-421 behaviour), and lazily-on-first-use\n// otherwise, so importing this module off-host (plain `vite dev`) never throws.\nensureInputListener();\n\n/** The task params this app was invoked with, or null if it isn't a task callee.\n *  Off-host (plain `vite dev`) this is always `null` — there is no host to invoke\n *  this app as a callee. */\nexport const getTaskInput = (): TaskInput | null => {\n  ensureInputListener();\n  return latestInput;\n};\n\n/**\n * Is a host transport reachable from this realm at all?\n *\n * The R3-421 off-host no-op below must mean EXACTLY \"there is nobody to answer\" —\n * plain `vite dev`, node, jsdom. A blanket try/catch around the send meant it also\n * swallowed a genuine failure against a REAL host (`DataCloneError` because the\n * result holds a DOM node, a function or a live class instance, being the usual\n * one): the host was then never told the task finished, and the caller's\n * `invokeTask` hung to its deadline with no diagnostic anywhere. Absence is\n * therefore decided BEFORE the send, and the send itself is left to throw.\n */\nconst hostReachable = (): boolean => {\n  try {\n    transport();\n    return true;\n  } catch {\n    return false; // no injected bundler bus and no §4 discovery global — off-host\n  }\n};\n\n/**\n * Finish the task, returning a result to the caller. The host validates it against\n * the contract's result schema before resolving the caller (`invalid-params` on\n * violation), then tears down this overlay.\n *\n * `result` must be STRUCTURED-CLONEABLE — it crosses a frame boundary. A DOM node, a\n * function, a class instance with methods, a `MediaStreamTrack`: all `DataCloneError`.\n * **That throws**, deliberately and loudly: the alternative is a caller left hanging to\n * its `invokeTask` deadline while this app believes it answered.\n *\n * Off-host (plain `vite dev` — no host transport) this is a no-op: there is no caller\n * to answer. That case, and only that case, is silent.\n */\nexport const completeTask = (result: unknown): void => {\n  if (!hostReachable()) return; // off-host: no caller to answer — documented no-op\n  // On-host, a failure here is REAL and the caller is waiting on this exact message.\n  sendMessage(TASK_COMPLETE, { result });\n};\n\n/** Abort the task; the caller's `invokeTask` rejects with `cancelled`.\n *  Off-host (plain `vite dev` — no host transport) this is a no-op; on-host a failed\n *  send throws rather than leaving the caller waiting, exactly as {@link completeTask}. */\nexport const cancelTask = (): void => {\n  if (!hostReachable()) return; // off-host: no caller to answer — documented no-op\n  sendMessage(TASK_CANCEL, {});\n};\n\n/** React hook: the task input for this callee, re-rendering when it arrives.\n *  Off-host (plain `vite dev`) it stays `null` forever — render the non-callee\n *  state rather than waiting on it. */\nexport const useTaskInput = (): TaskInput | null => {\n  const [input, setInput] = useState<TaskInput | null>(getTaskInput);\n  useEffect(() => {\n    const l = (i: TaskInput) => setInput(i);\n    inputListeners.add(l);\n    if (latestInput) setInput(latestInput);\n    return () => {\n      inputListeners.delete(l);\n    };\n  }, []);\n  return input;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBA,mBAAoC;AACpC,0BAA0D;AAC1D,2BAA0B;AAC1B,sBAAsE;AACtE,6BAAwB;AAmBjB,MAAM,UAAU,CAAC,KAA2C,UAA0C;AAAA,EAC3G,MAAM;AAAA,EACN,SAAS,IAAI;AAAA,EACb,SAAS,IAAI;AAAA,EACb,MAAM,KAAK;AACb;AAoBO,MAAM,SAAS,CAAC,KAA2C,UAAyC;AAAA,EACzG,MAAM;AAAA,EACN,SAAS,IAAI;AAAA,EACb,SAAS,IAAI;AAAA,EACb,MAAM,KAAK;AACb;AAiDO,MAAM,aAAa,OAAoB,MAAc,SAAkC,CAAC,MAAkB;AAC/G,QAAM,MAAO,UAAM,qCAAgB,+BAAQ,6BAAa,GAAG,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC;AAIvF,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,SAAS,IAAI,UAAU;AAC7D,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AA6EO,MAAM,eAAe,CAAC,UAA0B,CAAC,MACtD,WAA0B,iBAAiB,EAAE,GAAG,QAAQ,CAAC;AAIpD,MAAM,eAAe,CAAC,UAA0B,CAAC,MACtD,WAA0B,iBAAiB,EAAE,GAAG,QAAQ,CAAC;AAU3D,IAAI,cAAgC;AACpC,MAAM,iBAAiB,oBAAI,IAA4B;AACvD,IAAI,0BAA0B;AAM9B,MAAM,sBAAsB,MAAY;AACtC,MAAI,wBAAyB;AAC7B,MAAI;AACF,yCAAY,4BAAY,CAAC,MAA0D;AACjF,oBAAc,EAAE,MAAM,EAAE,MAAM,QAAQ,EAAE,UAAU,CAAC,EAAE;AACrD,qBAAe,QAAQ,CAAC,MAAM,EAAE,WAAY,CAAC;AAAA,IAC/C,CAAC;AAAA,EACH,QAAQ;AACN;AAAA,EACF;AACA,4BAA0B;AAC5B;AAYA,oBAAoB;AAKb,MAAM,eAAe,MAAwB;AAClD,sBAAoB;AACpB,SAAO;AACT;AAaA,MAAM,gBAAgB,MAAe;AACnC,MAAI;AACF,wCAAU;AACV,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAeO,MAAM,eAAe,CAAC,WAA0B;AACrD,MAAI,CAAC,cAAc,EAAG;AAEtB,uCAAY,+BAAe,EAAE,OAAO,CAAC;AACvC;AAKO,MAAM,aAAa,MAAY;AACpC,MAAI,CAAC,cAAc,EAAG;AACtB,uCAAY,6BAAa,CAAC,CAAC;AAC7B;AAKO,MAAM,eAAe,MAAwB;AAClD,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAA2B,YAAY;AACjE,8BAAU,MAAM;AACd,UAAM,IAAI,CAAC,MAAiB,SAAS,CAAC;AACtC,mBAAe,IAAI,CAAC;AACpB,QAAI,YAAa,UAAS,WAAW;AACrC,WAAO,MAAM;AACX,qBAAe,OAAO,CAAC;AAAA,IACzB;AAAA,EACF,GAAG,CAAC,CAAC;AACL,SAAO;AACT;","names":[]}

package/dist/tasks.d.cts

@@ -44,27 +44,156 @@ declare const capDir: (ref: {
 /**
  * Invoke another app via a task contract and await its typed result (Recipe B).
  * Rejects with a machine `.code` on refusal: `cancelled` (user dismissed the
- * overlay), `timeout` (§5.7.1 liveness), `forbidden` (undeclared task or a file
- * delegation you don't hold), `no-such-task`, `task-cycle`/`task-depth-exceeded`/
- * `task-version-mismatch`, or `invalid-params` (result failed the contract schema).
+ * overlay), `timeout` (§5.7.1 liveness), `forbidden` (missing `task:invoke`, or a
+ * file delegation you don't hold), `not-declared` (the task is missing from your
+ * `immediately.run.invokes`), `no-such-task` (no app is bound to that contract),
+ * `task-cycle`/`task-depth-exceeded`/`task-version-mismatch`, or `invalid-params`
+ * (result failed the contract schema). **Read `err.message`** — since R3-418 the host
+ * says which capability, which declaration or which param was at fault; the code alone
+ * does not distinguish them.
+ *
+ * Two things must BOTH be true before any invoke is admitted, and they are separate:
+ *  1. your `package.json` `immediately.run.invokes` lists the task (else `not-declared`);
+ *  2. your app holds the `task:invoke` capability — declare it in
+ *     `immediately.run.capabilities` so the user can grant it (else `forbidden`).
+ * Declaring the invoke does not imply the capability.
+ *
+ * ── `pick-file`: `roots` is required (SPACES_UI_SPEC §4.1) ───────────────────
+ * ```ts
+ * import { invokeTask, capDir, requestMount } from '@immediately-run/sdk';
+ *
+ * const mount = await requestMount();                    // the user picks a space
+ * // `invokeTask` returns `unknown` — name the result type, or the destructuring
+ * // below does not compile.
+ * const { root, path } = await invokeTask<{ root: number; path: string }>('pick-file', {
+ *   // `SandboxMount.id` is optional (absent on the primary repo mount) — fall back to
+ *   // `path`, which is always present and is what the host resolves against.
+ *   roots: [capDir({ mountId: mount.id ?? mount.path, relPath: 'boards' }, { mode: 'ro' })],
+ * });
+ * ```
+ * - `roots` is a NON-EMPTY `DirCap[]` of directories you **already hold**. The result
+ *   names its target as `{ root, path }` where `root` INDEXES `params.roots`, so
+ *   `invokeTask('pick-file', {})` can never produce a valid result and is rejected.
+ *   There is no rootless "pick from any of my spaces" mode by design: enumerating the
+ *   user's spaces is the host's powerbox (`requestMount()`), and composing the two —
+ *   as above — is that flow. See SPACES_UI_SPEC R-SPACES-5/R-SPACES-12.
+ * - Each `capDir` is attenuated against your own grant. **`{ mode: 'rw' }` over a space
+ *   the user granted `ro` is refused `forbidden`** — the commonest failure, because the
+ *   mount *was* granted and the path *is* inside it. Pass the mode you actually hold;
+ *   `ro` is right for a plain pick.
+ * - The `requestMount()` grant is DURABLE and survives a cancelled pick: the user
+ *   consented to the mount in host chrome, separately from the pick (SPACES_UI_SPEC §4.1).
+ *   Reuse it for later picks rather than re-requesting.
+ *
+ * Off-host (plain `vite dev` — no host transport) it rejects with a plain
+ * "no host transport" error: there is no host to resolve the task binding.
  */
 declare const invokeTask: <R = unknown>(task: string, params?: Record<string, unknown>) => Promise<R>;
+/** Bytes captured by the host, as `capturePhoto()` / `captureAudio()` return them.
+ *  `bytes` is a transferable `ArrayBuffer` — write it to a space, decode it, upload
+ *  it. You never receive a `MediaStream` or a `MediaStreamTrack`, and that is not an
+ *  omission: a track cannot be transferred into an app frame at all
+ *  (`DataCloneError`), and the frame's opaque origin cannot open a device itself
+ *  (`getUserMedia` throws `SecurityError: Invalid security origin`). */
+interface CaptureResult {
+    bytes: ArrayBuffer;
+    /** e.g. `image/jpeg`, `audio/webm`. Chosen by the HOST, not by you. */
+    mimeType: string;
+    /** How long the device was open, in ms. */
+    durationMs: number;
+}
+/** Optional hints for a capture. They deliberately name NOTHING — no device id, no
+ *  camera index — because the host chooses everything about how the capture is
+ *  performed. That is what lets the grant be a plain on/off instead of a per-call
+ *  target list the way `net:fetch` needs. */
+interface CaptureOptions {
+    /** Which way the camera should face, if the device has a choice. A HINT: the host
+     *  may ignore it. Ignored for audio. */
+    facing?: 'user' | 'environment';
+}
+/**
+ * Take one photo, or record one audio clip, through the HOST's capture UI
+ * (`BROWSER_CAPABILITIES_SPEC` §3 grade 1).
+ *
+ * The host opens the device at its own origin, draws the viewfinder, and hands you
+ * the bytes when the user presses Done. **You are never in the loop while the device
+ * is live** — that is the point of the design, not a limitation of it:
+ *
+ * - The capture UI is drawn by the host, so a user can trust it the way they trust
+ *   the sign-in dialog. Do not build a lookalike; imitating host chrome is spoofing.
+ * - While the device is open the host shows a persistent "camera on" / "microphone
+ *   on" indicator in its own chrome, for the whole session. You cannot hide it and
+ *   should not try to.
+ * - If the user cancels, this rejects `cancelled` and **nothing was recorded**. There
+ *   is no partial result — do not write error handling that hopes for one.
+ *
+ * ```ts
+ * import { capturePhoto, requestMount, openFs } from '@immediately-run/sdk';
+ *
+ * try {
+ *   const { bytes, mimeType } = await capturePhoto({ facing: 'environment' });
+ *   const mount = await requestMount();          // the user picks a space to save into
+ *   const fs = openFs(mount);                    // writeFile is a METHOD on the MountFs
+ *   await fs.mkdir('photos', { recursive: true }); // writeFile does not create parents
+ *   await fs.writeFile(`photos/latest.${mimeType === 'image/png' ? 'png' : 'jpg'}`, new Uint8Array(bytes));
+ * } catch (e) {
+ *   if ((e as { code?: string }).code === 'cancelled') return; // the user said no
+ *   throw e;
+ * }
+ * ```
+ * (The extension follows `mimeType` because the HOST chooses the format — do not assume
+ * JPEG. `openAppFs()` is the variant that writes to your own app space with no pick.)
+ *
+ * Two things must BOTH be true, exactly as for any other task:
+ *  1. `immediately.run.invokes` lists `capture-photo` (or `capture-audio`);
+ *  2. your app holds `task:invoke` **and** `device:camera` (or `device:microphone`)
+ *     — declare them in `immediately.run.capabilities` so the user can grant them.
+ *
+ * Rejects with `.code`: `cancelled` (the user dismissed the capture — nothing was
+ * recorded), `forbidden` (you lack the capability; `message: 'browser-denied'` means
+ * the BROWSER refused immediately.run itself, which your consent cannot fix),
+ * `unavailable` (no such device on this machine, or it would not start),
+ * `unsupported` (this host cannot capture), `not-declared`, `timeout`.
+ *
+ * *Zero-platform alternative, still worth knowing:* `<input type="file"
+ * accept="image/*" capture="environment">` opens the OS camera from inside the
+ * sandbox (file choosers are not permission-gated). It needs no capability and no
+ * host support; it also gives you no indicator and no host-drawn surface.
+ */
+declare const capturePhoto: (options?: CaptureOptions) => Promise<CaptureResult>;
+/** Record one audio clip through the host's capture UI. See {@link capturePhoto} —
+ *  every rule there applies verbatim, with `device:microphone` and `capture-audio`. */
+declare const captureAudio: (options?: CaptureOptions) => Promise<CaptureResult>;
 /** The params this app was invoked with as a task callee. */
 interface TaskInput {
     task: string;
     params: Record<string, unknown>;
 }
-/** The task params this app was invoked with, or null if it isn't a task callee. */
+/** The task params this app was invoked with, or null if it isn't a task callee.
+ *  Off-host (plain `vite dev`) this is always `null` — there is no host to invoke
+ *  this app as a callee. */
 declare const getTaskInput: () => TaskInput | null;
 /**
  * Finish the task, returning a result to the caller. The host validates it against
  * the contract's result schema before resolving the caller (`invalid-params` on
  * violation), then tears down this overlay.
+ *
+ * `result` must be STRUCTURED-CLONEABLE — it crosses a frame boundary. A DOM node, a
+ * function, a class instance with methods, a `MediaStreamTrack`: all `DataCloneError`.
+ * **That throws**, deliberately and loudly: the alternative is a caller left hanging to
+ * its `invokeTask` deadline while this app believes it answered.
+ *
+ * Off-host (plain `vite dev` — no host transport) this is a no-op: there is no caller
+ * to answer. That case, and only that case, is silent.
  */
 declare const completeTask: (result: unknown) => void;
-/** Abort the task; the caller's `invokeTask` rejects with `cancelled`. */
+/** Abort the task; the caller's `invokeTask` rejects with `cancelled`.
+ *  Off-host (plain `vite dev` — no host transport) this is a no-op; on-host a failed
+ *  send throws rather than leaving the caller waiting, exactly as {@link completeTask}. */
 declare const cancelTask: () => void;
-/** React hook: the task input for this callee, re-rendering when it arrives. */
+/** React hook: the task input for this callee, re-rendering when it arrives.
+ *  Off-host (plain `vite dev`) it stays `null` forever — render the non-callee
+ *  state rather than waiting on it. */
 declare const useTaskInput: () => TaskInput | null;
 
-export { type DirCap, type FileCap, type TaskInput, cancelTask, capDir, capFile, completeTask, getTaskInput, invokeTask, useTaskInput };
+export { type CaptureOptions, type CaptureResult, type DirCap, type FileCap, type TaskInput, cancelTask, capDir, capFile, captureAudio, capturePhoto, completeTask, getTaskInput, invokeTask, useTaskInput };