@immediately-run/sdk 0.45.3 → 0.47.0

package/dist/pathUtils.cjs

@@ -37,18 +37,15 @@ const joinPaths = (...pathPart) => pathPart.reduce((acc, part) => {
 const absPath = (rawPath) => {
   const absCandidate = joinPaths.apply(
     null,
-    rawPath.split(PATH_SEPARATOR).reduce(
-      (partialAbsPath, currentPathPart) => {
-        if (currentPathPart == ".") {
-          return partialAbsPath;
-        }
-        if (currentPathPart == "..") {
-          return partialAbsPath.slice(0, -1);
-        }
-        return partialAbsPath.concat(currentPathPart);
-      },
-      []
-    )
+    rawPath.split(PATH_SEPARATOR).reduce((partialAbsPath, currentPathPart) => {
+      if (currentPathPart == ".") {
+        return partialAbsPath;
+      }
+      if (currentPathPart == "..") {
+        return partialAbsPath.slice(0, -1);
+      }
+      return partialAbsPath.concat(currentPathPart);
+    }, [])
   );
   if (absCandidate === "" && rawPath.startsWith(PATH_SEPARATOR)) {
     return PATH_SEPARATOR;

package/dist/pathUtils.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/pathUtils.ts"],"sourcesContent":["const PATH_SEPARATOR = \"/\";\n\nexport const joinPaths = (...pathPart: string[]) => pathPart.reduce((acc, part) => {\n  const left = (acc.endsWith(PATH_SEPARATOR)) ? acc.slice(0, -1) : acc;\n  const right = (part.startsWith(PATH_SEPARATOR)) ? part.substring(1) : part;\n  if (left || acc === PATH_SEPARATOR) {\n    return `${left}${PATH_SEPARATOR}${right}`;\n  }\n  if (part.startsWith(PATH_SEPARATOR)) {\n    return `${PATH_SEPARATOR}${right}`;\n  }\n  return right;\n}, \"\");\n\nexport const absPath = (rawPath: string): string => {\n  const absCandidate = joinPaths.apply(\n    null,\n    rawPath.split(PATH_SEPARATOR).reduce(\n      (partialAbsPath: string[], currentPathPart: string) => {\n        if (currentPathPart == '.') {\n          return partialAbsPath;\n        }\n        if (currentPathPart == '..') {\n          return partialAbsPath.slice(0, -1)\n        }\n        return partialAbsPath.concat(currentPathPart);\n      },\n      []\n    ));\n  if (absCandidate === '' && rawPath.startsWith(PATH_SEPARATOR)) {\n    return PATH_SEPARATOR;\n  }\n  return absCandidate;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAAM,iBAAiB;AAEhB,MAAM,YAAY,IAAI,aAAuB,SAAS,OAAO,CAAC,KAAK,SAAS;AACjF,QAAM,OAAQ,IAAI,SAAS,cAAc,IAAK,IAAI,MAAM,GAAG,EAAE,IAAI;AACjE,QAAM,QAAS,KAAK,WAAW,cAAc,IAAK,KAAK,UAAU,CAAC,IAAI;AACtE,MAAI,QAAQ,QAAQ,gBAAgB;AAClC,WAAO,GAAG,IAAI,GAAG,cAAc,GAAG,KAAK;AAAA,EACzC;AACA,MAAI,KAAK,WAAW,cAAc,GAAG;AACnC,WAAO,GAAG,cAAc,GAAG,KAAK;AAAA,EAClC;AACA,SAAO;AACT,GAAG,EAAE;AAEE,MAAM,UAAU,CAAC,YAA4B;AAClD,QAAM,eAAe,UAAU;AAAA,IAC7B;AAAA,IACA,QAAQ,MAAM,cAAc,EAAE;AAAA,MAC5B,CAAC,gBAA0B,oBAA4B;AACrD,YAAI,mBAAmB,KAAK;AAC1B,iBAAO;AAAA,QACT;AACA,YAAI,mBAAmB,MAAM;AAC3B,iBAAO,eAAe,MAAM,GAAG,EAAE;AAAA,QACnC;AACA,eAAO,eAAe,OAAO,eAAe;AAAA,MAC9C;AAAA,MACA,CAAC;AAAA,IACH;AAAA,EAAC;AACH,MAAI,iBAAiB,MAAM,QAAQ,WAAW,cAAc,GAAG;AAC7D,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/pathUtils.ts"],"sourcesContent":["const PATH_SEPARATOR = '/';\n\nexport const joinPaths = (...pathPart: string[]) =>\n  pathPart.reduce((acc, part) => {\n    const left = acc.endsWith(PATH_SEPARATOR) ? acc.slice(0, -1) : acc;\n    const right = part.startsWith(PATH_SEPARATOR) ? part.substring(1) : part;\n    if (left || acc === PATH_SEPARATOR) {\n      return `${left}${PATH_SEPARATOR}${right}`;\n    }\n    if (part.startsWith(PATH_SEPARATOR)) {\n      return `${PATH_SEPARATOR}${right}`;\n    }\n    return right;\n  }, '');\n\nexport const absPath = (rawPath: string): string => {\n  const absCandidate = joinPaths.apply(\n    null,\n    rawPath.split(PATH_SEPARATOR).reduce((partialAbsPath: string[], currentPathPart: string) => {\n      if (currentPathPart == '.') {\n        return partialAbsPath;\n      }\n      if (currentPathPart == '..') {\n        return partialAbsPath.slice(0, -1);\n      }\n      return partialAbsPath.concat(currentPathPart);\n    }, []),\n  );\n  if (absCandidate === '' && rawPath.startsWith(PATH_SEPARATOR)) {\n    return PATH_SEPARATOR;\n  }\n  return absCandidate;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAAM,iBAAiB;AAEhB,MAAM,YAAY,IAAI,aAC3B,SAAS,OAAO,CAAC,KAAK,SAAS;AAC7B,QAAM,OAAO,IAAI,SAAS,cAAc,IAAI,IAAI,MAAM,GAAG,EAAE,IAAI;AAC/D,QAAM,QAAQ,KAAK,WAAW,cAAc,IAAI,KAAK,UAAU,CAAC,IAAI;AACpE,MAAI,QAAQ,QAAQ,gBAAgB;AAClC,WAAO,GAAG,IAAI,GAAG,cAAc,GAAG,KAAK;AAAA,EACzC;AACA,MAAI,KAAK,WAAW,cAAc,GAAG;AACnC,WAAO,GAAG,cAAc,GAAG,KAAK;AAAA,EAClC;AACA,SAAO;AACT,GAAG,EAAE;AAEA,MAAM,UAAU,CAAC,YAA4B;AAClD,QAAM,eAAe,UAAU;AAAA,IAC7B;AAAA,IACA,QAAQ,MAAM,cAAc,EAAE,OAAO,CAAC,gBAA0B,oBAA4B;AAC1F,UAAI,mBAAmB,KAAK;AAC1B,eAAO;AAAA,MACT;AACA,UAAI,mBAAmB,MAAM;AAC3B,eAAO,eAAe,MAAM,GAAG,EAAE;AAAA,MACnC;AACA,aAAO,eAAe,OAAO,eAAe;AAAA,IAC9C,GAAG,CAAC,CAAC;AAAA,EACP;AACA,MAAI,iBAAiB,MAAM,QAAQ,WAAW,cAAc,GAAG;AAC7D,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}

package/dist/pathUtils.js

@@ -14,18 +14,15 @@ const joinPaths = (...pathPart) => pathPart.reduce((acc, part) => {
 const absPath = (rawPath) => {
   const absCandidate = joinPaths.apply(
     null,
-    rawPath.split(PATH_SEPARATOR).reduce(
-      (partialAbsPath, currentPathPart) => {
-        if (currentPathPart == ".") {
-          return partialAbsPath;
-        }
-        if (currentPathPart == "..") {
-          return partialAbsPath.slice(0, -1);
-        }
-        return partialAbsPath.concat(currentPathPart);
-      },
-      []
-    )
+    rawPath.split(PATH_SEPARATOR).reduce((partialAbsPath, currentPathPart) => {
+      if (currentPathPart == ".") {
+        return partialAbsPath;
+      }
+      if (currentPathPart == "..") {
+        return partialAbsPath.slice(0, -1);
+      }
+      return partialAbsPath.concat(currentPathPart);
+    }, [])
   );
   if (absCandidate === "" && rawPath.startsWith(PATH_SEPARATOR)) {
     return PATH_SEPARATOR;

package/dist/pathUtils.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/pathUtils.ts"],"sourcesContent":["const PATH_SEPARATOR = \"/\";\n\nexport const joinPaths = (...pathPart: string[]) => pathPart.reduce((acc, part) => {\n  const left = (acc.endsWith(PATH_SEPARATOR)) ? acc.slice(0, -1) : acc;\n  const right = (part.startsWith(PATH_SEPARATOR)) ? part.substring(1) : part;\n  if (left || acc === PATH_SEPARATOR) {\n    return `${left}${PATH_SEPARATOR}${right}`;\n  }\n  if (part.startsWith(PATH_SEPARATOR)) {\n    return `${PATH_SEPARATOR}${right}`;\n  }\n  return right;\n}, \"\");\n\nexport const absPath = (rawPath: string): string => {\n  const absCandidate = joinPaths.apply(\n    null,\n    rawPath.split(PATH_SEPARATOR).reduce(\n      (partialAbsPath: string[], currentPathPart: string) => {\n        if (currentPathPart == '.') {\n          return partialAbsPath;\n        }\n        if (currentPathPart == '..') {\n          return partialAbsPath.slice(0, -1)\n        }\n        return partialAbsPath.concat(currentPathPart);\n      },\n      []\n    ));\n  if (absCandidate === '' && rawPath.startsWith(PATH_SEPARATOR)) {\n    return PATH_SEPARATOR;\n  }\n  return absCandidate;\n}\n"],"mappings":";AAAA,MAAM,iBAAiB;AAEhB,MAAM,YAAY,IAAI,aAAuB,SAAS,OAAO,CAAC,KAAK,SAAS;AACjF,QAAM,OAAQ,IAAI,SAAS,cAAc,IAAK,IAAI,MAAM,GAAG,EAAE,IAAI;AACjE,QAAM,QAAS,KAAK,WAAW,cAAc,IAAK,KAAK,UAAU,CAAC,IAAI;AACtE,MAAI,QAAQ,QAAQ,gBAAgB;AAClC,WAAO,GAAG,IAAI,GAAG,cAAc,GAAG,KAAK;AAAA,EACzC;AACA,MAAI,KAAK,WAAW,cAAc,GAAG;AACnC,WAAO,GAAG,cAAc,GAAG,KAAK;AAAA,EAClC;AACA,SAAO;AACT,GAAG,EAAE;AAEE,MAAM,UAAU,CAAC,YAA4B;AAClD,QAAM,eAAe,UAAU;AAAA,IAC7B;AAAA,IACA,QAAQ,MAAM,cAAc,EAAE;AAAA,MAC5B,CAAC,gBAA0B,oBAA4B;AACrD,YAAI,mBAAmB,KAAK;AAC1B,iBAAO;AAAA,QACT;AACA,YAAI,mBAAmB,MAAM;AAC3B,iBAAO,eAAe,MAAM,GAAG,EAAE;AAAA,QACnC;AACA,eAAO,eAAe,OAAO,eAAe;AAAA,MAC9C;AAAA,MACA,CAAC;AAAA,IACH;AAAA,EAAC;AACH,MAAI,iBAAiB,MAAM,QAAQ,WAAW,cAAc,GAAG;AAC7D,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/pathUtils.ts"],"sourcesContent":["const PATH_SEPARATOR = '/';\n\nexport const joinPaths = (...pathPart: string[]) =>\n  pathPart.reduce((acc, part) => {\n    const left = acc.endsWith(PATH_SEPARATOR) ? acc.slice(0, -1) : acc;\n    const right = part.startsWith(PATH_SEPARATOR) ? part.substring(1) : part;\n    if (left || acc === PATH_SEPARATOR) {\n      return `${left}${PATH_SEPARATOR}${right}`;\n    }\n    if (part.startsWith(PATH_SEPARATOR)) {\n      return `${PATH_SEPARATOR}${right}`;\n    }\n    return right;\n  }, '');\n\nexport const absPath = (rawPath: string): string => {\n  const absCandidate = joinPaths.apply(\n    null,\n    rawPath.split(PATH_SEPARATOR).reduce((partialAbsPath: string[], currentPathPart: string) => {\n      if (currentPathPart == '.') {\n        return partialAbsPath;\n      }\n      if (currentPathPart == '..') {\n        return partialAbsPath.slice(0, -1);\n      }\n      return partialAbsPath.concat(currentPathPart);\n    }, []),\n  );\n  if (absCandidate === '' && rawPath.startsWith(PATH_SEPARATOR)) {\n    return PATH_SEPARATOR;\n  }\n  return absCandidate;\n};\n"],"mappings":";AAAA,MAAM,iBAAiB;AAEhB,MAAM,YAAY,IAAI,aAC3B,SAAS,OAAO,CAAC,KAAK,SAAS;AAC7B,QAAM,OAAO,IAAI,SAAS,cAAc,IAAI,IAAI,MAAM,GAAG,EAAE,IAAI;AAC/D,QAAM,QAAQ,KAAK,WAAW,cAAc,IAAI,KAAK,UAAU,CAAC,IAAI;AACpE,MAAI,QAAQ,QAAQ,gBAAgB;AAClC,WAAO,GAAG,IAAI,GAAG,cAAc,GAAG,KAAK;AAAA,EACzC;AACA,MAAI,KAAK,WAAW,cAAc,GAAG;AACnC,WAAO,GAAG,cAAc,GAAG,KAAK;AAAA,EAClC;AACA,SAAO;AACT,GAAG,EAAE;AAEA,MAAM,UAAU,CAAC,YAA4B;AAClD,QAAM,eAAe,UAAU;AAAA,IAC7B;AAAA,IACA,QAAQ,MAAM,cAAc,EAAE,OAAO,CAAC,gBAA0B,oBAA4B;AAC1F,UAAI,mBAAmB,KAAK;AAC1B,eAAO;AAAA,MACT;AACA,UAAI,mBAAmB,MAAM;AAC3B,eAAO,eAAe,MAAM,GAAG,EAAE;AAAA,MACnC;AACA,aAAO,eAAe,OAAO,eAAe;AAAA,IAC9C,GAAG,CAAC,CAAC;AAAA,EACP;AACA,MAAI,iBAAiB,MAAM,QAAQ,WAAW,cAAc,GAAG;AAC7D,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}

package/dist/protocolDeadline.cjs

@@ -0,0 +1,205 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var protocolDeadline_exports = {};
+__export(protocolDeadline_exports, {
+  ATTENDED_FIRST_FRAME_MS: () => ATTENDED_FIRST_FRAME_MS,
+  ATTENDED_TIMEOUT_MS: () => ATTENDED_TIMEOUT_MS,
+  NETWORK_TIMEOUT_MS: () => NETWORK_TIMEOUT_MS,
+  PENDING_NOTICE_MS: () => PENDING_NOTICE_MS,
+  ProtocolCancelledError: () => ProtocolCancelledError,
+  ProtocolTimeoutError: () => ProtocolTimeoutError,
+  STREAM_IDLE_TIMEOUT_MS: () => STREAM_IDLE_TIMEOUT_MS,
+  UNATTENDED_TIMEOUT_MS: () => UNATTENDED_TIMEOUT_MS,
+  attendanceOf: () => attendanceOf,
+  attendanceReason: () => attendanceReason,
+  boundsFor: () => boundsFor,
+  createSuspendableDeadline: () => createSuspendableDeadline,
+  firstFrameBoundsFor: () => firstFrameBoundsFor,
+  firstFrameTimeoutFor: () => firstFrameTimeoutFor,
+  timeoutFor: () => timeoutFor
+});
+module.exports = __toCommonJS(protocolDeadline_exports);
+const UNATTENDED_TIMEOUT_MS = 3e4;
+const NETWORK_TIMEOUT_MS = 12e4;
+const ATTENDED_TIMEOUT_MS = 6e5;
+const ATTENDED_FIRST_FRAME_MS = 3e5;
+const STREAM_IDLE_TIMEOUT_MS = 12e4;
+const PENDING_NOTICE_MS = 3e3;
+const ATTENDED = {
+  // The powerbox and the add-secret modal are host-drawn and wait for the user to type or
+  // pick; the first use of any stored secret additionally raises a WebAuthn assertion
+  // (SECRETS_SPEC §3 — one unlock per session, from a live gesture). All three are wrapped
+  // presenters, so the signal covers this scheme completely.
+  secrets: {
+    reason: "host-drawn key entry / picker, and the per-session passkey unlock",
+    idleMs: UNATTENDED_TIMEOUT_MS
+  },
+  // Consent is raised INSIDE the request: presentMountConsent, presentGrantPicker,
+  // presentCreateConsent, presentShareDisclosure, presentReferenceConsent — every one of
+  // them a wrapped presenter. Unattended once the grant is held, attended on first use, and
+  // since R3-307 the host says which of those is happening.
+  spaces: {
+    reason: "first-use mount/share/create consent is drawn inside the request",
+    idleMs: UNATTENDED_TIMEOUT_MS
+  },
+  settings: {
+    reason: "settings verbs reach the same consent and picker surfaces as spaces",
+    idleMs: UNATTENDED_TIMEOUT_MS
+  },
+  // The contribute flow shows the full diff for approval before anything is written
+  // (TRUST_AND_SAFETY TS-19b: the approval MUST show the real diff, so a human reads it).
+  // NOT a wrapped presenter — no `idleMs`.
+  contribute: { reason: "the diff-approval step is a human read of the whole change" },
+  // A task is an app bound to a transient slot that the user interacts with; it returns
+  // when they finish, which is human-paced by construction. That is an APP's interaction,
+  // not a host prompt, so the attention channel never fires for it — no `idleMs`.
+  task: { reason: "a task app runs an interaction and returns when the user finishes" },
+  // Launching a target can raise consent for a not-yet-granted app — through the launch
+  // flow's own surface, not one of the wrapped presenters. No `idleMs`.
+  launch: { reason: "may raise first-use consent for the launched target" },
+  // A drag is a gesture in progress — its duration is the user's hand, and no host prompt
+  // is up while it happens. No `idleMs`.
+  dnd: { reason: "a drag is a human gesture in flight" },
+  // The chat stream's FIRST frame sits behind the session's first passkey unseal — the
+  // exact hang the dogfood run found — and that unseal IS a wrapped presenter. But the idle
+  // bound here is the NETWORK one, not the channel one: with no prompt up, this call is
+  // waiting on an arbitrary upstream model, and thirty seconds is a normal generation.
+  llm: {
+    reason: "the first frame can sit behind the session passkey unseal",
+    idleMs: NETWORK_TIMEOUT_MS
+  }
+};
+function attendedEntry(scheme, method) {
+  return ATTENDED[`${scheme}:${method}`] ?? ATTENDED[scheme];
+}
+function attendedReason(scheme, method) {
+  return attendedEntry(scheme, method)?.reason;
+}
+function attendanceOf(scheme, method) {
+  return attendedReason(scheme, method) ? "attended" : "unattended";
+}
+function attendanceReason(scheme, method) {
+  return attendedReason(scheme, method);
+}
+function timeoutFor(scheme, method) {
+  if (attendanceOf(scheme, method) === "attended") return ATTENDED_TIMEOUT_MS;
+  if (scheme === "fetch") return NETWORK_TIMEOUT_MS;
+  return UNATTENDED_TIMEOUT_MS;
+}
+function firstFrameTimeoutFor(scheme, method) {
+  return attendanceOf(scheme, method) === "attended" ? ATTENDED_FIRST_FRAME_MS : NETWORK_TIMEOUT_MS;
+}
+function boundsFor(scheme, method) {
+  const ceilingMs = timeoutFor(scheme, method);
+  const idleMs = attendedEntry(scheme, method)?.idleMs;
+  return { idleMs: idleMs === void 0 ? ceilingMs : Math.min(idleMs, ceilingMs), ceilingMs };
+}
+function firstFrameBoundsFor(scheme, method) {
+  const ceilingMs = firstFrameTimeoutFor(scheme, method);
+  const idleMs = attendedEntry(scheme, method)?.idleMs;
+  return { idleMs: idleMs === void 0 ? ceilingMs : Math.min(idleMs, ceilingMs), ceilingMs };
+}
+function createSuspendableDeadline(opts) {
+  const setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
+  const { idleMs, ceilingMs } = opts.bounds;
+  const hasIdleLeg = Number.isFinite(idleMs) && idleMs < ceilingMs;
+  let done = false;
+  let idle;
+  let ceiling;
+  const expire = (bound, boundMs) => {
+    if (done) return;
+    done = true;
+    opts.onExpire(bound, boundMs);
+  };
+  const armIdle = () => {
+    if (done || !hasIdleLeg || idle !== void 0) return;
+    idle = setTimer(() => {
+      idle = void 0;
+      expire("idle", idleMs);
+    }, idleMs);
+  };
+  const disarmIdle = () => {
+    if (idle !== void 0) {
+      clearTimer(idle);
+      idle = void 0;
+    }
+  };
+  if (Number.isFinite(ceilingMs)) {
+    ceiling = setTimer(() => {
+      ceiling = void 0;
+      expire("ceiling", ceilingMs);
+    }, ceilingMs);
+  }
+  armIdle();
+  return {
+    setAwaiting(awaiting) {
+      if (done) return;
+      if (awaiting) disarmIdle();
+      else armIdle();
+    },
+    dispose() {
+      done = true;
+      disarmIdle();
+      if (ceiling !== void 0) {
+        clearTimer(ceiling);
+        ceiling = void 0;
+      }
+    }
+  };
+}
+class ProtocolTimeoutError extends Error {
+  constructor(call, timeoutMs, attendance, bound = attendance === "attended" ? "ceiling" : "idle") {
+    super(
+      attendance === "attended" && bound === "ceiling" ? `immediately.run: ${call} was abandoned after ${Math.round(timeoutMs / 1e3)}s waiting for you` : `immediately.run: ${call} did not respond within ${Math.round(timeoutMs / 1e3)}s`
+    );
+    this.code = "timeout";
+    this.name = "ProtocolTimeoutError";
+    this.call = call;
+    this.timeoutMs = timeoutMs;
+    this.attendance = attendance;
+    this.bound = bound;
+  }
+}
+class ProtocolCancelledError extends Error {
+  constructor(call) {
+    super(`immediately.run: ${call} was cancelled`);
+    this.code = "cancelled";
+    this.name = "ProtocolCancelledError";
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ATTENDED_FIRST_FRAME_MS,
+  ATTENDED_TIMEOUT_MS,
+  NETWORK_TIMEOUT_MS,
+  PENDING_NOTICE_MS,
+  ProtocolCancelledError,
+  ProtocolTimeoutError,
+  STREAM_IDLE_TIMEOUT_MS,
+  UNATTENDED_TIMEOUT_MS,
+  attendanceOf,
+  attendanceReason,
+  boundsFor,
+  createSuspendableDeadline,
+  firstFrameBoundsFor,
+  firstFrameTimeoutFor,
+  timeoutFor
+});
+//# sourceMappingURL=protocolDeadline.cjs.map

package/dist/protocolDeadline.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocolDeadline.ts"],"sourcesContent":["// Deadlines for host protocol calls (R3-298) — so no platform request can hang forever.\n//\n// THE FAILURE THIS FIXES. `protocolRequest` and `hostFetch` carried no timeout, so a host\n// operation that never resolved presented as an indefinite \"Running…\" with no error, no\n// cancel, and nothing in the console. The GLM dogfood run hit exactly this: the first\n// `chat()` of a session parks on a WebAuthn unseal that never completes, and the surface\n// simply waits. A first-run user inside the setup wizard (R3-299) would be stranded on\n// \"Testing…\" — at the worst possible moment, on the screen whose whole purpose is to prove\n// setup worked.\n//\n// WHY A SINGLE CONSTANT IS THE WRONG ANSWER, AND WHAT IS DONE INSTEAD. A blanket timeout\n// was deferred once as risky, correctly: some host operations legitimately await a HUMAN —\n// a passkey tap, a consent decision, a file picker — and a flat deadline aborts those. So\n// calls are classified, and the two classes get very different bounds:\n//\n//   unattended — a network call or a channel round-trip. Nobody is being asked anything, so\n//                a reply that has not arrived in tens of seconds is a fault. Short bound.\n//   attended   — the host may draw chrome and wait for the user. The bound exists only to\n//                stop an ABANDONED prompt from pinning the caller forever, so it is set far\n//                beyond human reaction time.\n//\n// NOTHING IS UNBOUNDED. \"A long or absent deadline\" was the licence; absent is declined,\n// because absent is the bug. An attended bound of minutes never aborts a person who is\n// actually deciding, and does release a caller whose user walked away — which is the\n// difference between a slow flow and a wedged one.\n//\n// THE IMPRECISION, AND HOW R3-307 REMOVED IT. Attendedness is classified per\n// (scheme, method), but it is really a property of a MOMENT: `spaces:mount` is unattended\n// when the grant is already held and attended on first use, because the host raises consent\n// inside the request (`spaceHandler` `presentMountConsent`). A per-method table cannot see\n// that, so R3-298 classified any method that MAY prompt as `attended` and gave it the long\n// bound — which meant the common grant-held path also waited ten minutes before reporting a\n// fault.\n//\n// R3-307 added the host-attention channel (`hostAttention.ts`), on which the host says\n// whether a person is being asked something RIGHT NOW. So a call now carries TWO bounds:\n//\n//   idle    — in force while the host is not prompting. A may-prompt call runs on this,\n//             which is a real correctness gain: the grant-held `spaces:mount` faults in\n//             seconds, as it always should have.\n//   ceiling — absolute, from call start, NEVER suspended. An abandoned prompt still\n//             releases the caller. The signal may EXTEND a deadline, never remove it.\n//\n// AND THE SHORTENING IS OPT-IN PER ENTRY, which is the part worth not losing. A scheme\n// drops to the short idle bound only when EVERY prompt it can raise is one the host\n// actually announces on that channel (the powerbox, the add-secret modal, the passkey\n// unlock, and the spaceHandler consent surfaces — the presenters site-main wraps). A task\n// app's interaction and the contribute diff-approval are human-paced but are NOT host\n// prompts, so no signal would ever fire for them and they keep the full attended bound. A\n// signal that cannot fire must never be allowed to shorten a deadline.\n\nimport type { HostAttentionKind } from './hostAttention';\n\n/** Whether a call may block on a human being asked something. */\nexport type Attendance = 'unattended' | 'attended';\n\n/** Milliseconds. Exported so callers can reason about the defaults they are overriding. */\nexport const UNATTENDED_TIMEOUT_MS = 30_000;\n/** Network calls reach arbitrary upstreams; the host bounds the fetch itself, so this is a\n *  backstop against the host never replying, not a request budget. */\nexport const NETWORK_TIMEOUT_MS = 120_000;\n/** Far beyond human reaction time — this exists only so an ABANDONED prompt releases the\n *  caller. It must never be short enough to abort someone who is deciding. */\nexport const ATTENDED_TIMEOUT_MS = 600_000;\n/** A stream's first frame may be behind an unseal, so it gets an attended-scale bound of\n *  its own. See `firstFrameTimeoutFor`. */\nexport const ATTENDED_FIRST_FRAME_MS = 300_000;\n/** After the first frame, silence this long means the stream is wedged: the host is no\n *  longer producing and no human is being asked. */\nexport const STREAM_IDLE_TIMEOUT_MS = 120_000;\n/** When a call passes this, `onPending` fires so a caller can render a waiting state\n *  instead of an unexplained stall. */\nexport const PENDING_NOTICE_MS = 3_000;\n\n/**\n * Methods that may draw host chrome and wait for the user.\n *\n * Each entry is a `scheme:method` or a bare `scheme` (matching every method of it). The\n * REASON is recorded per entry, because this table is the item's actual content — a future\n * reader must be able to see why a method is on the long bound without re-deriving it from\n * the host source.\n */\ninterface AttendedEntry {\n  /** Why this call may block on a human. */\n  reason: string;\n  /**\n   * The bound this call runs on while the host reports NOBODY is being asked (R3-307).\n   *\n   * Set it ONLY when every prompt this entry can raise is one the host announces on the\n   * host-attention channel — i.e. a presenter site-main wraps (`hostAttention.ts` in that\n   * repo). Omitted ⇒ the call keeps the full attended bound at all times, because a signal\n   * that never fires must not be allowed to shorten a deadline.\n   */\n  idleMs?: number;\n}\n\nconst ATTENDED: Record<string, AttendedEntry> = {\n  // The powerbox and the add-secret modal are host-drawn and wait for the user to type or\n  // pick; the first use of any stored secret additionally raises a WebAuthn assertion\n  // (SECRETS_SPEC §3 — one unlock per session, from a live gesture). All three are wrapped\n  // presenters, so the signal covers this scheme completely.\n  secrets: {\n    reason: 'host-drawn key entry / picker, and the per-session passkey unlock',\n    idleMs: UNATTENDED_TIMEOUT_MS,\n  },\n  // Consent is raised INSIDE the request: presentMountConsent, presentGrantPicker,\n  // presentCreateConsent, presentShareDisclosure, presentReferenceConsent — every one of\n  // them a wrapped presenter. Unattended once the grant is held, attended on first use, and\n  // since R3-307 the host says which of those is happening.\n  spaces: {\n    reason: 'first-use mount/share/create consent is drawn inside the request',\n    idleMs: UNATTENDED_TIMEOUT_MS,\n  },\n  settings: {\n    reason: 'settings verbs reach the same consent and picker surfaces as spaces',\n    idleMs: UNATTENDED_TIMEOUT_MS,\n  },\n  // The contribute flow shows the full diff for approval before anything is written\n  // (TRUST_AND_SAFETY TS-19b: the approval MUST show the real diff, so a human reads it).\n  // NOT a wrapped presenter — no `idleMs`.\n  contribute: { reason: 'the diff-approval step is a human read of the whole change' },\n  // A task is an app bound to a transient slot that the user interacts with; it returns\n  // when they finish, which is human-paced by construction. That is an APP's interaction,\n  // not a host prompt, so the attention channel never fires for it — no `idleMs`.\n  task: { reason: 'a task app runs an interaction and returns when the user finishes' },\n  // Launching a target can raise consent for a not-yet-granted app — through the launch\n  // flow's own surface, not one of the wrapped presenters. No `idleMs`.\n  launch: { reason: 'may raise first-use consent for the launched target' },\n  // A drag is a gesture in progress — its duration is the user's hand, and no host prompt\n  // is up while it happens. No `idleMs`.\n  dnd: { reason: 'a drag is a human gesture in flight' },\n  // The chat stream's FIRST frame sits behind the session's first passkey unseal — the\n  // exact hang the dogfood run found — and that unseal IS a wrapped presenter. But the idle\n  // bound here is the NETWORK one, not the channel one: with no prompt up, this call is\n  // waiting on an arbitrary upstream model, and thirty seconds is a normal generation.\n  llm: {\n    reason: 'the first frame can sit behind the session passkey unseal',\n    idleMs: NETWORK_TIMEOUT_MS,\n  },\n};\n\n/** Look up a scheme/method in the attended table, preferring the exact method entry. */\nfunction attendedEntry(scheme: string, method: string): AttendedEntry | undefined {\n  return ATTENDED[`${scheme}:${method}`] ?? ATTENDED[scheme];\n}\n\n/** Look up a scheme/method in the attended table, preferring the exact method entry. */\nfunction attendedReason(scheme: string, method: string): string | undefined {\n  return attendedEntry(scheme, method)?.reason;\n}\n\n/** Whether a call may block on a human. Exported for the classification test + tooling. */\nexport function attendanceOf(scheme: string, method: string): Attendance {\n  return attendedReason(scheme, method) ? 'attended' : 'unattended';\n}\n\n/** Why a call is classified attended, or `undefined` when it is not. Exported so the\n *  classification is legible from a test failure rather than only from this source. */\nexport function attendanceReason(scheme: string, method: string): string | undefined {\n  return attendedReason(scheme, method);\n}\n\n/** The default deadline for a one-shot `protocolRequest`. */\nexport function timeoutFor(scheme: string, method: string): number {\n  if (attendanceOf(scheme, method) === 'attended') return ATTENDED_TIMEOUT_MS;\n  // `fetch` reaches an arbitrary upstream, so it gets the network bound rather than the\n  // channel-round-trip one.\n  if (scheme === 'fetch') return NETWORK_TIMEOUT_MS;\n  return UNATTENDED_TIMEOUT_MS;\n}\n\n/**\n * The default TIME-TO-FIRST-FRAME bound for a stream.\n *\n * Deliberately not a total-duration bound: a long generation that is streaming normally is\n * healthy, and killing it would be a worse bug than the one being fixed. The hang has a\n * distinct shape — NO frames at all — so that is what is bounded, plus an idle gap between\n * frames once flowing. Together they fire exactly on a wedged stream and never on a slow\n * one.\n */\nexport function firstFrameTimeoutFor(scheme: string, method: string): number {\n  return attendanceOf(scheme, method) === 'attended' ? ATTENDED_FIRST_FRAME_MS : NETWORK_TIMEOUT_MS;\n}\n\n/**\n * The two bounds a call runs under (R3-307).\n *\n * `idleMs` is in force while the host reports nobody is being asked; it is cleared while a\n * host prompt is up and restarted, in full, when the prompt goes away. `ceilingMs` runs from\n * call start and is NEVER suspended — it is what releases a caller whose user walked away.\n */\nexport interface CallBounds {\n  /** The bound in force while the host is not waiting on a person. */\n  idleMs: number;\n  /** The absolute bound from call start. Never suspended. */\n  ceilingMs: number;\n}\n\n/** Which of a call's two bounds elapsed. `idle` means the host was NOT prompting — nobody\n *  was being asked anything, so this is a fault. `ceiling` means the absolute bound ran out,\n *  which for an attended call is an abandoned prompt. */\nexport type DeadlineBound = 'idle' | 'ceiling';\n\n/** The bounds for a one-shot `protocolRequest`. */\nexport function boundsFor(scheme: string, method: string): CallBounds {\n  const ceilingMs = timeoutFor(scheme, method);\n  const idleMs = attendedEntry(scheme, method)?.idleMs;\n  // `Math.min` so an `idleMs` can only ever tighten: an entry that named a bound longer than\n  // its own ceiling would otherwise silently disable the idle leg.\n  return { idleMs: idleMs === undefined ? ceilingMs : Math.min(idleMs, ceilingMs), ceilingMs };\n}\n\n/** The bounds for a stream's time-to-first-frame. */\nexport function firstFrameBoundsFor(scheme: string, method: string): CallBounds {\n  const ceilingMs = firstFrameTimeoutFor(scheme, method);\n  const idleMs = attendedEntry(scheme, method)?.idleMs;\n  return { idleMs: idleMs === undefined ? ceilingMs : Math.min(idleMs, ceilingMs), ceilingMs };\n}\n\n/** A live deadline that the host-attention signal can suspend. */\nexport interface SuspendableDeadline {\n  /** Tell the deadline whether the host is waiting on a person right now. */\n  setAwaiting(awaiting: boolean): void;\n  /** Clear every timer. Idempotent — safe to call from a `finally`. */\n  dispose(): void;\n}\n\n/**\n * A deadline with a suspendable idle leg and an unsuspendable ceiling.\n *\n * Pure and injectable (`setTimer`/`clearTimer`) so the suspension rules are unit-testable\n * against a fake clock rather than by waiting minutes for real ones.\n *\n * The idle leg RESTARTS in full when a prompt clears rather than resuming where it left off.\n * That is deliberate: after the user dismisses a prompt the host begins fresh work, and the\n * seconds that elapsed before the prompt say nothing about how long that work should take.\n * The ceiling is what stops a repeatedly-prompting call from running forever.\n */\nexport function createSuspendableDeadline(opts: {\n  bounds: CallBounds;\n  /** Called once, with the bound that elapsed and its length in ms. */\n  onExpire: (bound: DeadlineBound, boundMs: number) => void;\n  setTimer?: (fn: () => void, ms: number) => unknown;\n  clearTimer?: (handle: unknown) => void;\n}): SuspendableDeadline {\n  const setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));\n  const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));\n  const { idleMs, ceilingMs } = opts.bounds;\n  // An idle leg at or above the ceiling can never fire first, so don't arm one — that keeps\n  // the common unattended case (idle === ceiling) on exactly one timer, as before R3-307.\n  const hasIdleLeg = Number.isFinite(idleMs) && idleMs < ceilingMs;\n\n  let done = false;\n  let idle: unknown;\n  let ceiling: unknown;\n\n  const expire = (bound: DeadlineBound, boundMs: number) => {\n    if (done) return;\n    done = true;\n    opts.onExpire(bound, boundMs);\n  };\n\n  const armIdle = () => {\n    if (done || !hasIdleLeg || idle !== undefined) return;\n    idle = setTimer(() => {\n      idle = undefined;\n      expire('idle', idleMs);\n    }, idleMs);\n  };\n  const disarmIdle = () => {\n    if (idle !== undefined) {\n      clearTimer(idle);\n      idle = undefined;\n    }\n  };\n\n  if (Number.isFinite(ceilingMs)) {\n    ceiling = setTimer(() => {\n      ceiling = undefined;\n      expire('ceiling', ceilingMs);\n    }, ceilingMs);\n  }\n  armIdle();\n\n  return {\n    setAwaiting(awaiting: boolean) {\n      if (done) return;\n      if (awaiting) disarmIdle();\n      else armIdle();\n    },\n    dispose() {\n      done = true;\n      disarmIdle();\n      if (ceiling !== undefined) {\n        clearTimer(ceiling);\n        ceiling = undefined;\n      }\n    },\n  };\n}\n\n/** The error a bounded call rejects with. `code` is `'timeout'` — the code R3-303's typed\n *  provider-error taxonomy adopts, so apps see one vocabulary. */\nexport class ProtocolTimeoutError extends Error {\n  readonly code = 'timeout';\n  /** `scheme:method` of the call that timed out. */\n  readonly call: string;\n  /** The bound that elapsed, in ms. */\n  readonly timeoutMs: number;\n  /** Whether the call was on the attended or unattended bound — the first thing anyone\n   *  debugging a timeout needs, and otherwise invisible. */\n  readonly attendance: Attendance;\n  /** WHICH bound elapsed (R3-307). An attended call that faults on its `idle` bound was not\n   *  waiting on anyone — the host said so — and that is a genuinely different diagnosis from\n   *  an abandoned prompt hitting the `ceiling`. */\n  readonly bound: DeadlineBound;\n  constructor(\n    call: string,\n    timeoutMs: number,\n    attendance: Attendance,\n    bound: DeadlineBound = attendance === 'attended' ? 'ceiling' : 'idle',\n  ) {\n    super(\n      attendance === 'attended' && bound === 'ceiling'\n        ? `immediately.run: ${call} was abandoned after ${Math.round(timeoutMs / 1000)}s waiting for you`\n        : `immediately.run: ${call} did not respond within ${Math.round(timeoutMs / 1000)}s`,\n    );\n    this.name = 'ProtocolTimeoutError';\n    this.call = call;\n    this.timeoutMs = timeoutMs;\n    this.attendance = attendance;\n    this.bound = bound;\n  }\n}\n\n/** The error a cancelled call rejects with. */\nexport class ProtocolCancelledError extends Error {\n  readonly code = 'cancelled';\n  constructor(call: string) {\n    super(`immediately.run: ${call} was cancelled`);\n    this.name = 'ProtocolCancelledError';\n  }\n}\n\n/** What the host is waiting for at this moment, as reported on the host-attention channel\n *  (R3-307). Present on a {@link PendingState} only while the host IS prompting. */\nexport interface PendingAttention {\n  /** The kind of prompt on screen, or `null` when the host reports a wait it cannot name. */\n  kind: HostAttentionKind | null;\n  /** `Date.now()` when the wait began, or `null`. */\n  since: number | null;\n}\n\n/** What `onPending` is told when a call is taking a while. */\nexport interface PendingState {\n  call: string;\n  attendance: Attendance;\n  elapsedMs: number;\n  /** Why this call *may* be waiting on a person — present only when attended. It comes from\n   *  the classification table, so it is a standing possibility, not a live fact. */\n  reason?: string;\n  /**\n   * What the host is waiting for RIGHT NOW (R3-307) — present only while a host prompt is\n   * actually up. Prefer it over {@link reason} when rendering: \"tap your passkey\" is a\n   * sentence the user can act on; \"this may need you\" is not.\n   */\n  awaiting?: PendingAttention;\n}\n\n/** Options accepted by every bounded host call. */\nexport interface BoundedCallOptions {\n  /** Override the classified default. `Infinity` disables the bound — an escape hatch for a\n   *  caller that genuinely owns the wait (it must then provide its own way out).\n   *\n   *  An explicit value is the WHOLE bound: it is never suspended by the host-attention\n   *  signal, because a caller that named a number owns the wait. */\n  timeoutMs?: number;\n  /** Abort the wait. The SDK stops waiting and rejects with `code: 'cancelled'`. */\n  signal?: AbortSignal;\n  /** Fired when the call passes `PENDING_NOTICE_MS`, so a caller can render a waiting state\n   *  rather than an unexplained pause — and again, after that, whenever the host starts or\n   *  stops waiting on the user, so the waiting state can name what is on screen now. */\n  onPending?: (state: PendingState) => void;\n}\n"],"mappings":"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","names":[]}

package/dist/protocolDeadline.d.cts

@@ -0,0 +1,146 @@
+import { HostAttentionKind } from './hostAttention.cjs';
+
+/** Whether a call may block on a human being asked something. */
+type Attendance = 'unattended' | 'attended';
+/** Milliseconds. Exported so callers can reason about the defaults they are overriding. */
+declare const UNATTENDED_TIMEOUT_MS = 30000;
+/** Network calls reach arbitrary upstreams; the host bounds the fetch itself, so this is a
+ *  backstop against the host never replying, not a request budget. */
+declare const NETWORK_TIMEOUT_MS = 120000;
+/** Far beyond human reaction time — this exists only so an ABANDONED prompt releases the
+ *  caller. It must never be short enough to abort someone who is deciding. */
+declare const ATTENDED_TIMEOUT_MS = 600000;
+/** A stream's first frame may be behind an unseal, so it gets an attended-scale bound of
+ *  its own. See `firstFrameTimeoutFor`. */
+declare const ATTENDED_FIRST_FRAME_MS = 300000;
+/** After the first frame, silence this long means the stream is wedged: the host is no
+ *  longer producing and no human is being asked. */
+declare const STREAM_IDLE_TIMEOUT_MS = 120000;
+/** When a call passes this, `onPending` fires so a caller can render a waiting state
+ *  instead of an unexplained stall. */
+declare const PENDING_NOTICE_MS = 3000;
+/** Whether a call may block on a human. Exported for the classification test + tooling. */
+declare function attendanceOf(scheme: string, method: string): Attendance;
+/** Why a call is classified attended, or `undefined` when it is not. Exported so the
+ *  classification is legible from a test failure rather than only from this source. */
+declare function attendanceReason(scheme: string, method: string): string | undefined;
+/** The default deadline for a one-shot `protocolRequest`. */
+declare function timeoutFor(scheme: string, method: string): number;
+/**
+ * The default TIME-TO-FIRST-FRAME bound for a stream.
+ *
+ * Deliberately not a total-duration bound: a long generation that is streaming normally is
+ * healthy, and killing it would be a worse bug than the one being fixed. The hang has a
+ * distinct shape — NO frames at all — so that is what is bounded, plus an idle gap between
+ * frames once flowing. Together they fire exactly on a wedged stream and never on a slow
+ * one.
+ */
+declare function firstFrameTimeoutFor(scheme: string, method: string): number;
+/**
+ * The two bounds a call runs under (R3-307).
+ *
+ * `idleMs` is in force while the host reports nobody is being asked; it is cleared while a
+ * host prompt is up and restarted, in full, when the prompt goes away. `ceilingMs` runs from
+ * call start and is NEVER suspended — it is what releases a caller whose user walked away.
+ */
+interface CallBounds {
+    /** The bound in force while the host is not waiting on a person. */
+    idleMs: number;
+    /** The absolute bound from call start. Never suspended. */
+    ceilingMs: number;
+}
+/** Which of a call's two bounds elapsed. `idle` means the host was NOT prompting — nobody
+ *  was being asked anything, so this is a fault. `ceiling` means the absolute bound ran out,
+ *  which for an attended call is an abandoned prompt. */
+type DeadlineBound = 'idle' | 'ceiling';
+/** The bounds for a one-shot `protocolRequest`. */
+declare function boundsFor(scheme: string, method: string): CallBounds;
+/** The bounds for a stream's time-to-first-frame. */
+declare function firstFrameBoundsFor(scheme: string, method: string): CallBounds;
+/** A live deadline that the host-attention signal can suspend. */
+interface SuspendableDeadline {
+    /** Tell the deadline whether the host is waiting on a person right now. */
+    setAwaiting(awaiting: boolean): void;
+    /** Clear every timer. Idempotent — safe to call from a `finally`. */
+    dispose(): void;
+}
+/**
+ * A deadline with a suspendable idle leg and an unsuspendable ceiling.
+ *
+ * Pure and injectable (`setTimer`/`clearTimer`) so the suspension rules are unit-testable
+ * against a fake clock rather than by waiting minutes for real ones.
+ *
+ * The idle leg RESTARTS in full when a prompt clears rather than resuming where it left off.
+ * That is deliberate: after the user dismisses a prompt the host begins fresh work, and the
+ * seconds that elapsed before the prompt say nothing about how long that work should take.
+ * The ceiling is what stops a repeatedly-prompting call from running forever.
+ */
+declare function createSuspendableDeadline(opts: {
+    bounds: CallBounds;
+    /** Called once, with the bound that elapsed and its length in ms. */
+    onExpire: (bound: DeadlineBound, boundMs: number) => void;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}): SuspendableDeadline;
+/** The error a bounded call rejects with. `code` is `'timeout'` — the code R3-303's typed
+ *  provider-error taxonomy adopts, so apps see one vocabulary. */
+declare class ProtocolTimeoutError extends Error {
+    readonly code = "timeout";
+    /** `scheme:method` of the call that timed out. */
+    readonly call: string;
+    /** The bound that elapsed, in ms. */
+    readonly timeoutMs: number;
+    /** Whether the call was on the attended or unattended bound — the first thing anyone
+     *  debugging a timeout needs, and otherwise invisible. */
+    readonly attendance: Attendance;
+    /** WHICH bound elapsed (R3-307). An attended call that faults on its `idle` bound was not
+     *  waiting on anyone — the host said so — and that is a genuinely different diagnosis from
+     *  an abandoned prompt hitting the `ceiling`. */
+    readonly bound: DeadlineBound;
+    constructor(call: string, timeoutMs: number, attendance: Attendance, bound?: DeadlineBound);
+}
+/** The error a cancelled call rejects with. */
+declare class ProtocolCancelledError extends Error {
+    readonly code = "cancelled";
+    constructor(call: string);
+}
+/** What the host is waiting for at this moment, as reported on the host-attention channel
+ *  (R3-307). Present on a {@link PendingState} only while the host IS prompting. */
+interface PendingAttention {
+    /** The kind of prompt on screen, or `null` when the host reports a wait it cannot name. */
+    kind: HostAttentionKind | null;
+    /** `Date.now()` when the wait began, or `null`. */
+    since: number | null;
+}
+/** What `onPending` is told when a call is taking a while. */
+interface PendingState {
+    call: string;
+    attendance: Attendance;
+    elapsedMs: number;
+    /** Why this call *may* be waiting on a person — present only when attended. It comes from
+     *  the classification table, so it is a standing possibility, not a live fact. */
+    reason?: string;
+    /**
+     * What the host is waiting for RIGHT NOW (R3-307) — present only while a host prompt is
+     * actually up. Prefer it over {@link reason} when rendering: "tap your passkey" is a
+     * sentence the user can act on; "this may need you" is not.
+     */
+    awaiting?: PendingAttention;
+}
+/** Options accepted by every bounded host call. */
+interface BoundedCallOptions {
+    /** Override the classified default. `Infinity` disables the bound — an escape hatch for a
+     *  caller that genuinely owns the wait (it must then provide its own way out).
+     *
+     *  An explicit value is the WHOLE bound: it is never suspended by the host-attention
+     *  signal, because a caller that named a number owns the wait. */
+    timeoutMs?: number;
+    /** Abort the wait. The SDK stops waiting and rejects with `code: 'cancelled'`. */
+    signal?: AbortSignal;
+    /** Fired when the call passes `PENDING_NOTICE_MS`, so a caller can render a waiting state
+     *  rather than an unexplained pause — and again, after that, whenever the host starts or
+     *  stops waiting on the user, so the waiting state can name what is on screen now. */
+    onPending?: (state: PendingState) => void;
+}
+
+export { ATTENDED_FIRST_FRAME_MS, ATTENDED_TIMEOUT_MS, type Attendance, type BoundedCallOptions, type CallBounds, type DeadlineBound, NETWORK_TIMEOUT_MS, PENDING_NOTICE_MS, type PendingAttention, type PendingState, ProtocolCancelledError, ProtocolTimeoutError, STREAM_IDLE_TIMEOUT_MS, type SuspendableDeadline, UNATTENDED_TIMEOUT_MS, attendanceOf, attendanceReason, boundsFor, createSuspendableDeadline, firstFrameBoundsFor, firstFrameTimeoutFor, timeoutFor };

package/dist/protocolDeadline.d.ts

@@ -0,0 +1,146 @@
+import { HostAttentionKind } from './hostAttention.js';
+
+/** Whether a call may block on a human being asked something. */
+type Attendance = 'unattended' | 'attended';
+/** Milliseconds. Exported so callers can reason about the defaults they are overriding. */
+declare const UNATTENDED_TIMEOUT_MS = 30000;
+/** Network calls reach arbitrary upstreams; the host bounds the fetch itself, so this is a
+ *  backstop against the host never replying, not a request budget. */
+declare const NETWORK_TIMEOUT_MS = 120000;
+/** Far beyond human reaction time — this exists only so an ABANDONED prompt releases the
+ *  caller. It must never be short enough to abort someone who is deciding. */
+declare const ATTENDED_TIMEOUT_MS = 600000;
+/** A stream's first frame may be behind an unseal, so it gets an attended-scale bound of
+ *  its own. See `firstFrameTimeoutFor`. */
+declare const ATTENDED_FIRST_FRAME_MS = 300000;
+/** After the first frame, silence this long means the stream is wedged: the host is no
+ *  longer producing and no human is being asked. */
+declare const STREAM_IDLE_TIMEOUT_MS = 120000;
+/** When a call passes this, `onPending` fires so a caller can render a waiting state
+ *  instead of an unexplained stall. */
+declare const PENDING_NOTICE_MS = 3000;
+/** Whether a call may block on a human. Exported for the classification test + tooling. */
+declare function attendanceOf(scheme: string, method: string): Attendance;
+/** Why a call is classified attended, or `undefined` when it is not. Exported so the
+ *  classification is legible from a test failure rather than only from this source. */
+declare function attendanceReason(scheme: string, method: string): string | undefined;
+/** The default deadline for a one-shot `protocolRequest`. */
+declare function timeoutFor(scheme: string, method: string): number;
+/**
+ * The default TIME-TO-FIRST-FRAME bound for a stream.
+ *
+ * Deliberately not a total-duration bound: a long generation that is streaming normally is
+ * healthy, and killing it would be a worse bug than the one being fixed. The hang has a
+ * distinct shape — NO frames at all — so that is what is bounded, plus an idle gap between
+ * frames once flowing. Together they fire exactly on a wedged stream and never on a slow
+ * one.
+ */
+declare function firstFrameTimeoutFor(scheme: string, method: string): number;
+/**
+ * The two bounds a call runs under (R3-307).
+ *
+ * `idleMs` is in force while the host reports nobody is being asked; it is cleared while a
+ * host prompt is up and restarted, in full, when the prompt goes away. `ceilingMs` runs from
+ * call start and is NEVER suspended — it is what releases a caller whose user walked away.
+ */
+interface CallBounds {
+    /** The bound in force while the host is not waiting on a person. */
+    idleMs: number;
+    /** The absolute bound from call start. Never suspended. */
+    ceilingMs: number;
+}
+/** Which of a call's two bounds elapsed. `idle` means the host was NOT prompting — nobody
+ *  was being asked anything, so this is a fault. `ceiling` means the absolute bound ran out,
+ *  which for an attended call is an abandoned prompt. */
+type DeadlineBound = 'idle' | 'ceiling';
+/** The bounds for a one-shot `protocolRequest`. */
+declare function boundsFor(scheme: string, method: string): CallBounds;
+/** The bounds for a stream's time-to-first-frame. */
+declare function firstFrameBoundsFor(scheme: string, method: string): CallBounds;
+/** A live deadline that the host-attention signal can suspend. */
+interface SuspendableDeadline {
+    /** Tell the deadline whether the host is waiting on a person right now. */
+    setAwaiting(awaiting: boolean): void;
+    /** Clear every timer. Idempotent — safe to call from a `finally`. */
+    dispose(): void;
+}
+/**
+ * A deadline with a suspendable idle leg and an unsuspendable ceiling.
+ *
+ * Pure and injectable (`setTimer`/`clearTimer`) so the suspension rules are unit-testable
+ * against a fake clock rather than by waiting minutes for real ones.
+ *
+ * The idle leg RESTARTS in full when a prompt clears rather than resuming where it left off.
+ * That is deliberate: after the user dismisses a prompt the host begins fresh work, and the
+ * seconds that elapsed before the prompt say nothing about how long that work should take.
+ * The ceiling is what stops a repeatedly-prompting call from running forever.
+ */
+declare function createSuspendableDeadline(opts: {
+    bounds: CallBounds;
+    /** Called once, with the bound that elapsed and its length in ms. */
+    onExpire: (bound: DeadlineBound, boundMs: number) => void;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}): SuspendableDeadline;
+/** The error a bounded call rejects with. `code` is `'timeout'` — the code R3-303's typed
+ *  provider-error taxonomy adopts, so apps see one vocabulary. */
+declare class ProtocolTimeoutError extends Error {
+    readonly code = "timeout";
+    /** `scheme:method` of the call that timed out. */
+    readonly call: string;
+    /** The bound that elapsed, in ms. */
+    readonly timeoutMs: number;
+    /** Whether the call was on the attended or unattended bound — the first thing anyone
+     *  debugging a timeout needs, and otherwise invisible. */
+    readonly attendance: Attendance;
+    /** WHICH bound elapsed (R3-307). An attended call that faults on its `idle` bound was not
+     *  waiting on anyone — the host said so — and that is a genuinely different diagnosis from
+     *  an abandoned prompt hitting the `ceiling`. */
+    readonly bound: DeadlineBound;
+    constructor(call: string, timeoutMs: number, attendance: Attendance, bound?: DeadlineBound);
+}
+/** The error a cancelled call rejects with. */
+declare class ProtocolCancelledError extends Error {
+    readonly code = "cancelled";
+    constructor(call: string);
+}
+/** What the host is waiting for at this moment, as reported on the host-attention channel
+ *  (R3-307). Present on a {@link PendingState} only while the host IS prompting. */
+interface PendingAttention {
+    /** The kind of prompt on screen, or `null` when the host reports a wait it cannot name. */
+    kind: HostAttentionKind | null;
+    /** `Date.now()` when the wait began, or `null`. */
+    since: number | null;
+}
+/** What `onPending` is told when a call is taking a while. */
+interface PendingState {
+    call: string;
+    attendance: Attendance;
+    elapsedMs: number;
+    /** Why this call *may* be waiting on a person — present only when attended. It comes from
+     *  the classification table, so it is a standing possibility, not a live fact. */
+    reason?: string;
+    /**
+     * What the host is waiting for RIGHT NOW (R3-307) — present only while a host prompt is
+     * actually up. Prefer it over {@link reason} when rendering: "tap your passkey" is a
+     * sentence the user can act on; "this may need you" is not.
+     */
+    awaiting?: PendingAttention;
+}
+/** Options accepted by every bounded host call. */
+interface BoundedCallOptions {
+    /** Override the classified default. `Infinity` disables the bound — an escape hatch for a
+     *  caller that genuinely owns the wait (it must then provide its own way out).
+     *
+     *  An explicit value is the WHOLE bound: it is never suspended by the host-attention
+     *  signal, because a caller that named a number owns the wait. */
+    timeoutMs?: number;
+    /** Abort the wait. The SDK stops waiting and rejects with `code: 'cancelled'`. */
+    signal?: AbortSignal;
+    /** Fired when the call passes `PENDING_NOTICE_MS`, so a caller can render a waiting state
+     *  rather than an unexplained pause — and again, after that, whenever the host starts or
+     *  stops waiting on the user, so the waiting state can name what is on screen now. */
+    onPending?: (state: PendingState) => void;
+}
+
+export { ATTENDED_FIRST_FRAME_MS, ATTENDED_TIMEOUT_MS, type Attendance, type BoundedCallOptions, type CallBounds, type DeadlineBound, NETWORK_TIMEOUT_MS, PENDING_NOTICE_MS, type PendingAttention, type PendingState, ProtocolCancelledError, ProtocolTimeoutError, STREAM_IDLE_TIMEOUT_MS, type SuspendableDeadline, UNATTENDED_TIMEOUT_MS, attendanceOf, attendanceReason, boundsFor, createSuspendableDeadline, firstFrameBoundsFor, firstFrameTimeoutFor, timeoutFor };