@athenaintel/react 0.41.3 → 0.42.1

package/dist/agent-runtime/src/offline-status.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Athena's offline language: the one set of states and words every app uses to
+ * say where the person stands when the network, or Athena, is out of reach —
+ * Olympus, the desktop app, the phone app, the Chrome extension and the Office
+ * add-in.
+ *
+ * The rule the words follow: say what still works before what doesn't. Work
+ * done while Athena can't be reached is kept on the device and syncs when
+ * Athena is back, so every message leads with that promise. Nothing here is
+ * shown while Athena answers and nothing waits; the "back" messages are brief.
+ *
+ * Pure strings and small functions, no UI library: each app draws them its own
+ * way (a banner, a header chip, a tooltip, a sheet). Reachability itself is
+ * each app's own (the browser's or OS's online flag AND agora answering its
+ * health read); this module only names the result.
+ */
+/** Where the app stands with Athena. */
+export type ConnectionState = 
+/** Athena answers. Nothing is shown. */
+'online'
+/** The device has no network. */
+ | 'offline'
+/** The network is up but Athena doesn't answer. */
+ | 'unreachable'
+/** Athena answers again and what waited is being sent. */
+ | 'reconnecting'
+/** Just back, and everything that waited was sent. Shown briefly. */
+ | 'synced';
+/** Where one document's edits stand, for the chip in its header. */
+export type DocumentSyncState = 
+/** In Athena. */
+'saved'
+/** Being sent to Athena. */
+ | 'saving'
+/** Kept on this device while Athena can't be reached; syncs when it is back. */
+ | 'on-device'
+/** Kept only while this tab or app stays open (no device storage); syncs when Athena is back. */
+ | 'in-memory'
+/** Sending what was kept on this device. */
+ | 'syncing'
+/** Some changes overlap with Athena's version: the person chooses. */
+ | 'needs-review'
+/** The document can no longer take these edits (access or state changed): kept, not sent. */
+ | 'view-only';
+/** How a sentence names the device the person is on. */
+export type DeviceNoun = 'this browser' | 'this Mac' | 'this computer' | 'this phone' | 'this tablet' | 'this device';
+/**
+ * What the app really keeps of work done while Athena can't be reached, so the
+ * words never promise more: `device` (stored on the device, survives closing),
+ * `memory` (kept only while this tab or app stays open: a tenant that turns
+ * device copies off, or storage the app can't open), `none` (a surface that
+ * keeps no work offline at all, like the Chrome side panel).
+ */
+export type OfflineKeeping = 'device' | 'memory' | 'none';
+/** A title and the one line under it (a banner, a sheet, a tooltip's heading). */
+export interface StatusCopy {
+    title: string;
+    detail: string;
+}
+/** A short label for a chip or a disabled control, and its one-line explanation. */
+export interface LabelCopy {
+    label: string;
+    detail: string;
+}
+/**
+ * The app-wide status line, or `null` while Athena answers and nothing waits.
+ * `waiting` counts changes not in Athena yet: while `reconnecting` they are
+ * being sent; while `online` they wait for something else (a copy that sends
+ * when it is next opened), and the line stays until they are gone.
+ * `keeping` is what the app really keeps offline (default `device`). A surface
+ * that keeps nothing (`none`) has nothing to sync, so its way back is only
+ * "Back online", never "Syncing…" or "All changes synced".
+ */
+export declare function connectionCopy({ state, device, waiting, keeping, }: {
+    state: ConnectionState;
+    device: DeviceNoun;
+    waiting?: number;
+    keeping?: OfflineKeeping;
+}): StatusCopy | null;
+/** The chip in a document's header, and the line it explains itself with. */
+export declare function documentSyncCopy({ state, device, }: {
+    state: DocumentSyncState;
+    device: DeviceNoun;
+}): LabelCopy;
+/**
+ * The reason on a control that needs Athena (share, run, upload, invite…),
+ * shown disabled while Athena can't be reached rather than failing when used.
+ */
+export declare const NEEDS_CONNECTION: LabelCopy;
+/**
+ * Whether an item opens without a connection on this device, for lists.
+ * `canKeep` says whether opening it online would keep a copy here (the
+ * deployment allows device copies and the item's type is one that is kept):
+ * only then is the person told to open it once.
+ */
+export declare function offlineAvailabilityCopy({ available, canKeep, device, }: {
+    available: boolean;
+    canKeep: boolean;
+    device: DeviceNoun;
+}): LabelCopy;
+/**
+ * The one-time explainer shown the first time the person goes offline, on a
+ * surface that keeps work there (`keeping` `device`). A surface that keeps
+ * nothing (`none`: the Chrome side panel, the Office task pane) shows no
+ * explainer; its status line already says all that holds.
+ */
+export declare function firstOfflineExplainer({ device }: {
+    device: DeviceNoun;
+}): StatusCopy & {
+    action: string;
+};
+/**
+ * The summary heading of the one "Waiting to sync" list, from what waits on
+ * the device; `null` when nothing does.
+ */
+export declare function waitingSummary({ changes, messages, recordings, }: {
+    changes?: number;
+    messages?: number;
+    recordings?: number;
+}): string | null;
+/**
+ * Where one item in the "Waiting to sync" list stands: a change, a message or a
+ * recording made while Athena couldn't be reached.
+ */
+export type WaitingItemState = 
+/** Saved on the device; it syncs when Athena is back. */
+'waiting'
+/** Being sent to Athena now. */
+ | 'syncing'
+/**
+ * Kept only while this tab or app stays open: it couldn't be saved on the
+ * device (the organization keeps nothing on devices, or storage failed).
+ */
+ | 'in-memory'
+/**
+ * Saved on the device in something that isn't open (a document closed before
+ * its edits synced, one made offline): it syncs when it is next opened with a
+ * connection (opening it offline sends nothing).
+ */
+ | 'when-opened'
+/** Made in another workspace: it syncs once that workspace is open again, with a connection. */
+ | 'other-workspace'
+/** It doesn't go on its own: the person chooses (a message that waited more than a day). */
+ | 'needs-you'
+/** Athena didn't take it: the app adds why, and what the person can do about it. */
+ | 'not-synced';
+/** The state of one item in the "Waiting to sync" list, and the line that explains it. */
+export declare function waitingItemCopy({ state, device, }: {
+    state: WaitingItemState;
+    device: DeviceNoun;
+}): LabelCopy;
+/** The headings of the "Waiting to sync" list, one per kind of item. */
+export declare const WAITING_SECTION_TITLES: {
+    readonly changes: 'Changes';
+    readonly messages: 'Messages';
+    readonly recordings: 'Recordings';
+};

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[];