@athenaintel/react 0.41.3 → 0.42.2

package/dist/agent-runtime/src/optimistic-content.d.ts

@@ -0,0 +1,21 @@
+import type { LangChainMessage } from '@assistant-ui/react-langgraph';
+/** Parts of a pending user message the optimistic bubble can render. */
+export type OptimisticContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    image: string;
+};
+type HumanMessageContent = Extract<LangChainMessage, {
+    type: 'human';
+}>['content'];
+/**
+ * Content for the optimistic human bubble built from a pending send. Image
+ * attachment parts become LangChain `image_url` blocks so the just-sent
+ * message renders its images immediately instead of waiting for the backend
+ * echo (which only carries images after server-side mention extraction).
+ * Text-only sends keep the plain joined string.
+ */
+export declare const buildOptimisticHumanContent: (parts: readonly OptimisticContentPart[]) => HumanMessageContent;
+export {};

package/dist/agent-runtime/src/protocol.cjs

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const runconfigContract = require("./generated/runconfig-contract.cjs");
+const DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION = runconfigContract.DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION - 1;
+function declaredDeepAgentProtocolVersion({
+  laneHistory = false
+} = {}) {
+  return laneHistory ? runconfigContract.DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION : DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION;
+}
 const isContractVersion = (value) => typeof value === "number" && Number.isInteger(value) && value >= 1;
 function readDeepAgentProtocol(state) {
   if (typeof state !== "object" || state === null) return null;
@@ -10,12 +16,12 @@ function readDeepAgentProtocol(state) {
   if (!isContractVersion(version)) return null;
   return { version };
 }
-function projectDeepAgentProtocol(state) {
+function projectDeepAgentProtocol(state, declaration = {}) {
   const lane = readDeepAgentProtocol(state);
   if (lane === null) return null;
   return {
     protocolVersion: lane.version,
-    clientVersion: runconfigContract.DEEP_AGENT_PROTOCOL_VERSION
+    clientVersion: declaredDeepAgentProtocolVersion(declaration)
   };
 }
 const seedProtocolLanes = /* @__PURE__ */ new WeakSet();
@@ -31,13 +37,15 @@ function isDeepAgentHostState(state) {
   const lane = state[runconfigContract.DEEP_AGENT_PROTOCOL_STATE_KEY];
   return typeof lane === "object" && lane !== null && readDeepAgentProtocol(state) !== null && !seedProtocolLanes.has(lane);
 }
-function withDeclaredProtocolVersion(headers) {
+function withDeclaredProtocolVersion(headers, declaration = {}) {
   if (runconfigContract.DEEP_AGENT_PROTOCOL_VERSION_HEADER in headers) return headers;
   return {
     ...headers,
-    [runconfigContract.DEEP_AGENT_PROTOCOL_VERSION_HEADER]: String(runconfigContract.DEEP_AGENT_PROTOCOL_VERSION)
+    [runconfigContract.DEEP_AGENT_PROTOCOL_VERSION_HEADER]: String(declaredDeepAgentProtocolVersion(declaration))
   };
 }
+exports.DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION = DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION;
+exports.declaredDeepAgentProtocolVersion = declaredDeepAgentProtocolVersion;
 exports.isDeepAgentHostState = isDeepAgentHostState;
 exports.projectDeepAgentProtocol = projectDeepAgentProtocol;
 exports.readDeepAgentProtocol = readDeepAgentProtocol;

package/dist/agent-runtime/src/protocol.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.cjs","sources":["../../../../agent-runtime/src/protocol.ts"],"sourcesContent":["import {\n  DEEP_AGENT_PROTOCOL_STATE_KEY,\n  DEEP_AGENT_PROTOCOL_VERSION,\n  DEEP_AGENT_PROTOCOL_VERSION_HEADER,\n} from './generated/runconfig-contract';\nimport type { DeepAgentStreamValues } from './types';\n\n/**\n * Wire-contract version declaration between the deep-agent statewire host and\n * this client build (the client half of agora's\n * `agora/graphs/athena_deep_agent/protocol_version.py`; upstream ask\n * assistant-ui/statewire #31506 would make this a library concern).\n *\n * - Declaration: {@link withDeclaredProtocolVersion} stamps the version this\n *   build speaks (`DEEP_AGENT_PROTOCOL_VERSION`, generated from the Python\n *   source of truth) onto the attach headers — they ride the first WS frame's\n *   mandatory `headers` field / the SSE request headers, so no statewire\n *   change is needed. The host records it for attach telemetry and\n *   per-version behaviour selection only.\n * - Advertisement: the host publishes its own `version` under the `protocol`\n *   state key in every attach snapshot; {@link readDeepAgentProtocol} /\n *   {@link projectDeepAgentProtocol} read it.\n *\n * There is no minimum client version: the host refuses no command for the\n * version its client declared (or for declaring none), so nothing here\n * compares versions or gates a send. Hosts still publish a `minClientVersion`\n * key (the constant 1) for installed clients whose lane reader required it;\n * this reader ignores it.\n *\n * Skew-tolerant on both sides: an old server advertises nothing (project\n * `null`, gate nothing), and a malformed lane reads as absent — the\n * declaration must never brick a client that could otherwise talk.\n */\nexport interface DeepAgentWireProtocol {\n  /** The wire-contract version the server speaks. */\n  version: number;\n}\n\n/** The advertised-lane projection a host surface reads. */\nexport interface DeepAgentProtocolStatus {\n  /** Server-advertised current contract version. */\n  protocolVersion: number;\n  /** The contract version THIS client build declares. */\n  clientVersion: number;\n}\n\nconst isContractVersion = (value: unknown): value is number =>\n  typeof value === 'number' && Number.isInteger(value) && value >= 1;\n\n/**\n * The server-advertised version lane off a raw statewire state, or `null`\n * while it is unreadable — pre-attach, a pre-negotiation server's snapshot\n * (no lane), or a malformed lane (tolerated as absent, never thrown on).\n */\nexport function readDeepAgentProtocol(state: unknown): DeepAgentWireProtocol | null {\n  if (typeof state !== 'object' || state === null) return null;\n  const lane = (state as Record<string, unknown>)[DEEP_AGENT_PROTOCOL_STATE_KEY];\n  if (typeof lane !== 'object' || lane === null) return null;\n  const { version } = lane as Record<string, unknown>;\n  if (!isContractVersion(version)) return null;\n  return { version };\n}\n\n/**\n * Project the advertised version for a host surface, or `null` while the\n * server has not advertised (see {@link readDeepAgentProtocol}). Pure and\n * selector-safe, mirroring `readSessionPersisted`.\n */\nexport function projectDeepAgentProtocol(state: unknown): DeepAgentProtocolStatus | null {\n  const lane = readDeepAgentProtocol(state);\n  if (lane === null) return null;\n  return {\n    protocolVersion: lane.version,\n    clientVersion: DEEP_AGENT_PROTOCOL_VERSION,\n  };\n}\n\n/**\n * The protocol lanes seeds carry ({@link withSeedProtocolLane}), by identity.\n * Statewire's optimistic folds are copy-on-write, so every state folded over a\n * seed keeps its lane object, while a state the host sent never holds one\n * (each is parsed off the wire).\n */\nconst seedProtocolLanes = new WeakSet<object>();\n\n/**\n * `state` with a protocol lane of its own, remembered as a seed's — for the\n * remembered states a mount is seeded with (`toThreadSnapshotSeed`), whose\n * lanes are what the host sent an earlier attach. The lane is copied rather\n * than remembered in place, so a live attach still holding the original object\n * is never read as a seed.\n */\nexport function withSeedProtocolLane(state: DeepAgentStreamValues): DeepAgentStreamValues {\n  const lane = state.protocol;\n  if (typeof lane !== 'object' || lane === null) return state;\n  const seeded = { ...lane };\n  seedProtocolLanes.add(seeded);\n  return { ...state, protocol: seeded };\n}\n\n/**\n * Whether `state` is one the host sent on this attach. The host advertises the\n * protocol lane in every attach snapshot and keeps it on every later frame;\n * the states a thread renders before its snapshot carry none (the placeholder\n * an existing thread loads with, and any optimistic fold over it) or a seed's\n * ({@link withSeedProtocolLane}).\n *\n * Decide anything about what the host holds — its config lane above all —\n * from these states only, never from the connection status: on a thread\n * mid-run the channel reports `connected` before the attach snapshot applies,\n * and a placeholder read as the host's says the thread has no config.\n *\n * A host predating the lane (2026-08-28) never answers true; the config lane\n * writes clients make (`config/patch`, 2026-09-05) came after it.\n */\nexport function isDeepAgentHostState(state: unknown): boolean {\n  if (typeof state !== 'object' || state === null) return false;\n  const lane = (state as Record<string, unknown>)[DEEP_AGENT_PROTOCOL_STATE_KEY];\n  return (\n    typeof lane === 'object' &&\n    lane !== null &&\n    readDeepAgentProtocol(state) !== null &&\n    !seedProtocolLanes.has(lane)\n  );\n}\n\n/**\n * Attach headers with this build's contract version declared. Applied by\n * `useDeepAgentThread` to every resolved header set, so all surfaces declare\n * without per-host wiring; an explicit entry (tests, forced overrides) wins.\n */\nexport function withDeclaredProtocolVersion(\n  headers: Record<string, string>\n): Record<string, string> {\n  if (DEEP_AGENT_PROTOCOL_VERSION_HEADER in headers) return headers;\n  return {\n    ...headers,\n    [DEEP_AGENT_PROTOCOL_VERSION_HEADER]: String(DEEP_AGENT_PROTOCOL_VERSION),\n  };\n}\n"],"names":["DEEP_AGENT_PROTOCOL_STATE_KEY","DEEP_AGENT_PROTOCOL_VERSION","DEEP_AGENT_PROTOCOL_VERSION_HEADER"],"mappings":";;;AA8CA,MAAM,oBAAoB,CAAC,UACzB,OAAO,UAAU,YAAY,OAAO,UAAU,KAAK,KAAK,SAAS;AAO5D,SAAS,sBAAsB,OAA8C;AAClF,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAQ,MAAkCA,+CAA6B;AAC7E,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,EAAE,YAAY;AACpB,MAAI,CAAC,kBAAkB,OAAO,EAAG,QAAO;AACxC,SAAO,EAAE,QAAA;AACX;AAOO,SAAS,yBAAyB,OAAgD;AACvF,QAAM,OAAO,sBAAsB,KAAK;AACxC,MAAI,SAAS,KAAM,QAAO;AAC1B,SAAO;AAAA,IACL,iBAAiB,KAAK;AAAA,IACtB,eAAeC,kBAAAA;AAAAA,EAAA;AAEnB;AAQA,MAAM,wCAAwB,QAAA;AASvB,SAAS,qBAAqB,OAAqD;AACxF,QAAM,OAAO,MAAM;AACnB,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,SAAS,EAAE,GAAG,KAAA;AACpB,oBAAkB,IAAI,MAAM;AAC5B,SAAO,EAAE,GAAG,OAAO,UAAU,OAAA;AAC/B;AAiBO,SAAS,qBAAqB,OAAyB;AAC5D,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAQ,MAAkCD,+CAA6B;AAC7E,SACE,OAAO,SAAS,YAChB,SAAS,QACT,sBAAsB,KAAK,MAAM,QACjC,CAAC,kBAAkB,IAAI,IAAI;AAE/B;AAOO,SAAS,4BACd,SACwB;AACxB,MAAIE,kBAAAA,sCAAsC,QAAS,QAAO;AAC1D,SAAO;AAAA,IACL,GAAG;AAAA,IACH,CAACA,kBAAAA,kCAAkC,GAAG,OAAOD,kBAAAA,2BAA2B;AAAA,EAAA;AAE5E;;;;;;"}
+{"version":3,"file":"protocol.cjs","sources":["../../../../agent-runtime/src/protocol.ts"],"sourcesContent":["import {\n  DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION,\n  DEEP_AGENT_PROTOCOL_STATE_KEY,\n  DEEP_AGENT_PROTOCOL_VERSION_HEADER,\n} from './generated/runconfig-contract';\nimport type { DeepAgentStreamValues } from './types';\n\n/**\n * Wire-contract version declaration between the deep-agent statewire host and\n * a client surface (the client half of agora's\n * `agora/graphs/athena_deep_agent/protocol_version.py`; upstream ask\n * assistant-ui/statewire #31506 would make this a library concern).\n *\n * - Declaration: {@link withDeclaredProtocolVersion} stamps the version the\n *   surface declares ({@link declaredDeepAgentProtocolVersion}) onto the\n *   attach headers — they ride the first WS frame's mandatory `headers` field /\n *   the SSE request headers, so no statewire change is needed. The host\n *   records it for attach telemetry and selects per-version behaviour by it.\n * - Advertisement: the host publishes its own `version` under the `protocol`\n *   state key in every attach snapshot; {@link readDeepAgentProtocol} /\n *   {@link projectDeepAgentProtocol} read it.\n *\n * A declared version is a promise the host acts on, not the newest version\n * this build knows (`DEEP_AGENT_PROTOCOL_VERSION`): a host serves a client\n * declaring `DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION` finished subagent lanes cut\n * to their newest steps, trusting it to page the rest. So a surface declares\n * what it implements ({@link DeepAgentProtocolDeclaration}), and a contract\n * bump never changes what a surface promises.\n *\n * There is no minimum client version: the host refuses no command for the\n * version its client declared (or for declaring none), so nothing here\n * compares versions or gates a send. Hosts still publish a `minClientVersion`\n * key (the constant 1) for installed clients whose lane reader required it;\n * this reader ignores it.\n *\n * Skew-tolerant on both sides: an old server advertises nothing (project\n * `null`, gate nothing), and a malformed lane reads as absent — the\n * declaration must never brick a client that could otherwise talk.\n */\nexport interface DeepAgentWireProtocol {\n  /** The wire-contract version the server speaks. */\n  version: number;\n}\n\n/**\n * What a surface implements of the contract, and so may declare on its\n * attaches ({@link declaredDeepAgentProtocolVersion}). Every field is off\n * until the surface ships the capability.\n */\nexport interface DeepAgentProtocolDeclaration {\n  /**\n   * The surface pages a cut lane's earlier steps (`useDeepAgentLaneHistory`\n   * over `history/lane`) wherever it shows a lane's steps. Its attaches then\n   * declare `DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION`, and the host sends a\n   * finished `task` card with a deep nested transcript cut to its newest\n   * steps, as it sends a running one, under the key\n   * `[threadId, \"main\", messageId, \"cut\"]`. Off, finished cards ride whole.\n   */\n  laneHistory?: boolean;\n}\n\n/**\n * The version a surface declares until it pages lanes: the one below the lane\n * cut, the newest contract under which the host sends every finished card\n * whole (the host's version gates are cumulative, `>=`).\n */\nexport const DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION: number =\n  DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION - 1;\n\n/**\n * The contract version a surface's attaches declare: the lane-cut version\n * when it pages lanes, else {@link DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION}.\n * Every attach of one surface — its thread, its pooled prewarm dials, its\n * wakes — declares the same, so a pooled hello is the hello the thread's own\n * attach would get.\n */\nexport function declaredDeepAgentProtocolVersion({\n  laneHistory = false,\n}: DeepAgentProtocolDeclaration = {}): number {\n  return laneHistory\n    ? DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION\n    : DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION;\n}\n\n/** The advertised-lane projection a host surface reads. */\nexport interface DeepAgentProtocolStatus {\n  /** Server-advertised current contract version. */\n  protocolVersion: number;\n  /** The contract version this surface's attach declares ({@link declaredDeepAgentProtocolVersion}). */\n  clientVersion: number;\n}\n\nconst isContractVersion = (value: unknown): value is number =>\n  typeof value === 'number' && Number.isInteger(value) && value >= 1;\n\n/**\n * The server-advertised version lane off a raw statewire state, or `null`\n * while it is unreadable — pre-attach, a pre-negotiation server's snapshot\n * (no lane), or a malformed lane (tolerated as absent, never thrown on).\n */\nexport function readDeepAgentProtocol(state: unknown): DeepAgentWireProtocol | null {\n  if (typeof state !== 'object' || state === null) return null;\n  const lane = (state as Record<string, unknown>)[DEEP_AGENT_PROTOCOL_STATE_KEY];\n  if (typeof lane !== 'object' || lane === null) return null;\n  const { version } = lane as Record<string, unknown>;\n  if (!isContractVersion(version)) return null;\n  return { version };\n}\n\n/**\n * Project the advertised version for a host surface, paired with what the\n * surface declares, or `null` while the server has not advertised (see\n * {@link readDeepAgentProtocol}). Pure and selector-safe, mirroring\n * `readSessionPersisted`.\n */\nexport function projectDeepAgentProtocol(\n  state: unknown,\n  declaration: DeepAgentProtocolDeclaration = {}\n): DeepAgentProtocolStatus | null {\n  const lane = readDeepAgentProtocol(state);\n  if (lane === null) return null;\n  return {\n    protocolVersion: lane.version,\n    clientVersion: declaredDeepAgentProtocolVersion(declaration),\n  };\n}\n\n/**\n * The protocol lanes seeds carry ({@link withSeedProtocolLane}), by identity.\n * Statewire's optimistic folds are copy-on-write, so every state folded over a\n * seed keeps its lane object, while a state the host sent never holds one\n * (each is parsed off the wire).\n */\nconst seedProtocolLanes = new WeakSet<object>();\n\n/**\n * `state` with a protocol lane of its own, remembered as a seed's — for the\n * remembered states a mount is seeded with (`toThreadSnapshotSeed`), whose\n * lanes are what the host sent an earlier attach. The lane is copied rather\n * than remembered in place, so a live attach still holding the original object\n * is never read as a seed.\n */\nexport function withSeedProtocolLane(state: DeepAgentStreamValues): DeepAgentStreamValues {\n  const lane = state.protocol;\n  if (typeof lane !== 'object' || lane === null) return state;\n  const seeded = { ...lane };\n  seedProtocolLanes.add(seeded);\n  return { ...state, protocol: seeded };\n}\n\n/**\n * Whether `state` is one the host sent on this attach. The host advertises the\n * protocol lane in every attach snapshot and keeps it on every later frame;\n * the states a thread renders before its snapshot carry none (the placeholder\n * an existing thread loads with, and any optimistic fold over it) or a seed's\n * ({@link withSeedProtocolLane}).\n *\n * Decide anything about what the host holds — its config lane above all —\n * from these states only, never from the connection status: on a thread\n * mid-run the channel reports `connected` before the attach snapshot applies,\n * and a placeholder read as the host's says the thread has no config.\n *\n * A host predating the lane (2026-08-28) never answers true; the config lane\n * writes clients make (`config/patch`, 2026-09-05) came after it.\n */\nexport function isDeepAgentHostState(state: unknown): boolean {\n  if (typeof state !== 'object' || state === null) return false;\n  const lane = (state as Record<string, unknown>)[DEEP_AGENT_PROTOCOL_STATE_KEY];\n  return (\n    typeof lane === 'object' &&\n    lane !== null &&\n    readDeepAgentProtocol(state) !== null &&\n    !seedProtocolLanes.has(lane)\n  );\n}\n\n/**\n * Attach headers with the surface's contract version declared\n * ({@link declaredDeepAgentProtocolVersion}). Applied by the attach recipe\n * (`createDeepAgentAttachTransport`, `wakeDeepAgentThread`) to every resolved\n * header set, so every surface declares without per-host wiring; an explicit\n * entry (tests, forced overrides) wins.\n */\nexport function withDeclaredProtocolVersion(\n  headers: Record<string, string>,\n  declaration: DeepAgentProtocolDeclaration = {}\n): Record<string, string> {\n  if (DEEP_AGENT_PROTOCOL_VERSION_HEADER in headers) return headers;\n  return {\n    ...headers,\n    [DEEP_AGENT_PROTOCOL_VERSION_HEADER]: String(declaredDeepAgentProtocolVersion(declaration)),\n  };\n}\n"],"names":["DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION","DEEP_AGENT_PROTOCOL_STATE_KEY","DEEP_AGENT_PROTOCOL_VERSION_HEADER"],"mappings":";;;AAkEO,MAAM,6CACXA,kBAAAA,uCAAuC;AASlC,SAAS,iCAAiC;AAAA,EAC/C,cAAc;AAChB,IAAkC,IAAY;AAC5C,SAAO,cACHA,kBAAAA,uCACA;AACN;AAUA,MAAM,oBAAoB,CAAC,UACzB,OAAO,UAAU,YAAY,OAAO,UAAU,KAAK,KAAK,SAAS;AAO5D,SAAS,sBAAsB,OAA8C;AAClF,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAQ,MAAkCC,+CAA6B;AAC7E,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,EAAE,YAAY;AACpB,MAAI,CAAC,kBAAkB,OAAO,EAAG,QAAO;AACxC,SAAO,EAAE,QAAA;AACX;AAQO,SAAS,yBACd,OACA,cAA4C,IACZ;AAChC,QAAM,OAAO,sBAAsB,KAAK;AACxC,MAAI,SAAS,KAAM,QAAO;AAC1B,SAAO;AAAA,IACL,iBAAiB,KAAK;AAAA,IACtB,eAAe,iCAAiC,WAAW;AAAA,EAAA;AAE/D;AAQA,MAAM,wCAAwB,QAAA;AASvB,SAAS,qBAAqB,OAAqD;AACxF,QAAM,OAAO,MAAM;AACnB,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,SAAS,EAAE,GAAG,KAAA;AACpB,oBAAkB,IAAI,MAAM;AAC5B,SAAO,EAAE,GAAG,OAAO,UAAU,OAAA;AAC/B;AAiBO,SAAS,qBAAqB,OAAyB;AAC5D,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAQ,MAAkCA,+CAA6B;AAC7E,SACE,OAAO,SAAS,YAChB,SAAS,QACT,sBAAsB,KAAK,MAAM,QACjC,CAAC,kBAAkB,IAAI,IAAI;AAE/B;AASO,SAAS,4BACd,SACA,cAA4C,IACpB;AACxB,MAAIC,kBAAAA,sCAAsC,QAAS,QAAO;AAC1D,SAAO;AAAA,IACL,GAAG;AAAA,IACH,CAACA,oDAAkC,GAAG,OAAO,iCAAiC,WAAW,CAAC;AAAA,EAAA;AAE9F;;;;;;;;"}

package/dist/agent-runtime/src/protocol.d.ts

@@ -0,0 +1,119 @@
+import type { DeepAgentStreamValues } from './types';
+/**
+ * Wire-contract version declaration between the deep-agent statewire host and
+ * a client surface (the client half of agora's
+ * `agora/graphs/athena_deep_agent/protocol_version.py`; upstream ask
+ * assistant-ui/statewire #31506 would make this a library concern).
+ *
+ * - Declaration: {@link withDeclaredProtocolVersion} stamps the version the
+ *   surface declares ({@link declaredDeepAgentProtocolVersion}) onto the
+ *   attach headers — they ride the first WS frame's mandatory `headers` field /
+ *   the SSE request headers, so no statewire change is needed. The host
+ *   records it for attach telemetry and selects per-version behaviour by it.
+ * - Advertisement: the host publishes its own `version` under the `protocol`
+ *   state key in every attach snapshot; {@link readDeepAgentProtocol} /
+ *   {@link projectDeepAgentProtocol} read it.
+ *
+ * A declared version is a promise the host acts on, not the newest version
+ * this build knows (`DEEP_AGENT_PROTOCOL_VERSION`): a host serves a client
+ * declaring `DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION` finished subagent lanes cut
+ * to their newest steps, trusting it to page the rest. So a surface declares
+ * what it implements ({@link DeepAgentProtocolDeclaration}), and a contract
+ * bump never changes what a surface promises.
+ *
+ * There is no minimum client version: the host refuses no command for the
+ * version its client declared (or for declaring none), so nothing here
+ * compares versions or gates a send. Hosts still publish a `minClientVersion`
+ * key (the constant 1) for installed clients whose lane reader required it;
+ * this reader ignores it.
+ *
+ * Skew-tolerant on both sides: an old server advertises nothing (project
+ * `null`, gate nothing), and a malformed lane reads as absent — the
+ * declaration must never brick a client that could otherwise talk.
+ */
+export interface DeepAgentWireProtocol {
+    /** The wire-contract version the server speaks. */
+    version: number;
+}
+/**
+ * What a surface implements of the contract, and so may declare on its
+ * attaches ({@link declaredDeepAgentProtocolVersion}). Every field is off
+ * until the surface ships the capability.
+ */
+export interface DeepAgentProtocolDeclaration {
+    /**
+     * The surface pages a cut lane's earlier steps (`useDeepAgentLaneHistory`
+     * over `history/lane`) wherever it shows a lane's steps. Its attaches then
+     * declare `DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION`, and the host sends a
+     * finished `task` card with a deep nested transcript cut to its newest
+     * steps, as it sends a running one, under the key
+     * `[threadId, "main", messageId, "cut"]`. Off, finished cards ride whole.
+     */
+    laneHistory?: boolean;
+}
+/**
+ * The version a surface declares until it pages lanes: the one below the lane
+ * cut, the newest contract under which the host sends every finished card
+ * whole (the host's version gates are cumulative, `>=`).
+ */
+export declare const DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION: number;
+/**
+ * The contract version a surface's attaches declare: the lane-cut version
+ * when it pages lanes, else {@link DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION}.
+ * Every attach of one surface — its thread, its pooled prewarm dials, its
+ * wakes — declares the same, so a pooled hello is the hello the thread's own
+ * attach would get.
+ */
+export declare function declaredDeepAgentProtocolVersion({ laneHistory, }?: DeepAgentProtocolDeclaration): number;
+/** The advertised-lane projection a host surface reads. */
+export interface DeepAgentProtocolStatus {
+    /** Server-advertised current contract version. */
+    protocolVersion: number;
+    /** The contract version this surface's attach declares ({@link declaredDeepAgentProtocolVersion}). */
+    clientVersion: number;
+}
+/**
+ * The server-advertised version lane off a raw statewire state, or `null`
+ * while it is unreadable — pre-attach, a pre-negotiation server's snapshot
+ * (no lane), or a malformed lane (tolerated as absent, never thrown on).
+ */
+export declare function readDeepAgentProtocol(state: unknown): DeepAgentWireProtocol | null;
+/**
+ * Project the advertised version for a host surface, paired with what the
+ * surface declares, or `null` while the server has not advertised (see
+ * {@link readDeepAgentProtocol}). Pure and selector-safe, mirroring
+ * `readSessionPersisted`.
+ */
+export declare function projectDeepAgentProtocol(state: unknown, declaration?: DeepAgentProtocolDeclaration): DeepAgentProtocolStatus | null;
+/**
+ * `state` with a protocol lane of its own, remembered as a seed's — for the
+ * remembered states a mount is seeded with (`toThreadSnapshotSeed`), whose
+ * lanes are what the host sent an earlier attach. The lane is copied rather
+ * than remembered in place, so a live attach still holding the original object
+ * is never read as a seed.
+ */
+export declare function withSeedProtocolLane(state: DeepAgentStreamValues): DeepAgentStreamValues;
+/**
+ * Whether `state` is one the host sent on this attach. The host advertises the
+ * protocol lane in every attach snapshot and keeps it on every later frame;
+ * the states a thread renders before its snapshot carry none (the placeholder
+ * an existing thread loads with, and any optimistic fold over it) or a seed's
+ * ({@link withSeedProtocolLane}).
+ *
+ * Decide anything about what the host holds — its config lane above all —
+ * from these states only, never from the connection status: on a thread
+ * mid-run the channel reports `connected` before the attach snapshot applies,
+ * and a placeholder read as the host's says the thread has no config.
+ *
+ * A host predating the lane (2026-08-28) never answers true; the config lane
+ * writes clients make (`config/patch`, 2026-09-05) came after it.
+ */
+export declare function isDeepAgentHostState(state: unknown): boolean;
+/**
+ * Attach headers with the surface's contract version declared
+ * ({@link declaredDeepAgentProtocolVersion}). Applied by the attach recipe
+ * (`createDeepAgentAttachTransport`, `wakeDeepAgentThread`) to every resolved
+ * header set, so every surface declares without per-host wiring; an explicit
+ * entry (tests, forced overrides) wins.
+ */
+export declare function withDeclaredProtocolVersion(headers: Record<string, string>, declaration?: DeepAgentProtocolDeclaration): Record<string, string>;

package/dist/agent-runtime/src/protocol.js

@@ -1,4 +1,10 @@
-import { DEEP_AGENT_PROTOCOL_VERSION, DEEP_AGENT_PROTOCOL_STATE_KEY, DEEP_AGENT_PROTOCOL_VERSION_HEADER } from "./generated/runconfig-contract.js";
+import { DEEP_AGENT_PROTOCOL_STATE_KEY, DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION, DEEP_AGENT_PROTOCOL_VERSION_HEADER } from "./generated/runconfig-contract.js";
+const DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION = DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION - 1;
+function declaredDeepAgentProtocolVersion({
+  laneHistory = false
+} = {}) {
+  return laneHistory ? DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION : DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION;
+}
 const isContractVersion = (value) => typeof value === "number" && Number.isInteger(value) && value >= 1;
 function readDeepAgentProtocol(state) {
   if (typeof state !== "object" || state === null) return null;
@@ -8,12 +14,12 @@ function readDeepAgentProtocol(state) {
   if (!isContractVersion(version)) return null;
   return { version };
 }
-function projectDeepAgentProtocol(state) {
+function projectDeepAgentProtocol(state, declaration = {}) {
   const lane = readDeepAgentProtocol(state);
   if (lane === null) return null;
   return {
     protocolVersion: lane.version,
-    clientVersion: DEEP_AGENT_PROTOCOL_VERSION
+    clientVersion: declaredDeepAgentProtocolVersion(declaration)
   };
 }
 const seedProtocolLanes = /* @__PURE__ */ new WeakSet();
@@ -29,14 +35,16 @@ function isDeepAgentHostState(state) {
   const lane = state[DEEP_AGENT_PROTOCOL_STATE_KEY];
   return typeof lane === "object" && lane !== null && readDeepAgentProtocol(state) !== null && !seedProtocolLanes.has(lane);
 }
-function withDeclaredProtocolVersion(headers) {
+function withDeclaredProtocolVersion(headers, declaration = {}) {
   if (DEEP_AGENT_PROTOCOL_VERSION_HEADER in headers) return headers;
   return {
     ...headers,
-    [DEEP_AGENT_PROTOCOL_VERSION_HEADER]: String(DEEP_AGENT_PROTOCOL_VERSION)
+    [DEEP_AGENT_PROTOCOL_VERSION_HEADER]: String(declaredDeepAgentProtocolVersion(declaration))
   };
 }
 export {
+  DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION,
+  declaredDeepAgentProtocolVersion,
   isDeepAgentHostState,
   projectDeepAgentProtocol,
   readDeepAgentProtocol,

package/dist/agent-runtime/src/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sources":["../../../../agent-runtime/src/protocol.ts"],"sourcesContent":["import {\n  DEEP_AGENT_PROTOCOL_STATE_KEY,\n  DEEP_AGENT_PROTOCOL_VERSION,\n  DEEP_AGENT_PROTOCOL_VERSION_HEADER,\n} from './generated/runconfig-contract';\nimport type { DeepAgentStreamValues } from './types';\n\n/**\n * Wire-contract version declaration between the deep-agent statewire host and\n * this client build (the client half of agora's\n * `agora/graphs/athena_deep_agent/protocol_version.py`; upstream ask\n * assistant-ui/statewire #31506 would make this a library concern).\n *\n * - Declaration: {@link withDeclaredProtocolVersion} stamps the version this\n *   build speaks (`DEEP_AGENT_PROTOCOL_VERSION`, generated from the Python\n *   source of truth) onto the attach headers — they ride the first WS frame's\n *   mandatory `headers` field / the SSE request headers, so no statewire\n *   change is needed. The host records it for attach telemetry and\n *   per-version behaviour selection only.\n * - Advertisement: the host publishes its own `version` under the `protocol`\n *   state key in every attach snapshot; {@link readDeepAgentProtocol} /\n *   {@link projectDeepAgentProtocol} read it.\n *\n * There is no minimum client version: the host refuses no command for the\n * version its client declared (or for declaring none), so nothing here\n * compares versions or gates a send. Hosts still publish a `minClientVersion`\n * key (the constant 1) for installed clients whose lane reader required it;\n * this reader ignores it.\n *\n * Skew-tolerant on both sides: an old server advertises nothing (project\n * `null`, gate nothing), and a malformed lane reads as absent — the\n * declaration must never brick a client that could otherwise talk.\n */\nexport interface DeepAgentWireProtocol {\n  /** The wire-contract version the server speaks. */\n  version: number;\n}\n\n/** The advertised-lane projection a host surface reads. */\nexport interface DeepAgentProtocolStatus {\n  /** Server-advertised current contract version. */\n  protocolVersion: number;\n  /** The contract version THIS client build declares. */\n  clientVersion: number;\n}\n\nconst isContractVersion = (value: unknown): value is number =>\n  typeof value === 'number' && Number.isInteger(value) && value >= 1;\n\n/**\n * The server-advertised version lane off a raw statewire state, or `null`\n * while it is unreadable — pre-attach, a pre-negotiation server's snapshot\n * (no lane), or a malformed lane (tolerated as absent, never thrown on).\n */\nexport function readDeepAgentProtocol(state: unknown): DeepAgentWireProtocol | null {\n  if (typeof state !== 'object' || state === null) return null;\n  const lane = (state as Record<string, unknown>)[DEEP_AGENT_PROTOCOL_STATE_KEY];\n  if (typeof lane !== 'object' || lane === null) return null;\n  const { version } = lane as Record<string, unknown>;\n  if (!isContractVersion(version)) return null;\n  return { version };\n}\n\n/**\n * Project the advertised version for a host surface, or `null` while the\n * server has not advertised (see {@link readDeepAgentProtocol}). Pure and\n * selector-safe, mirroring `readSessionPersisted`.\n */\nexport function projectDeepAgentProtocol(state: unknown): DeepAgentProtocolStatus | null {\n  const lane = readDeepAgentProtocol(state);\n  if (lane === null) return null;\n  return {\n    protocolVersion: lane.version,\n    clientVersion: DEEP_AGENT_PROTOCOL_VERSION,\n  };\n}\n\n/**\n * The protocol lanes seeds carry ({@link withSeedProtocolLane}), by identity.\n * Statewire's optimistic folds are copy-on-write, so every state folded over a\n * seed keeps its lane object, while a state the host sent never holds one\n * (each is parsed off the wire).\n */\nconst seedProtocolLanes = new WeakSet<object>();\n\n/**\n * `state` with a protocol lane of its own, remembered as a seed's — for the\n * remembered states a mount is seeded with (`toThreadSnapshotSeed`), whose\n * lanes are what the host sent an earlier attach. The lane is copied rather\n * than remembered in place, so a live attach still holding the original object\n * is never read as a seed.\n */\nexport function withSeedProtocolLane(state: DeepAgentStreamValues): DeepAgentStreamValues {\n  const lane = state.protocol;\n  if (typeof lane !== 'object' || lane === null) return state;\n  const seeded = { ...lane };\n  seedProtocolLanes.add(seeded);\n  return { ...state, protocol: seeded };\n}\n\n/**\n * Whether `state` is one the host sent on this attach. The host advertises the\n * protocol lane in every attach snapshot and keeps it on every later frame;\n * the states a thread renders before its snapshot carry none (the placeholder\n * an existing thread loads with, and any optimistic fold over it) or a seed's\n * ({@link withSeedProtocolLane}).\n *\n * Decide anything about what the host holds — its config lane above all —\n * from these states only, never from the connection status: on a thread\n * mid-run the channel reports `connected` before the attach snapshot applies,\n * and a placeholder read as the host's says the thread has no config.\n *\n * A host predating the lane (2026-08-28) never answers true; the config lane\n * writes clients make (`config/patch`, 2026-09-05) came after it.\n */\nexport function isDeepAgentHostState(state: unknown): boolean {\n  if (typeof state !== 'object' || state === null) return false;\n  const lane = (state as Record<string, unknown>)[DEEP_AGENT_PROTOCOL_STATE_KEY];\n  return (\n    typeof lane === 'object' &&\n    lane !== null &&\n    readDeepAgentProtocol(state) !== null &&\n    !seedProtocolLanes.has(lane)\n  );\n}\n\n/**\n * Attach headers with this build's contract version declared. Applied by\n * `useDeepAgentThread` to every resolved header set, so all surfaces declare\n * without per-host wiring; an explicit entry (tests, forced overrides) wins.\n */\nexport function withDeclaredProtocolVersion(\n  headers: Record<string, string>\n): Record<string, string> {\n  if (DEEP_AGENT_PROTOCOL_VERSION_HEADER in headers) return headers;\n  return {\n    ...headers,\n    [DEEP_AGENT_PROTOCOL_VERSION_HEADER]: String(DEEP_AGENT_PROTOCOL_VERSION),\n  };\n}\n"],"names":[],"mappings":";AA8CA,MAAM,oBAAoB,CAAC,UACzB,OAAO,UAAU,YAAY,OAAO,UAAU,KAAK,KAAK,SAAS;AAO5D,SAAS,sBAAsB,OAA8C;AAClF,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAQ,MAAkC,6BAA6B;AAC7E,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,EAAE,YAAY;AACpB,MAAI,CAAC,kBAAkB,OAAO,EAAG,QAAO;AACxC,SAAO,EAAE,QAAA;AACX;AAOO,SAAS,yBAAyB,OAAgD;AACvF,QAAM,OAAO,sBAAsB,KAAK;AACxC,MAAI,SAAS,KAAM,QAAO;AAC1B,SAAO;AAAA,IACL,iBAAiB,KAAK;AAAA,IACtB,eAAe;AAAA,EAAA;AAEnB;AAQA,MAAM,wCAAwB,QAAA;AASvB,SAAS,qBAAqB,OAAqD;AACxF,QAAM,OAAO,MAAM;AACnB,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,SAAS,EAAE,GAAG,KAAA;AACpB,oBAAkB,IAAI,MAAM;AAC5B,SAAO,EAAE,GAAG,OAAO,UAAU,OAAA;AAC/B;AAiBO,SAAS,qBAAqB,OAAyB;AAC5D,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAQ,MAAkC,6BAA6B;AAC7E,SACE,OAAO,SAAS,YAChB,SAAS,QACT,sBAAsB,KAAK,MAAM,QACjC,CAAC,kBAAkB,IAAI,IAAI;AAE/B;AAOO,SAAS,4BACd,SACwB;AACxB,MAAI,sCAAsC,QAAS,QAAO;AAC1D,SAAO;AAAA,IACL,GAAG;AAAA,IACH,CAAC,kCAAkC,GAAG,OAAO,2BAA2B;AAAA,EAAA;AAE5E;"}
+{"version":3,"file":"protocol.js","sources":["../../../../agent-runtime/src/protocol.ts"],"sourcesContent":["import {\n  DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION,\n  DEEP_AGENT_PROTOCOL_STATE_KEY,\n  DEEP_AGENT_PROTOCOL_VERSION_HEADER,\n} from './generated/runconfig-contract';\nimport type { DeepAgentStreamValues } from './types';\n\n/**\n * Wire-contract version declaration between the deep-agent statewire host and\n * a client surface (the client half of agora's\n * `agora/graphs/athena_deep_agent/protocol_version.py`; upstream ask\n * assistant-ui/statewire #31506 would make this a library concern).\n *\n * - Declaration: {@link withDeclaredProtocolVersion} stamps the version the\n *   surface declares ({@link declaredDeepAgentProtocolVersion}) onto the\n *   attach headers — they ride the first WS frame's mandatory `headers` field /\n *   the SSE request headers, so no statewire change is needed. The host\n *   records it for attach telemetry and selects per-version behaviour by it.\n * - Advertisement: the host publishes its own `version` under the `protocol`\n *   state key in every attach snapshot; {@link readDeepAgentProtocol} /\n *   {@link projectDeepAgentProtocol} read it.\n *\n * A declared version is a promise the host acts on, not the newest version\n * this build knows (`DEEP_AGENT_PROTOCOL_VERSION`): a host serves a client\n * declaring `DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION` finished subagent lanes cut\n * to their newest steps, trusting it to page the rest. So a surface declares\n * what it implements ({@link DeepAgentProtocolDeclaration}), and a contract\n * bump never changes what a surface promises.\n *\n * There is no minimum client version: the host refuses no command for the\n * version its client declared (or for declaring none), so nothing here\n * compares versions or gates a send. Hosts still publish a `minClientVersion`\n * key (the constant 1) for installed clients whose lane reader required it;\n * this reader ignores it.\n *\n * Skew-tolerant on both sides: an old server advertises nothing (project\n * `null`, gate nothing), and a malformed lane reads as absent — the\n * declaration must never brick a client that could otherwise talk.\n */\nexport interface DeepAgentWireProtocol {\n  /** The wire-contract version the server speaks. */\n  version: number;\n}\n\n/**\n * What a surface implements of the contract, and so may declare on its\n * attaches ({@link declaredDeepAgentProtocolVersion}). Every field is off\n * until the surface ships the capability.\n */\nexport interface DeepAgentProtocolDeclaration {\n  /**\n   * The surface pages a cut lane's earlier steps (`useDeepAgentLaneHistory`\n   * over `history/lane`) wherever it shows a lane's steps. Its attaches then\n   * declare `DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION`, and the host sends a\n   * finished `task` card with a deep nested transcript cut to its newest\n   * steps, as it sends a running one, under the key\n   * `[threadId, \"main\", messageId, \"cut\"]`. Off, finished cards ride whole.\n   */\n  laneHistory?: boolean;\n}\n\n/**\n * The version a surface declares until it pages lanes: the one below the lane\n * cut, the newest contract under which the host sends every finished card\n * whole (the host's version gates are cumulative, `>=`).\n */\nexport const DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION: number =\n  DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION - 1;\n\n/**\n * The contract version a surface's attaches declare: the lane-cut version\n * when it pages lanes, else {@link DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION}.\n * Every attach of one surface — its thread, its pooled prewarm dials, its\n * wakes — declares the same, so a pooled hello is the hello the thread's own\n * attach would get.\n */\nexport function declaredDeepAgentProtocolVersion({\n  laneHistory = false,\n}: DeepAgentProtocolDeclaration = {}): number {\n  return laneHistory\n    ? DEEP_AGENT_LANE_CUT_PROTOCOL_VERSION\n    : DEEP_AGENT_DEFAULT_CLIENT_PROTOCOL_VERSION;\n}\n\n/** The advertised-lane projection a host surface reads. */\nexport interface DeepAgentProtocolStatus {\n  /** Server-advertised current contract version. */\n  protocolVersion: number;\n  /** The contract version this surface's attach declares ({@link declaredDeepAgentProtocolVersion}). */\n  clientVersion: number;\n}\n\nconst isContractVersion = (value: unknown): value is number =>\n  typeof value === 'number' && Number.isInteger(value) && value >= 1;\n\n/**\n * The server-advertised version lane off a raw statewire state, or `null`\n * while it is unreadable — pre-attach, a pre-negotiation server's snapshot\n * (no lane), or a malformed lane (tolerated as absent, never thrown on).\n */\nexport function readDeepAgentProtocol(state: unknown): DeepAgentWireProtocol | null {\n  if (typeof state !== 'object' || state === null) return null;\n  const lane = (state as Record<string, unknown>)[DEEP_AGENT_PROTOCOL_STATE_KEY];\n  if (typeof lane !== 'object' || lane === null) return null;\n  const { version } = lane as Record<string, unknown>;\n  if (!isContractVersion(version)) return null;\n  return { version };\n}\n\n/**\n * Project the advertised version for a host surface, paired with what the\n * surface declares, or `null` while the server has not advertised (see\n * {@link readDeepAgentProtocol}). Pure and selector-safe, mirroring\n * `readSessionPersisted`.\n */\nexport function projectDeepAgentProtocol(\n  state: unknown,\n  declaration: DeepAgentProtocolDeclaration = {}\n): DeepAgentProtocolStatus | null {\n  const lane = readDeepAgentProtocol(state);\n  if (lane === null) return null;\n  return {\n    protocolVersion: lane.version,\n    clientVersion: declaredDeepAgentProtocolVersion(declaration),\n  };\n}\n\n/**\n * The protocol lanes seeds carry ({@link withSeedProtocolLane}), by identity.\n * Statewire's optimistic folds are copy-on-write, so every state folded over a\n * seed keeps its lane object, while a state the host sent never holds one\n * (each is parsed off the wire).\n */\nconst seedProtocolLanes = new WeakSet<object>();\n\n/**\n * `state` with a protocol lane of its own, remembered as a seed's — for the\n * remembered states a mount is seeded with (`toThreadSnapshotSeed`), whose\n * lanes are what the host sent an earlier attach. The lane is copied rather\n * than remembered in place, so a live attach still holding the original object\n * is never read as a seed.\n */\nexport function withSeedProtocolLane(state: DeepAgentStreamValues): DeepAgentStreamValues {\n  const lane = state.protocol;\n  if (typeof lane !== 'object' || lane === null) return state;\n  const seeded = { ...lane };\n  seedProtocolLanes.add(seeded);\n  return { ...state, protocol: seeded };\n}\n\n/**\n * Whether `state` is one the host sent on this attach. The host advertises the\n * protocol lane in every attach snapshot and keeps it on every later frame;\n * the states a thread renders before its snapshot carry none (the placeholder\n * an existing thread loads with, and any optimistic fold over it) or a seed's\n * ({@link withSeedProtocolLane}).\n *\n * Decide anything about what the host holds — its config lane above all —\n * from these states only, never from the connection status: on a thread\n * mid-run the channel reports `connected` before the attach snapshot applies,\n * and a placeholder read as the host's says the thread has no config.\n *\n * A host predating the lane (2026-08-28) never answers true; the config lane\n * writes clients make (`config/patch`, 2026-09-05) came after it.\n */\nexport function isDeepAgentHostState(state: unknown): boolean {\n  if (typeof state !== 'object' || state === null) return false;\n  const lane = (state as Record<string, unknown>)[DEEP_AGENT_PROTOCOL_STATE_KEY];\n  return (\n    typeof lane === 'object' &&\n    lane !== null &&\n    readDeepAgentProtocol(state) !== null &&\n    !seedProtocolLanes.has(lane)\n  );\n}\n\n/**\n * Attach headers with the surface's contract version declared\n * ({@link declaredDeepAgentProtocolVersion}). Applied by the attach recipe\n * (`createDeepAgentAttachTransport`, `wakeDeepAgentThread`) to every resolved\n * header set, so every surface declares without per-host wiring; an explicit\n * entry (tests, forced overrides) wins.\n */\nexport function withDeclaredProtocolVersion(\n  headers: Record<string, string>,\n  declaration: DeepAgentProtocolDeclaration = {}\n): Record<string, string> {\n  if (DEEP_AGENT_PROTOCOL_VERSION_HEADER in headers) return headers;\n  return {\n    ...headers,\n    [DEEP_AGENT_PROTOCOL_VERSION_HEADER]: String(declaredDeepAgentProtocolVersion(declaration)),\n  };\n}\n"],"names":[],"mappings":";AAkEO,MAAM,6CACX,uCAAuC;AASlC,SAAS,iCAAiC;AAAA,EAC/C,cAAc;AAChB,IAAkC,IAAY;AAC5C,SAAO,cACH,uCACA;AACN;AAUA,MAAM,oBAAoB,CAAC,UACzB,OAAO,UAAU,YAAY,OAAO,UAAU,KAAK,KAAK,SAAS;AAO5D,SAAS,sBAAsB,OAA8C;AAClF,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAQ,MAAkC,6BAA6B;AAC7E,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,EAAE,YAAY;AACpB,MAAI,CAAC,kBAAkB,OAAO,EAAG,QAAO;AACxC,SAAO,EAAE,QAAA;AACX;AAQO,SAAS,yBACd,OACA,cAA4C,IACZ;AAChC,QAAM,OAAO,sBAAsB,KAAK;AACxC,MAAI,SAAS,KAAM,QAAO;AAC1B,SAAO;AAAA,IACL,iBAAiB,KAAK;AAAA,IACtB,eAAe,iCAAiC,WAAW;AAAA,EAAA;AAE/D;AAQA,MAAM,wCAAwB,QAAA;AASvB,SAAS,qBAAqB,OAAqD;AACxF,QAAM,OAAO,MAAM;AACnB,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,SAAS,EAAE,GAAG,KAAA;AACpB,oBAAkB,IAAI,MAAM;AAC5B,SAAO,EAAE,GAAG,OAAO,UAAU,OAAA;AAC/B;AAiBO,SAAS,qBAAqB,OAAyB;AAC5D,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAQ,MAAkC,6BAA6B;AAC7E,SACE,OAAO,SAAS,YAChB,SAAS,QACT,sBAAsB,KAAK,MAAM,QACjC,CAAC,kBAAkB,IAAI,IAAI;AAE/B;AASO,SAAS,4BACd,SACA,cAA4C,IACpB;AACxB,MAAI,sCAAsC,QAAS,QAAO;AAC1D,SAAO;AAAA,IACL,GAAG;AAAA,IACH,CAAC,kCAAkC,GAAG,OAAO,iCAAiC,WAAW,CAAC;AAAA,EAAA;AAE9F;"}

package/dist/agent-runtime/src/ptc-subcalls.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Programmatic-tool-calling (PTC) sub-call parsing — the SDK method calls a
+ * sandbox `execute` / interpreter `eval` recorded, promoted by the backend onto
+ * the parent ToolMessage's artifact (`promote_artifact_with_ptc_subcalls`
+ * shape: one AIMessage carrying every call, then one ToolMessage per settled
+ * call). Pure parsing shared by the nested tool cards and the studio
+ * follow-along; React selectors over these live with each runtime host.
+ */
+import type { LangChainMessage } from '@assistant-ui/react-langgraph';
+/**
+ * One SDK sub-call recorded under a sandbox `execute` (or interpreter `eval`)
+ * tool call — an Athena SDK method call (e.g. `Presentation.create`) the
+ * backend's PTC display channel captured and promoted onto the parent
+ * ToolMessage's `artifact.subgraph_state.messages`.
+ */
+export interface PtcSubcall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    status: 'in_flight' | 'completed' | 'error';
+    /** The settled call's parsed result payload (`undefined` while in flight). */
+    result: unknown;
+    /** The settled call's result text ('' while in flight). */
+    resultText: string;
+}
+/** Parse the PTC sub-call list from a parent ToolMessage's promoted artifact. */
+export declare function ptcSubcallsFromArtifact(artifact: unknown): PtcSubcall[];
+/** One completed PTC parent (`execute`, `eval`, or a studio executor) carrying recorded sub-calls. */
+export interface CompletedPtcParent {
+    toolCallId: string;
+    /** The parent tool's name, one of `PTC_PARENT_TOOL_NAMES`. */
+    toolName: string;
+    /**
+     * The executor source the call ran (`eval`'s `code` arg), read off the AI
+     * message that requested it. The studio SDKs emit no cell-level sub-calls,
+     * so the code string is the only carrier of the written spreadsheet cell.
+     */
+    code: string | undefined;
+    /** Shape `computeStudioFollowTarget` expects: `{ artifact, result }`. */
+    rawResult: {
+        artifact: unknown;
+        result: unknown;
+    };
+}
+/**
+ * Every completed `execute`/`eval` ToolMessage carrying recorded PTC
+ * sub-calls, from the raw transport messages — including the ones a subagent
+ * ran inside a `task` call's nested transcript. Drives the deep-agent's studio
+ * follow-along (`DeepAgentPtcStudioFollowObserver`).
+ */
+export declare function extractCompletedPtcParents(messages: readonly LangChainMessage[]): CompletedPtcParent[];

package/dist/agent-runtime/src/queue.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Derivations for the server-owned statewire queue and steer lanes, shared by
+ * every queued-messages tray (Olympus, the React SDK, the Chrome extension).
+ *
+ * The queue is SERVER-owned: statewire surfaces it on the runs projection.
+ * "Send now" moves an item into the steer lane (`run/steer` — the host stops
+ * the run and dispatches it once the run settles; on a stopped/errored thread
+ * the same move dispatches immediately as a stop-/error-continue run) and
+ * remove issues `run/dequeue`. While the thread rests stopped/errored,
+ * stranded steer-lane entries list ahead of the queue — they dispatch first,
+ * as one batch, so they carry Remove but no per-row Send now.
+ *
+ * Pure helpers only: the host component reads `useStatewireRuns()` and
+ * `useDeepAgentThreadStatus()` itself (both mockable per surface) and passes
+ * the values in.
+ */
+import type { StatewireThread } from '@assistant-ui/react-statewire';
+import type { DeepAgentThreadStatus } from './thread-status';
+/** The text content of a queued entry (non-text parts render as fallbacks). */
+export declare function queueEntryText(parts: readonly {
+    type: string;
+    text?: string;
+}[]): string;
+/**
+ * Whether a lane entry is still awaiting its send's settle: the host stamps
+ * `meta` on every entry it admits (`_op_meta` — submitter and contextSync
+ * snapshot), so a meta-less entry is this client's own optimistic fold. The
+ * send is still in flight and can still be refused (billing gate, auth,
+ * reconnect), which the tray must not render as an accepted queue position.
+ */
+export declare function isQueueEntryUnsettled(entry: StatewireThread.RunsQueueEntry): boolean;
+/**
+ * The ids of queued entries the user prioritized (⚡ — `run/prioritize`), as
+ * the host records them in its durable `prioritizedQueueIds` state. A
+ * prioritized entry heads the queue lane and the live run ends at its next
+ * model-call boundary to deliver it, so trays render these rows lit and offer
+ * "Remove priority" instead of "Prioritize". Tolerates the key being absent
+ * (a thread that never prioritized, a pre-feature host) and ignores anything
+ * that is not a string id.
+ */
+export declare function readPrioritizedQueueIds(raw: unknown): readonly string[];
+export interface QueueLaneFlags {
+    isRunning: boolean;
+    /** A stopped/errored thread can continue with its queued work. */
+    isContinuable: boolean;
+}
+/** The thread-status split every queue tray keys its affordances on. */
+export declare function queueLaneFlags(status: DeepAgentThreadStatus): QueueLaneFlags;
+export interface StatewireQueueRow {
+    item: StatewireThread.RunsQueueEntry;
+    lane: 'queue' | 'steer';
+}
+/**
+ * The rows a queue tray renders, in dispatch order: stranded steer-lane
+ * entries first (only while the thread rests continuable — during a run they
+ * already render in the message list), then the queue lane.
+ */
+export declare function buildStatewireQueueRows(options: {
+    queue: readonly StatewireThread.RunsQueueEntry[];
+    steerQueue: readonly StatewireThread.RunsQueueEntry[];
+    isContinuable: boolean;
+}): StatewireQueueRow[];
+/**
+ * Whether a row offers "Send now": queue-lane rows only (steer entries already
+ * dispatch first), every row while the thread rests continuable, and only the
+ * head row while a run is live (later rows would jump the queue order).
+ */
+export declare function showQueueRowSendNow(options: {
+    lane: 'queue' | 'steer';
+    index: number;
+    isRunning: boolean;
+    isContinuable: boolean;
+}): boolean;
+/**
+ * Whether a row offers "Steer" (`run/steer-live`): queue-lane rows while a run
+ * is live. Steer folds the entry into the RUNNING turn at its next model call
+ * — after the in-flight tool chain, never mid-tool — and the run goes on with
+ * it in context (ChatGPT's and Codex's Steer, versus Queue). Nothing is
+ * cancelled and no second run starts, so every queued row qualifies, not just
+ * the head. At rest there is no turn to steer: Send now already dispatches.
+ */
+export declare function showQueueRowSteer(options: {
+    lane: 'queue' | 'steer';
+    isRunning: boolean;
+}): boolean;
+export type QueueEditCommand = {
+    type: 'run/steer';
+    runId: string;
+    message: StatewireThread.UserMessage;
+} | {
+    type: 'run/enqueue';
+    runId: string;
+    message: StatewireThread.UserMessage;
+};
+/**
+ * Re-send a queued entry under its own id on its own lane with edited text:
+ * the host replaces the queued message's content in place, leaving its queue
+ * position and lane untouched (a same-id send never dispatches). The built-in
+ * queue client has no update command, so this goes straight to the runs
+ * protocol. Returns `null` when there is nothing to send — blank or unchanged
+ * text, or no live run entry to address.
+ */
+export declare function buildQueueEditCommand(options: {
+    item: StatewireThread.RunsQueueEntry;
+    lane: 'queue' | 'steer';
+    runId: string | null;
+    text: string;
+    /**
+     * The edited message's metadata, replacing the entry's (the host replaces
+     * the queued message whole). Omitted, the entry's metadata is kept, minus a
+     * composer markdown that described the old text.
+     */
+    metadata?: Readonly<Record<string, unknown>> | undefined;
+}): QueueEditCommand | null;
+/**
+ * Grace between observing a stranded settle and auto-promoting the queue
+ * head — long enough for the host's own settle bookkeeping (or a status flap
+ * during reconnect) to resolve first, short enough to read as "it just
+ * continued" rather than "it hung".
+ */
+export declare const QUEUE_AUTO_CONTINUE_DELAY_MS = 2000;
+/** Whether the last cancellation marker records a user or client stop. */
+export declare function userStopBlocksQueueAutoContinue(options: {
+    marker: string | undefined;
+    source: string | undefined;
+}): boolean;
+/** `fate (cause)[: message]` — the detail a failed-send row carries. */
+export declare function describeQueueSendFailure(failure: StatewireThread.RunsFailedEntry['sendFailure']): string;
+/**
+ * Whether a `retryFailed` / `discardFailed` throw is the covered drop race:
+ * statewire drops a failed entry on its own as soon as a canonical update
+ * shows the message landed, and acting on a just-dropped entry throws. Both
+ * the session record ("unknown failed command") and the adapter's projection
+ * ("unknown failed entry") use this prefix. Nothing is lost in that race — the
+ * message already made it and the row is about to disappear — so a tray
+ * swallows it (keeping telemetry) instead of crashing the click handler.
+ */
+export declare function isFailedSendEntryRace(error: unknown): boolean;

package/dist/agent-runtime/src/quota-safe-local-storage-session.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const tap = require("@assistant-ui/tap");
 const storage = require("statewire/storage");
 const react = require("react");
+const sessionLaneScope = require("./session-lane-scope.cjs");
 const statewireTransport = require("./statewire-transport.cjs");
 const SESSION_PREFIX = "aui:statewire-session:";
 const SESSION_LOCK_PREFIX = "aui:statewire-session-lock:";
@@ -320,6 +321,15 @@ const useQuotaSafeLocalStorageSession = ({
   const sessionKey = key(threadId);
   const storageKey = SESSION_PREFIX + sessionKey;
   const lockName = SESSION_LOCK_PREFIX + sessionKey;
+  const mountedScope = react.useRef({
+    threadId,
+    laneKey: sessionKey
+  });
+  if (!sessionLaneScope.isSameSessionLaneScope({ scope: mountedScope.current, key })) {
+    throw new Error(
+      "statewire: principal changed; remount the account's thread/session"
+    );
+  }
   const latestOnDegraded = react.useRef(onStorageDegraded);
   latestOnDegraded.current = onStorageDegraded;
   const reportDegradation = react.useMemo(() => {