@immediately-run/sdk 0.45.3 → 0.46.0

package/dist/protocolStream.cjs

@@ -24,6 +24,7 @@ __export(protocolStream_exports, {
 });
 module.exports = __toCommonJS(protocolStream_exports);
 var import_sandboxUtils = require("./sandboxUtils");
+var import_protocolDeadline = require("./protocolDeadline");
 class StreamError extends Error {
   constructor(code, message) {
     super(message);
@@ -36,7 +37,7 @@ const nextMsgId = () => {
   streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;
   return streamCounter;
 };
-async function* consumeStream(transport, type, method, params, msgId = nextMsgId(), signal) {
+async function* consumeStream(transport, type, method, params, msgId = nextMsgId(), signal, opts) {
   const queue = [];
   let wake = null;
   let settled = false;
@@ -57,6 +58,52 @@ async function* consumeStream(transport, type, method, params, msgId = nextMsgId
     w?.();
   };
   if (signal) signal.addEventListener("abort", onAbort);
+  const scheme = type.startsWith("protocol-") ? type.slice("protocol-".length) : type;
+  const call = `${scheme}:${method}`;
+  const attendance = (0, import_protocolDeadline.attendanceOf)(scheme, method);
+  const firstFrameMs = opts?.timeoutMs ?? (0, import_protocolDeadline.firstFrameTimeoutFor)(scheme, method);
+  const idleMs = opts?.idleTimeoutMs ?? import_protocolDeadline.STREAM_IDLE_TIMEOUT_MS;
+  let sawFrame = false;
+  let noticed = false;
+  const awaitFrame = async () => {
+    const budget = sawFrame ? idleMs : firstFrameMs;
+    if (!Number.isFinite(budget)) {
+      await new Promise((resolve) => {
+        wake = resolve;
+      });
+      return;
+    }
+    const startedAt = Date.now();
+    let deadline;
+    let notice;
+    try {
+      await new Promise((resolve, reject) => {
+        wake = resolve;
+        deadline = setTimeout(
+          () => reject(new import_protocolDeadline.ProtocolTimeoutError(call, budget, attendance)),
+          budget
+        );
+        if (opts?.onPending && !noticed) {
+          notice = setTimeout(() => {
+            noticed = true;
+            try {
+              opts.onPending?.({
+                call,
+                attendance,
+                elapsedMs: Date.now() - startedAt,
+                ...(0, import_protocolDeadline.attendanceReason)(scheme, method) ? { reason: (0, import_protocolDeadline.attendanceReason)(scheme, method) } : {}
+              });
+            } catch {
+            }
+          }, import_protocolDeadline.PENDING_NOTICE_MS);
+        }
+      });
+    } finally {
+      if (deadline !== void 0) clearTimeout(deadline);
+      if (notice !== void 0) clearTimeout(notice);
+      wake = null;
+    }
+  };
   try {
     if (signal?.aborted) throw new StreamError("aborted", "stream aborted before start");
     transport.send({ type, method, params, msgId, stream: true });
@@ -64,11 +111,10 @@ async function* consumeStream(transport, type, method, params, msgId = nextMsgId
     while (true) {
       if (signal?.aborted) throw new StreamError("aborted", "stream aborted");
       if (queue.length === 0) {
-        await new Promise((resolve) => {
-          wake = resolve;
-        });
+        await awaitFrame();
         continue;
       }
+      sawFrame = true;
       const frame = queue.shift();
       if (frame.kind === "event") {
         yield frame.value;
@@ -91,8 +137,16 @@ const bundlerTransport = {
   subscribe: (type, handler) => (0, import_sandboxUtils.addListener)(type, (msg) => handler(msg)),
   cancel: (msg) => (0, import_sandboxUtils.sendMessage)(msg.type, msg)
 };
-function protocolStream(protocolName, method, params, signal) {
-  return consumeStream(bundlerTransport, protocolName, method, params, void 0, signal);
+function protocolStream(protocolName, method, params, signal, opts) {
+  return consumeStream(
+    bundlerTransport,
+    protocolName,
+    method,
+    params,
+    void 0,
+    signal,
+    opts
+  );
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/protocolStream.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocolStream.ts"],"sourcesContent":["// SDK-side consumer for the host streaming transport (UI_AS_APPS_SPEC §5.1).\n//\n// The host `pumpGenerator` emits, per request msgId, a run of `stream.event`\n// frames terminated by one `stream.done` (with the return value) or `stream.error`\n// frame. This reassembles that run into an AsyncGenerator: each `event` is a\n// `yield`, the `done` value is the generator's `return`, an `error` is a `throw`.\n//\n// `consumeStream` takes an injected `StreamTransport` so it's unit-tested with a\n// fake send/subscribe — no bundler. `protocolStream`/`contribute` below wire it to\n// the real sandbox messageBus via sandboxUtils.\nimport { addListener, sendMessage } from './sandboxUtils';\n\n/** One frame of a host stream: an `event` value, the terminal `done` value, or an `error`. */\nexport type StreamFrame =\n  | { kind: 'event'; value: unknown }\n  | { kind: 'done'; value: unknown }\n  | { kind: 'error'; code: string; message: string };\n\n/** The send/subscribe transport {@link consumeStream} drives (injected so it can be faked in tests). */\nexport interface StreamTransport {\n  // Fire the request that starts the stream. The host replies with frames tagged\n  // by the same `msgId`.\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) => void;\n  // Subscribe to inbound frames for `type`; returns an unsubscribe.\n  subscribe: (\n    type: string,\n    handler: (msg: { msgId?: number; stream?: StreamFrame }) => void\n  ) => () => void;\n  // Tell the host to STOP the stream early — abort the in-flight generation (and,\n  // for `llm:chat`, the upstream provider fetch so it stops BILLING). Sent when the\n  // consumer bails before a terminal frame: an early `break`/`return` out of the\n  // `for await`, or an `AbortSignal` firing. Carries the same `(type, msgId)` the\n  // host tagged its frames with, so the host aborts the matching generator\n  // (LLM_AND_AGENTS_SPEC §3.3 \"abort the in-flight LLM request\"). Optional — a\n  // transport predating the cancel frame simply omits it and the old behavior\n  // (host runs to completion) stands.\n  cancel?: (msg: { type: string; msgId: number; cancel: true }) => void;\n}\n\n/** Thrown when a stream ends in an `error` frame; carries the host's `code`. */\nexport class StreamError extends Error {\n  code: string;\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = 'StreamError';\n    this.code = code;\n  }\n}\n\nlet streamCounter = 0;\nconst nextMsgId = (): number => {\n  // Distinct from the bundler's own protocolRequest counter space is unnecessary —\n  // frames are filtered by (type, msgId, stream) so a collision with a one-shot\n  // reply (which has `result`, not `stream`) can't be misread.\n  streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;\n  return streamCounter;\n};\n\n/**\n * Drive one streamed request to completion over an injected transport.\n *\n * Yields each event value; returns the `done` value; throws `StreamError` on an\n * error frame. Always unsubscribes (via the generator's `finally`) so an early\n * `break` in the consumer doesn't leak the listener.\n *\n * `signal` wires a caller {@link AbortSignal} to mid-stream cancellation: when it\n * fires (or the consumer `break`s before a terminal frame), the `finally` sends a\n * `cancel` frame back over `transport.cancel` so the HOST stops generating — without\n * it, aborting only stops the app-side iterator while the upstream provider keeps\n * streaming and BILLING (LLM_AND_AGENTS_SPEC §3.3, R3-224 / adversarial F2).\n */\nexport async function* consumeStream<T = unknown, R = unknown>(\n  transport: StreamTransport,\n  type: string,\n  method: string,\n  params: unknown[],\n  msgId: number = nextMsgId(),\n  signal?: AbortSignal\n): AsyncGenerator<T, R, void> {\n  const queue: StreamFrame[] = [];\n  let wake: (() => void) | null = null;\n  // True once a terminal (`done`/`error`) frame arrived — so the `finally` knows the\n  // host already stopped and must NOT send a redundant cancel. Left false when the\n  // consumer bails early or the signal aborts (the two cases that DO need a cancel).\n  let settled = false;\n  // True once the request frame went out. A cancel is only meaningful for a stream\n  // the host actually started — an abort BEFORE `send` sends nothing to cancel.\n  let started = false;\n  const push = (frame: StreamFrame) => {\n    queue.push(frame);\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n\n  const unsubscribe = transport.subscribe(type, (msg) => {\n    if (msg.msgId !== msgId || !msg.stream) return;\n    push(msg.stream);\n  });\n\n  // An abort wakes the pull loop out of its idle `await`; the loop then throws.\n  const onAbort = () => {\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n  if (signal) signal.addEventListener('abort', onAbort);\n\n  try {\n    if (signal?.aborted) throw new StreamError('aborted', 'stream aborted before start');\n    transport.send({ type, method, params, msgId, stream: true });\n    started = true;\n    while (true) {\n      if (signal?.aborted) throw new StreamError('aborted', 'stream aborted');\n      if (queue.length === 0) {\n        await new Promise<void>((resolve) => {\n          wake = resolve;\n        });\n        continue;\n      }\n      const frame = queue.shift() as StreamFrame;\n      if (frame.kind === 'event') {\n        yield frame.value as T;\n      } else if (frame.kind === 'done') {\n        settled = true;\n        return frame.value as R;\n      } else {\n        settled = true;\n        throw new StreamError(frame.code, frame.message);\n      }\n    }\n  } finally {\n    unsubscribe();\n    if (signal) signal.removeEventListener('abort', onAbort);\n    // Consumer stopped pulling before a terminal frame (early break/return, or the\n    // signal aborted): tell the host to stop the in-flight generation + billing.\n    if (started && !settled) transport.cancel?.({ type, msgId, cancel: true });\n  }\n}\n\n// The real sandbox transport, built from the bundler messageBus helpers. `cancel`\n// rides the same messageBus as `send` — a `{type, msgId, cancel:true}` frame the\n// host dispatcher routes to the in-flight generator's AbortController.\nconst bundlerTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n  cancel: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n};\n\n/**\n * Consume an elevated streaming protocol method from app code.\n *\n * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`\n *\n * Pass `signal` to abort the stream (and the host's in-flight work) mid-flight.\n */\nexport function protocolStream<T = unknown, R = unknown>(\n  protocolName: string,\n  method: string,\n  params: unknown[],\n  signal?: AbortSignal\n): AsyncGenerator<T, R, void> {\n  return consumeStream<T, R>(bundlerTransport, protocolName, method, params, undefined, signal);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,0BAAyC;AA8BlC,MAAM,oBAAoB,MAAM;AAAA,EAErC,YAAY,MAAc,SAAiB;AACzC,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAEA,IAAI,gBAAgB;AACpB,MAAM,YAAY,MAAc;AAI9B,mBAAiB,gBAAgB,KAAK,OAAO;AAC7C,SAAO;AACT;AAeA,gBAAuB,cACrB,WACA,MACA,QACA,QACA,QAAgB,UAAU,GAC1B,QAC4B;AAC5B,QAAM,QAAuB,CAAC;AAC9B,MAAI,OAA4B;AAIhC,MAAI,UAAU;AAGd,MAAI,UAAU;AACd,QAAM,OAAO,CAAC,UAAuB;AACnC,UAAM,KAAK,KAAK;AAChB,UAAM,IAAI;AACV,WAAO;AACP,QAAI;AAAA,EACN;AAEA,QAAM,cAAc,UAAU,UAAU,MAAM,CAAC,QAAQ;AACrD,QAAI,IAAI,UAAU,SAAS,CAAC,IAAI,OAAQ;AACxC,SAAK,IAAI,MAAM;AAAA,EACjB,CAAC;AAGD,QAAM,UAAU,MAAM;AACpB,UAAM,IAAI;AACV,WAAO;AACP,QAAI;AAAA,EACN;AACA,MAAI,OAAQ,QAAO,iBAAiB,SAAS,OAAO;AAEpD,MAAI;AACF,QAAI,QAAQ,QAAS,OAAM,IAAI,YAAY,WAAW,6BAA6B;AACnF,cAAU,KAAK,EAAE,MAAM,QAAQ,QAAQ,OAAO,QAAQ,KAAK,CAAC;AAC5D,cAAU;AACV,WAAO,MAAM;AACX,UAAI,QAAQ,QAAS,OAAM,IAAI,YAAY,WAAW,gBAAgB;AACtE,UAAI,MAAM,WAAW,GAAG;AACtB,cAAM,IAAI,QAAc,CAAC,YAAY;AACnC,iBAAO;AAAA,QACT,CAAC;AACD;AAAA,MACF;AACA,YAAM,QAAQ,MAAM,MAAM;AAC1B,UAAI,MAAM,SAAS,SAAS;AAC1B,cAAM,MAAM;AAAA,MACd,WAAW,MAAM,SAAS,QAAQ;AAChC,kBAAU;AACV,eAAO,MAAM;AAAA,MACf,OAAO;AACL,kBAAU;AACV,cAAM,IAAI,YAAY,MAAM,MAAM,MAAM,OAAO;AAAA,MACjD;AAAA,IACF;AAAA,EACF,UAAE;AACA,gBAAY;AACZ,QAAI,OAAQ,QAAO,oBAAoB,SAAS,OAAO;AAGvD,QAAI,WAAW,CAAC,QAAS,WAAU,SAAS,EAAE,MAAM,OAAO,QAAQ,KAAK,CAAC;AAAA,EAC3E;AACF;AAKA,MAAM,mBAAoC;AAAA,EACxC,MAAM,CAAC,YAAQ,iCAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,gBAChB,iCAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AAAA,EACrF,QAAQ,CAAC,YAAQ,iCAAY,IAAI,MAAM,GAAyC;AAClF;AASO,SAAS,eACd,cACA,QACA,QACA,QAC4B;AAC5B,SAAO,cAAoB,kBAAkB,cAAc,QAAQ,QAAQ,QAAW,MAAM;AAC9F;","names":[]}
+{"version":3,"sources":["../src/protocolStream.ts"],"sourcesContent":["// SDK-side consumer for the host streaming transport (UI_AS_APPS_SPEC §5.1).\n//\n// The host `pumpGenerator` emits, per request msgId, a run of `stream.event`\n// frames terminated by one `stream.done` (with the return value) or `stream.error`\n// frame. This reassembles that run into an AsyncGenerator: each `event` is a\n// `yield`, the `done` value is the generator's `return`, an `error` is a `throw`.\n//\n// `consumeStream` takes an injected `StreamTransport` so it's unit-tested with a\n// fake send/subscribe — no bundler. `protocolStream`/`contribute` below wire it to\n// the real sandbox messageBus via sandboxUtils.\nimport { addListener, sendMessage } from './sandboxUtils';\nimport {\n  attendanceOf,\n  attendanceReason,\n  firstFrameTimeoutFor,\n  PENDING_NOTICE_MS,\n  ProtocolTimeoutError,\n  STREAM_IDLE_TIMEOUT_MS,\n  type BoundedCallOptions,\n} from './protocolDeadline';\n\n/** One frame of a host stream: an `event` value, the terminal `done` value, or an `error`. */\nexport type StreamFrame =\n  | { kind: 'event'; value: unknown }\n  | { kind: 'done'; value: unknown }\n  | { kind: 'error'; code: string; message: string };\n\n/** The send/subscribe transport {@link consumeStream} drives (injected so it can be faked in tests). */\nexport interface StreamTransport {\n  // Fire the request that starts the stream. The host replies with frames tagged\n  // by the same `msgId`.\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) => void;\n  // Subscribe to inbound frames for `type`; returns an unsubscribe.\n  subscribe: (\n    type: string,\n    handler: (msg: { msgId?: number; stream?: StreamFrame }) => void\n  ) => () => void;\n  // Tell the host to STOP the stream early — abort the in-flight generation (and,\n  // for `llm:chat`, the upstream provider fetch so it stops BILLING). Sent when the\n  // consumer bails before a terminal frame: an early `break`/`return` out of the\n  // `for await`, or an `AbortSignal` firing. Carries the same `(type, msgId)` the\n  // host tagged its frames with, so the host aborts the matching generator\n  // (LLM_AND_AGENTS_SPEC §3.3 \"abort the in-flight LLM request\"). Optional — a\n  // transport predating the cancel frame simply omits it and the old behavior\n  // (host runs to completion) stands.\n  cancel?: (msg: { type: string; msgId: number; cancel: true }) => void;\n}\n\n/** Thrown when a stream ends in an `error` frame; carries the host's `code`. */\nexport class StreamError extends Error {\n  code: string;\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = 'StreamError';\n    this.code = code;\n  }\n}\n\nlet streamCounter = 0;\nconst nextMsgId = (): number => {\n  // Distinct from the bundler's own protocolRequest counter space is unnecessary —\n  // frames are filtered by (type, msgId, stream) so a collision with a one-shot\n  // reply (which has `result`, not `stream`) can't be misread.\n  streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;\n  return streamCounter;\n};\n\n/**\n * Drive one streamed request to completion over an injected transport.\n *\n * Yields each event value; returns the `done` value; throws `StreamError` on an\n * error frame. Always unsubscribes (via the generator's `finally`) so an early\n * `break` in the consumer doesn't leak the listener.\n *\n * `signal` wires a caller {@link AbortSignal} to mid-stream cancellation: when it\n * fires (or the consumer `break`s before a terminal frame), the `finally` sends a\n * `cancel` frame back over `transport.cancel` so the HOST stops generating — without\n * it, aborting only stops the app-side iterator while the upstream provider keeps\n * streaming and BILLING (LLM_AND_AGENTS_SPEC §3.3, R3-224 / adversarial F2).\n */\nexport async function* consumeStream<T = unknown, R = unknown>(\n  transport: StreamTransport,\n  type: string,\n  method: string,\n  params: unknown[],\n  msgId: number = nextMsgId(),\n  signal?: AbortSignal,\n  opts?: BoundedCallOptions & { idleTimeoutMs?: number }\n): AsyncGenerator<T, R, void> {\n  const queue: StreamFrame[] = [];\n  let wake: (() => void) | null = null;\n  // True once a terminal (`done`/`error`) frame arrived — so the `finally` knows the\n  // host already stopped and must NOT send a redundant cancel. Left false when the\n  // consumer bails early or the signal aborts (the two cases that DO need a cancel).\n  let settled = false;\n  // True once the request frame went out. A cancel is only meaningful for a stream\n  // the host actually started — an abort BEFORE `send` sends nothing to cancel.\n  let started = false;\n  const push = (frame: StreamFrame) => {\n    queue.push(frame);\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n\n  const unsubscribe = transport.subscribe(type, (msg) => {\n    if (msg.msgId !== msgId || !msg.stream) return;\n    push(msg.stream);\n  });\n\n  // An abort wakes the pull loop out of its idle `await`; the loop then throws.\n  const onAbort = () => {\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n  if (signal) signal.addEventListener('abort', onAbort);\n\n  // R3-298 — a stream is bounded by SILENCE, not by duration.\n  //\n  // A total-duration deadline would be wrong here: a long generation that is streaming\n  // normally is healthy, and aborting it would be a worse bug than the hang. The hang has a\n  // distinct shape — no frames at all — so that is what is bounded: a time-to-FIRST-FRAME\n  // deadline, then an idle-gap deadline once frames are flowing. Together they fire exactly\n  // on a wedged stream and never on a slow one.\n  //\n  // The scheme's `type` is `protocol-llm`; the classification table is keyed on the bare\n  // scheme, so strip the prefix. The chat stream is classified ATTENDED because its first\n  // frame can sit behind the session's first passkey unseal — the dogfood hang.\n  const scheme = type.startsWith('protocol-') ? type.slice('protocol-'.length) : type;\n  const call = `${scheme}:${method}`;\n  const attendance = attendanceOf(scheme, method);\n  const firstFrameMs = opts?.timeoutMs ?? firstFrameTimeoutFor(scheme, method);\n  const idleMs = opts?.idleTimeoutMs ?? STREAM_IDLE_TIMEOUT_MS;\n  let sawFrame = false;\n  let noticed = false;\n\n  /** Wait for the next frame, bounded. Rejects with a typed timeout rather than parking. */\n  const awaitFrame = async (): Promise<void> => {\n    const budget = sawFrame ? idleMs : firstFrameMs;\n    if (!Number.isFinite(budget)) {\n      await new Promise<void>((resolve) => {\n        wake = resolve;\n      });\n      return;\n    }\n    const startedAt = Date.now();\n    let deadline: ReturnType<typeof setTimeout> | undefined;\n    let notice: ReturnType<typeof setTimeout> | undefined;\n    try {\n      await new Promise<void>((resolve, reject) => {\n        wake = resolve;\n        deadline = setTimeout(\n          () => reject(new ProtocolTimeoutError(call, budget, attendance)),\n          budget,\n        );\n        if (opts?.onPending && !noticed) {\n          notice = setTimeout(() => {\n            noticed = true;\n            try {\n              opts.onPending?.({\n                call,\n                attendance,\n                elapsedMs: Date.now() - startedAt,\n                ...(attendanceReason(scheme, method)\n                  ? { reason: attendanceReason(scheme, method) as string }\n                  : {}),\n              });\n            } catch {\n              /* a caller's render callback must never break the stream it describes */\n            }\n          }, PENDING_NOTICE_MS);\n        }\n      });\n    } finally {\n      if (deadline !== undefined) clearTimeout(deadline);\n      if (notice !== undefined) clearTimeout(notice);\n      wake = null;\n    }\n  };\n\n  try {\n    if (signal?.aborted) throw new StreamError('aborted', 'stream aborted before start');\n    transport.send({ type, method, params, msgId, stream: true });\n    started = true;\n    while (true) {\n      if (signal?.aborted) throw new StreamError('aborted', 'stream aborted');\n      if (queue.length === 0) {\n        // A timeout throws out of here into the `finally`, which sends the host a real\n        // cancel frame — so a wedged stream stops generating and BILLING rather than being\n        // merely abandoned by the app. Streams can do this because they own their `msgId`.\n        await awaitFrame();\n        continue;\n      }\n      sawFrame = true;\n      const frame = queue.shift() as StreamFrame;\n      if (frame.kind === 'event') {\n        yield frame.value as T;\n      } else if (frame.kind === 'done') {\n        settled = true;\n        return frame.value as R;\n      } else {\n        settled = true;\n        throw new StreamError(frame.code, frame.message);\n      }\n    }\n  } finally {\n    unsubscribe();\n    if (signal) signal.removeEventListener('abort', onAbort);\n    // Consumer stopped pulling before a terminal frame (early break/return, or the\n    // signal aborted): tell the host to stop the in-flight generation + billing.\n    if (started && !settled) transport.cancel?.({ type, msgId, cancel: true });\n  }\n}\n\n// The real sandbox transport, built from the bundler messageBus helpers. `cancel`\n// rides the same messageBus as `send` — a `{type, msgId, cancel:true}` frame the\n// host dispatcher routes to the in-flight generator's AbortController.\nconst bundlerTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n  cancel: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n};\n\n/**\n * Consume an elevated streaming protocol method from app code.\n *\n * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`\n *\n * Pass `signal` to abort the stream (and the host's in-flight work) mid-flight.\n */\nexport function protocolStream<T = unknown, R = unknown>(\n  protocolName: string,\n  method: string,\n  params: unknown[],\n  signal?: AbortSignal,\n  opts?: BoundedCallOptions & { idleTimeoutMs?: number }\n): AsyncGenerator<T, R, void> {\n  return consumeStream<T, R>(\n    bundlerTransport,\n    protocolName,\n    method,\n    params,\n    undefined,\n    signal,\n    opts\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/protocolStream.d.cts

@@ -1,3 +1,6 @@
+import { BoundedCallOptions } from './protocolDeadline.cjs';
+import './hostAttention.cjs';
+
 /** One frame of a host stream: an `event` value, the terminal `done` value, or an `error`. */
 type StreamFrame = {
     kind: 'event';
@@ -47,7 +50,9 @@ declare class StreamError extends Error {
  * it, aborting only stops the app-side iterator while the upstream provider keeps
  * streaming and BILLING (LLM_AND_AGENTS_SPEC §3.3, R3-224 / adversarial F2).
  */
-declare function consumeStream<T = unknown, R = unknown>(transport: StreamTransport, type: string, method: string, params: unknown[], msgId?: number, signal?: AbortSignal): AsyncGenerator<T, R, void>;
+declare function consumeStream<T = unknown, R = unknown>(transport: StreamTransport, type: string, method: string, params: unknown[], msgId?: number, signal?: AbortSignal, opts?: BoundedCallOptions & {
+    idleTimeoutMs?: number;
+}): AsyncGenerator<T, R, void>;
 /**
  * Consume an elevated streaming protocol method from app code.
  *
@@ -55,6 +60,8 @@ declare function consumeStream<T = unknown, R = unknown>(transport: StreamTransp
  *
  * Pass `signal` to abort the stream (and the host's in-flight work) mid-flight.
  */
-declare function protocolStream<T = unknown, R = unknown>(protocolName: string, method: string, params: unknown[], signal?: AbortSignal): AsyncGenerator<T, R, void>;
+declare function protocolStream<T = unknown, R = unknown>(protocolName: string, method: string, params: unknown[], signal?: AbortSignal, opts?: BoundedCallOptions & {
+    idleTimeoutMs?: number;
+}): AsyncGenerator<T, R, void>;
 
 export { StreamError, type StreamFrame, type StreamTransport, consumeStream, protocolStream };

package/dist/protocolStream.d.ts

@@ -1,3 +1,6 @@
+import { BoundedCallOptions } from './protocolDeadline.js';
+import './hostAttention.js';
+
 /** One frame of a host stream: an `event` value, the terminal `done` value, or an `error`. */
 type StreamFrame = {
     kind: 'event';
@@ -47,7 +50,9 @@ declare class StreamError extends Error {
  * it, aborting only stops the app-side iterator while the upstream provider keeps
  * streaming and BILLING (LLM_AND_AGENTS_SPEC §3.3, R3-224 / adversarial F2).
  */
-declare function consumeStream<T = unknown, R = unknown>(transport: StreamTransport, type: string, method: string, params: unknown[], msgId?: number, signal?: AbortSignal): AsyncGenerator<T, R, void>;
+declare function consumeStream<T = unknown, R = unknown>(transport: StreamTransport, type: string, method: string, params: unknown[], msgId?: number, signal?: AbortSignal, opts?: BoundedCallOptions & {
+    idleTimeoutMs?: number;
+}): AsyncGenerator<T, R, void>;
 /**
  * Consume an elevated streaming protocol method from app code.
  *
@@ -55,6 +60,8 @@ declare function consumeStream<T = unknown, R = unknown>(transport: StreamTransp
  *
  * Pass `signal` to abort the stream (and the host's in-flight work) mid-flight.
  */
-declare function protocolStream<T = unknown, R = unknown>(protocolName: string, method: string, params: unknown[], signal?: AbortSignal): AsyncGenerator<T, R, void>;
+declare function protocolStream<T = unknown, R = unknown>(protocolName: string, method: string, params: unknown[], signal?: AbortSignal, opts?: BoundedCallOptions & {
+    idleTimeoutMs?: number;
+}): AsyncGenerator<T, R, void>;
 
 export { StreamError, type StreamFrame, type StreamTransport, consumeStream, protocolStream };

package/dist/protocolStream.js

@@ -1,5 +1,13 @@
 import "./chunk-VHAA22YE.js";
 import { addListener, sendMessage } from "./sandboxUtils";
+import {
+  attendanceOf,
+  attendanceReason,
+  firstFrameTimeoutFor,
+  PENDING_NOTICE_MS,
+  ProtocolTimeoutError,
+  STREAM_IDLE_TIMEOUT_MS
+} from "./protocolDeadline";
 class StreamError extends Error {
   constructor(code, message) {
     super(message);
@@ -12,7 +20,7 @@ const nextMsgId = () => {
   streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;
   return streamCounter;
 };
-async function* consumeStream(transport, type, method, params, msgId = nextMsgId(), signal) {
+async function* consumeStream(transport, type, method, params, msgId = nextMsgId(), signal, opts) {
   const queue = [];
   let wake = null;
   let settled = false;
@@ -33,6 +41,52 @@ async function* consumeStream(transport, type, method, params, msgId = nextMsgId
     w?.();
   };
   if (signal) signal.addEventListener("abort", onAbort);
+  const scheme = type.startsWith("protocol-") ? type.slice("protocol-".length) : type;
+  const call = `${scheme}:${method}`;
+  const attendance = attendanceOf(scheme, method);
+  const firstFrameMs = opts?.timeoutMs ?? firstFrameTimeoutFor(scheme, method);
+  const idleMs = opts?.idleTimeoutMs ?? STREAM_IDLE_TIMEOUT_MS;
+  let sawFrame = false;
+  let noticed = false;
+  const awaitFrame = async () => {
+    const budget = sawFrame ? idleMs : firstFrameMs;
+    if (!Number.isFinite(budget)) {
+      await new Promise((resolve) => {
+        wake = resolve;
+      });
+      return;
+    }
+    const startedAt = Date.now();
+    let deadline;
+    let notice;
+    try {
+      await new Promise((resolve, reject) => {
+        wake = resolve;
+        deadline = setTimeout(
+          () => reject(new ProtocolTimeoutError(call, budget, attendance)),
+          budget
+        );
+        if (opts?.onPending && !noticed) {
+          notice = setTimeout(() => {
+            noticed = true;
+            try {
+              opts.onPending?.({
+                call,
+                attendance,
+                elapsedMs: Date.now() - startedAt,
+                ...attendanceReason(scheme, method) ? { reason: attendanceReason(scheme, method) } : {}
+              });
+            } catch {
+            }
+          }, PENDING_NOTICE_MS);
+        }
+      });
+    } finally {
+      if (deadline !== void 0) clearTimeout(deadline);
+      if (notice !== void 0) clearTimeout(notice);
+      wake = null;
+    }
+  };
   try {
     if (signal?.aborted) throw new StreamError("aborted", "stream aborted before start");
     transport.send({ type, method, params, msgId, stream: true });
@@ -40,11 +94,10 @@ async function* consumeStream(transport, type, method, params, msgId = nextMsgId
     while (true) {
       if (signal?.aborted) throw new StreamError("aborted", "stream aborted");
       if (queue.length === 0) {
-        await new Promise((resolve) => {
-          wake = resolve;
-        });
+        await awaitFrame();
         continue;
       }
+      sawFrame = true;
       const frame = queue.shift();
       if (frame.kind === "event") {
         yield frame.value;
@@ -67,8 +120,16 @@ const bundlerTransport = {
   subscribe: (type, handler) => addListener(type, (msg) => handler(msg)),
   cancel: (msg) => sendMessage(msg.type, msg)
 };
-function protocolStream(protocolName, method, params, signal) {
-  return consumeStream(bundlerTransport, protocolName, method, params, void 0, signal);
+function protocolStream(protocolName, method, params, signal, opts) {
+  return consumeStream(
+    bundlerTransport,
+    protocolName,
+    method,
+    params,
+    void 0,
+    signal,
+    opts
+  );
 }
 export {
   StreamError,

package/dist/protocolStream.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocolStream.ts"],"sourcesContent":["// SDK-side consumer for the host streaming transport (UI_AS_APPS_SPEC §5.1).\n//\n// The host `pumpGenerator` emits, per request msgId, a run of `stream.event`\n// frames terminated by one `stream.done` (with the return value) or `stream.error`\n// frame. This reassembles that run into an AsyncGenerator: each `event` is a\n// `yield`, the `done` value is the generator's `return`, an `error` is a `throw`.\n//\n// `consumeStream` takes an injected `StreamTransport` so it's unit-tested with a\n// fake send/subscribe — no bundler. `protocolStream`/`contribute` below wire it to\n// the real sandbox messageBus via sandboxUtils.\nimport { addListener, sendMessage } from './sandboxUtils';\n\n/** One frame of a host stream: an `event` value, the terminal `done` value, or an `error`. */\nexport type StreamFrame =\n  | { kind: 'event'; value: unknown }\n  | { kind: 'done'; value: unknown }\n  | { kind: 'error'; code: string; message: string };\n\n/** The send/subscribe transport {@link consumeStream} drives (injected so it can be faked in tests). */\nexport interface StreamTransport {\n  // Fire the request that starts the stream. The host replies with frames tagged\n  // by the same `msgId`.\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) => void;\n  // Subscribe to inbound frames for `type`; returns an unsubscribe.\n  subscribe: (\n    type: string,\n    handler: (msg: { msgId?: number; stream?: StreamFrame }) => void\n  ) => () => void;\n  // Tell the host to STOP the stream early — abort the in-flight generation (and,\n  // for `llm:chat`, the upstream provider fetch so it stops BILLING). Sent when the\n  // consumer bails before a terminal frame: an early `break`/`return` out of the\n  // `for await`, or an `AbortSignal` firing. Carries the same `(type, msgId)` the\n  // host tagged its frames with, so the host aborts the matching generator\n  // (LLM_AND_AGENTS_SPEC §3.3 \"abort the in-flight LLM request\"). Optional — a\n  // transport predating the cancel frame simply omits it and the old behavior\n  // (host runs to completion) stands.\n  cancel?: (msg: { type: string; msgId: number; cancel: true }) => void;\n}\n\n/** Thrown when a stream ends in an `error` frame; carries the host's `code`. */\nexport class StreamError extends Error {\n  code: string;\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = 'StreamError';\n    this.code = code;\n  }\n}\n\nlet streamCounter = 0;\nconst nextMsgId = (): number => {\n  // Distinct from the bundler's own protocolRequest counter space is unnecessary —\n  // frames are filtered by (type, msgId, stream) so a collision with a one-shot\n  // reply (which has `result`, not `stream`) can't be misread.\n  streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;\n  return streamCounter;\n};\n\n/**\n * Drive one streamed request to completion over an injected transport.\n *\n * Yields each event value; returns the `done` value; throws `StreamError` on an\n * error frame. Always unsubscribes (via the generator's `finally`) so an early\n * `break` in the consumer doesn't leak the listener.\n *\n * `signal` wires a caller {@link AbortSignal} to mid-stream cancellation: when it\n * fires (or the consumer `break`s before a terminal frame), the `finally` sends a\n * `cancel` frame back over `transport.cancel` so the HOST stops generating — without\n * it, aborting only stops the app-side iterator while the upstream provider keeps\n * streaming and BILLING (LLM_AND_AGENTS_SPEC §3.3, R3-224 / adversarial F2).\n */\nexport async function* consumeStream<T = unknown, R = unknown>(\n  transport: StreamTransport,\n  type: string,\n  method: string,\n  params: unknown[],\n  msgId: number = nextMsgId(),\n  signal?: AbortSignal\n): AsyncGenerator<T, R, void> {\n  const queue: StreamFrame[] = [];\n  let wake: (() => void) | null = null;\n  // True once a terminal (`done`/`error`) frame arrived — so the `finally` knows the\n  // host already stopped and must NOT send a redundant cancel. Left false when the\n  // consumer bails early or the signal aborts (the two cases that DO need a cancel).\n  let settled = false;\n  // True once the request frame went out. A cancel is only meaningful for a stream\n  // the host actually started — an abort BEFORE `send` sends nothing to cancel.\n  let started = false;\n  const push = (frame: StreamFrame) => {\n    queue.push(frame);\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n\n  const unsubscribe = transport.subscribe(type, (msg) => {\n    if (msg.msgId !== msgId || !msg.stream) return;\n    push(msg.stream);\n  });\n\n  // An abort wakes the pull loop out of its idle `await`; the loop then throws.\n  const onAbort = () => {\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n  if (signal) signal.addEventListener('abort', onAbort);\n\n  try {\n    if (signal?.aborted) throw new StreamError('aborted', 'stream aborted before start');\n    transport.send({ type, method, params, msgId, stream: true });\n    started = true;\n    while (true) {\n      if (signal?.aborted) throw new StreamError('aborted', 'stream aborted');\n      if (queue.length === 0) {\n        await new Promise<void>((resolve) => {\n          wake = resolve;\n        });\n        continue;\n      }\n      const frame = queue.shift() as StreamFrame;\n      if (frame.kind === 'event') {\n        yield frame.value as T;\n      } else if (frame.kind === 'done') {\n        settled = true;\n        return frame.value as R;\n      } else {\n        settled = true;\n        throw new StreamError(frame.code, frame.message);\n      }\n    }\n  } finally {\n    unsubscribe();\n    if (signal) signal.removeEventListener('abort', onAbort);\n    // Consumer stopped pulling before a terminal frame (early break/return, or the\n    // signal aborted): tell the host to stop the in-flight generation + billing.\n    if (started && !settled) transport.cancel?.({ type, msgId, cancel: true });\n  }\n}\n\n// The real sandbox transport, built from the bundler messageBus helpers. `cancel`\n// rides the same messageBus as `send` — a `{type, msgId, cancel:true}` frame the\n// host dispatcher routes to the in-flight generator's AbortController.\nconst bundlerTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n  cancel: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n};\n\n/**\n * Consume an elevated streaming protocol method from app code.\n *\n * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`\n *\n * Pass `signal` to abort the stream (and the host's in-flight work) mid-flight.\n */\nexport function protocolStream<T = unknown, R = unknown>(\n  protocolName: string,\n  method: string,\n  params: unknown[],\n  signal?: AbortSignal\n): AsyncGenerator<T, R, void> {\n  return consumeStream<T, R>(bundlerTransport, protocolName, method, params, undefined, signal);\n}\n"],"mappings":";AAUA,SAAS,aAAa,mBAAmB;AA8BlC,MAAM,oBAAoB,MAAM;AAAA,EAErC,YAAY,MAAc,SAAiB;AACzC,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAEA,IAAI,gBAAgB;AACpB,MAAM,YAAY,MAAc;AAI9B,mBAAiB,gBAAgB,KAAK,OAAO;AAC7C,SAAO;AACT;AAeA,gBAAuB,cACrB,WACA,MACA,QACA,QACA,QAAgB,UAAU,GAC1B,QAC4B;AAC5B,QAAM,QAAuB,CAAC;AAC9B,MAAI,OAA4B;AAIhC,MAAI,UAAU;AAGd,MAAI,UAAU;AACd,QAAM,OAAO,CAAC,UAAuB;AACnC,UAAM,KAAK,KAAK;AAChB,UAAM,IAAI;AACV,WAAO;AACP,QAAI;AAAA,EACN;AAEA,QAAM,cAAc,UAAU,UAAU,MAAM,CAAC,QAAQ;AACrD,QAAI,IAAI,UAAU,SAAS,CAAC,IAAI,OAAQ;AACxC,SAAK,IAAI,MAAM;AAAA,EACjB,CAAC;AAGD,QAAM,UAAU,MAAM;AACpB,UAAM,IAAI;AACV,WAAO;AACP,QAAI;AAAA,EACN;AACA,MAAI,OAAQ,QAAO,iBAAiB,SAAS,OAAO;AAEpD,MAAI;AACF,QAAI,QAAQ,QAAS,OAAM,IAAI,YAAY,WAAW,6BAA6B;AACnF,cAAU,KAAK,EAAE,MAAM,QAAQ,QAAQ,OAAO,QAAQ,KAAK,CAAC;AAC5D,cAAU;AACV,WAAO,MAAM;AACX,UAAI,QAAQ,QAAS,OAAM,IAAI,YAAY,WAAW,gBAAgB;AACtE,UAAI,MAAM,WAAW,GAAG;AACtB,cAAM,IAAI,QAAc,CAAC,YAAY;AACnC,iBAAO;AAAA,QACT,CAAC;AACD;AAAA,MACF;AACA,YAAM,QAAQ,MAAM,MAAM;AAC1B,UAAI,MAAM,SAAS,SAAS;AAC1B,cAAM,MAAM;AAAA,MACd,WAAW,MAAM,SAAS,QAAQ;AAChC,kBAAU;AACV,eAAO,MAAM;AAAA,MACf,OAAO;AACL,kBAAU;AACV,cAAM,IAAI,YAAY,MAAM,MAAM,MAAM,OAAO;AAAA,MACjD;AAAA,IACF;AAAA,EACF,UAAE;AACA,gBAAY;AACZ,QAAI,OAAQ,QAAO,oBAAoB,SAAS,OAAO;AAGvD,QAAI,WAAW,CAAC,QAAS,WAAU,SAAS,EAAE,MAAM,OAAO,QAAQ,KAAK,CAAC;AAAA,EAC3E;AACF;AAKA,MAAM,mBAAoC;AAAA,EACxC,MAAM,CAAC,QAAQ,YAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,YAChB,YAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AAAA,EACrF,QAAQ,CAAC,QAAQ,YAAY,IAAI,MAAM,GAAyC;AAClF;AASO,SAAS,eACd,cACA,QACA,QACA,QAC4B;AAC5B,SAAO,cAAoB,kBAAkB,cAAc,QAAQ,QAAQ,QAAW,MAAM;AAC9F;","names":[]}
+{"version":3,"sources":["../src/protocolStream.ts"],"sourcesContent":["// SDK-side consumer for the host streaming transport (UI_AS_APPS_SPEC §5.1).\n//\n// The host `pumpGenerator` emits, per request msgId, a run of `stream.event`\n// frames terminated by one `stream.done` (with the return value) or `stream.error`\n// frame. This reassembles that run into an AsyncGenerator: each `event` is a\n// `yield`, the `done` value is the generator's `return`, an `error` is a `throw`.\n//\n// `consumeStream` takes an injected `StreamTransport` so it's unit-tested with a\n// fake send/subscribe — no bundler. `protocolStream`/`contribute` below wire it to\n// the real sandbox messageBus via sandboxUtils.\nimport { addListener, sendMessage } from './sandboxUtils';\nimport {\n  attendanceOf,\n  attendanceReason,\n  firstFrameTimeoutFor,\n  PENDING_NOTICE_MS,\n  ProtocolTimeoutError,\n  STREAM_IDLE_TIMEOUT_MS,\n  type BoundedCallOptions,\n} from './protocolDeadline';\n\n/** One frame of a host stream: an `event` value, the terminal `done` value, or an `error`. */\nexport type StreamFrame =\n  | { kind: 'event'; value: unknown }\n  | { kind: 'done'; value: unknown }\n  | { kind: 'error'; code: string; message: string };\n\n/** The send/subscribe transport {@link consumeStream} drives (injected so it can be faked in tests). */\nexport interface StreamTransport {\n  // Fire the request that starts the stream. The host replies with frames tagged\n  // by the same `msgId`.\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) => void;\n  // Subscribe to inbound frames for `type`; returns an unsubscribe.\n  subscribe: (\n    type: string,\n    handler: (msg: { msgId?: number; stream?: StreamFrame }) => void\n  ) => () => void;\n  // Tell the host to STOP the stream early — abort the in-flight generation (and,\n  // for `llm:chat`, the upstream provider fetch so it stops BILLING). Sent when the\n  // consumer bails before a terminal frame: an early `break`/`return` out of the\n  // `for await`, or an `AbortSignal` firing. Carries the same `(type, msgId)` the\n  // host tagged its frames with, so the host aborts the matching generator\n  // (LLM_AND_AGENTS_SPEC §3.3 \"abort the in-flight LLM request\"). Optional — a\n  // transport predating the cancel frame simply omits it and the old behavior\n  // (host runs to completion) stands.\n  cancel?: (msg: { type: string; msgId: number; cancel: true }) => void;\n}\n\n/** Thrown when a stream ends in an `error` frame; carries the host's `code`. */\nexport class StreamError extends Error {\n  code: string;\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = 'StreamError';\n    this.code = code;\n  }\n}\n\nlet streamCounter = 0;\nconst nextMsgId = (): number => {\n  // Distinct from the bundler's own protocolRequest counter space is unnecessary —\n  // frames are filtered by (type, msgId, stream) so a collision with a one-shot\n  // reply (which has `result`, not `stream`) can't be misread.\n  streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;\n  return streamCounter;\n};\n\n/**\n * Drive one streamed request to completion over an injected transport.\n *\n * Yields each event value; returns the `done` value; throws `StreamError` on an\n * error frame. Always unsubscribes (via the generator's `finally`) so an early\n * `break` in the consumer doesn't leak the listener.\n *\n * `signal` wires a caller {@link AbortSignal} to mid-stream cancellation: when it\n * fires (or the consumer `break`s before a terminal frame), the `finally` sends a\n * `cancel` frame back over `transport.cancel` so the HOST stops generating — without\n * it, aborting only stops the app-side iterator while the upstream provider keeps\n * streaming and BILLING (LLM_AND_AGENTS_SPEC §3.3, R3-224 / adversarial F2).\n */\nexport async function* consumeStream<T = unknown, R = unknown>(\n  transport: StreamTransport,\n  type: string,\n  method: string,\n  params: unknown[],\n  msgId: number = nextMsgId(),\n  signal?: AbortSignal,\n  opts?: BoundedCallOptions & { idleTimeoutMs?: number }\n): AsyncGenerator<T, R, void> {\n  const queue: StreamFrame[] = [];\n  let wake: (() => void) | null = null;\n  // True once a terminal (`done`/`error`) frame arrived — so the `finally` knows the\n  // host already stopped and must NOT send a redundant cancel. Left false when the\n  // consumer bails early or the signal aborts (the two cases that DO need a cancel).\n  let settled = false;\n  // True once the request frame went out. A cancel is only meaningful for a stream\n  // the host actually started — an abort BEFORE `send` sends nothing to cancel.\n  let started = false;\n  const push = (frame: StreamFrame) => {\n    queue.push(frame);\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n\n  const unsubscribe = transport.subscribe(type, (msg) => {\n    if (msg.msgId !== msgId || !msg.stream) return;\n    push(msg.stream);\n  });\n\n  // An abort wakes the pull loop out of its idle `await`; the loop then throws.\n  const onAbort = () => {\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n  if (signal) signal.addEventListener('abort', onAbort);\n\n  // R3-298 — a stream is bounded by SILENCE, not by duration.\n  //\n  // A total-duration deadline would be wrong here: a long generation that is streaming\n  // normally is healthy, and aborting it would be a worse bug than the hang. The hang has a\n  // distinct shape — no frames at all — so that is what is bounded: a time-to-FIRST-FRAME\n  // deadline, then an idle-gap deadline once frames are flowing. Together they fire exactly\n  // on a wedged stream and never on a slow one.\n  //\n  // The scheme's `type` is `protocol-llm`; the classification table is keyed on the bare\n  // scheme, so strip the prefix. The chat stream is classified ATTENDED because its first\n  // frame can sit behind the session's first passkey unseal — the dogfood hang.\n  const scheme = type.startsWith('protocol-') ? type.slice('protocol-'.length) : type;\n  const call = `${scheme}:${method}`;\n  const attendance = attendanceOf(scheme, method);\n  const firstFrameMs = opts?.timeoutMs ?? firstFrameTimeoutFor(scheme, method);\n  const idleMs = opts?.idleTimeoutMs ?? STREAM_IDLE_TIMEOUT_MS;\n  let sawFrame = false;\n  let noticed = false;\n\n  /** Wait for the next frame, bounded. Rejects with a typed timeout rather than parking. */\n  const awaitFrame = async (): Promise<void> => {\n    const budget = sawFrame ? idleMs : firstFrameMs;\n    if (!Number.isFinite(budget)) {\n      await new Promise<void>((resolve) => {\n        wake = resolve;\n      });\n      return;\n    }\n    const startedAt = Date.now();\n    let deadline: ReturnType<typeof setTimeout> | undefined;\n    let notice: ReturnType<typeof setTimeout> | undefined;\n    try {\n      await new Promise<void>((resolve, reject) => {\n        wake = resolve;\n        deadline = setTimeout(\n          () => reject(new ProtocolTimeoutError(call, budget, attendance)),\n          budget,\n        );\n        if (opts?.onPending && !noticed) {\n          notice = setTimeout(() => {\n            noticed = true;\n            try {\n              opts.onPending?.({\n                call,\n                attendance,\n                elapsedMs: Date.now() - startedAt,\n                ...(attendanceReason(scheme, method)\n                  ? { reason: attendanceReason(scheme, method) as string }\n                  : {}),\n              });\n            } catch {\n              /* a caller's render callback must never break the stream it describes */\n            }\n          }, PENDING_NOTICE_MS);\n        }\n      });\n    } finally {\n      if (deadline !== undefined) clearTimeout(deadline);\n      if (notice !== undefined) clearTimeout(notice);\n      wake = null;\n    }\n  };\n\n  try {\n    if (signal?.aborted) throw new StreamError('aborted', 'stream aborted before start');\n    transport.send({ type, method, params, msgId, stream: true });\n    started = true;\n    while (true) {\n      if (signal?.aborted) throw new StreamError('aborted', 'stream aborted');\n      if (queue.length === 0) {\n        // A timeout throws out of here into the `finally`, which sends the host a real\n        // cancel frame — so a wedged stream stops generating and BILLING rather than being\n        // merely abandoned by the app. Streams can do this because they own their `msgId`.\n        await awaitFrame();\n        continue;\n      }\n      sawFrame = true;\n      const frame = queue.shift() as StreamFrame;\n      if (frame.kind === 'event') {\n        yield frame.value as T;\n      } else if (frame.kind === 'done') {\n        settled = true;\n        return frame.value as R;\n      } else {\n        settled = true;\n        throw new StreamError(frame.code, frame.message);\n      }\n    }\n  } finally {\n    unsubscribe();\n    if (signal) signal.removeEventListener('abort', onAbort);\n    // Consumer stopped pulling before a terminal frame (early break/return, or the\n    // signal aborted): tell the host to stop the in-flight generation + billing.\n    if (started && !settled) transport.cancel?.({ type, msgId, cancel: true });\n  }\n}\n\n// The real sandbox transport, built from the bundler messageBus helpers. `cancel`\n// rides the same messageBus as `send` — a `{type, msgId, cancel:true}` frame the\n// host dispatcher routes to the in-flight generator's AbortController.\nconst bundlerTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n  cancel: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n};\n\n/**\n * Consume an elevated streaming protocol method from app code.\n *\n * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`\n *\n * Pass `signal` to abort the stream (and the host's in-flight work) mid-flight.\n */\nexport function protocolStream<T = unknown, R = unknown>(\n  protocolName: string,\n  method: string,\n  params: unknown[],\n  signal?: AbortSignal,\n  opts?: BoundedCallOptions & { idleTimeoutMs?: number }\n): AsyncGenerator<T, R, void> {\n  return consumeStream<T, R>(\n    bundlerTransport,\n    protocolName,\n    method,\n    params,\n    undefined,\n    signal,\n    opts\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/pushChannel.cjs

@@ -22,21 +22,25 @@ __export(pushChannel_exports, {
 });
 module.exports = __toCommonJS(pushChannel_exports);
 var import_react = require("react");
-var import_sandboxUtils = require("./sandboxUtils");
-function createPushChannel(opts, transport = { sendMessage: import_sandboxUtils.sendMessage, addListener: import_sandboxUtils.addListener }) {
+var import_hostTransport = require("./hostTransport");
+function createPushChannel(opts, transport = { sendMessage: import_hostTransport.sendMessage, addListener: import_hostTransport.addListener }) {
   let current = opts.initial;
   const listeners = /* @__PURE__ */ new Set();
   let started = false;
   const start = () => {
     if (started) return;
+    try {
+      transport.addListener(opts.pushType, (msg) => {
+        const next = opts.parse(msg);
+        if (next !== void 0) {
+          current = next;
+          listeners.forEach((l) => l(current));
+        }
+      });
+    } catch {
+      return;
+    }
     started = true;
-    transport.addListener(opts.pushType, (msg) => {
-      const next = opts.parse(msg);
-      if (next !== void 0) {
-        current = next;
-        listeners.forEach((l) => l(current));
-      }
-    });
     if (opts.requestType) {
       try {
         transport.sendMessage(opts.requestType);

package/dist/pushChannel.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/pushChannel.ts"],"sourcesContent":["// Generic host→sandbox state channel read over the TRANSPORT\n// (SDK_PACKAGING_SPEC §4, expose-transport). The host pushes a `pushType`\n// message whenever the value changes and answers a `requestType` poll with the\n// current value — gated per-frame by the read ACL (site-main channelBridge.ts /\n// channelRouter). Historically the SDK read these values off injected sandbox\n// service objects (`module.evaluation.module.bundler.auth` etc.); this caches\n// the latest value SDK-side instead, so the SDK is self-contained and the\n// bundler services can eventually be retired.\n//\n// Every state helper (formFactor, auth, editorContext, theme, catalog) is a thin\n// wrapper over one of these — the get / onChange / use trio is identical.\nimport { useEffect, useState } from 'react';\nimport { sendMessage as defaultSend, addListener as defaultAddListener } from './sandboxUtils';\n\nexport interface PushChannel<T> {\n  /** Pollable snapshot of the current value. */\n  get(): T;\n  /** Subscribe; invoked immediately with the current value, then on every change. Returns unsubscribe. */\n  onChange(listener: (value: T) => void): () => void;\n  /** React hook returning the current value, re-rendering on change. */\n  use(): T;\n}\n\n/** Injectable transport — defaults to the real one; overridden in tests. */\nexport interface ChannelTransport {\n  sendMessage: (type: string, data?: Record<string, unknown>) => void;\n  addListener: (type: string, handler: (msg: Record<string, unknown>) => void) => () => void;\n}\n\nexport function createPushChannel<T>(\n  opts: {\n    /** Host→sandbox push message type (e.g. `form-factor`). */\n    pushType: string;\n    /** Poll message type the SDK sends to pull the current value (e.g. `request-form-factor`). */\n    requestType?: string;\n    /** Value assumed before the host answers — also the value when the app may not read the channel. */\n    initial: T;\n    /** Extract + validate the value from a push message; return `undefined` to ignore the message. */\n    parse: (msg: Record<string, unknown>) => T | undefined;\n  },\n  transport: ChannelTransport = { sendMessage: defaultSend, addListener: defaultAddListener },\n): PushChannel<T> {\n  let current = opts.initial;\n  const listeners = new Set<(value: T) => void>();\n  let started = false;\n\n  // Lazily start on first read: register the push listener + send one poll, so a\n  // late-mounting app still gets the current value. A channel the app may not\n  // read is simply never answered → `initial` stands.\n  const start = () => {\n    if (started) return;\n    started = true;\n    transport.addListener(opts.pushType, (msg) => {\n      const next = opts.parse(msg);\n      if (next !== undefined) {\n        current = next;\n        listeners.forEach((l) => l(current));\n      }\n    });\n    if (opts.requestType) {\n      try {\n        transport.sendMessage(opts.requestType);\n      } catch {\n        /* transport not ready — a proactive push will still arrive */\n      }\n    }\n  };\n\n  const get = (): T => {\n    start();\n    return current;\n  };\n\n  const onChange = (listener: (value: T) => void): (() => void) => {\n    start();\n    listeners.add(listener);\n    listener(current);\n    return () => {\n      listeners.delete(listener);\n    };\n  };\n\n  const use = (): T => {\n    const [value, setValue] = useState<T>(get);\n    useEffect(() => onChange(setValue), []);\n    return value;\n  };\n\n  return { get, onChange, use };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,mBAAoC;AACpC,0BAA8E;AAiBvE,SAAS,kBACd,MAUA,YAA8B,EAAE,aAAa,oBAAAA,aAAa,aAAa,oBAAAC,YAAmB,GAC1E;AAChB,MAAI,UAAU,KAAK;AACnB,QAAM,YAAY,oBAAI,IAAwB;AAC9C,MAAI,UAAU;AAKd,QAAM,QAAQ,MAAM;AAClB,QAAI,QAAS;AACb,cAAU;AACV,cAAU,YAAY,KAAK,UAAU,CAAC,QAAQ;AAC5C,YAAM,OAAO,KAAK,MAAM,GAAG;AAC3B,UAAI,SAAS,QAAW;AACtB,kBAAU;AACV,kBAAU,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;AAAA,MACrC;AAAA,IACF,CAAC;AACD,QAAI,KAAK,aAAa;AACpB,UAAI;AACF,kBAAU,YAAY,KAAK,WAAW;AAAA,MACxC,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM;AACN,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,CAAC,aAA+C;AAC/D,UAAM;AACN,cAAU,IAAI,QAAQ;AACtB,aAAS,OAAO;AAChB,WAAO,MAAM;AACX,gBAAU,OAAO,QAAQ;AAAA,IAC3B;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM,CAAC,OAAO,QAAQ,QAAI,uBAAY,GAAG;AACzC,gCAAU,MAAM,SAAS,QAAQ,GAAG,CAAC,CAAC;AACtC,WAAO;AAAA,EACT;AAEA,SAAO,EAAE,KAAK,UAAU,IAAI;AAC9B;","names":["defaultSend","defaultAddListener"]}
+{"version":3,"sources":["../src/pushChannel.ts"],"sourcesContent":["// Generic host→sandbox state channel read over the TRANSPORT\n// (SDK_PACKAGING_SPEC §4, expose-transport). The host pushes a `pushType`\n// message whenever the value changes and answers a `requestType` poll with the\n// current value — gated per-frame by the read ACL (site-main channelBridge.ts /\n// channelRouter). Historically the SDK read these values off injected sandbox\n// service objects (`module.evaluation.module.bundler.auth` etc.); this caches\n// the latest value SDK-side instead, so the SDK is self-contained and the\n// bundler services can eventually be retired.\n//\n// Every state helper (formFactor, auth, editorContext, theme, catalog) is a thin\n// wrapper over one of these — the get / onChange / use trio is identical.\nimport { useEffect, useState } from 'react';\nimport { sendMessage as defaultSend, addListener as defaultAddListener } from './hostTransport';\n\nexport interface PushChannel<T> {\n  /** Pollable snapshot of the current value. */\n  get(): T;\n  /** Subscribe; invoked immediately with the current value, then on every change. Returns unsubscribe. */\n  onChange(listener: (value: T) => void): () => void;\n  /** React hook returning the current value, re-rendering on change. */\n  use(): T;\n}\n\n/** Injectable transport — defaults to the real one; overridden in tests. */\nexport interface ChannelTransport {\n  sendMessage: (type: string, data?: Record<string, unknown>) => void;\n  addListener: (type: string, handler: (msg: Record<string, unknown>) => void) => () => void;\n}\n\nexport function createPushChannel<T>(\n  opts: {\n    /** Host→sandbox push message type (e.g. `form-factor`). */\n    pushType: string;\n    /** Poll message type the SDK sends to pull the current value (e.g. `request-form-factor`). */\n    requestType?: string;\n    /** Value assumed before the host answers — also the value when the app may not read the channel. */\n    initial: T;\n    /** Extract + validate the value from a push message; return `undefined` to ignore the message. */\n    parse: (msg: Record<string, unknown>) => T | undefined;\n  },\n  transport: ChannelTransport = { sendMessage: defaultSend, addListener: defaultAddListener },\n): PushChannel<T> {\n  let current = opts.initial;\n  const listeners = new Set<(value: T) => void>();\n  let started = false;\n\n  // Lazily start on first read: register the push listener + send one poll, so a\n  // late-mounting app still gets the current value. A channel the app may not\n  // read is simply never answered → `initial` stands.\n  const start = () => {\n    if (started) return;\n    try {\n      transport.addListener(opts.pushType, (msg) => {\n        const next = opts.parse(msg);\n        if (next !== undefined) {\n          current = next;\n          listeners.forEach((l) => l(current));\n        }\n      });\n    } catch {\n      // No host transport in this realm yet (the resolver throws when neither the injected\n      // bundler bus nor the §4 discovery global is present). Leave `started` false so the\n      // NEXT read retries, and let `initial` stand meanwhile — which is exactly the\n      // documented behaviour for a channel the host never answers. Throwing here instead\n      // would make a plain `getHostTheme()` fatal outside a sandbox, and since R3-307 the\n      // deadline on every host call reads a channel, so one throw would be every call.\n      return;\n    }\n    started = true;\n    if (opts.requestType) {\n      try {\n        transport.sendMessage(opts.requestType);\n      } catch {\n        /* transport not ready — a proactive push will still arrive */\n      }\n    }\n  };\n\n  const get = (): T => {\n    start();\n    return current;\n  };\n\n  const onChange = (listener: (value: T) => void): (() => void) => {\n    start();\n    listeners.add(listener);\n    listener(current);\n    return () => {\n      listeners.delete(listener);\n    };\n  };\n\n  const use = (): T => {\n    const [value, setValue] = useState<T>(get);\n    useEffect(() => onChange(setValue), []);\n    return value;\n  };\n\n  return { get, onChange, use };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,mBAAoC;AACpC,2BAA8E;AAiBvE,SAAS,kBACd,MAUA,YAA8B,EAAE,aAAa,qBAAAA,aAAa,aAAa,qBAAAC,YAAmB,GAC1E;AAChB,MAAI,UAAU,KAAK;AACnB,QAAM,YAAY,oBAAI,IAAwB;AAC9C,MAAI,UAAU;AAKd,QAAM,QAAQ,MAAM;AAClB,QAAI,QAAS;AACb,QAAI;AACF,gBAAU,YAAY,KAAK,UAAU,CAAC,QAAQ;AAC5C,cAAM,OAAO,KAAK,MAAM,GAAG;AAC3B,YAAI,SAAS,QAAW;AACtB,oBAAU;AACV,oBAAU,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;AAAA,QACrC;AAAA,MACF,CAAC;AAAA,IACH,QAAQ;AAON;AAAA,IACF;AACA,cAAU;AACV,QAAI,KAAK,aAAa;AACpB,UAAI;AACF,kBAAU,YAAY,KAAK,WAAW;AAAA,MACxC,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM;AACN,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,CAAC,aAA+C;AAC/D,UAAM;AACN,cAAU,IAAI,QAAQ;AACtB,aAAS,OAAO;AAChB,WAAO,MAAM;AACX,gBAAU,OAAO,QAAQ;AAAA,IAC3B;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM,CAAC,OAAO,QAAQ,QAAI,uBAAY,GAAG;AACzC,gCAAU,MAAM,SAAS,QAAQ,GAAG,CAAC,CAAC;AACtC,WAAO;AAAA,EACT;AAEA,SAAO,EAAE,KAAK,UAAU,IAAI;AAC9B;","names":["defaultSend","defaultAddListener"]}

package/dist/pushChannel.js

@@ -1,20 +1,24 @@
 import "./chunk-VHAA22YE.js";
 import { useEffect, useState } from "react";
-import { sendMessage as defaultSend, addListener as defaultAddListener } from "./sandboxUtils";
+import { sendMessage as defaultSend, addListener as defaultAddListener } from "./hostTransport";
 function createPushChannel(opts, transport = { sendMessage: defaultSend, addListener: defaultAddListener }) {
   let current = opts.initial;
   const listeners = /* @__PURE__ */ new Set();
   let started = false;
   const start = () => {
     if (started) return;
+    try {
+      transport.addListener(opts.pushType, (msg) => {
+        const next = opts.parse(msg);
+        if (next !== void 0) {
+          current = next;
+          listeners.forEach((l) => l(current));
+        }
+      });
+    } catch {
+      return;
+    }
     started = true;
-    transport.addListener(opts.pushType, (msg) => {
-      const next = opts.parse(msg);
-      if (next !== void 0) {
-        current = next;
-        listeners.forEach((l) => l(current));
-      }
-    });
     if (opts.requestType) {
       try {
         transport.sendMessage(opts.requestType);

package/dist/pushChannel.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/pushChannel.ts"],"sourcesContent":["// Generic host→sandbox state channel read over the TRANSPORT\n// (SDK_PACKAGING_SPEC §4, expose-transport). The host pushes a `pushType`\n// message whenever the value changes and answers a `requestType` poll with the\n// current value — gated per-frame by the read ACL (site-main channelBridge.ts /\n// channelRouter). Historically the SDK read these values off injected sandbox\n// service objects (`module.evaluation.module.bundler.auth` etc.); this caches\n// the latest value SDK-side instead, so the SDK is self-contained and the\n// bundler services can eventually be retired.\n//\n// Every state helper (formFactor, auth, editorContext, theme, catalog) is a thin\n// wrapper over one of these — the get / onChange / use trio is identical.\nimport { useEffect, useState } from 'react';\nimport { sendMessage as defaultSend, addListener as defaultAddListener } from './sandboxUtils';\n\nexport interface PushChannel<T> {\n  /** Pollable snapshot of the current value. */\n  get(): T;\n  /** Subscribe; invoked immediately with the current value, then on every change. Returns unsubscribe. */\n  onChange(listener: (value: T) => void): () => void;\n  /** React hook returning the current value, re-rendering on change. */\n  use(): T;\n}\n\n/** Injectable transport — defaults to the real one; overridden in tests. */\nexport interface ChannelTransport {\n  sendMessage: (type: string, data?: Record<string, unknown>) => void;\n  addListener: (type: string, handler: (msg: Record<string, unknown>) => void) => () => void;\n}\n\nexport function createPushChannel<T>(\n  opts: {\n    /** Host→sandbox push message type (e.g. `form-factor`). */\n    pushType: string;\n    /** Poll message type the SDK sends to pull the current value (e.g. `request-form-factor`). */\n    requestType?: string;\n    /** Value assumed before the host answers — also the value when the app may not read the channel. */\n    initial: T;\n    /** Extract + validate the value from a push message; return `undefined` to ignore the message. */\n    parse: (msg: Record<string, unknown>) => T | undefined;\n  },\n  transport: ChannelTransport = { sendMessage: defaultSend, addListener: defaultAddListener },\n): PushChannel<T> {\n  let current = opts.initial;\n  const listeners = new Set<(value: T) => void>();\n  let started = false;\n\n  // Lazily start on first read: register the push listener + send one poll, so a\n  // late-mounting app still gets the current value. A channel the app may not\n  // read is simply never answered → `initial` stands.\n  const start = () => {\n    if (started) return;\n    started = true;\n    transport.addListener(opts.pushType, (msg) => {\n      const next = opts.parse(msg);\n      if (next !== undefined) {\n        current = next;\n        listeners.forEach((l) => l(current));\n      }\n    });\n    if (opts.requestType) {\n      try {\n        transport.sendMessage(opts.requestType);\n      } catch {\n        /* transport not ready — a proactive push will still arrive */\n      }\n    }\n  };\n\n  const get = (): T => {\n    start();\n    return current;\n  };\n\n  const onChange = (listener: (value: T) => void): (() => void) => {\n    start();\n    listeners.add(listener);\n    listener(current);\n    return () => {\n      listeners.delete(listener);\n    };\n  };\n\n  const use = (): T => {\n    const [value, setValue] = useState<T>(get);\n    useEffect(() => onChange(setValue), []);\n    return value;\n  };\n\n  return { get, onChange, use };\n}\n"],"mappings":";AAWA,SAAS,WAAW,gBAAgB;AACpC,SAAS,eAAe,aAAa,eAAe,0BAA0B;AAiBvE,SAAS,kBACd,MAUA,YAA8B,EAAE,aAAa,aAAa,aAAa,mBAAmB,GAC1E;AAChB,MAAI,UAAU,KAAK;AACnB,QAAM,YAAY,oBAAI,IAAwB;AAC9C,MAAI,UAAU;AAKd,QAAM,QAAQ,MAAM;AAClB,QAAI,QAAS;AACb,cAAU;AACV,cAAU,YAAY,KAAK,UAAU,CAAC,QAAQ;AAC5C,YAAM,OAAO,KAAK,MAAM,GAAG;AAC3B,UAAI,SAAS,QAAW;AACtB,kBAAU;AACV,kBAAU,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;AAAA,MACrC;AAAA,IACF,CAAC;AACD,QAAI,KAAK,aAAa;AACpB,UAAI;AACF,kBAAU,YAAY,KAAK,WAAW;AAAA,MACxC,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM;AACN,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,CAAC,aAA+C;AAC/D,UAAM;AACN,cAAU,IAAI,QAAQ;AACtB,aAAS,OAAO;AAChB,WAAO,MAAM;AACX,gBAAU,OAAO,QAAQ;AAAA,IAC3B;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM,CAAC,OAAO,QAAQ,IAAI,SAAY,GAAG;AACzC,cAAU,MAAM,SAAS,QAAQ,GAAG,CAAC,CAAC;AACtC,WAAO;AAAA,EACT;AAEA,SAAO,EAAE,KAAK,UAAU,IAAI;AAC9B;","names":[]}
+{"version":3,"sources":["../src/pushChannel.ts"],"sourcesContent":["// Generic host→sandbox state channel read over the TRANSPORT\n// (SDK_PACKAGING_SPEC §4, expose-transport). The host pushes a `pushType`\n// message whenever the value changes and answers a `requestType` poll with the\n// current value — gated per-frame by the read ACL (site-main channelBridge.ts /\n// channelRouter). Historically the SDK read these values off injected sandbox\n// service objects (`module.evaluation.module.bundler.auth` etc.); this caches\n// the latest value SDK-side instead, so the SDK is self-contained and the\n// bundler services can eventually be retired.\n//\n// Every state helper (formFactor, auth, editorContext, theme, catalog) is a thin\n// wrapper over one of these — the get / onChange / use trio is identical.\nimport { useEffect, useState } from 'react';\nimport { sendMessage as defaultSend, addListener as defaultAddListener } from './hostTransport';\n\nexport interface PushChannel<T> {\n  /** Pollable snapshot of the current value. */\n  get(): T;\n  /** Subscribe; invoked immediately with the current value, then on every change. Returns unsubscribe. */\n  onChange(listener: (value: T) => void): () => void;\n  /** React hook returning the current value, re-rendering on change. */\n  use(): T;\n}\n\n/** Injectable transport — defaults to the real one; overridden in tests. */\nexport interface ChannelTransport {\n  sendMessage: (type: string, data?: Record<string, unknown>) => void;\n  addListener: (type: string, handler: (msg: Record<string, unknown>) => void) => () => void;\n}\n\nexport function createPushChannel<T>(\n  opts: {\n    /** Host→sandbox push message type (e.g. `form-factor`). */\n    pushType: string;\n    /** Poll message type the SDK sends to pull the current value (e.g. `request-form-factor`). */\n    requestType?: string;\n    /** Value assumed before the host answers — also the value when the app may not read the channel. */\n    initial: T;\n    /** Extract + validate the value from a push message; return `undefined` to ignore the message. */\n    parse: (msg: Record<string, unknown>) => T | undefined;\n  },\n  transport: ChannelTransport = { sendMessage: defaultSend, addListener: defaultAddListener },\n): PushChannel<T> {\n  let current = opts.initial;\n  const listeners = new Set<(value: T) => void>();\n  let started = false;\n\n  // Lazily start on first read: register the push listener + send one poll, so a\n  // late-mounting app still gets the current value. A channel the app may not\n  // read is simply never answered → `initial` stands.\n  const start = () => {\n    if (started) return;\n    try {\n      transport.addListener(opts.pushType, (msg) => {\n        const next = opts.parse(msg);\n        if (next !== undefined) {\n          current = next;\n          listeners.forEach((l) => l(current));\n        }\n      });\n    } catch {\n      // No host transport in this realm yet (the resolver throws when neither the injected\n      // bundler bus nor the §4 discovery global is present). Leave `started` false so the\n      // NEXT read retries, and let `initial` stand meanwhile — which is exactly the\n      // documented behaviour for a channel the host never answers. Throwing here instead\n      // would make a plain `getHostTheme()` fatal outside a sandbox, and since R3-307 the\n      // deadline on every host call reads a channel, so one throw would be every call.\n      return;\n    }\n    started = true;\n    if (opts.requestType) {\n      try {\n        transport.sendMessage(opts.requestType);\n      } catch {\n        /* transport not ready — a proactive push will still arrive */\n      }\n    }\n  };\n\n  const get = (): T => {\n    start();\n    return current;\n  };\n\n  const onChange = (listener: (value: T) => void): (() => void) => {\n    start();\n    listeners.add(listener);\n    listener(current);\n    return () => {\n      listeners.delete(listener);\n    };\n  };\n\n  const use = (): T => {\n    const [value, setValue] = useState<T>(get);\n    useEffect(() => onChange(setValue), []);\n    return value;\n  };\n\n  return { get, onChange, use };\n}\n"],"mappings":";AAWA,SAAS,WAAW,gBAAgB;AACpC,SAAS,eAAe,aAAa,eAAe,0BAA0B;AAiBvE,SAAS,kBACd,MAUA,YAA8B,EAAE,aAAa,aAAa,aAAa,mBAAmB,GAC1E;AAChB,MAAI,UAAU,KAAK;AACnB,QAAM,YAAY,oBAAI,IAAwB;AAC9C,MAAI,UAAU;AAKd,QAAM,QAAQ,MAAM;AAClB,QAAI,QAAS;AACb,QAAI;AACF,gBAAU,YAAY,KAAK,UAAU,CAAC,QAAQ;AAC5C,cAAM,OAAO,KAAK,MAAM,GAAG;AAC3B,YAAI,SAAS,QAAW;AACtB,oBAAU;AACV,oBAAU,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;AAAA,QACrC;AAAA,MACF,CAAC;AAAA,IACH,QAAQ;AAON;AAAA,IACF;AACA,cAAU;AACV,QAAI,KAAK,aAAa;AACpB,UAAI;AACF,kBAAU,YAAY,KAAK,WAAW;AAAA,MACxC,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM;AACN,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,CAAC,aAA+C;AAC/D,UAAM;AACN,cAAU,IAAI,QAAQ;AACtB,aAAS,OAAO;AAChB,WAAO,MAAM;AACX,gBAAU,OAAO,QAAQ;AAAA,IAC3B;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM,CAAC,OAAO,QAAQ,IAAI,SAAY,GAAG;AACzC,cAAU,MAAM,SAAS,QAAQ,GAAG,CAAC,CAAC;AACtC,WAAO;AAAA,EACT;AAEA,SAAO,EAAE,KAAK,UAAU,IAAI;AAC9B;","names":[]}

package/dist/sandboxUtils.cjs

@@ -18,39 +18,89 @@ 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