@athenaintel/react 0.41.3 → 0.42.2

package/dist/agent-runtime/src/sealed-idb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-idb.js","sources":["../../../../agent-runtime/src/sealed-idb.ts"],"sourcesContent":["/**\n * The sealed-record toolkit the device stores in this package share (the thread snapshot mirror,\n * the chat outbox): AES-GCM-256 sealing with a fresh IV and additional data that binds a record to\n * where it is stored, SHA-256 names so a database names no one, and the part of IndexedDB they use.\n *\n * This package compiles without the DOM lib (React Native honesty, `globals.d.ts`), so IndexedDB is\n * described structurally here; the stores run only where it exists and degrade to nothing where it\n * does not.\n */\n\nexport type IdbListener = ((event?: unknown) => void) | null;\n\nexport interface IdbRequest<T> {\n  readonly result: T;\n  readonly error: unknown;\n  onsuccess: IdbListener;\n  onerror: IdbListener;\n}\n\nexport interface IdbOpenRequest extends IdbRequest<IdbDatabase> {\n  onupgradeneeded: IdbListener;\n  onblocked: IdbListener;\n}\n\nexport interface IdbFactory {\n  open(name: string, version?: number): IdbOpenRequest;\n}\n\nexport interface IdbCursor {\n  readonly primaryKey: unknown;\n  continue(): void;\n}\n\nexport interface IdbIndex {\n  getAll(query?: unknown): IdbRequest<unknown[]>;\n  getAllKeys(query?: unknown): IdbRequest<unknown[]>;\n  openKeyCursor(range?: unknown, direction?: string): IdbRequest<IdbCursor | null>;\n}\n\nexport interface IdbObjectStore {\n  put(value: unknown): IdbRequest<unknown>;\n  get(key: unknown): IdbRequest<unknown>;\n  delete(key: unknown): IdbRequest<unknown>;\n  clear(): IdbRequest<unknown>;\n  index(name: string): IdbIndex;\n  createIndex(name: string, keyPath: string | string[], options?: { unique?: boolean }): unknown;\n}\n\nexport interface IdbTransaction {\n  objectStore(name: string): IdbObjectStore;\n  readonly error: unknown;\n  oncomplete: IdbListener;\n  onabort: IdbListener;\n  onerror: IdbListener;\n}\n\nexport interface IdbDatabase {\n  readonly objectStoreNames: { contains(name: string): boolean };\n  transaction(stores: string | string[], mode?: \"readonly\" | \"readwrite\"): IdbTransaction;\n  createObjectStore(name: string, options?: { keyPath: string }): IdbObjectStore;\n  onversionchange: IdbListener;\n  addEventListener(type: string, listener: () => void): void;\n  close(): void;\n}\n\nexport interface IdbKeyRangeStatic {\n  bound(lower: unknown, upper: unknown): unknown;\n}\n\nexport const idbGlobals = globalThis as { indexedDB?: object; IDBKeyRange?: IdbKeyRangeStatic };\n\n/** The AES-GCM IV length, prefixed to every sealed payload. */\nexport const SEALED_IV_BYTES = 12;\n\nconst encoder = new TextEncoder();\nconst decoder = new TextDecoder();\n\nexport async function sha256Hex(value: string): Promise<string> {\n  const digest = await crypto.subtle.digest(\"SHA-256\", encoder.encode(value));\n  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, \"0\")).join(\"\");\n}\n\n/** `value` as JSON, sealed under `key` with a fresh IV; `aad` binds it to where it is stored. */\nexport async function sealJson({\n  key,\n  value,\n  aad,\n}: {\n  key: CryptoKey;\n  value: unknown;\n  aad: string;\n}): Promise<Uint8Array> {\n  const iv = crypto.getRandomValues(new Uint8Array(SEALED_IV_BYTES));\n  const ciphertext = new Uint8Array(\n    await crypto.subtle.encrypt(\n      { name: \"AES-GCM\", iv, additionalData: encoder.encode(aad) },\n      key,\n      encoder.encode(JSON.stringify(value)),\n    ),\n  );\n  const sealed = new Uint8Array(SEALED_IV_BYTES + ciphertext.byteLength);\n  sealed.set(iv, 0);\n  sealed.set(ciphertext, SEALED_IV_BYTES);\n  return sealed;\n}\n\n/** Opens what {@link sealJson} sealed; throws for the wrong key, the wrong `aad`, or a damaged record. */\nexport async function openJson({\n  key,\n  sealed,\n  aad,\n}: {\n  key: CryptoKey;\n  sealed: Uint8Array;\n  aad: string;\n}): Promise<unknown> {\n  const iv = sealed.subarray(0, SEALED_IV_BYTES) as Uint8Array<ArrayBuffer>;\n  const plaintext = await crypto.subtle.decrypt(\n    { name: \"AES-GCM\", iv, additionalData: encoder.encode(aad) },\n    key,\n    sealed.subarray(SEALED_IV_BYTES) as Uint8Array<ArrayBuffer>,\n  );\n  return JSON.parse(decoder.decode(plaintext)) as unknown;\n}\n\nexport function requestToPromise<T>(request: IdbRequest<T>): Promise<T> {\n  return new Promise((resolve, reject) => {\n    request.onsuccess = () => resolve(request.result);\n    request.onerror = () => reject(request.error ?? new Error(\"IndexedDB request failed\"));\n  });\n}\n\nexport function transactionDone(tx: IdbTransaction): Promise<void> {\n  return new Promise((resolve, reject) => {\n    tx.oncomplete = () => resolve();\n    tx.onabort = () => reject(tx.error ?? new Error(\"IndexedDB transaction aborted\"));\n    tx.onerror = () => reject(tx.error ?? new Error(\"IndexedDB transaction failed\"));\n  });\n}\n\n/**\n * Opens `name` at `version`, creating what `upgrade` creates. Resolves `null` instead of failing:\n * a database a newer build upgraded past this version, a blocked open, or no IndexedDB at all\n * (private browsing, SSR) all mean \"no store here\".\n */\nexport function openSealedDatabase({\n  factory,\n  name,\n  version,\n  upgrade,\n}: {\n  factory: IdbFactory;\n  name: string;\n  version: number;\n  upgrade: (db: IdbDatabase) => void;\n}): Promise<IdbDatabase | null> {\n  return new Promise((resolve) => {\n    try {\n      const request = factory.open(name, version);\n      request.onupgradeneeded = () => upgrade(request.result);\n      request.onsuccess = () => {\n        const db = request.result;\n        // Another page deleting or upgrading the database: step aside.\n        db.onversionchange = () => db.close();\n        resolve(db);\n      };\n      request.onerror = () => resolve(null);\n      request.onblocked = () => resolve(null);\n    } catch {\n      resolve(null);\n    }\n  });\n}\n\n/**\n * A lazily opened database handle that reopens after the browser (or another page's upgrade or\n * delete) closes it. `null` while there is no IndexedDB or Web Crypto here.\n */\nexport function lazySealedDatabase({\n  factory,\n  name,\n  version,\n  upgrade,\n}: {\n  factory: object | undefined;\n  name: string;\n  version: number;\n  upgrade: (db: IdbDatabase) => void;\n}): () => Promise<IdbDatabase | null> {\n  let databasePromise: Promise<IdbDatabase | null> | null = null;\n  return () => {\n    if (!factory || typeof crypto === \"undefined\" || !crypto.subtle) return Promise.resolve(null);\n    databasePromise ??= openSealedDatabase({ factory: factory as IdbFactory, name, version, upgrade }).then(\n      (db) => {\n        if (db) {\n          const forget = () => {\n            databasePromise = null;\n          };\n          db.addEventListener(\"versionchange\", forget);\n          db.addEventListener(\"close\", forget);\n        } else {\n          databasePromise = null;\n        }\n        return db;\n      },\n    );\n    return databasePromise;\n  };\n}\n"],"names":[],"mappings":"AAqEO,MAAM,aAAa;AAGnB,MAAM,kBAAkB;AAE/B,MAAM,UAAU,IAAI,YAAA;AACpB,MAAM,UAAU,IAAI,YAAA;AAEpB,eAAsB,UAAU,OAAgC;AAC9D,QAAM,SAAS,MAAM,OAAO,OAAO,OAAO,WAAW,QAAQ,OAAO,KAAK,CAAC;AAC1E,SAAO,MAAM,KAAK,IAAI,WAAW,MAAM,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAAE,KAAK,EAAE;AACjG;AAGA,eAAsB,SAAS;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AACF,GAIwB;AACtB,QAAM,KAAK,OAAO,gBAAgB,IAAI,WAAW,eAAe,CAAC;AACjE,QAAM,aAAa,IAAI;AAAA,IACrB,MAAM,OAAO,OAAO;AAAA,MAClB,EAAE,MAAM,WAAW,IAAI,gBAAgB,QAAQ,OAAO,GAAG,EAAA;AAAA,MACzD;AAAA,MACA,QAAQ,OAAO,KAAK,UAAU,KAAK,CAAC;AAAA,IAAA;AAAA,EACtC;AAEF,QAAM,SAAS,IAAI,WAAW,kBAAkB,WAAW,UAAU;AACrE,SAAO,IAAI,IAAI,CAAC;AAChB,SAAO,IAAI,YAAY,eAAe;AACtC,SAAO;AACT;AAGA,eAAsB,SAAS;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AACF,GAIqB;AACnB,QAAM,KAAK,OAAO,SAAS,GAAG,eAAe;AAC7C,QAAM,YAAY,MAAM,OAAO,OAAO;AAAA,IACpC,EAAE,MAAM,WAAW,IAAI,gBAAgB,QAAQ,OAAO,GAAG,EAAA;AAAA,IACzD;AAAA,IACA,OAAO,SAAS,eAAe;AAAA,EAAA;AAEjC,SAAO,KAAK,MAAM,QAAQ,OAAO,SAAS,CAAC;AAC7C;AAEO,SAAS,iBAAoB,SAAoC;AACtE,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,YAAQ,YAAY,MAAM,QAAQ,QAAQ,MAAM;AAChD,YAAQ,UAAU,MAAM,OAAO,QAAQ,SAAS,IAAI,MAAM,0BAA0B,CAAC;AAAA,EACvF,CAAC;AACH;AAEO,SAAS,gBAAgB,IAAmC;AACjE,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,OAAG,aAAa,MAAM,QAAA;AACtB,OAAG,UAAU,MAAM,OAAO,GAAG,SAAS,IAAI,MAAM,+BAA+B,CAAC;AAChF,OAAG,UAAU,MAAM,OAAO,GAAG,SAAS,IAAI,MAAM,8BAA8B,CAAC;AAAA,EACjF,CAAC;AACH;AAOO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAKgC;AAC9B,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,QAAI;AACF,YAAM,UAAU,QAAQ,KAAK,MAAM,OAAO;AAC1C,cAAQ,kBAAkB,MAAM,QAAQ,QAAQ,MAAM;AACtD,cAAQ,YAAY,MAAM;AACxB,cAAM,KAAK,QAAQ;AAEnB,WAAG,kBAAkB,MAAM,GAAG,MAAA;AAC9B,gBAAQ,EAAE;AAAA,MACZ;AACA,cAAQ,UAAU,MAAM,QAAQ,IAAI;AACpC,cAAQ,YAAY,MAAM,QAAQ,IAAI;AAAA,IACxC,QAAQ;AACN,cAAQ,IAAI;AAAA,IACd;AAAA,EACF,CAAC;AACH;AAMO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAKsC;AACpC,MAAI,kBAAsD;AAC1D,SAAO,MAAM;AACX,QAAI,CAAC,WAAW,OAAO,WAAW,eAAe,CAAC,OAAO,OAAQ,QAAO,QAAQ,QAAQ,IAAI;AAC5F,0CAAoB,mBAAmB,EAAE,SAAgC,MAAM,SAAS,QAAA,CAAS,EAAE;AAAA,MACjG,CAAC,OAAO;AACN,YAAI,IAAI;AACN,gBAAM,SAAS,MAAM;AACnB,8BAAkB;AAAA,UACpB;AACA,aAAG,iBAAiB,iBAAiB,MAAM;AAC3C,aAAG,iBAAiB,SAAS,MAAM;AAAA,QACrC,OAAO;AACL,4BAAkB;AAAA,QACpB;AACA,eAAO;AAAA,MACT;AAAA,IAAA;AAEF,WAAO;AAAA,EACT;AACF;"}

package/dist/agent-runtime/src/send-recovery.d.ts

@@ -0,0 +1,40 @@
+import type { StatewireDiagnosticsCommandUpdate, StatewireDiagnosticsRecorder } from './statewire-diagnostics';
+import type { StatewireFailedSendLane } from './thread-extras';
+export interface DeepAgentSendRecoveryOptions {
+    /**
+     * Reads the thread's failed-send lane. `null` while it is unavailable (the
+     * client has not mounted yet, or its extras are not a statewire thread) —
+     * the controller stays armed and retries on the next state change.
+     */
+    lane: () => StatewireFailedSendLane | null;
+    /**
+     * Persisted failure stamps (message id → epoch ms of the original send) for
+     * the freshness gate. `null`/absent means no persistence is readable — every
+     * lane entry then counts as fresh (an in-memory failed lane can only hold
+     * failures from this page session).
+     */
+    failureStamps?: (() => ReadonlyMap<string, number> | null) | undefined;
+    /** Transport lifecycle recorder; read per event so a late-mounted recorder still sees retries. */
+    diagnostics?: (() => StatewireDiagnosticsRecorder | undefined) | undefined;
+    /** Injectable clock (tests). */
+    now?: () => number;
+    /** Sweep scheduler; defaults to `queueMicrotask` so a sweep never dispatches
+     * from inside a statewire flush or a React render. */
+    schedule?: (task: () => void) => void;
+}
+export interface DeepAgentSendRecovery {
+    /** Feed every (normalized) statewire state change; hydration arms the mount sweep. */
+    observeStateChange(state: unknown): void;
+    /** Feed every command-lifecycle update; a never-server-judged settle arms a sweep. */
+    observeCommand(update: StatewireDiagnosticsCommandUpdate): void;
+    /** Feed client notifications too: failed history can publish after the
+     * command settles, without any change to the canonical thread snapshot. */
+    observeFailedLaneChange(): void;
+    dispose(): void;
+}
+/** Whether a settle failure is a client-side death the recovery re-dispatches
+ * (the server never judged the command). Exported for host-side telemetry. */
+export declare function shouldAutoRetryFailedSend(failure: {
+    fate: string;
+} | undefined): boolean;
+export declare function createDeepAgentSendRecovery(options: DeepAgentSendRecoveryOptions): DeepAgentSendRecovery;

package/dist/agent-runtime/src/session-lane-scope.cjs

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function isSameSessionLaneScope({
+  scope,
+  key
+}) {
+  return key(scope.threadId) === scope.laneKey;
+}
+const INITIAL_SESSION_LANE_EPOCH = { scope: null, epoch: 0 };
+function nextSessionLaneEpoch({
+  previous,
+  threadId,
+  key
+}) {
+  if (key === null) return previous;
+  if (previous.scope === null) {
+    return { scope: { threadId, laneKey: key(threadId) }, epoch: previous.epoch };
+  }
+  if (isSameSessionLaneScope({ scope: previous.scope, key })) return previous;
+  return { scope: { threadId, laneKey: key(threadId) }, epoch: previous.epoch + 1 };
+}
+exports.INITIAL_SESSION_LANE_EPOCH = INITIAL_SESSION_LANE_EPOCH;
+exports.isSameSessionLaneScope = isSameSessionLaneScope;
+exports.nextSessionLaneEpoch = nextSessionLaneEpoch;
+//# sourceMappingURL=session-lane-scope.cjs.map

package/dist/agent-runtime/src/session-lane-scope.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lane-scope.cjs","sources":["../../../../agent-runtime/src/session-lane-scope.ts"],"sourcesContent":["/**\n * The scope of a thread's durable command lane, as the host names it: the\n * host's `key` maps a thread id to the lane's storage key, and folds into it\n * whatever the lane belongs to (the signed-in principal, the sync host). A lane\n * is one principal's: it holds that principal's client id, lane clocks and the\n * commands still waiting for a durable verdict, and everything in it is sent\n * under whatever credential the transport holds when it next attaches.\n *\n * The scope is the key the host's `key` gave one thread. Probing that same\n * thread again tells a change of scope (another principal, another backend)\n * apart from a thread switch, which moves to another lane of the same scope.\n */\nexport type DeepAgentSessionLaneScope = {\n  /** The thread the scope was taken on. */\n  threadId: string;\n  /** The lane key the host's `key` gave that thread. */\n  laneKey: string;\n};\n\n/** The host's lane key: thread id to the lane's storage key. */\nexport type DeepAgentSessionLaneKey = (threadId: string) => string;\n\n/**\n * Whether `key` still names the lanes of `scope`: a thread switch keeps the\n * scope, a principal change does not.\n */\nexport function isSameSessionLaneScope({\n  scope,\n  key,\n}: {\n  scope: DeepAgentSessionLaneScope;\n  key: DeepAgentSessionLaneKey;\n}): boolean {\n  return key(scope.threadId) === scope.laneKey;\n}\n\n/**\n * A mounted thread's lane epoch: the scope its current lane belongs to, and how\n * many times that scope changed under the mount. `scope` is `null` until the\n * first lane is known (a `pending` lane waits for its principal).\n */\nexport type DeepAgentSessionLaneEpoch = {\n  scope: DeepAgentSessionLaneScope | null;\n  epoch: number;\n};\n\nexport const INITIAL_SESSION_LANE_EPOCH: DeepAgentSessionLaneEpoch = { scope: null, epoch: 0 };\n\n/**\n * The lane epoch after a render with the host's current lane key (`null` while\n * the host names no lane: `pending`, process-local or a host session store).\n *\n * The first lane a mount learns sets the scope without starting a new epoch:\n * a `pending` lane that resolves to its principal is that principal's first\n * lane, not a change. A key that maps the scope's thread to another lane starts\n * the next epoch: the lane now belongs to another principal (or another\n * backend), so nothing of the previous lane — its client id, clocks, journal,\n * the state it rendered — may carry over. A gap with no lane in between (the\n * previous principal signed out, the next one still loading) does not hide\n * the change, and a key with the same scope (a token refresh, a fresh `key`\n * function for the same principal, a thread switch) changes nothing.\n *\n * Returns `previous` itself when nothing changed.\n */\nexport function nextSessionLaneEpoch({\n  previous,\n  threadId,\n  key,\n}: {\n  previous: DeepAgentSessionLaneEpoch;\n  threadId: string;\n  key: DeepAgentSessionLaneKey | null;\n}): DeepAgentSessionLaneEpoch {\n  if (key === null) return previous;\n  if (previous.scope === null) {\n    return { scope: { threadId, laneKey: key(threadId) }, epoch: previous.epoch };\n  }\n  if (isSameSessionLaneScope({ scope: previous.scope, key })) return previous;\n  return { scope: { threadId, laneKey: key(threadId) }, epoch: previous.epoch + 1 };\n}\n"],"names":[],"mappings":";;AA0BO,SAAS,uBAAuB;AAAA,EACrC;AAAA,EACA;AACF,GAGY;AACV,SAAO,IAAI,MAAM,QAAQ,MAAM,MAAM;AACvC;AAYO,MAAM,6BAAwD,EAAE,OAAO,MAAM,OAAO,EAAA;AAkBpF,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AACF,GAI8B;AAC5B,MAAI,QAAQ,KAAM,QAAO;AACzB,MAAI,SAAS,UAAU,MAAM;AAC3B,WAAO,EAAE,OAAO,EAAE,UAAU,SAAS,IAAI,QAAQ,KAAK,OAAO,SAAS,MAAA;AAAA,EACxE;AACA,MAAI,uBAAuB,EAAE,OAAO,SAAS,OAAO,IAAA,CAAK,EAAG,QAAO;AACnE,SAAO,EAAE,OAAO,EAAE,UAAU,SAAS,IAAI,QAAQ,EAAA,GAAK,OAAO,SAAS,QAAQ,EAAA;AAChF;;;;"}

package/dist/agent-runtime/src/session-lane-scope.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The scope of a thread's durable command lane, as the host names it: the
+ * host's `key` maps a thread id to the lane's storage key, and folds into it
+ * whatever the lane belongs to (the signed-in principal, the sync host). A lane
+ * is one principal's: it holds that principal's client id, lane clocks and the
+ * commands still waiting for a durable verdict, and everything in it is sent
+ * under whatever credential the transport holds when it next attaches.
+ *
+ * The scope is the key the host's `key` gave one thread. Probing that same
+ * thread again tells a change of scope (another principal, another backend)
+ * apart from a thread switch, which moves to another lane of the same scope.
+ */
+export type DeepAgentSessionLaneScope = {
+    /** The thread the scope was taken on. */
+    threadId: string;
+    /** The lane key the host's `key` gave that thread. */
+    laneKey: string;
+};
+/** The host's lane key: thread id to the lane's storage key. */
+export type DeepAgentSessionLaneKey = (threadId: string) => string;
+/**
+ * Whether `key` still names the lanes of `scope`: a thread switch keeps the
+ * scope, a principal change does not.
+ */
+export declare function isSameSessionLaneScope({ scope, key, }: {
+    scope: DeepAgentSessionLaneScope;
+    key: DeepAgentSessionLaneKey;
+}): boolean;
+/**
+ * A mounted thread's lane epoch: the scope its current lane belongs to, and how
+ * many times that scope changed under the mount. `scope` is `null` until the
+ * first lane is known (a `pending` lane waits for its principal).
+ */
+export type DeepAgentSessionLaneEpoch = {
+    scope: DeepAgentSessionLaneScope | null;
+    epoch: number;
+};
+export declare const INITIAL_SESSION_LANE_EPOCH: DeepAgentSessionLaneEpoch;
+/**
+ * The lane epoch after a render with the host's current lane key (`null` while
+ * the host names no lane: `pending`, process-local or a host session store).
+ *
+ * The first lane a mount learns sets the scope without starting a new epoch:
+ * a `pending` lane that resolves to its principal is that principal's first
+ * lane, not a change. A key that maps the scope's thread to another lane starts
+ * the next epoch: the lane now belongs to another principal (or another
+ * backend), so nothing of the previous lane — its client id, clocks, journal,
+ * the state it rendered — may carry over. A gap with no lane in between (the
+ * previous principal signed out, the next one still loading) does not hide
+ * the change, and a key with the same scope (a token refresh, a fresh `key`
+ * function for the same principal, a thread switch) changes nothing.
+ *
+ * Returns `previous` itself when nothing changed.
+ */
+export declare function nextSessionLaneEpoch({ previous, threadId, key, }: {
+    previous: DeepAgentSessionLaneEpoch;
+    threadId: string;
+    key: DeepAgentSessionLaneKey | null;
+}): DeepAgentSessionLaneEpoch;

package/dist/agent-runtime/src/session-lane-scope.js

@@ -0,0 +1,25 @@
+function isSameSessionLaneScope({
+  scope,
+  key
+}) {
+  return key(scope.threadId) === scope.laneKey;
+}
+const INITIAL_SESSION_LANE_EPOCH = { scope: null, epoch: 0 };
+function nextSessionLaneEpoch({
+  previous,
+  threadId,
+  key
+}) {
+  if (key === null) return previous;
+  if (previous.scope === null) {
+    return { scope: { threadId, laneKey: key(threadId) }, epoch: previous.epoch };
+  }
+  if (isSameSessionLaneScope({ scope: previous.scope, key })) return previous;
+  return { scope: { threadId, laneKey: key(threadId) }, epoch: previous.epoch + 1 };
+}
+export {
+  INITIAL_SESSION_LANE_EPOCH,
+  isSameSessionLaneScope,
+  nextSessionLaneEpoch
+};
+//# sourceMappingURL=session-lane-scope.js.map

package/dist/agent-runtime/src/session-lane-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lane-scope.js","sources":["../../../../agent-runtime/src/session-lane-scope.ts"],"sourcesContent":["/**\n * The scope of a thread's durable command lane, as the host names it: the\n * host's `key` maps a thread id to the lane's storage key, and folds into it\n * whatever the lane belongs to (the signed-in principal, the sync host). A lane\n * is one principal's: it holds that principal's client id, lane clocks and the\n * commands still waiting for a durable verdict, and everything in it is sent\n * under whatever credential the transport holds when it next attaches.\n *\n * The scope is the key the host's `key` gave one thread. Probing that same\n * thread again tells a change of scope (another principal, another backend)\n * apart from a thread switch, which moves to another lane of the same scope.\n */\nexport type DeepAgentSessionLaneScope = {\n  /** The thread the scope was taken on. */\n  threadId: string;\n  /** The lane key the host's `key` gave that thread. */\n  laneKey: string;\n};\n\n/** The host's lane key: thread id to the lane's storage key. */\nexport type DeepAgentSessionLaneKey = (threadId: string) => string;\n\n/**\n * Whether `key` still names the lanes of `scope`: a thread switch keeps the\n * scope, a principal change does not.\n */\nexport function isSameSessionLaneScope({\n  scope,\n  key,\n}: {\n  scope: DeepAgentSessionLaneScope;\n  key: DeepAgentSessionLaneKey;\n}): boolean {\n  return key(scope.threadId) === scope.laneKey;\n}\n\n/**\n * A mounted thread's lane epoch: the scope its current lane belongs to, and how\n * many times that scope changed under the mount. `scope` is `null` until the\n * first lane is known (a `pending` lane waits for its principal).\n */\nexport type DeepAgentSessionLaneEpoch = {\n  scope: DeepAgentSessionLaneScope | null;\n  epoch: number;\n};\n\nexport const INITIAL_SESSION_LANE_EPOCH: DeepAgentSessionLaneEpoch = { scope: null, epoch: 0 };\n\n/**\n * The lane epoch after a render with the host's current lane key (`null` while\n * the host names no lane: `pending`, process-local or a host session store).\n *\n * The first lane a mount learns sets the scope without starting a new epoch:\n * a `pending` lane that resolves to its principal is that principal's first\n * lane, not a change. A key that maps the scope's thread to another lane starts\n * the next epoch: the lane now belongs to another principal (or another\n * backend), so nothing of the previous lane — its client id, clocks, journal,\n * the state it rendered — may carry over. A gap with no lane in between (the\n * previous principal signed out, the next one still loading) does not hide\n * the change, and a key with the same scope (a token refresh, a fresh `key`\n * function for the same principal, a thread switch) changes nothing.\n *\n * Returns `previous` itself when nothing changed.\n */\nexport function nextSessionLaneEpoch({\n  previous,\n  threadId,\n  key,\n}: {\n  previous: DeepAgentSessionLaneEpoch;\n  threadId: string;\n  key: DeepAgentSessionLaneKey | null;\n}): DeepAgentSessionLaneEpoch {\n  if (key === null) return previous;\n  if (previous.scope === null) {\n    return { scope: { threadId, laneKey: key(threadId) }, epoch: previous.epoch };\n  }\n  if (isSameSessionLaneScope({ scope: previous.scope, key })) return previous;\n  return { scope: { threadId, laneKey: key(threadId) }, epoch: previous.epoch + 1 };\n}\n"],"names":[],"mappings":"AA0BO,SAAS,uBAAuB;AAAA,EACrC;AAAA,EACA;AACF,GAGY;AACV,SAAO,IAAI,MAAM,QAAQ,MAAM,MAAM;AACvC;AAYO,MAAM,6BAAwD,EAAE,OAAO,MAAM,OAAO,EAAA;AAkBpF,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AACF,GAI8B;AAC5B,MAAI,QAAQ,KAAM,QAAO;AACzB,MAAI,SAAS,UAAU,MAAM;AAC3B,WAAO,EAAE,OAAO,EAAE,UAAU,SAAS,IAAI,QAAQ,KAAK,OAAO,SAAS,MAAA;AAAA,EACxE;AACA,MAAI,uBAAuB,EAAE,OAAO,SAAS,OAAO,IAAA,CAAK,EAAG,QAAO;AACnE,SAAO,EAAE,OAAO,EAAE,UAAU,SAAS,IAAI,QAAQ,EAAA,GAAK,OAAO,SAAS,QAAQ,EAAA;AAChF;"}

package/dist/agent-runtime/src/statewire-attach-observer.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Attach-path instrumentation for the deep-agent statewire transport, wired
+ * through the two injection points statewire already exposes — the
+ * `webSocket` constructor (`StatewireClient.WebsocketOptions`) and `fetch`
+ * (`StatewireClient.HttpOptions`) — so the runtime can observe what the library
+ * does not surface:
+ *
+ * - socket open latency (`ws_open_ms`), the hello frame's size and its
+ *   synchronous handler cost (`hello_bytes`, `hello_handler_ms`), and close
+ *   codes/reasons, for the thread-switch telemetry;
+ * - a server `Retry-After` hint, honoured as a floor under the next dial.
+ *
+ * Retry-After today: statewire honours `retry-after` only on 429 command-frame
+ * refusals (folded into the refusal `syn.retry`); its attach paths treat a 503
+ * as a generic `HTTP 503` / `network` failure and back off exponentially with
+ * no server input. Browsers never expose the response headers of a refused
+ * WebSocket upgrade at all, so for the WS transport the hint can only ride
+ * something the client can read: the close frame. The contract this module
+ * reads is a close `reason` carrying `retry-after=<seconds>` (or
+ * `retry-after-ms=<ms>`) — the pinboard half of that contract is a separate
+ * change; until it lands the WS path simply sees no hint. The SSE attach
+ * (`POST …/stream`) is a plain fetch, so its `Retry-After` header is read here
+ * directly.
+ *
+ * This package compiles without the DOM lib (React Native honesty), so the
+ * browser surface is typed structurally and resolved through `globalThis`.
+ */
+/**
+ * Who refused a wake (503/429), read off the response body against the two
+ * refusal vocabularies the iris scaler also classifies data-plane 503s by
+ * (`iris/scaler/src/v2AccessLog.ts`):
+ *
+ * - `"placement"` — the pinboard's own refusal, `{"error": …}` with one of its
+ *   known strings ("no live workers for hostname", "registry cold start,
+ *   retry", "takeover in progress, retry", …): the thread has no worker to
+ *   dial right now.
+ * - `"worker"` — a pinned instance-lifecycle refusal, `{"detail": …}` with one
+ *   of its known strings ("instance closing; retry", "activation queue full;
+ *   retry", "host draining; retry", …): one instance on the worker the thread
+ *   is already placed on, cleared in the time a teardown takes.
+ * - `"unknown"` — any other 503/429 body (unreadable, an unfamiliar string, a
+ *   real worker failure such as "Thread history load failed"): treated
+ *   conservatively — the full `Retry-After`, no dial dropped.
+ * - `null` — not a refusal status.
+ */
+export type DeepAgentWakeRefusal = "placement" | "worker" | "unknown" | null;
+export type DeepAgentAttachTimingEvent = {
+    type: "socket-open";
+    url: string;
+    openMs: number;
+} | {
+    type: "hello";
+    url: string;
+    /** UTF-16 length of the hello frame — bytes for the ASCII JSON the wire carries. */
+    bytes: number;
+    /** Synchronous cost of statewire's message handler for the hello (parse + apply + flush). */
+    handlerMs: number;
+    /** Hello arrival relative to the socket open; `null` when the open was not observed. */
+    sinceOpenMs: number | null;
+} | {
+    type: "socket-close";
+    url: string;
+    code: number | undefined;
+    reason: string | undefined;
+    sinceOpenMs: number | null;
+} | {
+    type: "retry-after";
+    url: string;
+    delayMs: number;
+    source: "ws-close" | "http-header";
+} | {
+    /** `POST …/prewarm` answered (see `wakeDeepAgentThread`). */
+    type: "wake";
+    url: string;
+    status: number;
+    durationMs: number;
+    /** How the host sourced the history: already resident (`warm`) or loaded by this call. */
+    history: "fresh_load" | "warm" | null;
+    /** Who refused a 503/429 (see {@link DeepAgentWakeRefusal}); `null` otherwise. */
+    refusal: DeepAgentWakeRefusal;
+};
+/** Longest server hint honoured — a buggy or hostile hint must not park a client. */
+export declare const MAX_RETRY_AFTER_MS = 30000;
+/**
+ * Parse an HTTP `Retry-After` header value: delta-seconds or an HTTP-date.
+ * Returns the delay in ms clamped to {@link MAX_RETRY_AFTER_MS}, or `null` when
+ * the value is absent or unparseable.
+ */
+export declare function parseRetryAfterHeaderMs(value: string | null | undefined, now?: () => number): number | null;
+/**
+ * Parse a retry hint off a WebSocket close reason: `retry-after=<seconds>` or
+ * `retry-after-ms=<ms>` anywhere in the reason text (case-insensitive, `=` or
+ * `:`). Returns ms clamped to {@link MAX_RETRY_AFTER_MS}, or `null`.
+ */
+export declare function parseRetryAfterFromCloseReason(reason: string | undefined): number | null;
+export interface AttachRetryGate {
+    /** Record a hint: no dial for `key` before `now + delayMs` (clamped). */
+    noteRetryAfter(key: string, delayMs: number): void;
+    /** Resolves once the recorded floor for `key` has passed (immediately when none). */
+    waitForDial(key: string): Promise<void>;
+    /** Remaining floor for `key` in ms (0 when none). */
+    remainingMs(key: string): number;
+    /** Drop one key's floor, or every floor. */
+    reset(key?: string): void;
+}
+/**
+ * Per-key dial floors. Keyed by the thread's attach URL so a hint delivered
+ * for one thread never delays another. The floor is a minimum under
+ * statewire's own backoff, never a replacement for it: the transport still
+ * schedules its retry, and the dial simply waits out the remainder inside the
+ * headers resolve (both attach paths resolve headers before they dial).
+ */
+export declare function createAttachRetryGate({ now, wait, }?: {
+    now?: () => number;
+    wait?: (ms: number) => Promise<void>;
+}): AttachRetryGate;
+/** Process-wide gate shared by every deep-agent transport in the host. */
+export declare const attachRetryGate: AttachRetryGate;
+/** Structural subset of the browser `WebSocket` that statewire's WS transport touches. */
+export interface AttachSocketLike {
+    readonly readyState: number;
+    readonly protocol: string;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code?: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+export type AttachWebSocketConstructor = new (url: string, protocols?: string | string[]) => AttachSocketLike;
+/**
+ * Wrap a socket in a forwarding facade whose handler setters time the events
+ * statewire attaches to (`onopen`, `onmessage`, `onclose`). A facade rather
+ * than a subclass so the same instrumentation works over any host `WebSocket`
+ * implementation, including test fakes.
+ */
+export declare function instrumentAttachSocket({ socket, url, onEvent, now, }: {
+    socket: AttachSocketLike;
+    /** The thread attach URL the events are attributed to (not the socket URL). */
+    url: string;
+    onEvent: (event: DeepAgentAttachTimingEvent) => void;
+    now?: () => number;
+}): AttachSocketLike;
+/**
+ * A `WebSocket`-shaped constructor that dials through `Base` and reports the
+ * attach events for `url`. Constructor semantics (`new` returns the facade)
+ * match what statewire's `webSocket` option expects.
+ */
+export declare function instrumentedWebSocketConstructor({ Base, url, onEvent, now, }: {
+    Base: AttachWebSocketConstructor;
+    url: string;
+    onEvent: (event: DeepAgentAttachTimingEvent) => void;
+    now?: () => number;
+}): AttachWebSocketConstructor;
+/** Structural `fetch` — what statewire's SSE transport calls. */
+export type AttachFetch = (input: string | URL, init?: unknown) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+}>;
+/**
+ * A `fetch` that reports a `Retry-After` header on refused attach requests
+ * (the SSE `POST …/stream`) before handing the response back untouched.
+ */
+export declare function instrumentedAttachFetch<TFetch extends AttachFetch>({ baseFetch, url, onEvent, now, }: {
+    baseFetch: TFetch;
+    url: string;
+    onEvent: (event: DeepAgentAttachTimingEvent) => void;
+    now?: () => number;
+}): TFetch;
+/**
+ * The transport option overrides for one attach: an instrumented `webSocket`
+ * (WS) or `fetch` (SSE) that reports attach events for `url` and feeds
+ * `Retry-After` hints into the gate. Returns `{}` where the host has no such
+ * global (a server render, a non-browser runtime) so the transport keeps its
+ * defaults.
+ */
+export declare function createAttachInstrumentation({ url, sse, onEvent, retryGate, now, }: {
+    url: string;
+    sse: boolean;
+    onEvent?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;
+    retryGate?: AttachRetryGate;
+    now?: () => number;
+}): {
+    webSocket?: AttachWebSocketConstructor;
+    fetch?: AttachFetch;
+};

package/dist/agent-runtime/src/statewire-diagnostics.d.ts

@@ -0,0 +1,74 @@
+import type { StatewireClient } from 'statewire';
+/**
+ * Allocation-light lifecycle recorder for the deep-agent statewire transport.
+ *
+ * `useDeepAgentThread` feeds it from the seams it already owns — the raw
+ * connection each converter pass, every command-lifecycle update, transport
+ * errors, and stale-auth header resolves — and it distills them into a small
+ * ring buffer of transition events:
+ *
+ * - `connection/dialing` · `connection/connected` (with attach latency + attempts)
+ * - `connection/retrying` (cause, attempt, lastError) · `connection/gone` · `connection/idle` · `connection/deferred`
+ * - `command/settled` (fate: `durable` or the failure fate, with settle latency)
+ * - `auth/stale-renewal` (a header resolve forced by a refused credential)
+ * - `transport/error`
+ *
+ * The recorder itself persists nothing: the host passes `onRecord` to mirror
+ * entries into its own persistence (Olympus wires it into the persisted
+ * diagnostics framework). Hosts should only construct one when their
+ * diagnostics channel is enabled — an absent recorder costs a single optional
+ * call at each seam. When present, the hot paths (`observeConnection` runs on
+ * every converter pass) compare plain fields and allocate only on an actual
+ * transition.
+ */
+export interface StatewireDiagnosticsEntry {
+    /** ms since page navigation start (`performance.now()`), or epoch ms fallback. */
+    at: number;
+    event: string;
+    data?: Record<string, unknown>;
+}
+/** The command-lifecycle fields the recorder reads; structural subset of `Statewire.CommandUpdate`. */
+export interface StatewireDiagnosticsCommandUpdate {
+    method: string;
+    /** The wire statement's params (a run send carries its message first). */
+    params?: readonly unknown[];
+    seq: number;
+    status: 'queued' | 'posted' | 'applied' | 'settled';
+    failure?: {
+        fate: string;
+        cause?: string;
+        code?: string;
+        message?: string;
+    };
+}
+export interface StatewireDiagnosticsRecorderOptions {
+    /** Ring-buffer capacity; oldest entries are overwritten. */
+    maxEntries?: number;
+    /** Injectable clock (tests). Defaults to `performance.now()`. */
+    now?: () => number;
+    /** Persistence sink, invoked once per recorded entry (exceptions swallowed). */
+    onRecord?: (entry: StatewireDiagnosticsEntry) => void;
+}
+export interface StatewireDiagnosticsRecorder {
+    /** Record an arbitrary host event (outbox replays, boundary crashes, …). */
+    record(event: string, data?: Record<string, unknown>): void;
+    /**
+     * Fold a connection into the transition log; call as often as you like —
+     * unchanged states are free. Takes the raw statewire connection so any host
+     * observer can feed it, and reads it only through
+     * `projectDeepAgentConnection` — the one seam over the wire vocabulary.
+     */
+    observeConnection(connection: StatewireClient.ConnectionState): void;
+    /** Fold a command-lifecycle update; records settle fates with latency. */
+    observeCommand(update: StatewireDiagnosticsCommandUpdate): void;
+    /** Fold a headers resolve; records only stale-auth renewals. */
+    observeAuthResolve(ctx: {
+        staleAuth: boolean;
+    }): void;
+    /** Record a transport error surfaced through `onError`. */
+    observeError(error: unknown): void;
+    /** Entries in arrival order (oldest first). */
+    getEntries(): StatewireDiagnosticsEntry[];
+    clear(): void;
+}
+export declare function createStatewireDiagnosticsRecorder(options?: StatewireDiagnosticsRecorderOptions): StatewireDiagnosticsRecorder;

package/dist/agent-runtime/src/statewire-state.d.ts

@@ -0,0 +1,29 @@
+import type { DeepAgentStreamValues } from './types';
+export declare const DEEP_AGENT_PRE_STREAM_STATE: DeepAgentStreamValues;
+/**
+ * Read the deep-agent stream values off a raw statewire state, substituting
+ * {@link DEEP_AGENT_PRE_STREAM_STATE} while the state is not an object yet
+ * (pre-attach, or a replay boundary republishing `undefined`).
+ *
+ * Identity-preserving: a hydrated state returns the same object reference it
+ * was given and the pre-stream branch always returns the same module constant,
+ * so this is safe to call inside `useStatewireState` selectors.
+ */
+export declare function readDeepAgentStreamValues(state: unknown): DeepAgentStreamValues;
+/**
+ * Whether a state (raw, or already normalized through
+ * {@link readDeepAgentStreamValues}) carries a real wire payload. `false`
+ * exactly while the pre-stream default stands in — the explicit signal for
+ * code that must distinguish "empty thread" from "no snapshot yet".
+ */
+export declare function isDeepAgentStateHydrated(state: unknown): boolean;
+/** Record that `threadId`'s attach produced `state` (the converter's output). */
+export declare function pairDeepAgentStateWithThread({ state, threadId, }: {
+    state: object;
+    threadId: string;
+}): void;
+/**
+ * The thread whose attach produced `state`, or `null` for a state no deep-agent
+ * converter published (the pre-stream default, a state built elsewhere).
+ */
+export declare function readDeepAgentStateThreadId(state: unknown): string | null;

package/dist/agent-runtime/src/statewire-suspended.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"statewire-suspended.cjs","sources":["../../../../agent-runtime/src/statewire-suspended.ts"],"sourcesContent":["import { resource } from '@assistant-ui/tap';\nimport type { ResourceElement } from '@assistant-ui/tap';\nimport { useRef, useState } from 'react';\nimport type { Statewire, StatewireClient } from 'statewire';\nimport { StatewireSendError } from 'statewire';\n\nexport interface SuspendedStatewireOptions {\n  /** Why the transport is parked; surfaced as the connection message. */\n  message: string;\n  /**\n   * Invoked when a surface asks the parked connection to `reconnect()` (the\n   * connection indicator's retry affordance). Hosts that park for a reason\n   * only they can clear (e.g. the user has no workspace) omit it.\n   */\n  onReconnectRequested?: (() => void) | undefined;\n}\n\nconst suspendedCommands = <\n  TCommands extends Statewire.Commands,\n>(): Statewire.CommandsProxy<TCommands> =>\n  new Proxy({} as Statewire.CommandsProxy<TCommands>, {\n    get: (_target, method) => {\n      if (typeof method !== 'string') return undefined;\n      // Settle like a locally-dead channel: hosts already classify\n      // non-\"server\" causes as channel teardown (quiet log, no user error).\n      return () =>\n        Promise.reject(new StatewireSendError({ fate: 'aborted', cause: 'stream-gone' }));\n    },\n  });\n\nconst useSuspendedStatewire = <TCommands extends Statewire.Commands = Statewire.Commands>(\n  options: SuspendedStatewireOptions\n): Statewire<undefined, TCommands> => {\n  const latest = useRef(options);\n  latest.current = options;\n  // `state` stays undefined so the thread keeps serving its `initialState`\n  // (the same contract a live transport has before its attach snapshot).\n  const [value] = useState((): Statewire<undefined, TCommands> => {\n    const connection: StatewireClient.Connection & { readonly message: string } = {\n      status: 'standby',\n      reason: 'deferred',\n      get message() {\n        return latest.current.message;\n      },\n      reconnect: () => latest.current.onReconnectRequested?.(),\n      degraded: false,\n    };\n    return {\n      state: undefined,\n      commands: suspendedCommands<TCommands>(),\n      connection,\n      // Context updates while parked are local and must never start a dial.\n      // The live transport receives the current snapshot when it replaces us.\n      setContext: () => {},\n      isBusy: false,\n    };\n  });\n  return value;\n};\n\n/**\n * A statewire transport that never dials.\n *\n * Swapped in for the live WS/SSE transport when attaching is known to be\n * pointless — the host gates it (no workspace) or repeated `unauthorized`\n * denials parked it — so the thread element stays mounted for assistant-ui\n * consumers while the reconnect loop stops entirely.\n */\nexport const StatewireSuspended = resource(useSuspendedStatewire) as <\n  TCommands extends Statewire.Commands = Statewire.Commands,\n>(\n  options: SuspendedStatewireOptions\n) => ResourceElement<Statewire<undefined, TCommands>>;\n"],"names":["StatewireSendError","useRef","useState","resource"],"mappings":";;;;;AAiBA,MAAM,oBAAoB,MAGxB,IAAI,MAAM,IAA0C;AAAA,EAClD,KAAK,CAAC,SAAS,WAAW;AACxB,QAAI,OAAO,WAAW,SAAU,QAAO;AAGvC,WAAO,MACL,QAAQ,OAAO,IAAIA,UAAAA,mBAAmB,EAAE,MAAM,WAAW,OAAO,cAAA,CAAe,CAAC;AAAA,EACpF;AACF,CAAC;AAEH,MAAM,wBAAwB,CAC5B,YACoC;AACpC,QAAM,SAASC,MAAAA,OAAO,OAAO;AAC7B,SAAO,UAAU;AAGjB,QAAM,CAAC,KAAK,IAAIC,MAAAA,SAAS,MAAuC;AAC9D,UAAM,aAAwE;AAAA,MAC5E,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,IAAI,UAAU;AACZ,eAAO,OAAO,QAAQ;AAAA,MACxB;AAAA,MACA,WAAW,MAAA;;AAAM,kCAAO,SAAQ,yBAAf;AAAA;AAAA,MACjB,UAAU;AAAA,IAAA;AAEZ,WAAO;AAAA,MACL,OAAO;AAAA,MACP,UAAU,kBAAA;AAAA,MACV;AAAA;AAAA;AAAA,MAGA,YAAY,MAAM;AAAA,MAAC;AAAA,MACnB,QAAQ;AAAA,IAAA;AAAA,EAEZ,CAAC;AACD,SAAO;AACT;AAUO,MAAM,qBAAqBC,IAAAA,SAAS,qBAAqB;;"}
+{"version":3,"file":"statewire-suspended.cjs","sources":["../../../../agent-runtime/src/statewire-suspended.ts"],"sourcesContent":["import { resource } from '@assistant-ui/tap';\nimport type { ResourceElement } from '@assistant-ui/tap';\nimport { useRef, useState } from 'react';\nimport type { Statewire, StatewireClient } from 'statewire';\nimport { StatewireSendError } from 'statewire';\n\nexport interface SuspendedStatewireOptions {\n  /**\n   * Why the transport is parked; surfaced as the connection message. Omitted\n   * for a park that is part of normal startup rather than a refusal (a\n   * `pending` session lane, whose principal is still loading): the connection\n   * then carries no message and reads like a never-started chat, which hosts\n   * render as ready rather than paused.\n   */\n  message?: string | undefined;\n  /**\n   * Invoked when a surface asks the parked connection to `reconnect()` (the\n   * connection indicator's retry affordance). Hosts that park for a reason\n   * only they can clear (e.g. the user has no workspace) omit it.\n   */\n  onReconnectRequested?: (() => void) | undefined;\n}\n\nconst suspendedCommands = <\n  TCommands extends Statewire.Commands,\n>(): Statewire.CommandsProxy<TCommands> =>\n  new Proxy({} as Statewire.CommandsProxy<TCommands>, {\n    get: (_target, method) => {\n      if (typeof method !== 'string') return undefined;\n      // Settle like a locally-dead channel: hosts already classify\n      // non-\"server\" causes as channel teardown (quiet log, no user error).\n      return () =>\n        Promise.reject(new StatewireSendError({ fate: 'aborted', cause: 'stream-gone' }));\n    },\n  });\n\nconst useSuspendedStatewire = <TCommands extends Statewire.Commands = Statewire.Commands>(\n  options: SuspendedStatewireOptions\n): Statewire<undefined, TCommands> => {\n  const latest = useRef(options);\n  latest.current = options;\n  // `state` stays undefined so the thread keeps serving its `initialState`\n  // (the same contract a live transport has before its attach snapshot).\n  const [value] = useState((): Statewire<undefined, TCommands> => {\n    const connection: StatewireClient.Connection & { readonly message: string | undefined } = {\n      status: 'standby',\n      reason: 'deferred',\n      get message() {\n        return latest.current.message;\n      },\n      reconnect: () => latest.current.onReconnectRequested?.(),\n      degraded: false,\n    };\n    return {\n      state: undefined,\n      commands: suspendedCommands<TCommands>(),\n      connection,\n      // Context updates while parked are local and must never start a dial.\n      // The live transport receives the current snapshot when it replaces us.\n      setContext: () => {},\n      isBusy: false,\n    };\n  });\n  return value;\n};\n\n/**\n * A statewire transport that never dials.\n *\n * Swapped in for the live WS/SSE transport when attaching is known to be\n * pointless — the host gates it (no workspace) or repeated `unauthorized`\n * denials parked it — so the thread element stays mounted for assistant-ui\n * consumers while the reconnect loop stops entirely.\n */\nexport const StatewireSuspended = resource(useSuspendedStatewire) as <\n  TCommands extends Statewire.Commands = Statewire.Commands,\n>(\n  options: SuspendedStatewireOptions\n) => ResourceElement<Statewire<undefined, TCommands>>;\n"],"names":["StatewireSendError","useRef","useState","resource"],"mappings":";;;;;AAuBA,MAAM,oBAAoB,MAGxB,IAAI,MAAM,IAA0C;AAAA,EAClD,KAAK,CAAC,SAAS,WAAW;AACxB,QAAI,OAAO,WAAW,SAAU,QAAO;AAGvC,WAAO,MACL,QAAQ,OAAO,IAAIA,UAAAA,mBAAmB,EAAE,MAAM,WAAW,OAAO,cAAA,CAAe,CAAC;AAAA,EACpF;AACF,CAAC;AAEH,MAAM,wBAAwB,CAC5B,YACoC;AACpC,QAAM,SAASC,MAAAA,OAAO,OAAO;AAC7B,SAAO,UAAU;AAGjB,QAAM,CAAC,KAAK,IAAIC,MAAAA,SAAS,MAAuC;AAC9D,UAAM,aAAoF;AAAA,MACxF,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,IAAI,UAAU;AACZ,eAAO,OAAO,QAAQ;AAAA,MACxB;AAAA,MACA,WAAW,MAAA;;AAAM,kCAAO,SAAQ,yBAAf;AAAA;AAAA,MACjB,UAAU;AAAA,IAAA;AAEZ,WAAO;AAAA,MACL,OAAO;AAAA,MACP,UAAU,kBAAA;AAAA,MACV;AAAA;AAAA;AAAA,MAGA,YAAY,MAAM;AAAA,MAAC;AAAA,MACnB,QAAQ;AAAA,IAAA;AAAA,EAEZ,CAAC;AACD,SAAO;AACT;AAUO,MAAM,qBAAqBC,IAAAA,SAAS,qBAAqB;;"}

package/dist/agent-runtime/src/statewire-suspended.d.ts

@@ -0,0 +1,27 @@
+import type { ResourceElement } from '@assistant-ui/tap';
+import type { Statewire } from 'statewire';
+export interface SuspendedStatewireOptions {
+    /**
+     * Why the transport is parked; surfaced as the connection message. Omitted
+     * for a park that is part of normal startup rather than a refusal (a
+     * `pending` session lane, whose principal is still loading): the connection
+     * then carries no message and reads like a never-started chat, which hosts
+     * render as ready rather than paused.
+     */
+    message?: string | undefined;
+    /**
+     * Invoked when a surface asks the parked connection to `reconnect()` (the
+     * connection indicator's retry affordance). Hosts that park for a reason
+     * only they can clear (e.g. the user has no workspace) omit it.
+     */
+    onReconnectRequested?: (() => void) | undefined;
+}
+/**
+ * A statewire transport that never dials.
+ *
+ * Swapped in for the live WS/SSE transport when attaching is known to be
+ * pointless — the host gates it (no workspace) or repeated `unauthorized`
+ * denials parked it — so the thread element stays mounted for assistant-ui
+ * consumers while the reconnect loop stops entirely.
+ */
+export declare const StatewireSuspended: <TCommands extends Statewire.Commands = Statewire.Commands>(options: SuspendedStatewireOptions) => ResourceElement<Statewire<undefined, TCommands>>;

package/dist/agent-runtime/src/statewire-suspended.js.map

@@ -1 +1 @@
-{"version":3,"file":"statewire-suspended.js","sources":["../../../../agent-runtime/src/statewire-suspended.ts"],"sourcesContent":["import { resource } from '@assistant-ui/tap';\nimport type { ResourceElement } from '@assistant-ui/tap';\nimport { useRef, useState } from 'react';\nimport type { Statewire, StatewireClient } from 'statewire';\nimport { StatewireSendError } from 'statewire';\n\nexport interface SuspendedStatewireOptions {\n  /** Why the transport is parked; surfaced as the connection message. */\n  message: string;\n  /**\n   * Invoked when a surface asks the parked connection to `reconnect()` (the\n   * connection indicator's retry affordance). Hosts that park for a reason\n   * only they can clear (e.g. the user has no workspace) omit it.\n   */\n  onReconnectRequested?: (() => void) | undefined;\n}\n\nconst suspendedCommands = <\n  TCommands extends Statewire.Commands,\n>(): Statewire.CommandsProxy<TCommands> =>\n  new Proxy({} as Statewire.CommandsProxy<TCommands>, {\n    get: (_target, method) => {\n      if (typeof method !== 'string') return undefined;\n      // Settle like a locally-dead channel: hosts already classify\n      // non-\"server\" causes as channel teardown (quiet log, no user error).\n      return () =>\n        Promise.reject(new StatewireSendError({ fate: 'aborted', cause: 'stream-gone' }));\n    },\n  });\n\nconst useSuspendedStatewire = <TCommands extends Statewire.Commands = Statewire.Commands>(\n  options: SuspendedStatewireOptions\n): Statewire<undefined, TCommands> => {\n  const latest = useRef(options);\n  latest.current = options;\n  // `state` stays undefined so the thread keeps serving its `initialState`\n  // (the same contract a live transport has before its attach snapshot).\n  const [value] = useState((): Statewire<undefined, TCommands> => {\n    const connection: StatewireClient.Connection & { readonly message: string } = {\n      status: 'standby',\n      reason: 'deferred',\n      get message() {\n        return latest.current.message;\n      },\n      reconnect: () => latest.current.onReconnectRequested?.(),\n      degraded: false,\n    };\n    return {\n      state: undefined,\n      commands: suspendedCommands<TCommands>(),\n      connection,\n      // Context updates while parked are local and must never start a dial.\n      // The live transport receives the current snapshot when it replaces us.\n      setContext: () => {},\n      isBusy: false,\n    };\n  });\n  return value;\n};\n\n/**\n * A statewire transport that never dials.\n *\n * Swapped in for the live WS/SSE transport when attaching is known to be\n * pointless — the host gates it (no workspace) or repeated `unauthorized`\n * denials parked it — so the thread element stays mounted for assistant-ui\n * consumers while the reconnect loop stops entirely.\n */\nexport const StatewireSuspended = resource(useSuspendedStatewire) as <\n  TCommands extends Statewire.Commands = Statewire.Commands,\n>(\n  options: SuspendedStatewireOptions\n) => ResourceElement<Statewire<undefined, TCommands>>;\n"],"names":[],"mappings":";;;AAiBA,MAAM,oBAAoB,MAGxB,IAAI,MAAM,IAA0C;AAAA,EAClD,KAAK,CAAC,SAAS,WAAW;AACxB,QAAI,OAAO,WAAW,SAAU,QAAO;AAGvC,WAAO,MACL,QAAQ,OAAO,IAAI,mBAAmB,EAAE,MAAM,WAAW,OAAO,cAAA,CAAe,CAAC;AAAA,EACpF;AACF,CAAC;AAEH,MAAM,wBAAwB,CAC5B,YACoC;AACpC,QAAM,SAAS,OAAO,OAAO;AAC7B,SAAO,UAAU;AAGjB,QAAM,CAAC,KAAK,IAAI,SAAS,MAAuC;AAC9D,UAAM,aAAwE;AAAA,MAC5E,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,IAAI,UAAU;AACZ,eAAO,OAAO,QAAQ;AAAA,MACxB;AAAA,MACA,WAAW,MAAA;;AAAM,kCAAO,SAAQ,yBAAf;AAAA;AAAA,MACjB,UAAU;AAAA,IAAA;AAEZ,WAAO;AAAA,MACL,OAAO;AAAA,MACP,UAAU,kBAAA;AAAA,MACV;AAAA;AAAA;AAAA,MAGA,YAAY,MAAM;AAAA,MAAC;AAAA,MACnB,QAAQ;AAAA,IAAA;AAAA,EAEZ,CAAC;AACD,SAAO;AACT;AAUO,MAAM,qBAAqB,SAAS,qBAAqB;"}
+{"version":3,"file":"statewire-suspended.js","sources":["../../../../agent-runtime/src/statewire-suspended.ts"],"sourcesContent":["import { resource } from '@assistant-ui/tap';\nimport type { ResourceElement } from '@assistant-ui/tap';\nimport { useRef, useState } from 'react';\nimport type { Statewire, StatewireClient } from 'statewire';\nimport { StatewireSendError } from 'statewire';\n\nexport interface SuspendedStatewireOptions {\n  /**\n   * Why the transport is parked; surfaced as the connection message. Omitted\n   * for a park that is part of normal startup rather than a refusal (a\n   * `pending` session lane, whose principal is still loading): the connection\n   * then carries no message and reads like a never-started chat, which hosts\n   * render as ready rather than paused.\n   */\n  message?: string | undefined;\n  /**\n   * Invoked when a surface asks the parked connection to `reconnect()` (the\n   * connection indicator's retry affordance). Hosts that park for a reason\n   * only they can clear (e.g. the user has no workspace) omit it.\n   */\n  onReconnectRequested?: (() => void) | undefined;\n}\n\nconst suspendedCommands = <\n  TCommands extends Statewire.Commands,\n>(): Statewire.CommandsProxy<TCommands> =>\n  new Proxy({} as Statewire.CommandsProxy<TCommands>, {\n    get: (_target, method) => {\n      if (typeof method !== 'string') return undefined;\n      // Settle like a locally-dead channel: hosts already classify\n      // non-\"server\" causes as channel teardown (quiet log, no user error).\n      return () =>\n        Promise.reject(new StatewireSendError({ fate: 'aborted', cause: 'stream-gone' }));\n    },\n  });\n\nconst useSuspendedStatewire = <TCommands extends Statewire.Commands = Statewire.Commands>(\n  options: SuspendedStatewireOptions\n): Statewire<undefined, TCommands> => {\n  const latest = useRef(options);\n  latest.current = options;\n  // `state` stays undefined so the thread keeps serving its `initialState`\n  // (the same contract a live transport has before its attach snapshot).\n  const [value] = useState((): Statewire<undefined, TCommands> => {\n    const connection: StatewireClient.Connection & { readonly message: string | undefined } = {\n      status: 'standby',\n      reason: 'deferred',\n      get message() {\n        return latest.current.message;\n      },\n      reconnect: () => latest.current.onReconnectRequested?.(),\n      degraded: false,\n    };\n    return {\n      state: undefined,\n      commands: suspendedCommands<TCommands>(),\n      connection,\n      // Context updates while parked are local and must never start a dial.\n      // The live transport receives the current snapshot when it replaces us.\n      setContext: () => {},\n      isBusy: false,\n    };\n  });\n  return value;\n};\n\n/**\n * A statewire transport that never dials.\n *\n * Swapped in for the live WS/SSE transport when attaching is known to be\n * pointless — the host gates it (no workspace) or repeated `unauthorized`\n * denials parked it — so the thread element stays mounted for assistant-ui\n * consumers while the reconnect loop stops entirely.\n */\nexport const StatewireSuspended = resource(useSuspendedStatewire) as <\n  TCommands extends Statewire.Commands = Statewire.Commands,\n>(\n  options: SuspendedStatewireOptions\n) => ResourceElement<Statewire<undefined, TCommands>>;\n"],"names":[],"mappings":";;;AAuBA,MAAM,oBAAoB,MAGxB,IAAI,MAAM,IAA0C;AAAA,EAClD,KAAK,CAAC,SAAS,WAAW;AACxB,QAAI,OAAO,WAAW,SAAU,QAAO;AAGvC,WAAO,MACL,QAAQ,OAAO,IAAI,mBAAmB,EAAE,MAAM,WAAW,OAAO,cAAA,CAAe,CAAC;AAAA,EACpF;AACF,CAAC;AAEH,MAAM,wBAAwB,CAC5B,YACoC;AACpC,QAAM,SAAS,OAAO,OAAO;AAC7B,SAAO,UAAU;AAGjB,QAAM,CAAC,KAAK,IAAI,SAAS,MAAuC;AAC9D,UAAM,aAAoF;AAAA,MACxF,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,IAAI,UAAU;AACZ,eAAO,OAAO,QAAQ;AAAA,MACxB;AAAA,MACA,WAAW,MAAA;;AAAM,kCAAO,SAAQ,yBAAf;AAAA;AAAA,MACjB,UAAU;AAAA,IAAA;AAEZ,WAAO;AAAA,MACL,OAAO;AAAA,MACP,UAAU,kBAAA;AAAA,MACV;AAAA;AAAA;AAAA,MAGA,YAAY,MAAM;AAAA,MAAC;AAAA,MACnB,QAAQ;AAAA,IAAA;AAAA,EAEZ,CAAC;AACD,SAAO;AACT;AAUO,MAAM,qBAAqB,SAAS,qBAAqB;"}

package/dist/agent-runtime/src/statewire-transport.d.ts

@@ -0,0 +1,40 @@
+import { type Statewire, type StatewireClient } from 'statewire';
+import type { DeepAgentStreamValues } from './types';
+export type StatewireTransportOptions = StatewireClient.HttpOptions & StatewireClient.WebsocketOptions;
+/**
+ * The application protocol the deep-agent transport stamps on every command.
+ * The thread client must declare the same protocol: statewire's core applies
+ * its optimistic folds only to commands of its own protocol, so a mismatch
+ * leaves a send invisible until the server's frame lands.
+ */
+export declare const DEEP_AGENT_STATEWIRE_PROTOCOL = "athena";
+/** Durable Athena commands keep their schema version across wire upgrades. */
+export declare const DEEP_AGENT_STATEWIRE_PROTOCOL_VERSION = "2026-09-13";
+/**
+ * The wire contract every deep-agent transport offers. Athena's hosts (Python
+ * statewire 0.20) speak 2026-09-30 natively, so no legacy context range is
+ * advertised.
+ */
+export declare const DEEP_AGENT_STATEWIRE_WIRE_VERSION: NonNullable<StatewireTransportOptions['wireVersion']>;
+export type StatewireTransportKind = 'sse' | 'websocket';
+/**
+ * The transport a host gets: SSE when it asks for SSE, WebSocket otherwise.
+ * Whatever instruments the transport must read this too, so it matches the
+ * transport actually built.
+ */
+export declare function resolveStatewireTransportKind({ sse }: {
+    sse: boolean;
+}): StatewireTransportKind;
+/**
+ * Build the deep-agent statewire transport: WebSocket by default, SSE when the
+ * host app's toggle asks for it ({@link resolveStatewireTransportKind}). The
+ * toggle source is host-specific (env var, extension flag, config store), so
+ * the caller resolves it to a boolean.
+ *
+ * `TState` defaults to the deep-agent wire shape: the thread mounts that make
+ * up nearly every caller get a typed state without naming it, and the other
+ * mounts (the conversation index) name theirs.
+ */
+export declare const statewireTransport: <TState = DeepAgentStreamValues, TCommands extends Statewire.Commands = Statewire.Commands>(options: StatewireTransportOptions, { sse }?: {
+    sse?: boolean;
+}) => import("@assistant-ui/tap").ResourceElement<Statewire<TState | undefined, TCommands>>;