@immediately-run/sdk 0.45.3 → 0.46.0

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(\n    protocolName,\n    method,\n    () => transport().protocolRequest(protocolName, method, params),\n    opts,\n  );\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\n      ? { idleMs: opts.timeoutMs, ceilingMs: opts.timeoutMs }\n      : 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)\n              ? { reason: attendanceReason(scheme, method) as string }\n              : {}),\n            ...(attention?.awaiting\n              ? { awaiting: { kind: attention.kind, since: attention.since } }\n              : {}),\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) =>\n          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,EACE;AAAA,EACA;AAAA,EACA,UAAM,gCAAU,EAAE,gBAAgB,cAAc,QAAQ,MAAM;AAAA,EAC9D;AACF;AAaF,eAAsB,aACpB,QACA,QACA,OACA,MACY;AACZ,QAAM,OAAO,GAAG,MAAM,IAAI,MAAM;AAChC,QAAM,iBAAa,sCAAa,QAAQ,MAAM;AAC9C,QAAM,SACJ,MAAM,cAAc,SAChB,EAAE,QAAQ,KAAK,WAAW,WAAW,KAAK,UAAU,QACpD,mCAAU,QAAQ,MAAM;AAC9B,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,IAC/B,EAAE,YAAQ,0CAAiB,QAAQ,MAAM,EAAY,IACrD,CAAC;AAAA,YACL,GAAI,WAAW,WACX,EAAE,UAAU,EAAE,MAAM,UAAU,MAAM,OAAO,UAAU,MAAM,EAAE,IAC7D,CAAC;AAAA,UACP,CAAC;AAAA,QACH,QAAQ;AAAA,QAER;AAAA,MACF;AAEA,qBAAW,mDAA0B;AAAA,QACnC;AAAA,QACA,UAAU,CAAC,OAAO,mBAChB,OAAO,IAAI,6CAAqB,MAAM,gBAAgB,YAAY,KAAK,CAAC;AAAA,MAC5E,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,88 @@
 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(\n    protocolName,\n    method,\n    () => transport().protocolRequest(protocolName, method, params),\n    opts,\n  );\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\n      ? { idleMs: opts.timeoutMs, ceilingMs: opts.timeoutMs }\n      : 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)\n              ? { reason: attendanceReason(scheme, method) as string }\n              : {}),\n            ...(attention?.awaiting\n              ? { awaiting: { kind: attention.kind, since: attention.since } }\n              : {}),\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) =>\n          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,EACE;AAAA,EACA;AAAA,EACA,MAAM,UAAU,EAAE,gBAAgB,cAAc,QAAQ,MAAM;AAAA,EAC9D;AACF;AAaF,eAAsB,aACpB,QACA,QACA,OACA,MACY;AACZ,QAAM,OAAO,GAAG,MAAM,IAAI,MAAM;AAChC,QAAM,aAAa,aAAa,QAAQ,MAAM;AAC9C,QAAM,SACJ,MAAM,cAAc,SAChB,EAAE,QAAQ,KAAK,WAAW,WAAW,KAAK,UAAU,IACpD,UAAU,QAAQ,MAAM;AAC9B,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,IAC/B,EAAE,QAAQ,iBAAiB,QAAQ,MAAM,EAAY,IACrD,CAAC;AAAA,YACL,GAAI,WAAW,WACX,EAAE,UAAU,EAAE,MAAM,UAAU,MAAM,OAAO,UAAU,MAAM,EAAE,IAC7D,CAAC;AAAA,UACP,CAAC;AAAA,QACH,QAAQ;AAAA,QAER;AAAA,MACF;AAEA,iBAAW,0BAA0B;AAAA,QACnC;AAAA,QACA,UAAU,CAAC,OAAO,mBAChB,OAAO,IAAI,qBAAqB,MAAM,gBAAgB,YAAY,KAAK,CAAC;AAAA,MAC5E,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/version.cjs

@@ -21,7 +21,7 @@ __export(version_exports, {
   SDK_VERSION: () => SDK_VERSION
 });
 module.exports = __toCommonJS(version_exports);
-const SDK_VERSION = "0.45.3";
+const SDK_VERSION = "0.46.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SDK_VERSION

package/dist/version.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.45.3';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.46.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,cAAc;","names":[]}

package/dist/version.d.cts

@@ -1,4 +1,4 @@
 /** This SDK's package version, baked from package.json at build (SP2-6). */
-declare const SDK_VERSION = "0.45.3";
+declare const SDK_VERSION = "0.46.0";
 
 export { SDK_VERSION };

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** This SDK's package version, baked from package.json at build (SP2-6). */
-declare const SDK_VERSION = "0.45.3";
+declare const SDK_VERSION = "0.46.0";
 
 export { SDK_VERSION };

package/dist/version.js

@@ -1,5 +1,5 @@
 import "./chunk-VHAA22YE.js";
-const SDK_VERSION = "0.45.3";
+const SDK_VERSION = "0.46.0";
 export {
   SDK_VERSION
 };

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.45.3';\n"],"mappings":";AAIO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.46.0';\n"],"mappings":";AAIO,MAAM,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.45.3",
+  "version": "0.46.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "@immediately-run/platform-constants": "0.2.0",
-    "@immediately-run/sandbox-protocol": "0.3.1",
+    "@immediately-run/sandbox-protocol": "0.4.0",
     "react-error-boundary": "^6.0.0"
   },
   "devDependencies": {