@immediately-run/sdk 0.45.3 → 0.47.0

package/dist/sandboxUtils.cjs

@@ -18,39 +18,84 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var sandboxUtils_exports = {};
 __export(sandboxUtils_exports, {
-  addListener: () => addListener,
+  addListener: () => import_hostTransport2.addListener,
   protocolRequest: () => protocolRequest,
-  sendMessage: () => sendMessage
+  sendMessage: () => import_hostTransport2.sendMessage,
+  withDeadline: () => withDeadline
 });
 module.exports = __toCommonJS(sandboxUtils_exports);
-var import_hostRuntime = require("./hostRuntime");
-function transport() {
+var import_hostTransport = require("./hostTransport");
+var import_hostAttention = require("./hostAttention");
+var import_protocolDeadline = require("./protocolDeadline");
+var import_hostTransport2 = require("./hostTransport");
+const protocolRequest = (protocolName, method, params, opts) => withDeadline(protocolName, method, () => (0, import_hostTransport.transport)().protocolRequest(protocolName, method, params), opts);
+async function withDeadline(scheme, method, start, opts) {
+  const call = `${scheme}:${method}`;
+  const attendance = (0, import_protocolDeadline.attendanceOf)(scheme, method);
+  const bounds = opts?.timeoutMs !== void 0 ? { idleMs: opts.timeoutMs, ceilingMs: opts.timeoutMs } : (0, import_protocolDeadline.boundsFor)(scheme, method);
+  const signal = opts?.signal;
+  if (signal?.aborted) throw new import_protocolDeadline.ProtocolCancelledError(call);
+  const work = start();
+  if (!Number.isFinite(bounds.ceilingMs) && !signal && !opts?.onPending) return work;
+  let deadline;
+  let notice;
+  let unsubscribeAttention;
+  let onAbort;
+  const started = Date.now();
   try {
-    const injected = module?.evaluation?.module?.bundler?.messageBus;
-    if (injected && typeof injected.sendMessage === "function") return injected;
-  } catch {
+    return await new Promise((resolve, reject) => {
+      work.then(resolve, reject);
+      let attention;
+      let noticeFired = false;
+      const fireNotice = () => {
+        try {
+          opts?.onPending?.({
+            call,
+            attendance,
+            elapsedMs: Date.now() - started,
+            ...(0, import_protocolDeadline.attendanceReason)(scheme, method) ? { reason: (0, import_protocolDeadline.attendanceReason)(scheme, method) } : {},
+            ...attention?.awaiting ? { awaiting: { kind: attention.kind, since: attention.since } } : {}
+          });
+        } catch {
+        }
+      };
+      deadline = (0, import_protocolDeadline.createSuspendableDeadline)({
+        bounds,
+        onExpire: (bound, elapsedBoundMs) => reject(new import_protocolDeadline.ProtocolTimeoutError(call, elapsedBoundMs, attendance, bound))
+      });
+      if (opts?.onPending) {
+        notice = setTimeout(() => {
+          noticeFired = true;
+          fireNotice();
+        }, import_protocolDeadline.PENDING_NOTICE_MS);
+      }
+      try {
+        unsubscribeAttention = (0, import_hostAttention.onHostAttentionChange)((next) => {
+          const wasAwaiting = attention?.awaiting ?? false;
+          attention = next;
+          deadline?.setAwaiting(next.awaiting);
+          if (noticeFired && next.awaiting !== wasAwaiting) fireNotice();
+        });
+      } catch {
+      }
+      if (signal) {
+        onAbort = () => reject(new import_protocolDeadline.ProtocolCancelledError(call));
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+  } finally {
+    deadline?.dispose();
+    if (notice !== void 0) clearTimeout(notice);
+    unsubscribeAttention?.();
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+    work.catch(() => void 0);
   }
-  const t = (0, import_hostRuntime.getHostRuntime)()?.transport;
-  if (t && typeof t.sendMessage === "function") return t;
-  throw new Error("immediately.run: no host transport (neither injected nor __immediatelyRun__)");
 }
-const sendMessage = (type, data = {}) => {
-  transport().sendMessage(type, data);
-};
-const protocolRequest = (protocolName, method, params) => transport().protocolRequest(protocolName, method, params);
-const addListener = (msgType, handler, event) => {
-  const onMessage = event ?? transport().onMessage;
-  const disposable = onMessage((msg) => {
-    if (msg.type === msgType) {
-      handler(msg);
-    }
-  });
-  return () => disposable.dispose();
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   addListener,
   protocolRequest,
-  sendMessage
+  sendMessage,
+  withDeadline
 });
 //# sourceMappingURL=sandboxUtils.cjs.map

package/dist/sandboxUtils.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sandboxUtils.ts"],"sourcesContent":["// Host transport access (SDK_PACKAGING_SPEC §4, expose-transport). All host comms\n// (sendMessage / protocolRequest / onMessage) go through ONE resolver so the SDK is\n// transport-agnostic: it works whether it was INJECTED into the bundler's evaluation\n// context (the current path — `module.evaluation.module.bundler.messageBus`) OR\n// fetched from npm as an ordinary dependency, in which case the sandbox runtime hands\n// it the transport via the §4 discovery global (`globalThis.__immediatelyRun__`).\n//\n// Dual-mode (§8): injection wins while it's active, so existing behaviour is\n// byte-for-byte preserved; the global is the fallback the npm-fetched SDK uses. When\n// injection is removed (phase 3), only the global path remains — `bundler.*` stops\n// being API, which is the whole point.\nimport { getHostRuntime } from './hostRuntime';\n\ninterface HostTransport {\n  sendMessage(type: string, data?: Record<string, any>): void;\n  protocolRequest(protocolName: string, method: string, params: Array<any>): Promise<any>;\n  onMessage(handler: (msg: any) => void): { dispose(): void };\n}\n\nfunction transport(): HostTransport {\n  // Injected bundler messageBus first — the current path, unchanged.\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    const injected = module?.evaluation?.module?.bundler?.messageBus;\n    if (injected && typeof injected.sendMessage === 'function') return injected;\n  } catch {\n    /* no injection in this realm — fall through to the §4 global */\n  }\n  // §4 runtime-discovery transport (the npm-fetched SDK path).\n  const t = getHostRuntime()?.transport as HostTransport | undefined;\n  if (t && typeof t.sendMessage === 'function') return t;\n  throw new Error('immediately.run: no host transport (neither injected nor __immediatelyRun__)');\n}\n\nexport const sendMessage = (type: string, data: Record<string, any> = {}) => {\n  transport().sendMessage(type, data);\n};\n\nexport const protocolRequest = (\n  protocolName: string,\n  method: string,\n  params: Array<any>,\n): Promise<any> => transport().protocolRequest(protocolName, method, params);\n\nexport const addListener = (\n  msgType: string,\n  handler: (msg: any) => void,\n  event?: any,\n): (() => void) => {\n  const onMessage = event ?? transport().onMessage;\n  const disposable = onMessage((msg: any) => {\n    if (msg.type === msgType) {\n      handler(msg);\n    }\n  });\n  return () => disposable.dispose();\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,yBAA+B;AAQ/B,SAAS,YAA2B;AAElC,MAAI;AAEF,UAAM,WAAW,QAAQ,YAAY,QAAQ,SAAS;AACtD,QAAI,YAAY,OAAO,SAAS,gBAAgB,WAAY,QAAO;AAAA,EACrE,QAAQ;AAAA,EAER;AAEA,QAAM,QAAI,mCAAe,GAAG;AAC5B,MAAI,KAAK,OAAO,EAAE,gBAAgB,WAAY,QAAO;AACrD,QAAM,IAAI,MAAM,8EAA8E;AAChG;AAEO,MAAM,cAAc,CAAC,MAAc,OAA4B,CAAC,MAAM;AAC3E,YAAU,EAAE,YAAY,MAAM,IAAI;AACpC;AAEO,MAAM,kBAAkB,CAC7B,cACA,QACA,WACiB,UAAU,EAAE,gBAAgB,cAAc,QAAQ,MAAM;AAEpE,MAAM,cAAc,CACzB,SACA,SACA,UACiB;AACjB,QAAM,YAAY,SAAS,UAAU,EAAE;AACvC,QAAM,aAAa,UAAU,CAAC,QAAa;AACzC,QAAI,IAAI,SAAS,SAAS;AACxB,cAAQ,GAAG;AAAA,IACb;AAAA,EACF,CAAC;AACD,SAAO,MAAM,WAAW,QAAQ;AAClC;","names":[]}
+{"version":3,"sources":["../src/sandboxUtils.ts"],"sourcesContent":["// Bounded host calls (R3-298) + the host-attention-aware deadline (R3-307).\n//\n// The transport primitives this builds on moved to `hostTransport.ts` — see that file for\n// why. `sendMessage` and `addListener` are re-exported here unchanged, so every existing\n// import site (and this module's api-snapshot entry) is exactly as it was.\nimport { transport } from './hostTransport';\nimport { onHostAttentionChange, type HostAttention } from './hostAttention';\n\nimport {\n  attendanceOf,\n  attendanceReason,\n  boundsFor,\n  createSuspendableDeadline,\n  PENDING_NOTICE_MS,\n  ProtocolCancelledError,\n  ProtocolTimeoutError,\n  type BoundedCallOptions,\n  type CallBounds,\n} from './protocolDeadline';\n\nexport { sendMessage, addListener } from './hostTransport';\n\n/**\n * One host protocol request, BOUNDED (R3-298).\n *\n * The bound comes from the call's classification (`protocolDeadline.ts`): an unattended\n * channel round-trip gets tens of seconds, a call that may draw host chrome and wait for a\n * person gets minutes. Nothing is unbounded — an unbounded wait is the failure this fixes.\n *\n * Since R3-307 a call whose prompts the host actually announces runs on the SHORT bound and\n * is suspended only while the host says a person is being asked, so the common\n * grant-already-held path reports a fault in seconds instead of minutes. The absolute\n * ceiling still applies: the signal may extend a deadline, never remove it.\n *\n * The host's own work is NOT cancelled by `signal` or by the deadline. The one-shot\n * transport allocates its `msgId` internally, so the SDK has no handle to send the host a\n * cancel for (streams do, and `consumeStream` uses it). What the caller gets back is\n * control: it stops waiting and gets a typed error instead of hanging. A host prompt that\n * is already on screen stays there until the user dismisses it, which is correct — the SDK\n * must not be able to tear down host chrome the user is looking at.\n */\nexport const protocolRequest = (\n  protocolName: string,\n  method: string,\n  params: Array<any>,\n  opts?: BoundedCallOptions,\n): Promise<any> =>\n  withDeadline(protocolName, method, () => transport().protocolRequest(protocolName, method, params), opts);\n\n/**\n * Race a host call against its deadline, a caller abort, and a pending notice.\n *\n * Kept separate from the transport so it is unit-testable against a promise that simply\n * never settles — which is the whole scenario, and one no live transport reproduces on\n * demand.\n *\n * An explicit `opts.timeoutMs` is the WHOLE bound and is never suspended: a caller that\n * names a number owns the wait, and silently stretching it past what they asked for would\n * be the same class of surprise this machinery exists to remove.\n */\nexport async function withDeadline<T>(\n  scheme: string,\n  method: string,\n  start: () => Promise<T>,\n  opts?: BoundedCallOptions,\n): Promise<T> {\n  const call = `${scheme}:${method}`;\n  const attendance = attendanceOf(scheme, method);\n  const bounds: CallBounds =\n    opts?.timeoutMs !== undefined ? { idleMs: opts.timeoutMs, ceilingMs: opts.timeoutMs } : boundsFor(scheme, method);\n  const signal = opts?.signal;\n\n  if (signal?.aborted) throw new ProtocolCancelledError(call);\n\n  const work = start();\n  // No bound and no abort wanted: hand back the untouched promise rather than wrapping it\n  // in timers that would never fire.\n  if (!Number.isFinite(bounds.ceilingMs) && !signal && !opts?.onPending) return work;\n\n  let deadline: { setAwaiting: (a: boolean) => void; dispose: () => void } | undefined;\n  let notice: ReturnType<typeof setTimeout> | undefined;\n  let unsubscribeAttention: (() => void) | undefined;\n  let onAbort: (() => void) | undefined;\n  const started = Date.now();\n\n  try {\n    return await new Promise<T>((resolve, reject) => {\n      // `work` settling always wins — a call that answered a millisecond before its\n      // deadline must not be reported as a timeout.\n      work.then(resolve, reject);\n\n      // The host's live \"a person is being asked\" signal. Read defensively: a host that\n      // never pushes the channel leaves this at \"not awaiting\", which is exactly the\n      // pre-R3-307 behaviour for a call on its idle bound.\n      let attention: HostAttention | undefined;\n      let noticeFired = false;\n      const fireNotice = () => {\n        try {\n          opts?.onPending?.({\n            call,\n            attendance,\n            elapsedMs: Date.now() - started,\n            ...(attendanceReason(scheme, method) ? { reason: attendanceReason(scheme, method) as string } : {}),\n            ...(attention?.awaiting ? { awaiting: { kind: attention.kind, since: attention.since } } : {}),\n          });\n        } catch {\n          /* a caller's render callback must never break the call it describes */\n        }\n      };\n\n      deadline = createSuspendableDeadline({\n        bounds,\n        onExpire: (bound, elapsedBoundMs) => reject(new ProtocolTimeoutError(call, elapsedBoundMs, attendance, bound)),\n      });\n\n      if (opts?.onPending) {\n        notice = setTimeout(() => {\n          noticeFired = true;\n          fireNotice();\n        }, PENDING_NOTICE_MS);\n      }\n\n      // Subscribing invokes the listener immediately with the current value, so the\n      // deadline starts in the right state even if a prompt was already up.\n      //\n      // Guarded because this sits on the path of EVERY host call: a fault in the attention\n      // channel must degrade to \"no signal\" (the pre-R3-307 behaviour, bounds unsuspended),\n      // never take down every request in the SDK.\n      try {\n        unsubscribeAttention = onHostAttentionChange((next) => {\n          const wasAwaiting = attention?.awaiting ?? false;\n          attention = next;\n          deadline?.setAwaiting(next.awaiting);\n          // Re-notify once the notice has fired: \"still waiting\" → \"tap your passkey\" is\n          // the whole point, and a caller rendering a waiting state wants the live\n          // sentence, not the one that was true three seconds in.\n          if (noticeFired && next.awaiting !== wasAwaiting) fireNotice();\n        });\n      } catch {\n        /* no attention signal available — the bounds simply never suspend */\n      }\n\n      if (signal) {\n        onAbort = () => reject(new ProtocolCancelledError(call));\n        signal.addEventListener('abort', onAbort, { once: true });\n      }\n    });\n  } finally {\n    deadline?.dispose();\n    if (notice !== undefined) clearTimeout(notice);\n    unsubscribeAttention?.();\n    if (signal && onAbort) signal.removeEventListener('abort', onAbort);\n    // The host may still answer after we stopped waiting; swallow it so a late rejection\n    // does not surface as an unhandled promise rejection in the app's console.\n    work.catch(() => undefined);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,2BAA0B;AAC1B,2BAA0D;AAE1D,8BAUO;AAEP,IAAAA,wBAAyC;AAqBlC,MAAM,kBAAkB,CAC7B,cACA,QACA,QACA,SAEA,aAAa,cAAc,QAAQ,UAAM,gCAAU,EAAE,gBAAgB,cAAc,QAAQ,MAAM,GAAG,IAAI;AAa1G,eAAsB,aACpB,QACA,QACA,OACA,MACY;AACZ,QAAM,OAAO,GAAG,MAAM,IAAI,MAAM;AAChC,QAAM,iBAAa,sCAAa,QAAQ,MAAM;AAC9C,QAAM,SACJ,MAAM,cAAc,SAAY,EAAE,QAAQ,KAAK,WAAW,WAAW,KAAK,UAAU,QAAI,mCAAU,QAAQ,MAAM;AAClH,QAAM,SAAS,MAAM;AAErB,MAAI,QAAQ,QAAS,OAAM,IAAI,+CAAuB,IAAI;AAE1D,QAAM,OAAO,MAAM;AAGnB,MAAI,CAAC,OAAO,SAAS,OAAO,SAAS,KAAK,CAAC,UAAU,CAAC,MAAM,UAAW,QAAO;AAE9E,MAAI;AACJ,MAAI;AACJ,MAAI;AACJ,MAAI;AACJ,QAAM,UAAU,KAAK,IAAI;AAEzB,MAAI;AACF,WAAO,MAAM,IAAI,QAAW,CAAC,SAAS,WAAW;AAG/C,WAAK,KAAK,SAAS,MAAM;AAKzB,UAAI;AACJ,UAAI,cAAc;AAClB,YAAM,aAAa,MAAM;AACvB,YAAI;AACF,gBAAM,YAAY;AAAA,YAChB;AAAA,YACA;AAAA,YACA,WAAW,KAAK,IAAI,IAAI;AAAA,YACxB,OAAI,0CAAiB,QAAQ,MAAM,IAAI,EAAE,YAAQ,0CAAiB,QAAQ,MAAM,EAAY,IAAI,CAAC;AAAA,YACjG,GAAI,WAAW,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,MAAM,OAAO,UAAU,MAAM,EAAE,IAAI,CAAC;AAAA,UAC9F,CAAC;AAAA,QACH,QAAQ;AAAA,QAER;AAAA,MACF;AAEA,qBAAW,mDAA0B;AAAA,QACnC;AAAA,QACA,UAAU,CAAC,OAAO,mBAAmB,OAAO,IAAI,6CAAqB,MAAM,gBAAgB,YAAY,KAAK,CAAC;AAAA,MAC/G,CAAC;AAED,UAAI,MAAM,WAAW;AACnB,iBAAS,WAAW,MAAM;AACxB,wBAAc;AACd,qBAAW;AAAA,QACb,GAAG,yCAAiB;AAAA,MACtB;AAQA,UAAI;AACF,mCAAuB,4CAAsB,CAAC,SAAS;AACrD,gBAAM,cAAc,WAAW,YAAY;AAC3C,sBAAY;AACZ,oBAAU,YAAY,KAAK,QAAQ;AAInC,cAAI,eAAe,KAAK,aAAa,YAAa,YAAW;AAAA,QAC/D,CAAC;AAAA,MACH,QAAQ;AAAA,MAER;AAEA,UAAI,QAAQ;AACV,kBAAU,MAAM,OAAO,IAAI,+CAAuB,IAAI,CAAC;AACvD,eAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;AAAA,MAC1D;AAAA,IACF,CAAC;AAAA,EACH,UAAE;AACA,cAAU,QAAQ;AAClB,QAAI,WAAW,OAAW,cAAa,MAAM;AAC7C,2BAAuB;AACvB,QAAI,UAAU,QAAS,QAAO,oBAAoB,SAAS,OAAO;AAGlE,SAAK,MAAM,MAAM,MAAS;AAAA,EAC5B;AACF;","names":["import_hostTransport"]}

package/dist/sandboxUtils.d.cts

@@ -1,5 +1,38 @@
-declare const sendMessage: (type: string, data?: Record<string, any>) => void;
-declare const protocolRequest: (protocolName: string, method: string, params: Array<any>) => Promise<any>;
-declare const addListener: (msgType: string, handler: (msg: any) => void, event?: any) => (() => void);
+import { BoundedCallOptions } from './protocolDeadline.cjs';
+export { addListener, sendMessage } from './hostTransport.cjs';
+import './hostAttention.cjs';
 
-export { addListener, protocolRequest, sendMessage };
+/**
+ * One host protocol request, BOUNDED (R3-298).
+ *
+ * The bound comes from the call's classification (`protocolDeadline.ts`): an unattended
+ * channel round-trip gets tens of seconds, a call that may draw host chrome and wait for a
+ * person gets minutes. Nothing is unbounded — an unbounded wait is the failure this fixes.
+ *
+ * Since R3-307 a call whose prompts the host actually announces runs on the SHORT bound and
+ * is suspended only while the host says a person is being asked, so the common
+ * grant-already-held path reports a fault in seconds instead of minutes. The absolute
+ * ceiling still applies: the signal may extend a deadline, never remove it.
+ *
+ * The host's own work is NOT cancelled by `signal` or by the deadline. The one-shot
+ * transport allocates its `msgId` internally, so the SDK has no handle to send the host a
+ * cancel for (streams do, and `consumeStream` uses it). What the caller gets back is
+ * control: it stops waiting and gets a typed error instead of hanging. A host prompt that
+ * is already on screen stays there until the user dismisses it, which is correct — the SDK
+ * must not be able to tear down host chrome the user is looking at.
+ */
+declare const protocolRequest: (protocolName: string, method: string, params: Array<any>, opts?: BoundedCallOptions) => Promise<any>;
+/**
+ * Race a host call against its deadline, a caller abort, and a pending notice.
+ *
+ * Kept separate from the transport so it is unit-testable against a promise that simply
+ * never settles — which is the whole scenario, and one no live transport reproduces on
+ * demand.
+ *
+ * An explicit `opts.timeoutMs` is the WHOLE bound and is never suspended: a caller that
+ * names a number owns the wait, and silently stretching it past what they asked for would
+ * be the same class of surprise this machinery exists to remove.
+ */
+declare function withDeadline<T>(scheme: string, method: string, start: () => Promise<T>, opts?: BoundedCallOptions): Promise<T>;
+
+export { protocolRequest, withDeadline };

package/dist/sandboxUtils.d.ts

@@ -1,5 +1,38 @@
-declare const sendMessage: (type: string, data?: Record<string, any>) => void;
-declare const protocolRequest: (protocolName: string, method: string, params: Array<any>) => Promise<any>;
-declare const addListener: (msgType: string, handler: (msg: any) => void, event?: any) => (() => void);
+import { BoundedCallOptions } from './protocolDeadline.js';
+export { addListener, sendMessage } from './hostTransport.js';
+import './hostAttention.js';
 
-export { addListener, protocolRequest, sendMessage };
+/**
+ * One host protocol request, BOUNDED (R3-298).
+ *
+ * The bound comes from the call's classification (`protocolDeadline.ts`): an unattended
+ * channel round-trip gets tens of seconds, a call that may draw host chrome and wait for a
+ * person gets minutes. Nothing is unbounded — an unbounded wait is the failure this fixes.
+ *
+ * Since R3-307 a call whose prompts the host actually announces runs on the SHORT bound and
+ * is suspended only while the host says a person is being asked, so the common
+ * grant-already-held path reports a fault in seconds instead of minutes. The absolute
+ * ceiling still applies: the signal may extend a deadline, never remove it.
+ *
+ * The host's own work is NOT cancelled by `signal` or by the deadline. The one-shot
+ * transport allocates its `msgId` internally, so the SDK has no handle to send the host a
+ * cancel for (streams do, and `consumeStream` uses it). What the caller gets back is
+ * control: it stops waiting and gets a typed error instead of hanging. A host prompt that
+ * is already on screen stays there until the user dismisses it, which is correct — the SDK
+ * must not be able to tear down host chrome the user is looking at.
+ */
+declare const protocolRequest: (protocolName: string, method: string, params: Array<any>, opts?: BoundedCallOptions) => Promise<any>;
+/**
+ * Race a host call against its deadline, a caller abort, and a pending notice.
+ *
+ * Kept separate from the transport so it is unit-testable against a promise that simply
+ * never settles — which is the whole scenario, and one no live transport reproduces on
+ * demand.
+ *
+ * An explicit `opts.timeoutMs` is the WHOLE bound and is never suspended: a caller that
+ * names a number owns the wait, and silently stretching it past what they asked for would
+ * be the same class of surprise this machinery exists to remove.
+ */
+declare function withDeadline<T>(scheme: string, method: string, start: () => Promise<T>, opts?: BoundedCallOptions): Promise<T>;
+
+export { protocolRequest, withDeadline };

package/dist/sandboxUtils.js

@@ -1,31 +1,83 @@
 import "./chunk-VHAA22YE.js";
-import { getHostRuntime } from "./hostRuntime";
-function transport() {
+import { transport } from "./hostTransport";
+import { onHostAttentionChange } from "./hostAttention";
+import {
+  attendanceOf,
+  attendanceReason,
+  boundsFor,
+  createSuspendableDeadline,
+  PENDING_NOTICE_MS,
+  ProtocolCancelledError,
+  ProtocolTimeoutError
+} from "./protocolDeadline";
+import { sendMessage, addListener } from "./hostTransport";
+const protocolRequest = (protocolName, method, params, opts) => withDeadline(protocolName, method, () => transport().protocolRequest(protocolName, method, params), opts);
+async function withDeadline(scheme, method, start, opts) {
+  const call = `${scheme}:${method}`;
+  const attendance = attendanceOf(scheme, method);
+  const bounds = opts?.timeoutMs !== void 0 ? { idleMs: opts.timeoutMs, ceilingMs: opts.timeoutMs } : boundsFor(scheme, method);
+  const signal = opts?.signal;
+  if (signal?.aborted) throw new ProtocolCancelledError(call);
+  const work = start();
+  if (!Number.isFinite(bounds.ceilingMs) && !signal && !opts?.onPending) return work;
+  let deadline;
+  let notice;
+  let unsubscribeAttention;
+  let onAbort;
+  const started = Date.now();
   try {
-    const injected = module?.evaluation?.module?.bundler?.messageBus;
-    if (injected && typeof injected.sendMessage === "function") return injected;
-  } catch {
+    return await new Promise((resolve, reject) => {
+      work.then(resolve, reject);
+      let attention;
+      let noticeFired = false;
+      const fireNotice = () => {
+        try {
+          opts?.onPending?.({
+            call,
+            attendance,
+            elapsedMs: Date.now() - started,
+            ...attendanceReason(scheme, method) ? { reason: attendanceReason(scheme, method) } : {},
+            ...attention?.awaiting ? { awaiting: { kind: attention.kind, since: attention.since } } : {}
+          });
+        } catch {
+        }
+      };
+      deadline = createSuspendableDeadline({
+        bounds,
+        onExpire: (bound, elapsedBoundMs) => reject(new ProtocolTimeoutError(call, elapsedBoundMs, attendance, bound))
+      });
+      if (opts?.onPending) {
+        notice = setTimeout(() => {
+          noticeFired = true;
+          fireNotice();
+        }, PENDING_NOTICE_MS);
+      }
+      try {
+        unsubscribeAttention = onHostAttentionChange((next) => {
+          const wasAwaiting = attention?.awaiting ?? false;
+          attention = next;
+          deadline?.setAwaiting(next.awaiting);
+          if (noticeFired && next.awaiting !== wasAwaiting) fireNotice();
+        });
+      } catch {
+      }
+      if (signal) {
+        onAbort = () => reject(new ProtocolCancelledError(call));
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+  } finally {
+    deadline?.dispose();
+    if (notice !== void 0) clearTimeout(notice);
+    unsubscribeAttention?.();
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+    work.catch(() => void 0);
   }
-  const t = getHostRuntime()?.transport;
-  if (t && typeof t.sendMessage === "function") return t;
-  throw new Error("immediately.run: no host transport (neither injected nor __immediatelyRun__)");
 }
-const sendMessage = (type, data = {}) => {
-  transport().sendMessage(type, data);
-};
-const protocolRequest = (protocolName, method, params) => transport().protocolRequest(protocolName, method, params);
-const addListener = (msgType, handler, event) => {
-  const onMessage = event ?? transport().onMessage;
-  const disposable = onMessage((msg) => {
-    if (msg.type === msgType) {
-      handler(msg);
-    }
-  });
-  return () => disposable.dispose();
-};
 export {
   addListener,
   protocolRequest,
-  sendMessage
+  sendMessage,
+  withDeadline
 };
 //# sourceMappingURL=sandboxUtils.js.map

package/dist/sandboxUtils.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sandboxUtils.ts"],"sourcesContent":["// Host transport access (SDK_PACKAGING_SPEC §4, expose-transport). All host comms\n// (sendMessage / protocolRequest / onMessage) go through ONE resolver so the SDK is\n// transport-agnostic: it works whether it was INJECTED into the bundler's evaluation\n// context (the current path — `module.evaluation.module.bundler.messageBus`) OR\n// fetched from npm as an ordinary dependency, in which case the sandbox runtime hands\n// it the transport via the §4 discovery global (`globalThis.__immediatelyRun__`).\n//\n// Dual-mode (§8): injection wins while it's active, so existing behaviour is\n// byte-for-byte preserved; the global is the fallback the npm-fetched SDK uses. When\n// injection is removed (phase 3), only the global path remains — `bundler.*` stops\n// being API, which is the whole point.\nimport { getHostRuntime } from './hostRuntime';\n\ninterface HostTransport {\n  sendMessage(type: string, data?: Record<string, any>): void;\n  protocolRequest(protocolName: string, method: string, params: Array<any>): Promise<any>;\n  onMessage(handler: (msg: any) => void): { dispose(): void };\n}\n\nfunction transport(): HostTransport {\n  // Injected bundler messageBus first — the current path, unchanged.\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    const injected = module?.evaluation?.module?.bundler?.messageBus;\n    if (injected && typeof injected.sendMessage === 'function') return injected;\n  } catch {\n    /* no injection in this realm — fall through to the §4 global */\n  }\n  // §4 runtime-discovery transport (the npm-fetched SDK path).\n  const t = getHostRuntime()?.transport as HostTransport | undefined;\n  if (t && typeof t.sendMessage === 'function') return t;\n  throw new Error('immediately.run: no host transport (neither injected nor __immediatelyRun__)');\n}\n\nexport const sendMessage = (type: string, data: Record<string, any> = {}) => {\n  transport().sendMessage(type, data);\n};\n\nexport const protocolRequest = (\n  protocolName: string,\n  method: string,\n  params: Array<any>,\n): Promise<any> => transport().protocolRequest(protocolName, method, params);\n\nexport const addListener = (\n  msgType: string,\n  handler: (msg: any) => void,\n  event?: any,\n): (() => void) => {\n  const onMessage = event ?? transport().onMessage;\n  const disposable = onMessage((msg: any) => {\n    if (msg.type === msgType) {\n      handler(msg);\n    }\n  });\n  return () => disposable.dispose();\n};\n"],"mappings":";AAWA,SAAS,sBAAsB;AAQ/B,SAAS,YAA2B;AAElC,MAAI;AAEF,UAAM,WAAW,QAAQ,YAAY,QAAQ,SAAS;AACtD,QAAI,YAAY,OAAO,SAAS,gBAAgB,WAAY,QAAO;AAAA,EACrE,QAAQ;AAAA,EAER;AAEA,QAAM,IAAI,eAAe,GAAG;AAC5B,MAAI,KAAK,OAAO,EAAE,gBAAgB,WAAY,QAAO;AACrD,QAAM,IAAI,MAAM,8EAA8E;AAChG;AAEO,MAAM,cAAc,CAAC,MAAc,OAA4B,CAAC,MAAM;AAC3E,YAAU,EAAE,YAAY,MAAM,IAAI;AACpC;AAEO,MAAM,kBAAkB,CAC7B,cACA,QACA,WACiB,UAAU,EAAE,gBAAgB,cAAc,QAAQ,MAAM;AAEpE,MAAM,cAAc,CACzB,SACA,SACA,UACiB;AACjB,QAAM,YAAY,SAAS,UAAU,EAAE;AACvC,QAAM,aAAa,UAAU,CAAC,QAAa;AACzC,QAAI,IAAI,SAAS,SAAS;AACxB,cAAQ,GAAG;AAAA,IACb;AAAA,EACF,CAAC;AACD,SAAO,MAAM,WAAW,QAAQ;AAClC;","names":[]}
+{"version":3,"sources":["../src/sandboxUtils.ts"],"sourcesContent":["// Bounded host calls (R3-298) + the host-attention-aware deadline (R3-307).\n//\n// The transport primitives this builds on moved to `hostTransport.ts` — see that file for\n// why. `sendMessage` and `addListener` are re-exported here unchanged, so every existing\n// import site (and this module's api-snapshot entry) is exactly as it was.\nimport { transport } from './hostTransport';\nimport { onHostAttentionChange, type HostAttention } from './hostAttention';\n\nimport {\n  attendanceOf,\n  attendanceReason,\n  boundsFor,\n  createSuspendableDeadline,\n  PENDING_NOTICE_MS,\n  ProtocolCancelledError,\n  ProtocolTimeoutError,\n  type BoundedCallOptions,\n  type CallBounds,\n} from './protocolDeadline';\n\nexport { sendMessage, addListener } from './hostTransport';\n\n/**\n * One host protocol request, BOUNDED (R3-298).\n *\n * The bound comes from the call's classification (`protocolDeadline.ts`): an unattended\n * channel round-trip gets tens of seconds, a call that may draw host chrome and wait for a\n * person gets minutes. Nothing is unbounded — an unbounded wait is the failure this fixes.\n *\n * Since R3-307 a call whose prompts the host actually announces runs on the SHORT bound and\n * is suspended only while the host says a person is being asked, so the common\n * grant-already-held path reports a fault in seconds instead of minutes. The absolute\n * ceiling still applies: the signal may extend a deadline, never remove it.\n *\n * The host's own work is NOT cancelled by `signal` or by the deadline. The one-shot\n * transport allocates its `msgId` internally, so the SDK has no handle to send the host a\n * cancel for (streams do, and `consumeStream` uses it). What the caller gets back is\n * control: it stops waiting and gets a typed error instead of hanging. A host prompt that\n * is already on screen stays there until the user dismisses it, which is correct — the SDK\n * must not be able to tear down host chrome the user is looking at.\n */\nexport const protocolRequest = (\n  protocolName: string,\n  method: string,\n  params: Array<any>,\n  opts?: BoundedCallOptions,\n): Promise<any> =>\n  withDeadline(protocolName, method, () => transport().protocolRequest(protocolName, method, params), opts);\n\n/**\n * Race a host call against its deadline, a caller abort, and a pending notice.\n *\n * Kept separate from the transport so it is unit-testable against a promise that simply\n * never settles — which is the whole scenario, and one no live transport reproduces on\n * demand.\n *\n * An explicit `opts.timeoutMs` is the WHOLE bound and is never suspended: a caller that\n * names a number owns the wait, and silently stretching it past what they asked for would\n * be the same class of surprise this machinery exists to remove.\n */\nexport async function withDeadline<T>(\n  scheme: string,\n  method: string,\n  start: () => Promise<T>,\n  opts?: BoundedCallOptions,\n): Promise<T> {\n  const call = `${scheme}:${method}`;\n  const attendance = attendanceOf(scheme, method);\n  const bounds: CallBounds =\n    opts?.timeoutMs !== undefined ? { idleMs: opts.timeoutMs, ceilingMs: opts.timeoutMs } : boundsFor(scheme, method);\n  const signal = opts?.signal;\n\n  if (signal?.aborted) throw new ProtocolCancelledError(call);\n\n  const work = start();\n  // No bound and no abort wanted: hand back the untouched promise rather than wrapping it\n  // in timers that would never fire.\n  if (!Number.isFinite(bounds.ceilingMs) && !signal && !opts?.onPending) return work;\n\n  let deadline: { setAwaiting: (a: boolean) => void; dispose: () => void } | undefined;\n  let notice: ReturnType<typeof setTimeout> | undefined;\n  let unsubscribeAttention: (() => void) | undefined;\n  let onAbort: (() => void) | undefined;\n  const started = Date.now();\n\n  try {\n    return await new Promise<T>((resolve, reject) => {\n      // `work` settling always wins — a call that answered a millisecond before its\n      // deadline must not be reported as a timeout.\n      work.then(resolve, reject);\n\n      // The host's live \"a person is being asked\" signal. Read defensively: a host that\n      // never pushes the channel leaves this at \"not awaiting\", which is exactly the\n      // pre-R3-307 behaviour for a call on its idle bound.\n      let attention: HostAttention | undefined;\n      let noticeFired = false;\n      const fireNotice = () => {\n        try {\n          opts?.onPending?.({\n            call,\n            attendance,\n            elapsedMs: Date.now() - started,\n            ...(attendanceReason(scheme, method) ? { reason: attendanceReason(scheme, method) as string } : {}),\n            ...(attention?.awaiting ? { awaiting: { kind: attention.kind, since: attention.since } } : {}),\n          });\n        } catch {\n          /* a caller's render callback must never break the call it describes */\n        }\n      };\n\n      deadline = createSuspendableDeadline({\n        bounds,\n        onExpire: (bound, elapsedBoundMs) => reject(new ProtocolTimeoutError(call, elapsedBoundMs, attendance, bound)),\n      });\n\n      if (opts?.onPending) {\n        notice = setTimeout(() => {\n          noticeFired = true;\n          fireNotice();\n        }, PENDING_NOTICE_MS);\n      }\n\n      // Subscribing invokes the listener immediately with the current value, so the\n      // deadline starts in the right state even if a prompt was already up.\n      //\n      // Guarded because this sits on the path of EVERY host call: a fault in the attention\n      // channel must degrade to \"no signal\" (the pre-R3-307 behaviour, bounds unsuspended),\n      // never take down every request in the SDK.\n      try {\n        unsubscribeAttention = onHostAttentionChange((next) => {\n          const wasAwaiting = attention?.awaiting ?? false;\n          attention = next;\n          deadline?.setAwaiting(next.awaiting);\n          // Re-notify once the notice has fired: \"still waiting\" → \"tap your passkey\" is\n          // the whole point, and a caller rendering a waiting state wants the live\n          // sentence, not the one that was true three seconds in.\n          if (noticeFired && next.awaiting !== wasAwaiting) fireNotice();\n        });\n      } catch {\n        /* no attention signal available — the bounds simply never suspend */\n      }\n\n      if (signal) {\n        onAbort = () => reject(new ProtocolCancelledError(call));\n        signal.addEventListener('abort', onAbort, { once: true });\n      }\n    });\n  } finally {\n    deadline?.dispose();\n    if (notice !== undefined) clearTimeout(notice);\n    unsubscribeAttention?.();\n    if (signal && onAbort) signal.removeEventListener('abort', onAbort);\n    // The host may still answer after we stopped waiting; swallow it so a late rejection\n    // does not surface as an unhandled promise rejection in the app's console.\n    work.catch(() => undefined);\n  }\n}\n"],"mappings":";AAKA,SAAS,iBAAiB;AAC1B,SAAS,6BAAiD;AAE1D;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AAEP,SAAS,aAAa,mBAAmB;AAqBlC,MAAM,kBAAkB,CAC7B,cACA,QACA,QACA,SAEA,aAAa,cAAc,QAAQ,MAAM,UAAU,EAAE,gBAAgB,cAAc,QAAQ,MAAM,GAAG,IAAI;AAa1G,eAAsB,aACpB,QACA,QACA,OACA,MACY;AACZ,QAAM,OAAO,GAAG,MAAM,IAAI,MAAM;AAChC,QAAM,aAAa,aAAa,QAAQ,MAAM;AAC9C,QAAM,SACJ,MAAM,cAAc,SAAY,EAAE,QAAQ,KAAK,WAAW,WAAW,KAAK,UAAU,IAAI,UAAU,QAAQ,MAAM;AAClH,QAAM,SAAS,MAAM;AAErB,MAAI,QAAQ,QAAS,OAAM,IAAI,uBAAuB,IAAI;AAE1D,QAAM,OAAO,MAAM;AAGnB,MAAI,CAAC,OAAO,SAAS,OAAO,SAAS,KAAK,CAAC,UAAU,CAAC,MAAM,UAAW,QAAO;AAE9E,MAAI;AACJ,MAAI;AACJ,MAAI;AACJ,MAAI;AACJ,QAAM,UAAU,KAAK,IAAI;AAEzB,MAAI;AACF,WAAO,MAAM,IAAI,QAAW,CAAC,SAAS,WAAW;AAG/C,WAAK,KAAK,SAAS,MAAM;AAKzB,UAAI;AACJ,UAAI,cAAc;AAClB,YAAM,aAAa,MAAM;AACvB,YAAI;AACF,gBAAM,YAAY;AAAA,YAChB;AAAA,YACA;AAAA,YACA,WAAW,KAAK,IAAI,IAAI;AAAA,YACxB,GAAI,iBAAiB,QAAQ,MAAM,IAAI,EAAE,QAAQ,iBAAiB,QAAQ,MAAM,EAAY,IAAI,CAAC;AAAA,YACjG,GAAI,WAAW,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,MAAM,OAAO,UAAU,MAAM,EAAE,IAAI,CAAC;AAAA,UAC9F,CAAC;AAAA,QACH,QAAQ;AAAA,QAER;AAAA,MACF;AAEA,iBAAW,0BAA0B;AAAA,QACnC;AAAA,QACA,UAAU,CAAC,OAAO,mBAAmB,OAAO,IAAI,qBAAqB,MAAM,gBAAgB,YAAY,KAAK,CAAC;AAAA,MAC/G,CAAC;AAED,UAAI,MAAM,WAAW;AACnB,iBAAS,WAAW,MAAM;AACxB,wBAAc;AACd,qBAAW;AAAA,QACb,GAAG,iBAAiB;AAAA,MACtB;AAQA,UAAI;AACF,+BAAuB,sBAAsB,CAAC,SAAS;AACrD,gBAAM,cAAc,WAAW,YAAY;AAC3C,sBAAY;AACZ,oBAAU,YAAY,KAAK,QAAQ;AAInC,cAAI,eAAe,KAAK,aAAa,YAAa,YAAW;AAAA,QAC/D,CAAC;AAAA,MACH,QAAQ;AAAA,MAER;AAEA,UAAI,QAAQ;AACV,kBAAU,MAAM,OAAO,IAAI,uBAAuB,IAAI,CAAC;AACvD,eAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;AAAA,MAC1D;AAAA,IACF,CAAC;AAAA,EACH,UAAE;AACA,cAAU,QAAQ;AAClB,QAAI,WAAW,OAAW,cAAa,MAAM;AAC7C,2BAAuB;AACvB,QAAI,UAAU,QAAS,QAAO,oBAAoB,SAAS,OAAO;AAGlE,SAAK,MAAM,MAAM,MAAS;AAAA,EAC5B;AACF;","names":[]}

package/dist/scrollToId.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/scrollToId.ts"],"sourcesContent":["/**\n * Scroll the element addressed by a fragment id into view (deep-linking Capability\n * C, MARKDOWN_SYNTAX_SPEC §13.5). Tries the element's own `id` first — a heading's\n * `sec-…`/text-slug id (§15) — then the `[data-slug]` fallback, so a citation that\n * used the prose text slug still lands even when the heading's own id is the\n * prose-independent `sec-…` id. Returns whether a target was found; the caller\n * decides whether to fall back to top-of-page. **Never throws** — a missing\n * fragment is a soft failure, not an error.\n */\nexport const scrollToId = (id: string): boolean => {\n  if (!id || typeof document === 'undefined') return false;\n  let el: Element | null = null;\n  try {\n    el = document.getElementById(id);\n    if (!el) {\n      // A citation that targeted the prose text slug still resolves via the\n      // `data-slug` hook the kernel emits alongside the `sec-…` id.\n      const escaped =\n        typeof CSS !== 'undefined' && typeof CSS.escape === 'function'\n          ? CSS.escape(id)\n          : id.replace(/[\"\\\\]/g, '\\\\$&');\n      el = document.querySelector(`[data-slug=\"${escaped}\"]`);\n    }\n  } catch {\n    return false;\n  }\n  if (el && typeof (el as HTMLElement).scrollIntoView === 'function') {\n    (el as HTMLElement).scrollIntoView();\n    return true;\n  }\n  return false;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AASO,MAAM,aAAa,CAAC,OAAwB;AACjD,MAAI,CAAC,MAAM,OAAO,aAAa,YAAa,QAAO;AACnD,MAAI,KAAqB;AACzB,MAAI;AACF,SAAK,SAAS,eAAe,EAAE;AAC/B,QAAI,CAAC,IAAI;AAGP,YAAM,UACJ,OAAO,QAAQ,eAAe,OAAO,IAAI,WAAW,aAChD,IAAI,OAAO,EAAE,IACb,GAAG,QAAQ,UAAU,MAAM;AACjC,WAAK,SAAS,cAAc,eAAe,OAAO,IAAI;AAAA,IACxD;AAAA,EACF,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,MAAM,OAAQ,GAAmB,mBAAmB,YAAY;AAClE,IAAC,GAAmB,eAAe;AACnC,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/scrollToId.ts"],"sourcesContent":["/**\n * Scroll the element addressed by a fragment id into view (deep-linking Capability\n * C, MARKDOWN_SYNTAX_SPEC §13.5). Tries the element's own `id` first — a heading's\n * `sec-…`/text-slug id (§15) — then the `[data-slug]` fallback, so a citation that\n * used the prose text slug still lands even when the heading's own id is the\n * prose-independent `sec-…` id. Returns whether a target was found; the caller\n * decides whether to fall back to top-of-page. **Never throws** — a missing\n * fragment is a soft failure, not an error.\n */\nexport const scrollToId = (id: string): boolean => {\n  if (!id || typeof document === 'undefined') return false;\n  let el: Element | null = null;\n  try {\n    el = document.getElementById(id);\n    if (!el) {\n      // A citation that targeted the prose text slug still resolves via the\n      // `data-slug` hook the kernel emits alongside the `sec-…` id.\n      const escaped =\n        typeof CSS !== 'undefined' && typeof CSS.escape === 'function' ? CSS.escape(id) : id.replace(/[\"\\\\]/g, '\\\\$&');\n      el = document.querySelector(`[data-slug=\"${escaped}\"]`);\n    }\n  } catch {\n    return false;\n  }\n  if (el && typeof (el as HTMLElement).scrollIntoView === 'function') {\n    (el as HTMLElement).scrollIntoView();\n    return true;\n  }\n  return false;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AASO,MAAM,aAAa,CAAC,OAAwB;AACjD,MAAI,CAAC,MAAM,OAAO,aAAa,YAAa,QAAO;AACnD,MAAI,KAAqB;AACzB,MAAI;AACF,SAAK,SAAS,eAAe,EAAE;AAC/B,QAAI,CAAC,IAAI;AAGP,YAAM,UACJ,OAAO,QAAQ,eAAe,OAAO,IAAI,WAAW,aAAa,IAAI,OAAO,EAAE,IAAI,GAAG,QAAQ,UAAU,MAAM;AAC/G,WAAK,SAAS,cAAc,eAAe,OAAO,IAAI;AAAA,IACxD;AAAA,EACF,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,MAAM,OAAQ,GAAmB,mBAAmB,YAAY;AAClE,IAAC,GAAmB,eAAe;AACnC,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}

package/dist/scrollToId.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/scrollToId.ts"],"sourcesContent":["/**\n * Scroll the element addressed by a fragment id into view (deep-linking Capability\n * C, MARKDOWN_SYNTAX_SPEC §13.5). Tries the element's own `id` first — a heading's\n * `sec-…`/text-slug id (§15) — then the `[data-slug]` fallback, so a citation that\n * used the prose text slug still lands even when the heading's own id is the\n * prose-independent `sec-…` id. Returns whether a target was found; the caller\n * decides whether to fall back to top-of-page. **Never throws** — a missing\n * fragment is a soft failure, not an error.\n */\nexport const scrollToId = (id: string): boolean => {\n  if (!id || typeof document === 'undefined') return false;\n  let el: Element | null = null;\n  try {\n    el = document.getElementById(id);\n    if (!el) {\n      // A citation that targeted the prose text slug still resolves via the\n      // `data-slug` hook the kernel emits alongside the `sec-…` id.\n      const escaped =\n        typeof CSS !== 'undefined' && typeof CSS.escape === 'function'\n          ? CSS.escape(id)\n          : id.replace(/[\"\\\\]/g, '\\\\$&');\n      el = document.querySelector(`[data-slug=\"${escaped}\"]`);\n    }\n  } catch {\n    return false;\n  }\n  if (el && typeof (el as HTMLElement).scrollIntoView === 'function') {\n    (el as HTMLElement).scrollIntoView();\n    return true;\n  }\n  return false;\n};\n"],"mappings":";AASO,MAAM,aAAa,CAAC,OAAwB;AACjD,MAAI,CAAC,MAAM,OAAO,aAAa,YAAa,QAAO;AACnD,MAAI,KAAqB;AACzB,MAAI;AACF,SAAK,SAAS,eAAe,EAAE;AAC/B,QAAI,CAAC,IAAI;AAGP,YAAM,UACJ,OAAO,QAAQ,eAAe,OAAO,IAAI,WAAW,aAChD,IAAI,OAAO,EAAE,IACb,GAAG,QAAQ,UAAU,MAAM;AACjC,WAAK,SAAS,cAAc,eAAe,OAAO,IAAI;AAAA,IACxD;AAAA,EACF,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,MAAM,OAAQ,GAAmB,mBAAmB,YAAY;AAClE,IAAC,GAAmB,eAAe;AACnC,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/scrollToId.ts"],"sourcesContent":["/**\n * Scroll the element addressed by a fragment id into view (deep-linking Capability\n * C, MARKDOWN_SYNTAX_SPEC §13.5). Tries the element's own `id` first — a heading's\n * `sec-…`/text-slug id (§15) — then the `[data-slug]` fallback, so a citation that\n * used the prose text slug still lands even when the heading's own id is the\n * prose-independent `sec-…` id. Returns whether a target was found; the caller\n * decides whether to fall back to top-of-page. **Never throws** — a missing\n * fragment is a soft failure, not an error.\n */\nexport const scrollToId = (id: string): boolean => {\n  if (!id || typeof document === 'undefined') return false;\n  let el: Element | null = null;\n  try {\n    el = document.getElementById(id);\n    if (!el) {\n      // A citation that targeted the prose text slug still resolves via the\n      // `data-slug` hook the kernel emits alongside the `sec-…` id.\n      const escaped =\n        typeof CSS !== 'undefined' && typeof CSS.escape === 'function' ? CSS.escape(id) : id.replace(/[\"\\\\]/g, '\\\\$&');\n      el = document.querySelector(`[data-slug=\"${escaped}\"]`);\n    }\n  } catch {\n    return false;\n  }\n  if (el && typeof (el as HTMLElement).scrollIntoView === 'function') {\n    (el as HTMLElement).scrollIntoView();\n    return true;\n  }\n  return false;\n};\n"],"mappings":";AASO,MAAM,aAAa,CAAC,OAAwB;AACjD,MAAI,CAAC,MAAM,OAAO,aAAa,YAAa,QAAO;AACnD,MAAI,KAAqB;AACzB,MAAI;AACF,SAAK,SAAS,eAAe,EAAE;AAC/B,QAAI,CAAC,IAAI;AAGP,YAAM,UACJ,OAAO,QAAQ,eAAe,OAAO,IAAI,WAAW,aAAa,IAAI,OAAO,EAAE,IAAI,GAAG,QAAQ,UAAU,MAAM;AAC/G,WAAK,SAAS,cAAc,eAAe,OAAO,IAAI;AAAA,IACxD;AAAA,EACF,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,MAAM,OAAQ,GAAmB,mBAAmB,YAAY;AAClE,IAAC,GAAmB,eAAe;AACnC,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}

package/dist/secrets.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/secrets.ts"],"sourcesContent":["// The host-owned secret store — app-facing surface (SECRETS_SPEC §4/§5).\n//\n// An app can ASK the user to store a secret (`requestAddSecret`), be GRANTED the\n// right to USE a specific secret (`requestSecret`, the powerbox flow), LIST\n// secret METADATA (`getSecrets`/`useSecrets`, never values), and REVOKE one\n// (`revokeSecret`). The secret VALUE never crosses this boundary: it is read\n// host-side, once, at the `net:fetch` injection point (SECRETS_SPEC §6). These\n// functions move only hints, metadata, and grant handles.\n//\n// Resolves LLM_AND_AGENTS_SPEC D2 — the host-mediated BYOK key store. Inert until\n// the host implements `protocol-secrets` + the `secrets-metadata` channel\n// (SECRETS_SPEC §3/§6 host work, roadmap P1.E); the contract is shipped here so\n// apps (e.g. the in-browser coding agent, P3-73) can be written against it.\nimport { protocolRequest } from './sandboxUtils';\nimport { createPushChannel } from './pushChannel';\nimport { PROTOCOL_SECRETS, REQUEST_SECRETS_METADATA, SECRETS_METADATA } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/** The closed secret-type vocabulary (SECRETS_SPEC §2). `api-key` is always\n *  origin-bound; `oauth-refresh` is reserved (no substitution in v1). */\nexport type SecretType = 'api-key' | 'bearer-token' | 'oauth-refresh';\n\n/**\n * The metadata-only projection of a stored secret (SECRETS_SPEC §2/§4) — exactly\n * what `secrets:list` and the powerbox return. **There is no `value` field by\n * design**: the plaintext is never part of any record an app receives.\n */\nexport interface SecretView {\n  id: string;\n  type: SecretType;\n  family?: string;\n  description: string;\n  /** Required for `type:'api-key'` — the one https origin it may be sent to. */\n  boundOrigin?: string;\n  /** ISO-8601, or null if never used (drives the §8.15 90-day expiry). */\n  lastUsedAt: string | null;\n}\n\n/** Hints for the host's \"add secret\" modal (SECRETS_SPEC §4 `secrets:add`). The\n *  app supplies only hints; the user types the value into host chrome. */\nexport interface SecretHints {\n  type?: SecretType;\n  family?: string;\n  /** Pre-fill the bound origin (e.g. `https://api.anthropic.com`). */\n  suggestedOrigin?: string;\n  description?: string;\n}\n\n/** What `requestSecret()` matches against in the powerbox picker (SECRETS_SPEC §5). */\nexport interface SecretQuery {\n  type?: SecretType;\n  family?: string;\n}\n\n/**\n * The result of a granted `requestSecret()` — a durable `(appKey, secretId)` use\n * grant plus the secret's metadata. **Never the value.** Hold onto nothing but\n * this; the host substitutes the value into matching `net:fetch` requests.\n */\nexport interface SecretGrant {\n  /** Opaque handle for the minted `(appKey, secretId)` grant. */\n  grantId: string;\n  /** Metadata of the bound secret (no value). */\n  secret: SecretView;\n}\n\n/** An error from a secret operation, carrying a machine-readable `code`. */\nexport interface SecretError extends Error {\n  code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'invalid-params' | 'unknown';\n}\n\ntype SecretResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\n// Issue a `protocol-secrets` request, unwrapping the host's {ok,data} envelope\n// and throwing a typed SecretError on failure (mirrors mounts.ts `request`).\nconst request = async <T = unknown>(\n  method: string,\n  query: object = {},\n): Promise<T> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_SECRETS], method, [query])) as SecretResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'secret request failed') as SecretError;\n    err.code = (res?.code as SecretError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n/**\n * Ask the user to store a new secret (SECRETS_SPEC §4 `secrets:add`). Opens a\n * **host-drawn** modal (the value is typed into host chrome, never via the app);\n * resolves with the new secret's {@link SecretView} metadata, or rejects with a\n * {@link SecretError} (`cancelled` if the user dismisses the modal). Requires the\n * `secrets:add` capability.\n */\nexport const requestAddSecret = (hints: SecretHints = {}): Promise<SecretView> =>\n  request<SecretView>('add', hints);\n\n/**\n * Ask the user to bind one of their stored secrets to this app (SECRETS_SPEC §5,\n * the powerbox flow — modeled on `requestSpace()`). The host draws a picker of\n * **only the user's matching secrets**; the user picks, declines, or creates one.\n * On success the host records a durable `(appKey, secretId)` grant and resolves\n * with a {@link SecretGrant} (handle + metadata, **never the value**).\n *\n * **No existence oracle (T20/T27):** a decline, an ungranted secret, and a\n * nonexistent secret are indistinguishable — all reject with a {@link SecretError}\n * `cancelled`; the app never sees the list it chose from.\n */\nexport const requestSecret = (query: SecretQuery = {}): Promise<SecretGrant> =>\n  request<SecretGrant>('request', query);\n\n/**\n * Delete a stored secret and tombstone every dependent per-app use grant\n * (SECRETS_SPEC §4 `secrets:revoke`, §8.15 cascade). Requires `secrets:revoke`.\n */\nexport const revokeSecret = async (id: string): Promise<void> => {\n  await request('revoke', { id });\n};\n\n// The metadata-only `secrets-metadata` channel (Recipe A): the host pushes the\n// current secret metadata on change and replays it on register-frame; gated by\n// `secrets:list`. NEVER carries a value (SECRETS_SPEC §4).\nconst channel = createPushChannel<SecretView[]>({\n  pushType: SECRETS_METADATA,\n  requestType: REQUEST_SECRETS_METADATA,\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.secrets) ? (msg.secrets as SecretView[]) : undefined),\n});\n\n/** The metadata of the user's stored secrets (never values), `secrets:list`. Poll\n *  for a one-off read; use {@link onSecretsChange}/{@link useSecrets} to react. */\nexport const getSecrets = (): SecretView[] => channel.get();\n\n/** Subscribe to secret-metadata changes (added/revoked). Invoked immediately with\n *  the current list, then on every change. Returns an unsubscribe fn. */\nexport const onSecretsChange = (listener: (secrets: SecretView[]) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the user's secret metadata (never values), re-rendering\n *  on change. For the Settings app (SECRETS_SPEC §7). */\nexport const useSecrets = (): SecretView[] => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAaA,0BAAgC;AAChC,yBAAkC;AAClC,sBAA6E;AAC7E,6BAAwB;AA6DxB,MAAM,UAAU,OACd,QACA,QAAgB,CAAC,MACF;AACf,QAAM,MAAO,UAAM,qCAAgB,+BAAQ,gCAAgB,GAAG,QAAQ,CAAC,KAAK,CAAC;AAC7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,uBAAuB;AAC7D,QAAI,OAAQ,KAAK,QAAgC;AACjD,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AASO,MAAM,mBAAmB,CAAC,QAAqB,CAAC,MACrD,QAAoB,OAAO,KAAK;AAa3B,MAAM,gBAAgB,CAAC,QAAqB,CAAC,MAClD,QAAqB,WAAW,KAAK;AAMhC,MAAM,eAAe,OAAO,OAA8B;AAC/D,QAAM,QAAQ,UAAU,EAAE,GAAG,CAAC;AAChC;AAKA,MAAM,cAAU,sCAAgC;AAAA,EAC9C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAA2B;AAChF,CAAC;AAIM,MAAM,aAAa,MAAoB,QAAQ,IAAI;AAInD,MAAM,kBAAkB,CAAC,aAC9B,QAAQ,SAAS,QAAQ;AAIpB,MAAM,aAAa,MAAoB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/secrets.ts"],"sourcesContent":["// The host-owned secret store — app-facing surface (SECRETS_SPEC §4/§5).\n//\n// An app can ASK the user to store a secret (`requestAddSecret`), be GRANTED the\n// right to USE a specific secret (`requestSecret`, the powerbox flow), LIST\n// secret METADATA (`getSecrets`/`useSecrets`, never values), and REVOKE one\n// (`revokeSecret`). The secret VALUE never crosses this boundary: it is read\n// host-side, once, at the `net:fetch` injection point (SECRETS_SPEC §6). These\n// functions move only hints, metadata, and grant handles.\n//\n// Resolves LLM_AND_AGENTS_SPEC D2 — the host-mediated BYOK key store. Inert until\n// the host implements `protocol-secrets` + the `secrets-metadata` channel\n// (SECRETS_SPEC §3/§6 host work, roadmap P1.E); the contract is shipped here so\n// apps (e.g. the in-browser coding agent, P3-73) can be written against it.\nimport { protocolRequest } from './sandboxUtils';\nimport { createPushChannel } from './pushChannel';\nimport { PROTOCOL_SECRETS, REQUEST_SECRETS_METADATA, SECRETS_METADATA } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/** The closed secret-type vocabulary (SECRETS_SPEC §2). `api-key` is always\n *  origin-bound; `oauth-refresh` is reserved (no substitution in v1). */\nexport type SecretType = 'api-key' | 'bearer-token' | 'oauth-refresh';\n\n/**\n * The metadata-only projection of a stored secret (SECRETS_SPEC §2/§4) — exactly\n * what `secrets:list` and the powerbox return. **There is no `value` field by\n * design**: the plaintext is never part of any record an app receives.\n */\nexport interface SecretView {\n  id: string;\n  type: SecretType;\n  family?: string;\n  description: string;\n  /** Required for `type:'api-key'` — the one https origin it may be sent to. */\n  boundOrigin?: string;\n  /** ISO-8601, or null if never used (drives the §8.15 90-day expiry). */\n  lastUsedAt: string | null;\n}\n\n/** Hints for the host's \"add secret\" modal (SECRETS_SPEC §4 `secrets:add`). The\n *  app supplies only hints; the user types the value into host chrome. */\nexport interface SecretHints {\n  type?: SecretType;\n  family?: string;\n  /** Pre-fill the bound origin (e.g. `https://api.anthropic.com`). */\n  suggestedOrigin?: string;\n  description?: string;\n}\n\n/** What `requestSecret()` matches against in the powerbox picker (SECRETS_SPEC §5). */\nexport interface SecretQuery {\n  type?: SecretType;\n  family?: string;\n}\n\n/**\n * The result of a granted `requestSecret()` — a durable `(appKey, secretId)` use\n * grant plus the secret's metadata. **Never the value.** Hold onto nothing but\n * this; the host substitutes the value into matching `net:fetch` requests.\n */\nexport interface SecretGrant {\n  /** Opaque handle for the minted `(appKey, secretId)` grant. */\n  grantId: string;\n  /** Metadata of the bound secret (no value). */\n  secret: SecretView;\n}\n\n/** An error from a secret operation, carrying a machine-readable `code`. */\nexport interface SecretError extends Error {\n  code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'invalid-params' | 'unknown';\n}\n\ntype SecretResult = { ok: true; data: unknown } | { ok: false; code: string; message: string };\n\n// Issue a `protocol-secrets` request, unwrapping the host's {ok,data} envelope\n// and throwing a typed SecretError on failure (mirrors mounts.ts `request`).\nconst request = async <T = unknown>(method: string, query: object = {}): Promise<T> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_SECRETS], method, [query])) as SecretResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'secret request failed') as SecretError;\n    err.code = (res?.code as SecretError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n/**\n * Ask the user to store a new secret (SECRETS_SPEC §4 `secrets:add`). Opens a\n * **host-drawn** modal (the value is typed into host chrome, never via the app);\n * resolves with the new secret's {@link SecretView} metadata, or rejects with a\n * {@link SecretError} (`cancelled` if the user dismisses the modal). Requires the\n * `secrets:add` capability.\n */\nexport const requestAddSecret = (hints: SecretHints = {}): Promise<SecretView> => request<SecretView>('add', hints);\n\n/**\n * Ask the user to bind one of their stored secrets to this app (SECRETS_SPEC §5,\n * the powerbox flow — modeled on `requestSpace()`). The host draws a picker of\n * **only the user's matching secrets**; the user picks, declines, or creates one.\n * On success the host records a durable `(appKey, secretId)` grant and resolves\n * with a {@link SecretGrant} (handle + metadata, **never the value**).\n *\n * **No existence oracle (T20/T27):** a decline, an ungranted secret, and a\n * nonexistent secret are indistinguishable — all reject with a {@link SecretError}\n * `cancelled`; the app never sees the list it chose from.\n */\nexport const requestSecret = (query: SecretQuery = {}): Promise<SecretGrant> => request<SecretGrant>('request', query);\n\n/**\n * Delete a stored secret and tombstone every dependent per-app use grant\n * (SECRETS_SPEC §4 `secrets:revoke`, §8.15 cascade). Requires `secrets:revoke`.\n */\nexport const revokeSecret = async (id: string): Promise<void> => {\n  await request('revoke', { id });\n};\n\n// The metadata-only `secrets-metadata` channel (Recipe A): the host pushes the\n// current secret metadata on change and replays it on register-frame; gated by\n// `secrets:list`. NEVER carries a value (SECRETS_SPEC §4).\nconst channel = createPushChannel<SecretView[]>({\n  pushType: SECRETS_METADATA,\n  requestType: REQUEST_SECRETS_METADATA,\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.secrets) ? (msg.secrets as SecretView[]) : undefined),\n});\n\n/** The metadata of the user's stored secrets (never values), `secrets:list`. Poll\n *  for a one-off read; use {@link onSecretsChange}/{@link useSecrets} to react. */\nexport const getSecrets = (): SecretView[] => channel.get();\n\n/** Subscribe to secret-metadata changes (added/revoked). Invoked immediately with\n *  the current list, then on every change. Returns an unsubscribe fn. */\nexport const onSecretsChange = (listener: (secrets: SecretView[]) => void): (() => void) => channel.onChange(listener);\n\n/** React hook returning the user's secret metadata (never values), re-rendering\n *  on change. For the Settings app (SECRETS_SPEC §7). */\nexport const useSecrets = (): SecretView[] => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAaA,0BAAgC;AAChC,yBAAkC;AAClC,sBAA6E;AAC7E,6BAAwB;AA2DxB,MAAM,UAAU,OAAoB,QAAgB,QAAgB,CAAC,MAAkB;AACrF,QAAM,MAAO,UAAM,qCAAgB,+BAAQ,gCAAgB,GAAG,QAAQ,CAAC,KAAK,CAAC;AAC7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,uBAAuB;AAC7D,QAAI,OAAQ,KAAK,QAAgC;AACjD,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AASO,MAAM,mBAAmB,CAAC,QAAqB,CAAC,MAA2B,QAAoB,OAAO,KAAK;AAa3G,MAAM,gBAAgB,CAAC,QAAqB,CAAC,MAA4B,QAAqB,WAAW,KAAK;AAM9G,MAAM,eAAe,OAAO,OAA8B;AAC/D,QAAM,QAAQ,UAAU,EAAE,GAAG,CAAC;AAChC;AAKA,MAAM,cAAU,sCAAgC;AAAA,EAC9C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAA2B;AAChF,CAAC;AAIM,MAAM,aAAa,MAAoB,QAAQ,IAAI;AAInD,MAAM,kBAAkB,CAAC,aAA4D,QAAQ,SAAS,QAAQ;AAI9G,MAAM,aAAa,MAAoB,QAAQ,IAAI;","names":[]}

package/dist/secrets.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/secrets.ts"],"sourcesContent":["// The host-owned secret store — app-facing surface (SECRETS_SPEC §4/§5).\n//\n// An app can ASK the user to store a secret (`requestAddSecret`), be GRANTED the\n// right to USE a specific secret (`requestSecret`, the powerbox flow), LIST\n// secret METADATA (`getSecrets`/`useSecrets`, never values), and REVOKE one\n// (`revokeSecret`). The secret VALUE never crosses this boundary: it is read\n// host-side, once, at the `net:fetch` injection point (SECRETS_SPEC §6). These\n// functions move only hints, metadata, and grant handles.\n//\n// Resolves LLM_AND_AGENTS_SPEC D2 — the host-mediated BYOK key store. Inert until\n// the host implements `protocol-secrets` + the `secrets-metadata` channel\n// (SECRETS_SPEC §3/§6 host work, roadmap P1.E); the contract is shipped here so\n// apps (e.g. the in-browser coding agent, P3-73) can be written against it.\nimport { protocolRequest } from './sandboxUtils';\nimport { createPushChannel } from './pushChannel';\nimport { PROTOCOL_SECRETS, REQUEST_SECRETS_METADATA, SECRETS_METADATA } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/** The closed secret-type vocabulary (SECRETS_SPEC §2). `api-key` is always\n *  origin-bound; `oauth-refresh` is reserved (no substitution in v1). */\nexport type SecretType = 'api-key' | 'bearer-token' | 'oauth-refresh';\n\n/**\n * The metadata-only projection of a stored secret (SECRETS_SPEC §2/§4) — exactly\n * what `secrets:list` and the powerbox return. **There is no `value` field by\n * design**: the plaintext is never part of any record an app receives.\n */\nexport interface SecretView {\n  id: string;\n  type: SecretType;\n  family?: string;\n  description: string;\n  /** Required for `type:'api-key'` — the one https origin it may be sent to. */\n  boundOrigin?: string;\n  /** ISO-8601, or null if never used (drives the §8.15 90-day expiry). */\n  lastUsedAt: string | null;\n}\n\n/** Hints for the host's \"add secret\" modal (SECRETS_SPEC §4 `secrets:add`). The\n *  app supplies only hints; the user types the value into host chrome. */\nexport interface SecretHints {\n  type?: SecretType;\n  family?: string;\n  /** Pre-fill the bound origin (e.g. `https://api.anthropic.com`). */\n  suggestedOrigin?: string;\n  description?: string;\n}\n\n/** What `requestSecret()` matches against in the powerbox picker (SECRETS_SPEC §5). */\nexport interface SecretQuery {\n  type?: SecretType;\n  family?: string;\n}\n\n/**\n * The result of a granted `requestSecret()` — a durable `(appKey, secretId)` use\n * grant plus the secret's metadata. **Never the value.** Hold onto nothing but\n * this; the host substitutes the value into matching `net:fetch` requests.\n */\nexport interface SecretGrant {\n  /** Opaque handle for the minted `(appKey, secretId)` grant. */\n  grantId: string;\n  /** Metadata of the bound secret (no value). */\n  secret: SecretView;\n}\n\n/** An error from a secret operation, carrying a machine-readable `code`. */\nexport interface SecretError extends Error {\n  code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'invalid-params' | 'unknown';\n}\n\ntype SecretResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\n// Issue a `protocol-secrets` request, unwrapping the host's {ok,data} envelope\n// and throwing a typed SecretError on failure (mirrors mounts.ts `request`).\nconst request = async <T = unknown>(\n  method: string,\n  query: object = {},\n): Promise<T> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_SECRETS], method, [query])) as SecretResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'secret request failed') as SecretError;\n    err.code = (res?.code as SecretError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n/**\n * Ask the user to store a new secret (SECRETS_SPEC §4 `secrets:add`). Opens a\n * **host-drawn** modal (the value is typed into host chrome, never via the app);\n * resolves with the new secret's {@link SecretView} metadata, or rejects with a\n * {@link SecretError} (`cancelled` if the user dismisses the modal). Requires the\n * `secrets:add` capability.\n */\nexport const requestAddSecret = (hints: SecretHints = {}): Promise<SecretView> =>\n  request<SecretView>('add', hints);\n\n/**\n * Ask the user to bind one of their stored secrets to this app (SECRETS_SPEC §5,\n * the powerbox flow — modeled on `requestSpace()`). The host draws a picker of\n * **only the user's matching secrets**; the user picks, declines, or creates one.\n * On success the host records a durable `(appKey, secretId)` grant and resolves\n * with a {@link SecretGrant} (handle + metadata, **never the value**).\n *\n * **No existence oracle (T20/T27):** a decline, an ungranted secret, and a\n * nonexistent secret are indistinguishable — all reject with a {@link SecretError}\n * `cancelled`; the app never sees the list it chose from.\n */\nexport const requestSecret = (query: SecretQuery = {}): Promise<SecretGrant> =>\n  request<SecretGrant>('request', query);\n\n/**\n * Delete a stored secret and tombstone every dependent per-app use grant\n * (SECRETS_SPEC §4 `secrets:revoke`, §8.15 cascade). Requires `secrets:revoke`.\n */\nexport const revokeSecret = async (id: string): Promise<void> => {\n  await request('revoke', { id });\n};\n\n// The metadata-only `secrets-metadata` channel (Recipe A): the host pushes the\n// current secret metadata on change and replays it on register-frame; gated by\n// `secrets:list`. NEVER carries a value (SECRETS_SPEC §4).\nconst channel = createPushChannel<SecretView[]>({\n  pushType: SECRETS_METADATA,\n  requestType: REQUEST_SECRETS_METADATA,\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.secrets) ? (msg.secrets as SecretView[]) : undefined),\n});\n\n/** The metadata of the user's stored secrets (never values), `secrets:list`. Poll\n *  for a one-off read; use {@link onSecretsChange}/{@link useSecrets} to react. */\nexport const getSecrets = (): SecretView[] => channel.get();\n\n/** Subscribe to secret-metadata changes (added/revoked). Invoked immediately with\n *  the current list, then on every change. Returns an unsubscribe fn. */\nexport const onSecretsChange = (listener: (secrets: SecretView[]) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the user's secret metadata (never values), re-rendering\n *  on change. For the Settings app (SECRETS_SPEC §7). */\nexport const useSecrets = (): SecretView[] => channel.use();\n"],"mappings":";AAaA,SAAS,uBAAuB;AAChC,SAAS,yBAAyB;AAClC,SAAS,kBAAkB,0BAA0B,wBAAwB;AAC7E,SAAS,eAAe;AA6DxB,MAAM,UAAU,OACd,QACA,QAAgB,CAAC,MACF;AACf,QAAM,MAAO,MAAM,gBAAgB,QAAQ,gBAAgB,GAAG,QAAQ,CAAC,KAAK,CAAC;AAC7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,uBAAuB;AAC7D,QAAI,OAAQ,KAAK,QAAgC;AACjD,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AASO,MAAM,mBAAmB,CAAC,QAAqB,CAAC,MACrD,QAAoB,OAAO,KAAK;AAa3B,MAAM,gBAAgB,CAAC,QAAqB,CAAC,MAClD,QAAqB,WAAW,KAAK;AAMhC,MAAM,eAAe,OAAO,OAA8B;AAC/D,QAAM,QAAQ,UAAU,EAAE,GAAG,CAAC;AAChC;AAKA,MAAM,UAAU,kBAAgC;AAAA,EAC9C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAA2B;AAChF,CAAC;AAIM,MAAM,aAAa,MAAoB,QAAQ,IAAI;AAInD,MAAM,kBAAkB,CAAC,aAC9B,QAAQ,SAAS,QAAQ;AAIpB,MAAM,aAAa,MAAoB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/secrets.ts"],"sourcesContent":["// The host-owned secret store — app-facing surface (SECRETS_SPEC §4/§5).\n//\n// An app can ASK the user to store a secret (`requestAddSecret`), be GRANTED the\n// right to USE a specific secret (`requestSecret`, the powerbox flow), LIST\n// secret METADATA (`getSecrets`/`useSecrets`, never values), and REVOKE one\n// (`revokeSecret`). The secret VALUE never crosses this boundary: it is read\n// host-side, once, at the `net:fetch` injection point (SECRETS_SPEC §6). These\n// functions move only hints, metadata, and grant handles.\n//\n// Resolves LLM_AND_AGENTS_SPEC D2 — the host-mediated BYOK key store. Inert until\n// the host implements `protocol-secrets` + the `secrets-metadata` channel\n// (SECRETS_SPEC §3/§6 host work, roadmap P1.E); the contract is shipped here so\n// apps (e.g. the in-browser coding agent, P3-73) can be written against it.\nimport { protocolRequest } from './sandboxUtils';\nimport { createPushChannel } from './pushChannel';\nimport { PROTOCOL_SECRETS, REQUEST_SECRETS_METADATA, SECRETS_METADATA } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/** The closed secret-type vocabulary (SECRETS_SPEC §2). `api-key` is always\n *  origin-bound; `oauth-refresh` is reserved (no substitution in v1). */\nexport type SecretType = 'api-key' | 'bearer-token' | 'oauth-refresh';\n\n/**\n * The metadata-only projection of a stored secret (SECRETS_SPEC §2/§4) — exactly\n * what `secrets:list` and the powerbox return. **There is no `value` field by\n * design**: the plaintext is never part of any record an app receives.\n */\nexport interface SecretView {\n  id: string;\n  type: SecretType;\n  family?: string;\n  description: string;\n  /** Required for `type:'api-key'` — the one https origin it may be sent to. */\n  boundOrigin?: string;\n  /** ISO-8601, or null if never used (drives the §8.15 90-day expiry). */\n  lastUsedAt: string | null;\n}\n\n/** Hints for the host's \"add secret\" modal (SECRETS_SPEC §4 `secrets:add`). The\n *  app supplies only hints; the user types the value into host chrome. */\nexport interface SecretHints {\n  type?: SecretType;\n  family?: string;\n  /** Pre-fill the bound origin (e.g. `https://api.anthropic.com`). */\n  suggestedOrigin?: string;\n  description?: string;\n}\n\n/** What `requestSecret()` matches against in the powerbox picker (SECRETS_SPEC §5). */\nexport interface SecretQuery {\n  type?: SecretType;\n  family?: string;\n}\n\n/**\n * The result of a granted `requestSecret()` — a durable `(appKey, secretId)` use\n * grant plus the secret's metadata. **Never the value.** Hold onto nothing but\n * this; the host substitutes the value into matching `net:fetch` requests.\n */\nexport interface SecretGrant {\n  /** Opaque handle for the minted `(appKey, secretId)` grant. */\n  grantId: string;\n  /** Metadata of the bound secret (no value). */\n  secret: SecretView;\n}\n\n/** An error from a secret operation, carrying a machine-readable `code`. */\nexport interface SecretError extends Error {\n  code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'invalid-params' | 'unknown';\n}\n\ntype SecretResult = { ok: true; data: unknown } | { ok: false; code: string; message: string };\n\n// Issue a `protocol-secrets` request, unwrapping the host's {ok,data} envelope\n// and throwing a typed SecretError on failure (mirrors mounts.ts `request`).\nconst request = async <T = unknown>(method: string, query: object = {}): Promise<T> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_SECRETS], method, [query])) as SecretResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'secret request failed') as SecretError;\n    err.code = (res?.code as SecretError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n/**\n * Ask the user to store a new secret (SECRETS_SPEC §4 `secrets:add`). Opens a\n * **host-drawn** modal (the value is typed into host chrome, never via the app);\n * resolves with the new secret's {@link SecretView} metadata, or rejects with a\n * {@link SecretError} (`cancelled` if the user dismisses the modal). Requires the\n * `secrets:add` capability.\n */\nexport const requestAddSecret = (hints: SecretHints = {}): Promise<SecretView> => request<SecretView>('add', hints);\n\n/**\n * Ask the user to bind one of their stored secrets to this app (SECRETS_SPEC §5,\n * the powerbox flow — modeled on `requestSpace()`). The host draws a picker of\n * **only the user's matching secrets**; the user picks, declines, or creates one.\n * On success the host records a durable `(appKey, secretId)` grant and resolves\n * with a {@link SecretGrant} (handle + metadata, **never the value**).\n *\n * **No existence oracle (T20/T27):** a decline, an ungranted secret, and a\n * nonexistent secret are indistinguishable — all reject with a {@link SecretError}\n * `cancelled`; the app never sees the list it chose from.\n */\nexport const requestSecret = (query: SecretQuery = {}): Promise<SecretGrant> => request<SecretGrant>('request', query);\n\n/**\n * Delete a stored secret and tombstone every dependent per-app use grant\n * (SECRETS_SPEC §4 `secrets:revoke`, §8.15 cascade). Requires `secrets:revoke`.\n */\nexport const revokeSecret = async (id: string): Promise<void> => {\n  await request('revoke', { id });\n};\n\n// The metadata-only `secrets-metadata` channel (Recipe A): the host pushes the\n// current secret metadata on change and replays it on register-frame; gated by\n// `secrets:list`. NEVER carries a value (SECRETS_SPEC §4).\nconst channel = createPushChannel<SecretView[]>({\n  pushType: SECRETS_METADATA,\n  requestType: REQUEST_SECRETS_METADATA,\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.secrets) ? (msg.secrets as SecretView[]) : undefined),\n});\n\n/** The metadata of the user's stored secrets (never values), `secrets:list`. Poll\n *  for a one-off read; use {@link onSecretsChange}/{@link useSecrets} to react. */\nexport const getSecrets = (): SecretView[] => channel.get();\n\n/** Subscribe to secret-metadata changes (added/revoked). Invoked immediately with\n *  the current list, then on every change. Returns an unsubscribe fn. */\nexport const onSecretsChange = (listener: (secrets: SecretView[]) => void): (() => void) => channel.onChange(listener);\n\n/** React hook returning the user's secret metadata (never values), re-rendering\n *  on change. For the Settings app (SECRETS_SPEC §7). */\nexport const useSecrets = (): SecretView[] => channel.use();\n"],"mappings":";AAaA,SAAS,uBAAuB;AAChC,SAAS,yBAAyB;AAClC,SAAS,kBAAkB,0BAA0B,wBAAwB;AAC7E,SAAS,eAAe;AA2DxB,MAAM,UAAU,OAAoB,QAAgB,QAAgB,CAAC,MAAkB;AACrF,QAAM,MAAO,MAAM,gBAAgB,QAAQ,gBAAgB,GAAG,QAAQ,CAAC,KAAK,CAAC;AAC7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,uBAAuB;AAC7D,QAAI,OAAQ,KAAK,QAAgC;AACjD,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AASO,MAAM,mBAAmB,CAAC,QAAqB,CAAC,MAA2B,QAAoB,OAAO,KAAK;AAa3G,MAAM,gBAAgB,CAAC,QAAqB,CAAC,MAA4B,QAAqB,WAAW,KAAK;AAM9G,MAAM,eAAe,OAAO,OAA8B;AAC/D,QAAM,QAAQ,UAAU,EAAE,GAAG,CAAC;AAChC;AAKA,MAAM,UAAU,kBAAgC;AAAA,EAC9C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAA2B;AAChF,CAAC;AAIM,MAAM,aAAa,MAAoB,QAAQ,IAAI;AAInD,MAAM,kBAAkB,CAAC,aAA4D,QAAQ,SAAS,QAAQ;AAI9G,MAAM,aAAa,MAAoB,QAAQ,IAAI;","names":[]}

package/dist/tasks.cjs

@@ -31,8 +31,18 @@ var import_react = require("react");
 var import_sandboxUtils = require("./sandboxUtils");
 var import_protocol = require("./generated/protocol");
 var import_protocolSchemes = require("./protocolSchemes");
-const capFile = (ref, opts) => ({ $cap: "file", mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });
-const capDir = (ref, opts) => ({ $cap: "dir", mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });
+const capFile = (ref, opts) => ({
+  $cap: "file",
+  mountId: ref.mountId,
+  relPath: ref.relPath,
+  mode: opts.mode
+});
+const capDir = (ref, opts) => ({
+  $cap: "dir",
+  mountId: ref.mountId,
+  relPath: ref.relPath,
+  mode: opts.mode
+});
 const invokeTask = async (task, params = {}) => {
   const res = await (0, import_sandboxUtils.protocolRequest)(import_protocolSchemes.SCHEMES[import_protocol.PROTOCOL_TASK], "invoke", [{ task, params }]);
   if (!res || res.ok !== true) {

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 = (\n  ref: { mountId: string; relPath: string },\n  opts: { mode: 'ro' | 'rw' },\n): FileCap => ({ $cap: 'file', mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });\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 = (\n  ref: { mountId: string; relPath: string },\n  opts: { mode: 'ro' | 'rw' },\n): DirCap => ({ $cap: 'dir', mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });\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>(\n  task: string,\n  params: Record<string, unknown> = {},\n): 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,CACrB,KACA,UACa,EAAE,MAAM,QAAQ,SAAS,IAAI,SAAS,SAAS,IAAI,SAAS,MAAM,KAAK,KAAK;AAoBpF,MAAM,SAAS,CACpB,KACA,UACY,EAAE,MAAM,OAAO,SAAS,IAAI,SAAS,SAAS,IAAI,SAAS,MAAM,KAAK,KAAK;AASlF,MAAM,aAAa,OACxB,MACA,SAAkC,CAAC,MACpB;AACf,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()`.\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":[]}

package/dist/tasks.js

@@ -3,8 +3,18 @@ import { useEffect, useState } from "react";
 import { protocolRequest, sendMessage, addListener } from "./sandboxUtils";
 import { PROTOCOL_TASK, TASK_CANCEL, TASK_COMPLETE, TASK_INPUT } from "./generated/protocol";
 import { SCHEMES } from "./protocolSchemes";
-const capFile = (ref, opts) => ({ $cap: "file", mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });
-const capDir = (ref, opts) => ({ $cap: "dir", mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });
+const capFile = (ref, opts) => ({
+  $cap: "file",
+  mountId: ref.mountId,
+  relPath: ref.relPath,
+  mode: opts.mode
+});
+const capDir = (ref, opts) => ({
+  $cap: "dir",
+  mountId: ref.mountId,
+  relPath: ref.relPath,
+  mode: opts.mode
+});
 const invokeTask = async (task, params = {}) => {
   const res = await protocolRequest(SCHEMES[PROTOCOL_TASK], "invoke", [{ task, params }]);
   if (!res || res.ok !== true) {