@athenaintel/react 0.57.2 → 0.60.0

package/dist/agent-runtime/src/use-deep-agent-chat-outbox.js

@@ -5,14 +5,14 @@ function useDeepAgentChatOutbox({
   client,
   threadId,
   isNewChat,
-  store,
+  directory,
+  legacy,
   reachability,
   foreground,
   restore,
   openThread,
   onEvent,
   checkAttachments,
-  sendGate,
   enabled = true,
   countdownMs
 }) {
@@ -28,9 +28,6 @@ function useDeepAgentChatOutbox({
   const checkAttachmentsRef = useRef(checkAttachments);
   checkAttachmentsRef.current = checkAttachments;
   const checksAttachments = checkAttachments !== void 0;
-  const sendGateRef = useRef(sendGate);
-  sendGateRef.current = sendGate;
-  const gatesSends = sendGate !== void 0;
   const reachabilityRef = useRef(reachability);
   reachabilityRef.current = reachability;
   const foregroundRef = useRef(foreground);
@@ -55,7 +52,11 @@ function useDeepAgentChatOutbox({
   const isNewChatRef = useRef(isNewChat);
   isNewChatRef.current = isNewChat;
   const [outbox, setOutbox] = useState(null);
+  const legacyRef = useRef(legacy);
+  legacyRef.current = legacy;
+  const migrates = legacy !== void 0;
   useEffect(() => {
+    var _a;
     if (!enabled || !threadId) {
       setOutbox(null);
       return void 0;
@@ -64,7 +65,39 @@ function useDeepAgentChatOutbox({
       threadId,
       // Read at each hold: a chat that starts while mounted stamps its later messages as started.
       isNewChat: () => isNewChatRef.current,
-      store,
+      ...directory && { directory },
+      ...migrates && {
+        legacy: {
+          reader: {
+            listAll: () => {
+              var _a2;
+              return ((_a2 = legacyRef.current) == null ? void 0 : _a2.reader.listAll()) ?? Promise.resolve([]);
+            },
+            list: (id) => {
+              var _a2;
+              return ((_a2 = legacyRef.current) == null ? void 0 : _a2.reader.list(id)) ?? Promise.resolve([]);
+            },
+            count: () => {
+              var _a2;
+              return ((_a2 = legacyRef.current) == null ? void 0 : _a2.reader.count()) ?? Promise.resolve(0);
+            },
+            remove: (id, messageId) => {
+              var _a2;
+              return ((_a2 = legacyRef.current) == null ? void 0 : _a2.reader.remove(id, messageId)) ?? Promise.resolve();
+            },
+            clear: () => {
+              var _a2;
+              return ((_a2 = legacyRef.current) == null ? void 0 : _a2.reader.clear()) ?? Promise.resolve();
+            }
+          },
+          ...((_a = legacyRef.current) == null ? void 0 : _a.isKept) !== void 0 && {
+            isKept: (id, messageId) => {
+              var _a2, _b;
+              return ((_b = (_a2 = legacyRef.current) == null ? void 0 : _a2.isKept) == null ? void 0 : _b.call(_a2, id, messageId)) ?? Promise.resolve(false);
+            }
+          }
+        }
+      },
       reachability: stableSignals.reachability,
       foreground: stableSignals.foreground,
       thread: {
@@ -79,34 +112,18 @@ function useDeepAgentChatOutbox({
       restore: (entry) => restoreRef.current(entry),
       ...canOpenThreads && {
         openThread: (target) => {
-          var _a;
-          return (_a = openThreadRef.current) == null ? void 0 : _a.call(openThreadRef, target);
+          var _a2;
+          return (_a2 = openThreadRef.current) == null ? void 0 : _a2.call(openThreadRef, target);
         }
       },
       onEvent: (event) => {
-        var _a;
-        return (_a = onEventRef.current) == null ? void 0 : _a.call(onEventRef, event);
+        var _a2;
+        return (_a2 = onEventRef.current) == null ? void 0 : _a2.call(onEventRef, event);
       },
       ...checksAttachments && {
         checkAttachments: (attachments) => {
-          var _a;
-          return ((_a = checkAttachmentsRef.current) == null ? void 0 : _a.call(checkAttachmentsRef, attachments)) ?? Promise.resolve("ok");
-        }
-      },
-      ...gatesSends && {
-        sendGate: {
-          keyOf: (entry) => {
-            var _a;
-            return ((_a = sendGateRef.current) == null ? void 0 : _a.keyOf(entry)) ?? "";
-          },
-          mayHandOff: (entry) => {
-            var _a;
-            return ((_a = sendGateRef.current) == null ? void 0 : _a.mayHandOff(entry)) ?? true;
-          },
-          subscribe: (listener) => {
-            var _a;
-            return ((_a = sendGateRef.current) == null ? void 0 : _a.subscribe(listener)) ?? (() => void 0);
-          }
+          var _a2;
+          return ((_a2 = checkAttachmentsRef.current) == null ? void 0 : _a2.call(checkAttachmentsRef, attachments)) ?? Promise.resolve("ok");
         }
       },
       ...countdownMs !== void 0 && { countdownMs }
@@ -116,7 +133,7 @@ function useDeepAgentChatOutbox({
       created.dispose();
       setOutbox((current) => current === created ? null : current);
     };
-  }, [enabled, threadId, store, countdownMs, canOpenThreads, checksAttachments, gatesSends]);
+  }, [enabled, threadId, directory, countdownMs, canOpenThreads, checksAttachments, migrates]);
   return outbox !== null && outbox.threadId === threadId ? outbox : null;
 }
 const EMPTY_SNAPSHOT = {

package/dist/agent-runtime/src/use-deep-agent-chat-outbox.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-deep-agent-chat-outbox.js","sources":["../../../../agent-runtime/src/use-deep-agent-chat-outbox.ts"],"sourcesContent":["import {\n  type Context,\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from \"react\";\nimport type { ChatOutboxAttachmentCheck } from \"./chat-outbox-attachments\";\nimport {\n  type ChatOutbox,\n  type ChatOutboxCommandUpdate,\n  type ChatOutboxEvent,\n  type ChatOutboxSendGate,\n  type ChatOutboxSignal,\n  type ChatOutboxSnapshot,\n  createChatOutbox,\n} from \"./chat-outbox\";\nimport type { ChatOutboxEntry, ChatOutboxStore } from \"./chat-outbox-store\";\nimport { type ChatOutboxClientHost, createStatewireChatOutboxPort } from \"./chat-outbox-thread\";\n\nexport interface UseDeepAgentChatOutboxOptions {\n  /** The thread's assistant-ui client (`useDeepAgentRuntime`'s result). */\n  client: ChatOutboxClientHost;\n  threadId: string;\n  /** The conversation has never started (a new chat). */\n  isNewChat: boolean;\n  /**\n   * This person's outbox store, one per person for the life of the page or app (a message the\n   * device cannot keep waits in its memory, across thread switches); `null` keeps waiting messages\n   * in this outbox alone.\n   */\n  store: ChatOutboxStore | null;\n  /** Athena's reachability (the host's own model: the browser online AND agora answering). */\n  reachability: ChatOutboxSignal;\n  /** The app is in front (a visible tab, an active app, a focused desktop window). */\n  foreground: ChatOutboxSignal;\n  /** Give a cancelled message's text back to the composer. */\n  restore: (entry: ChatOutboxEntry) => void;\n  /**\n   * Open another of the person's conversations holding waiting messages (the tray's Open); omit\n   * it where the host cannot switch conversations.\n   */\n  openThread?: (target: { threadId: string; newChat: boolean }) => void;\n  onEvent?: (event: ChatOutboxEvent) => void;\n  /**\n   * Asks Athena whether a waiting message's attachments can still be opened, right before it goes\n   * (`createChatOutboxAttachmentCheck`); omitted, attachments go unchecked.\n   */\n  checkAttachments?: ChatOutboxAttachmentCheck;\n  /**\n   * Which waiting messages go together, and when (`ChatOutboxOptions.sendGate`): a host whose\n   * messages carry per-send settings keeps a message with other settings than a send the\n   * conversation has not taken yet waiting until it has. Read through a ref: a host may rebuild it.\n   */\n  sendGate?: ChatOutboxSendGate;\n  /** Off: no outbox (a read-only or suspended surface); sends behave as before. */\n  enabled?: boolean;\n  /** The countdown before a waiting message is sent (tests); defaults to `CHAT_OUTBOX_COUNTDOWN_MS`. */\n  countdownMs?: number;\n}\n\n/**\n * The chat outbox for the mounted thread (`chat-outbox.ts`), one per thread and store: a thread\n * switch disposes it and makes the next thread's. The host forwards statewire's command lifecycle\n * to {@link ChatOutbox.observeCommand} (its `useDeepAgentRuntime` `onCommandChange`), shares the\n * instance through {@link DeepAgentChatOutboxContext}, and has its composer call\n * {@link ChatOutbox.shouldHold} / {@link ChatOutbox.hold} before sending.\n */\nexport function useDeepAgentChatOutbox({\n  client,\n  threadId,\n  isNewChat,\n  store,\n  reachability,\n  foreground,\n  restore,\n  openThread,\n  onEvent,\n  checkAttachments,\n  sendGate,\n  enabled = true,\n  countdownMs,\n}: UseDeepAgentChatOutboxOptions): ChatOutbox | null {\n  const clientRef = useRef(client);\n  clientRef.current = client;\n  const restoreRef = useRef(restore);\n  restoreRef.current = restore;\n  const openThreadRef = useRef(openThread);\n  openThreadRef.current = openThread;\n  const canOpenThreads = openThread !== undefined;\n  const onEventRef = useRef(onEvent);\n  onEventRef.current = onEvent;\n  const checkAttachmentsRef = useRef(checkAttachments);\n  checkAttachmentsRef.current = checkAttachments;\n  const checksAttachments = checkAttachments !== undefined;\n  const sendGateRef = useRef(sendGate);\n  sendGateRef.current = sendGate;\n  const gatesSends = sendGate !== undefined;\n  const reachabilityRef = useRef(reachability);\n  reachabilityRef.current = reachability;\n  const foregroundRef = useRef(foreground);\n  foregroundRef.current = foreground;\n  // The client's notifications reach the port through this set, so a client whose identity\n  // changes mid-thread is followed without remaking the outbox (and losing its countdown).\n  const [threadListeners] = useState(() => new Set<() => void>());\n  // A host without an outbox (`enabled` false) is never subscribed to.\n  useEffect(() => {\n    if (!enabled) return undefined;\n    return client.subscribe(() => {\n      for (const listener of threadListeners) listener();\n    });\n  }, [client, threadListeners, enabled]);\n  // Signals read through refs for the same reason: a host rebuilding its signal objects per render\n  // never remakes the outbox.\n  const [stableSignals] = useState(() => {\n    const forward = (pick: () => ChatOutboxSignal): ChatOutboxSignal => ({\n      get: () => pick().get(),\n      subscribe: (listener) => pick().subscribe(listener),\n    });\n    return {\n      reachability: forward(() => reachabilityRef.current),\n      foreground: forward(() => foregroundRef.current),\n    };\n  });\n  const isNewChatRef = useRef(isNewChat);\n  isNewChatRef.current = isNewChat;\n\n  const [outbox, setOutbox] = useState<ChatOutbox | null>(null);\n  // Made in an effect, not during render: the outbox subscribes to its signals and reads its\n  // store, and a render React throws away must not leave those behind.\n  // biome-ignore lint/correctness/useExhaustiveDependencies: one outbox per thread and store; everything else is read through refs.\n  useEffect(() => {\n    if (!enabled || !threadId) {\n      setOutbox(null);\n      return undefined;\n    }\n    const created = createChatOutbox({\n      threadId,\n      // Read at each hold: a chat that starts while mounted stamps its later messages as started.\n      isNewChat: () => isNewChatRef.current,\n      store,\n      reachability: stableSignals.reachability,\n      foreground: stableSignals.foreground,\n      thread: {\n        ...createStatewireChatOutboxPort({ client: () => clientRef.current }),\n        subscribe: (listener) => {\n          threadListeners.add(listener);\n          return () => {\n            threadListeners.delete(listener);\n          };\n        },\n      },\n      restore: (entry) => restoreRef.current(entry),\n      ...(canOpenThreads && {\n        openThread: (target: { threadId: string; newChat: boolean }) => openThreadRef.current?.(target),\n      }),\n      onEvent: (event) => onEventRef.current?.(event),\n      ...(checksAttachments && {\n        checkAttachments: (attachments: Parameters<ChatOutboxAttachmentCheck>[0]) =>\n          checkAttachmentsRef.current?.(attachments) ?? Promise.resolve(\"ok\" as const),\n      }),\n      ...(gatesSends && {\n        sendGate: {\n          keyOf: (entry: ChatOutboxEntry) => sendGateRef.current?.keyOf(entry) ?? \"\",\n          mayHandOff: (entry: ChatOutboxEntry) => sendGateRef.current?.mayHandOff(entry) ?? true,\n          subscribe: (listener: () => void) => sendGateRef.current?.subscribe(listener) ?? (() => undefined),\n        },\n      }),\n      ...(countdownMs !== undefined && { countdownMs }),\n    });\n    setOutbox(created);\n    return () => {\n      created.dispose();\n      setOutbox((current) => (current === created ? null : current));\n    };\n  }, [enabled, threadId, store, countdownMs, canOpenThreads, checksAttachments, gatesSends]);\n  // During a thread switch's first render the previous thread's outbox is still in state.\n  return outbox !== null && outbox.threadId === threadId ? outbox : null;\n}\n\nconst EMPTY_SNAPSHOT: ChatOutboxSnapshot = {\n  rows: [],\n  countdownEndsAt: null,\n  durable: true,\n  loaded: true,\n  elsewhere: [],\n};\nconst noopSubscribe = () => () => undefined;\n\n/** The outbox's rows and countdown, re-rendering on every change (`null` outbox: nothing waits). */\nexport function useChatOutboxSnapshot(outbox: ChatOutbox | null): ChatOutboxSnapshot {\n  return useSyncExternalStore(\n    outbox ? outbox.subscribe : noopSubscribe,\n    () => outbox?.getSnapshot() ?? EMPTY_SNAPSHOT,\n    () => outbox?.getSnapshot() ?? EMPTY_SNAPSHOT,\n  );\n}\n\n/**\n * Whether Athena can be reached, as the thread's outbox reads it: `true` without an outbox (a host\n * that keeps none sends and edits as before). What a sent message's Edit is offered on; a boolean,\n * so a reader re-renders only when it flips.\n */\nexport function useChatOutboxReachable(outbox: ChatOutbox | null): boolean {\n  const subscribe = useCallback(\n    (listener: () => void) => (outbox ? outbox.reachability.subscribe(listener) : () => undefined),\n    [outbox],\n  );\n  const reachable = () => outbox?.reachability.get() ?? true;\n  return useSyncExternalStore(subscribe, reachable, reachable);\n}\n\n/**\n * The context lives on `globalThis`, not in module scope, because two copies of this module can\n * run in one page: the SDK bundles agent-runtime into its dist while a host such as Olympus imports\n * agent-runtime directly. The host provides its thread's outbox through its own copy and mounts the\n * SDK's queue tray, which reads it through the SDK's copy: one context per copy, and the tray would\n * never see a waiting message (`asset-attachment.ts` shares its registry the same way).\n */\nconst CHAT_OUTBOX_CONTEXT = Symbol.for(\"@athenaintel/agent-runtime/deep-agent-chat-outbox-context\");\n\ntype ChatOutboxContextHost = typeof globalThis & {\n  [CHAT_OUTBOX_CONTEXT]?: Context<ChatOutbox | null>;\n};\n\nfunction sharedChatOutboxContext(): Context<ChatOutbox | null> {\n  const host = globalThis as ChatOutboxContextHost;\n  return (host[CHAT_OUTBOX_CONTEXT] ??= createContext<ChatOutbox | null>(null));\n}\n\n/** The mounted thread's chat outbox, shared from its runtime provider to its composer and tray. */\nexport const DeepAgentChatOutboxContext: Context<ChatOutbox | null> = sharedChatOutboxContext();\n\nexport function useDeepAgentChatOutboxContext(): ChatOutbox | null {\n  return useContext(DeepAgentChatOutboxContext);\n}\n\n/** Forward statewire's command lifecycle to an outbox held in a ref (the runtime is made first). */\nexport function forwardChatOutboxCommand(\n  outbox: { current: ChatOutbox | null },\n  update: ChatOutboxCommandUpdate,\n): void {\n  outbox.current?.observeCommand(update);\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-deep-agent-chat-outbox.js","sources":["../../../../agent-runtime/src/use-deep-agent-chat-outbox.ts"],"sourcesContent":["import {\n  type Context,\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from \"react\";\nimport type { ChatOutboxAttachmentCheck } from \"./chat-outbox-attachments\";\nimport {\n  type ChatOutbox,\n  type ChatOutboxEvent,\n  type ChatOutboxLegacyOptions,\n  type ChatOutboxSignal,\n  type ChatOutboxSnapshot,\n  createChatOutbox,\n} from \"./chat-outbox\";\nimport type { ChatOutboxEntry } from \"./chat-outbox-entry\";\nimport type { ChatOutboxDirectory } from \"./chat-outbox-storage\";\nimport { type ChatOutboxClientHost, createStatewireChatOutboxPort } from \"./chat-outbox-thread\";\n\nexport interface UseDeepAgentChatOutboxOptions {\n  /** The thread's assistant-ui client (`useDeepAgentRuntime`'s result). */\n  client: ChatOutboxClientHost;\n  threadId: string;\n  /** The conversation has never started (a new chat). */\n  isNewChat: boolean;\n  /**\n   * Every thread's waiting messages (`createChatOutboxDirectory`, one per person over the same\n   * backend, namespace and codec as the thread sessions): the tray's other conversations.\n   */\n  directory?: ChatOutboxDirectory;\n  /** The previous store (`createLegacyChatOutboxReader`): this thread's records move into its outbox. */\n  legacy?: ChatOutboxLegacyOptions;\n  /** Athena's reachability (the host's own model: the browser online AND agora answering). */\n  reachability: ChatOutboxSignal;\n  /** The app is in front (a visible tab, an active app, a focused desktop window). */\n  foreground: ChatOutboxSignal;\n  /** Give a cancelled message's text back to the composer. */\n  restore: (entry: ChatOutboxEntry) => void;\n  /**\n   * Open another of the person's conversations holding waiting messages (the tray's Open); omit\n   * it where the host cannot switch conversations.\n   */\n  openThread?: (target: { threadId: string; newChat: boolean }) => void;\n  onEvent?: (event: ChatOutboxEvent) => void;\n  /**\n   * Asks Athena whether a waiting message's attachments can still be opened, right before it goes\n   * (`createChatOutboxAttachmentCheck`); omitted, attachments go unchecked.\n   */\n  checkAttachments?: ChatOutboxAttachmentCheck;\n  /** Off: no outbox (a read-only or suspended surface, a thread without a session); sends behave as before. */\n  enabled?: boolean;\n  /** The countdown before a waiting message is sent (tests); defaults to `CHAT_OUTBOX_COUNTDOWN_MS`. */\n  countdownMs?: number;\n}\n\n/**\n * The chat outbox for the mounted thread (`chat-outbox.ts`), one per thread: a thread switch\n * disposes it and makes the next thread's. It reads the thread's statewire outbox\n * (`extras.outbox`), so the thread must mount a session (`useDeepAgentRuntime`'s `session`). The\n * host shares the instance through {@link DeepAgentChatOutboxContext} and has its composer call\n * {@link ChatOutbox.shouldHold} / {@link ChatOutbox.hold} before sending.\n */\nexport function useDeepAgentChatOutbox({\n  client,\n  threadId,\n  isNewChat,\n  directory,\n  legacy,\n  reachability,\n  foreground,\n  restore,\n  openThread,\n  onEvent,\n  checkAttachments,\n  enabled = true,\n  countdownMs,\n}: UseDeepAgentChatOutboxOptions): ChatOutbox | null {\n  const clientRef = useRef(client);\n  clientRef.current = client;\n  const restoreRef = useRef(restore);\n  restoreRef.current = restore;\n  const openThreadRef = useRef(openThread);\n  openThreadRef.current = openThread;\n  const canOpenThreads = openThread !== undefined;\n  const onEventRef = useRef(onEvent);\n  onEventRef.current = onEvent;\n  const checkAttachmentsRef = useRef(checkAttachments);\n  checkAttachmentsRef.current = checkAttachments;\n  const checksAttachments = checkAttachments !== undefined;\n  const reachabilityRef = useRef(reachability);\n  reachabilityRef.current = reachability;\n  const foregroundRef = useRef(foreground);\n  foregroundRef.current = foreground;\n  // The client's notifications reach the port through this set, so a client whose identity\n  // changes mid-thread is followed without remaking the outbox (and losing its countdown).\n  const [threadListeners] = useState(() => new Set<() => void>());\n  // A host without an outbox (`enabled` false) is never subscribed to.\n  useEffect(() => {\n    if (!enabled) return undefined;\n    return client.subscribe(() => {\n      for (const listener of threadListeners) listener();\n    });\n  }, [client, threadListeners, enabled]);\n  // Signals read through refs for the same reason: a host rebuilding its signal objects per render\n  // never remakes the outbox.\n  const [stableSignals] = useState(() => {\n    const forward = (pick: () => ChatOutboxSignal): ChatOutboxSignal => ({\n      get: () => pick().get(),\n      subscribe: (listener) => pick().subscribe(listener),\n    });\n    return {\n      reachability: forward(() => reachabilityRef.current),\n      foreground: forward(() => foregroundRef.current),\n    };\n  });\n  const isNewChatRef = useRef(isNewChat);\n  isNewChatRef.current = isNewChat;\n\n  const [outbox, setOutbox] = useState<ChatOutbox | null>(null);\n  const legacyRef = useRef(legacy);\n  legacyRef.current = legacy;\n  const migrates = legacy !== undefined;\n  // Made in an effect, not during render: the outbox subscribes to its signals and its thread, and\n  // a render React throws away must not leave those behind.\n  // biome-ignore lint/correctness/useExhaustiveDependencies: one outbox per thread and directory; everything else is read through refs.\n  useEffect(() => {\n    if (!enabled || !threadId) {\n      setOutbox(null);\n      return undefined;\n    }\n    const created = createChatOutbox({\n      threadId,\n      // Read at each hold: a chat that starts while mounted stamps its later messages as started.\n      isNewChat: () => isNewChatRef.current,\n      ...(directory && { directory }),\n      ...(migrates && {\n        legacy: {\n          reader: {\n            listAll: () => legacyRef.current?.reader.listAll() ?? Promise.resolve([]),\n            list: (id: string) => legacyRef.current?.reader.list(id) ?? Promise.resolve([]),\n            count: () => legacyRef.current?.reader.count() ?? Promise.resolve(0),\n            remove: (id: string, messageId: string) =>\n              legacyRef.current?.reader.remove(id, messageId) ?? Promise.resolve(),\n            clear: () => legacyRef.current?.reader.clear() ?? Promise.resolve(),\n          },\n          ...(legacyRef.current?.isKept !== undefined && {\n            isKept: (id: string, messageId: string) =>\n              legacyRef.current?.isKept?.(id, messageId) ?? Promise.resolve(false),\n          }),\n        },\n      }),\n      reachability: stableSignals.reachability,\n      foreground: stableSignals.foreground,\n      thread: {\n        ...createStatewireChatOutboxPort({ client: () => clientRef.current }),\n        subscribe: (listener) => {\n          threadListeners.add(listener);\n          return () => {\n            threadListeners.delete(listener);\n          };\n        },\n      },\n      restore: (entry) => restoreRef.current(entry),\n      ...(canOpenThreads && {\n        openThread: (target: { threadId: string; newChat: boolean }) => openThreadRef.current?.(target),\n      }),\n      onEvent: (event) => onEventRef.current?.(event),\n      ...(checksAttachments && {\n        checkAttachments: (attachments: Parameters<ChatOutboxAttachmentCheck>[0]) =>\n          checkAttachmentsRef.current?.(attachments) ?? Promise.resolve(\"ok\" as const),\n      }),\n      ...(countdownMs !== undefined && { countdownMs }),\n    });\n    setOutbox(created);\n    return () => {\n      created.dispose();\n      setOutbox((current) => (current === created ? null : current));\n    };\n  }, [enabled, threadId, directory, countdownMs, canOpenThreads, checksAttachments, migrates]);\n  // During a thread switch's first render the previous thread's outbox is still in state.\n  return outbox !== null && outbox.threadId === threadId ? outbox : null;\n}\n\nconst EMPTY_SNAPSHOT: ChatOutboxSnapshot = {\n  rows: [],\n  countdownEndsAt: null,\n  durable: true,\n  loaded: true,\n  elsewhere: [],\n};\nconst noopSubscribe = () => () => undefined;\n\n/** The outbox's rows and countdown, re-rendering on every change (`null` outbox: nothing waits). */\nexport function useChatOutboxSnapshot(outbox: ChatOutbox | null): ChatOutboxSnapshot {\n  return useSyncExternalStore(\n    outbox ? outbox.subscribe : noopSubscribe,\n    () => outbox?.getSnapshot() ?? EMPTY_SNAPSHOT,\n    () => outbox?.getSnapshot() ?? EMPTY_SNAPSHOT,\n  );\n}\n\n/**\n * Whether Athena can be reached, as the thread's outbox reads it: `true` without an outbox (a host\n * that keeps none sends and edits as before). What a sent message's Edit is offered on; a boolean,\n * so a reader re-renders only when it flips.\n */\nexport function useChatOutboxReachable(outbox: ChatOutbox | null): boolean {\n  const subscribe = useCallback(\n    (listener: () => void) => (outbox ? outbox.reachability.subscribe(listener) : () => undefined),\n    [outbox],\n  );\n  const reachable = () => outbox?.reachability.get() ?? true;\n  return useSyncExternalStore(subscribe, reachable, reachable);\n}\n\n/**\n * The context lives on `globalThis`, not in module scope, because two copies of this module can\n * run in one page: the SDK bundles agent-runtime into its dist while a host such as Olympus imports\n * agent-runtime directly. The host provides its thread's outbox through its own copy and mounts the\n * SDK's queue tray, which reads it through the SDK's copy: one context per copy, and the tray would\n * never see a waiting message (`asset-attachment.ts` shares its registry the same way).\n */\nconst CHAT_OUTBOX_CONTEXT = Symbol.for(\"@athenaintel/agent-runtime/deep-agent-chat-outbox-context\");\n\ntype ChatOutboxContextHost = typeof globalThis & {\n  [CHAT_OUTBOX_CONTEXT]?: Context<ChatOutbox | null>;\n};\n\nfunction sharedChatOutboxContext(): Context<ChatOutbox | null> {\n  const host = globalThis as ChatOutboxContextHost;\n  return (host[CHAT_OUTBOX_CONTEXT] ??= createContext<ChatOutbox | null>(null));\n}\n\n/** The mounted thread's chat outbox, shared from its runtime provider to its composer and tray. */\nexport const DeepAgentChatOutboxContext: Context<ChatOutbox | null> = sharedChatOutboxContext();\n\nexport function useDeepAgentChatOutboxContext(): ChatOutbox | null {\n  return useContext(DeepAgentChatOutboxContext);\n}\n"],"names":["_a"],"mappings":"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"}

package/dist/agent-runtime/src/use-deep-agent-runtime.cjs

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const tap = require("@assistant-ui/tap");
 const require$$0 = require("react");
+const chatOutboxPolicy = require("./chat-outbox-policy.cjs");
 const errors = require("./errors.cjs");
 const modelContext = require("./model-context.cjs");
 const quotaSafeLocalStorageSession = require("./quota-safe-local-storage-session.cjs");
 const sendRecovery = require("./send-recovery.cjs");
 const sessionLaneScope = require("./session-lane-scope.cjs");
-const threadExtras = require("./thread-extras.cjs");
+const statewireHeldSends = require("./statewire-held-sends.cjs");
 const useDeepAgentConfig = require("./use-deep-agent-config.cjs");
 const useDeepAgentThread = require("./use-deep-agent-thread.cjs");
 function pendingSessionAttachKey(attachKey) {
@@ -38,6 +40,14 @@ function loadSessionRecord(store) {
     return null;
   }
 }
+const ObservedSessionStorage = tap.resource(function useObservedSessionStorage({
+  element,
+  observe
+}) {
+  const store = tap.useResource(element);
+  observe(store);
+  return store;
+});
 function logUnhandledStatewireError(surface, error) {
   if (errors.isStatewireChannelTeardown(error)) {
     console.debug(`[${surface}] statewire channel teardown:`, error);
@@ -49,6 +59,9 @@ function logUnhandledStatewireError(surface, error) {
   }
   console.error(`[${surface}] statewire transport error:`, error);
 }
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && typeof value.then === "function";
+}
 function useDeepAgentRuntime(options) {
   const {
     surface,
@@ -56,6 +69,7 @@ function useDeepAgentRuntime(options) {
     useClient,
     runConfig,
     onBeforeSendRetry,
+    foreground,
     onError,
     onStateChange,
     onCommandChange,
@@ -70,18 +84,43 @@ function useDeepAgentRuntime(options) {
   onStateChangeRef.current = onStateChange;
   const onCommandChangeRef = require$$0.useRef(onCommandChange);
   onCommandChangeRef.current = onCommandChange;
+  const foregroundRef = require$$0.useRef(foreground);
+  foregroundRef.current = foreground;
+  const holdsHiddenReloads = foreground !== void 0;
   const diagnosticsRef = require$$0.useRef(threadOptions.diagnostics);
   diagnosticsRef.current = threadOptions.diagnostics;
   const onBeforeSendRetryRef = require$$0.useRef(onBeforeSendRetry);
   onBeforeSendRetryRef.current = onBeforeSendRetry;
   const clientRef = require$$0.useRef(null);
+  const storageSessionRef = require$$0.useRef(null);
+  const observeStorageSession = require$$0.useRef((store) => {
+    storageSessionRef.current = store;
+  }).current;
   const failureStampsRef = require$$0.useRef(
     void 0
   );
-  failureStampsRef.current = session === false || session.kind === "pending" ? void 0 : session.kind === "local-storage" ? canPersistLocalSession ? () => quotaSafeLocalStorageSession.readPersistedFailedSendStamps(session.key(threadOptions.threadId)) : void 0 : () => quotaSafeLocalStorageSession.readFailedSendStampsFromRecord(loadSessionRecord(session.store));
+  failureStampsRef.current = session === false || session.kind === "pending" ? void 0 : session.kind === "local-storage" ? canPersistLocalSession ? () => quotaSafeLocalStorageSession.readPersistedFailedSendStamps(
+    quotaSafeLocalStorageSession.localStorageSessionKey({
+      namespace: session.namespace,
+      principal: session.principal,
+      threadId: threadOptions.threadId
+    })
+  ) : void 0 : session.kind === "session-store" ? () => quotaSafeLocalStorageSession.readFailedSendStampsFromRecord(loadSessionRecord(session.store)) : session.kind === "storage" ? () => {
+    const store = storageSessionRef.current;
+    return store ? quotaSafeLocalStorageSession.readFailedSendStampsFromRecord(loadSessionRecord(store)) : null;
+  } : void 0;
   const sessionPending = session !== false && session.kind === "pending";
   const attachKey = sessionPending ? pendingSessionAttachKey(threadOptions.attachKey) : threadOptions.attachKey;
-  const laneKey = session !== false && session.kind === "local-storage" ? session.key : null;
+  const laneNamespace = session !== false && session.kind === "local-storage" ? session.namespace : null;
+  const lanePrincipal = session !== false && session.kind === "local-storage" ? session.principal : null;
+  const laneKey = require$$0.useMemo(
+    () => laneNamespace === null || lanePrincipal === null ? null : (threadId) => quotaSafeLocalStorageSession.localStorageSessionKey({
+      namespace: laneNamespace,
+      principal: lanePrincipal,
+      threadId
+    }),
+    [laneNamespace, lanePrincipal]
+  );
   const [laneEpochState, setLaneEpochState] = require$$0.useState(
     () => sessionLaneScope.nextSessionLaneEpoch({
       previous: sessionLaneScope.INITIAL_SESSION_LANE_EPOCH,
@@ -99,10 +138,10 @@ function useDeepAgentRuntime(options) {
   const attachId = useDeepAgentThread.deepAgentAttachId({ threadId: threadOptions.threadId, attachKey, laneEpoch });
   const sendRecovery$1 = require$$0.useMemo(
     () => sendRecovery.createDeepAgentSendRecovery({
-      lane: () => {
+      outbox: () => {
         const client2 = clientRef.current;
         if (!client2) return null;
-        return threadExtras.readStatewireFailedSendLane(client2.thread().getState().extras);
+        return statewireHeldSends.readStatewireOutbox(client2.thread().getState().extras);
       },
       failureStamps: () => {
         var _a;
@@ -138,21 +177,51 @@ function useDeepAgentRuntime(options) {
       storage: {
         session: quotaSafeLocalStorageSession.QuotaSafeLocalStorageSession({
           threadId: threadOptions.threadId,
-          key: session.key,
+          namespace: session.namespace,
+          principal: session.principal,
+          ...session.unscopedPrefix !== void 0 && { unscopedPrefix: session.unscopedPrefix },
           ...session.onStorageDegraded === void 0 ? {} : { onStorageDegraded: session.onStorageDegraded }
         })
       }
     },
     ...session !== false && session.kind === "session-store" && { sessionStore: session.store },
+    ...session !== false && session.kind === "storage" && {
+      storage: {
+        session: ObservedSessionStorage({
+          element: session.session(threadOptions.threadId),
+          observe: observeStorageSession
+        })
+      }
+    },
+    ...holdsHiddenReloads && {
+      onFlush: chatOutboxPolicy.createChatOutboxFlushPolicy({
+        foreground: () => {
+          var _a;
+          return ((_a = foregroundRef.current) == null ? void 0 : _a.get()) ?? true;
+        },
+        outbox: () => {
+          var _a;
+          const client2 = clientRef.current;
+          if (!client2) return null;
+          const outbox = (_a = client2.thread().getState().extras) == null ? void 0 : _a.outbox;
+          return outbox && typeof outbox.hold === "function" ? outbox : null;
+        }
+      })
+    },
     onStateChange: (state, ctx) => {
       var _a;
-      sendRecoveryRef.current.observeStateChange(state);
       (_a = onStateChangeRef.current) == null ? void 0 : _a.call(onStateChangeRef, state, ctx);
     },
+    // A durable `settled` update is acked once the returned promise resolves:
+    // the host's handler and send recovery both finish before it is.
     onCommandChange: (update, ctx) => {
       var _a;
-      sendRecoveryRef.current.observeCommand(update);
-      (_a = onCommandChangeRef.current) == null ? void 0 : _a.call(onCommandChangeRef, update, ctx);
+      const recovered = sendRecoveryRef.current.onCommandChange(update, ctx);
+      const observed = (_a = onCommandChangeRef.current) == null ? void 0 : _a.call(onCommandChangeRef, update, ctx);
+      if (recovered === void 0 && !isPromiseLike(observed)) return observed;
+      const settled = Promise.all([recovered, observed]).then(() => void 0);
+      settled.catch(() => void 0);
+      return settled;
     },
     onError: (error) => {
       const handler = onErrorRef.current;
@@ -165,11 +234,6 @@ function useDeepAgentRuntime(options) {
   });
   const client = useClient(thread);
   clientRef.current = client;
-  require$$0.useEffect(() => {
-    const unsubscribe = client.subscribe(() => sendRecovery$1.observeFailedLaneChange());
-    sendRecovery$1.observeFailedLaneChange();
-    return unsubscribe;
-  }, [client, sendRecovery$1]);
   const getRunConfigRef = require$$0.useRef(runConfig == null ? void 0 : runConfig.get);
   getRunConfigRef.current = runConfig == null ? void 0 : runConfig.get;
   const hasRunConfig = runConfig !== void 0;

package/dist/agent-runtime/src/use-deep-agent-runtime.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-deep-agent-runtime.cjs","sources":["../../../../agent-runtime/src/use-deep-agent-runtime.ts"],"sourcesContent":["import { useEffect, useMemo, useRef, useState } from 'react';\nimport { isStatewireChannelTeardown } from './errors';\nimport { type DeepAgentModelContextHost, registerDeepAgentRunConfig } from './model-context';\nimport {\n  isStorageQuotaError,\n  QuotaSafeLocalStorageSession,\n  readFailedSendStampsFromRecord,\n  readPersistedFailedSendStamps,\n  type SessionStorageDegradation,\n} from './quota-safe-local-storage-session';\nimport { createDeepAgentSendRecovery } from './send-recovery';\nimport { INITIAL_SESSION_LANE_EPOCH, nextSessionLaneEpoch } from './session-lane-scope';\nimport type { StatewireTransportOptions } from './statewire-transport';\nimport { readStatewireFailedSendLane } from './thread-extras';\nimport { isConfigSyncUnavailableRejection } from './use-deep-agent-config';\nimport {\n  deepAgentAttachId,\n  useDeepAgentThread,\n  type UseDeepAgentThreadOptions,\n} from './use-deep-agent-thread';\n\n/** The thread element `useDeepAgentThread` produces — what the host's `useAui`\n * consumes (`useAui({ thread })`). */\nexport type DeepAgentThreadElement = ReturnType<typeof useDeepAgentThread>;\n\n/**\n * Durable command-lane persistence for the thread — where the lane identity and\n * the commands still awaiting a durable verdict live, so a reload resumes the\n * lane instead of minting a new client.\n *\n * - `local-storage`: browser hosts. Backed by {@link QuotaSafeLocalStorageSession}\n *   (the upstream `LocalStorageSession` contract with Athena keys, legacy\n *   metadata, and retention). A storage failure after mounting — the origin\n *   out of quota after statewire's own sweep, a lockdown-mode write refusal —\n *   degrades the session to memory-only persistence and is reported through\n *   `onStorageDegraded` (default: one console warning); it never stops the\n *   connection. Guarded by a shared availability probe: SSR, storage-blocked\n *   iframes, and locked-down browsers keep the session process-local, exactly\n *   as before the seam existed, while an origin that is merely full mounts the\n *   session and lets it degrade. `key` scopes the stored lane — a thread id is\n *   only meaningful against the backend (and, where relevant, principal) that\n *   minted it, so include the sync-host URL.\n * - `session-store`: React Native hosts pass a hydrated library store backed\n *   by AsyncStorage. Its synchronous `load()` is\n *   also the send-recovery freshness gate's view of the persisted failed lane,\n *   so a store that persists `failed` gets the same 24 h staleness rule as the\n *   browser hosts.\n * - `pending`: the principal the lane is scoped by is not known yet (the\n *   host's signed-in user is still loading). See {@link DeepAgentPendingSession}.\n * - `false`: process-local session (a reload mints a new client).\n *\n * A `local-storage` `key` names one principal's lanes (and one backend's). The\n * statewire session that mounts on a lane keeps the client id, lane clocks and\n * journal it loaded there, and everything in that journal is sent under\n * whatever credential the transport holds at its next attach. So a mounted\n * session never moves to another key: when the key starts naming another\n * principal's lanes for the same thread (another account signed in under a\n * mounted chat), the runtime starts a new lane epoch\n * (`UseDeepAgentThreadOptions['laneEpoch']`). The whole statewire thread\n * remounts on the new principal's lane and attaches afresh, as that lane's own\n * client, with nothing remembered or pooled from before. The previous\n * principal's record stays where it is, with its client id and whatever it had\n * journaled and not yet delivered: that principal's next mount on this browser\n * resends it as them, and the retention sweep retires it otherwise. It is never\n * sent as anyone else. A key for the same principal (a token refresh, a fresh\n * `key` function) and a thread switch keep the lane as it is. A host whose\n * principal arrives after mount passes `pending` until it does, never a\n * stand-in key: moving off a stand-in would be a principal change, a second\n * attach.\n */\nexport type DeepAgentSessionPersistence =\n  | {\n      kind: 'local-storage';\n      key: (threadId: string) => string;\n      onStorageDegraded?: (degradation: SessionStorageDegradation) => void;\n    }\n  | { kind: 'session-store'; store: NonNullable<StatewireTransportOptions['sessionStore']> }\n  | DeepAgentPendingSession\n  | false;\n\n/**\n * The durable lane's principal is not known yet. A lane belongs to one\n * principal and a mounted session cannot move to another lane (see\n * {@link DeepAgentSessionPersistence}), so nothing is mounted, nothing is\n * journaled and the transport stays parked — no dial — until the host passes\n * the real persistence. The park is an attach identity of its own: the attach\n * that follows makes every per-attach decision afresh (the remembered-snapshot\n * seed, the pooled hello, which the park leaves in the pool) and dials the real\n * lane once, as the thread's first attach. The park carries no connection\n * message, so it reads like a never-started chat rather than a paused one; a\n * host suspension, when one applies, wins.\n */\nexport type DeepAgentPendingSession = { kind: 'pending' };\n\n/**\n * The attach key a pending-lane park runs under. It differs from every key the\n * host passes, so the real attach after it is a new attach identity.\n */\nexport function pendingSessionAttachKey(attachKey: string | number | undefined): string {\n  return `session-pending:${attachKey ?? ''}`;\n}\n\n/** Structural view of the browser storage global — this package compiles\n * without the DOM lib (React Native honesty; see `globals.d.ts`). */\ntype StorageGlobals = {\n  localStorage?: {\n    setItem(key: string, value: string): void;\n    removeItem(key: string): void;\n  };\n  navigator?: { locks?: unknown };\n};\n\n/**\n * Whether a localStorage-backed session can persist here. A write probe, not a\n * `typeof` check: storage-blocked iframes (SDK embeds under third-party-storage\n * blocking) throw from the `localStorage` accessor itself, and lockdown-mode\n * origins throw from `setItem` — each of those must mean \"stay process-local\",\n * never a crash at mount. An origin that is merely out of quota still reads\n * and takes locks, so it mounts the session: {@link QuotaSafeLocalStorageSession}\n * degrades that to memory-only persistence and recovers when room frees,\n * where staying process-local would give up cross-tab sharing for the whole\n * page load over a condition that clears.\n *\n * The Web Locks API is probed too: the session storage serializes the shared\n * record across tabs through `navigator.locks` and refuses to mount without it\n * (the same precondition as the vendor `LocalStorageSession`), so an origin\n * with localStorage but no Web Locks — older WebViews, Safari before 15.4 —\n * must also stay process-local instead of throwing at mount.\n */\nexport function canPersistDeepAgentSession(): boolean {\n  try {\n    const globals = globalThis as StorageGlobals;\n    if (!globals.navigator?.locks) return false;\n    const storage = globals.localStorage;\n    if (!storage) return false;\n    const probeKey = '__athena_statewire_session_probe__';\n    try {\n      storage.setItem(probeKey, probeKey);\n      storage.removeItem(probeKey);\n    } catch (error) {\n      return isStorageQuotaError(error);\n    }\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/** A host session store's current record, or `null` when the read throws —\n * the recovery gate must never take the runtime down over a storage fault. */\nfunction loadSessionRecord(\n  store: NonNullable<StatewireTransportOptions['sessionStore']>\n): ReturnType<NonNullable<StatewireTransportOptions['sessionStore']>['load']> | null {\n  try {\n    return store.load();\n  } catch {\n    return null;\n  }\n}\n\n/**\n * The shared tail of every surface's transport error policy: channel teardown\n * is lifecycle noise (logged at debug), as is `config_sync_unavailable` — only\n * `config/*` writes emit it, and the host's config sync already handles it\n * through its own command promise (regionally-pinned workspaces run on\n * local-only config); everything else is a real transport error. Hosts with their own error chain\n * (paywall, telemetry, send-failure stores) end it with this so the fallback\n * logging stays uniform per surface.\n */\nexport function logUnhandledStatewireError(surface: string, error: Error): void {\n  if (isStatewireChannelTeardown(error)) {\n    console.debug(`[${surface}] statewire channel teardown:`, error);\n    return;\n  }\n  if (isConfigSyncUnavailableRejection(error)) {\n    console.debug(`[${surface}] config sync unavailable (handled by config sync):`, error);\n    return;\n  }\n  console.error(`[${surface}] statewire transport error:`, error);\n}\n\n/**\n * The imperative thread-state slice of an assistant-ui client — structural so\n * web and native `useAui` results both satisfy it. The send-recovery layer\n * reads the statewire thread extras through it (the sanctioned imperative\n * pattern: `aui.thread().getState()` inside callbacks/effects, never render).\n */\nexport interface DeepAgentThreadStateClientHost {\n  thread: () => { getState: () => { extras?: unknown } };\n  subscribe: (listener: () => void) => () => void;\n}\n\n/** Deep-agent runConfig registration on the ambient model context (see\n * {@link registerDeepAgentRunConfig}). */\nexport interface DeepAgentRunConfigRegistration {\n  /**\n   * Builds the `runConfig` that drives the run. The core pulls it when the\n   * model context notifies (mount and each key change); the server reads that\n   * synced value at command admission. The per-render ref makes each pull use\n   * the latest closure but does not trigger a pull itself.\n   */\n  get: () => Record<string, unknown>;\n  /**\n   * Re-registers the provider and notifies model-context sync when this value\n   * changes (reference equality). Include getter inputs that can change while\n   * mounted; they reach the server only after a key change triggers a pull.\n   */\n  key?: unknown;\n  /**\n   * Notifies when a getter input changes outside React, so model-context sync\n   * pulls `get` at once, before a command sent right after leaves (Olympus\n   * stages a send's named agents right before `composer.send`). Subscribed\n   * when the provider registers; a key change subscribes again.\n   */\n  subscribe?: (listener: () => void) => () => void;\n}\n\nexport interface UseDeepAgentRuntimeOptions<\n  TClient extends DeepAgentModelContextHost & DeepAgentThreadStateClientHost,\n> extends Omit<UseDeepAgentThreadOptions, 'storage' | 'sessionStore' | 'laneEpoch'> {\n  /** Host surface tag for the shared fallback error logging (e.g.\n   * `'AthenaDeepAgent'`, `'AthenaSDK'`, `'ChromeStatewire'`). */\n  surface: string;\n  /** Durable command-lane persistence; defaults to process-local. */\n  session?: DeepAgentSessionPersistence;\n  /**\n   * Builds the host's assistant-ui client from the thread element — pass the\n   * platform `useAui` (web hosts from `@assistant-ui/react`, React Native\n   * hosts from `@assistant-ui/react-native`; this package imports neither).\n   * Called unconditionally on every render, so it MUST be (or call) a hook\n   * following the rules of hooks — define it at module scope with a `use*`\n   * name: `const useHostClient = (thread: DeepAgentThreadElement) =>\n   * useAui({ thread })`.\n   */\n  useClient: (thread: DeepAgentThreadElement) => TClient;\n  /** Registers the deep-agent runConfig on the client's model context. Hosts\n   * that register elsewhere (e.g. a bridge component mounted under the\n   * provider) omit it. */\n  runConfig?: DeepAgentRunConfigRegistration;\n  /**\n   * Called right before send recovery dispatches a failed send again, with its\n   * message id: the host puts back the per-send context that message was sent\n   * with (Olympus stages the agents it named) before its command leaves. A\n   * promise holds that retry (and the ones behind it) until it settles, then\n   * the host is asked again: it can't put the context back while a send with\n   * another one is still on its way (see `DeepAgentSendRecoveryOptions.beforeRetry`).\n   * A function returned is called when the retry does not go after all.\n   */\n  onBeforeSendRetry?: (messageId: string) => void | PromiseLike<void> | (() => void);\n}\n\n/**\n * The configurable deep-agent statewire runtime — the one hook every Athena\n * chat surface (Olympus, `@athenaintel/react` SDK, Chrome extension, Office\n * add-in, mobile) mounts its assistant-ui client through.\n *\n * Composes the pieces every surface previously wired by hand:\n * `useDeepAgentThread` (attach lifecycle, auth parking, lane projection,\n * connection/running observers), durable session persistence with the shared\n * availability guard, transport-level send recovery (failed sends the server\n * never judged auto-retry under their original message id — `send-recovery.ts`),\n * the platform client via `useClient`, and the\n * runConfig model-context registration on provider notifications. Everything\n * host-specific — auth headers, run-config building, error policy, adapters,\n * diagnostics recorders — stays an option, so per-surface behavior is\n * configuration, not a fork.\n */\nexport function useDeepAgentRuntime<\n  TClient extends DeepAgentModelContextHost & DeepAgentThreadStateClientHost,\n>(options: UseDeepAgentRuntimeOptions<TClient>): TClient {\n  const {\n    surface,\n    session = false,\n    useClient,\n    runConfig,\n    onBeforeSendRetry,\n    onError,\n    onStateChange,\n    onCommandChange,\n    ...threadOptions\n  } = options;\n\n  // Probed once per mount, like every browser host did individually: an origin\n  // that cannot persist stays process-local for the mount's lifetime.\n  const [canPersistLocalSession] = useState(canPersistDeepAgentSession);\n\n  // Per-render refs so the transport never remounts on a new closure identity\n  // and always reads the latest policy.\n  const onErrorRef = useRef(onError);\n  onErrorRef.current = onError;\n  const surfaceRef = useRef(surface);\n  surfaceRef.current = surface;\n  const onStateChangeRef = useRef(onStateChange);\n  onStateChangeRef.current = onStateChange;\n  const onCommandChangeRef = useRef(onCommandChange);\n  onCommandChangeRef.current = onCommandChange;\n  const diagnosticsRef = useRef(threadOptions.diagnostics);\n  diagnosticsRef.current = threadOptions.diagnostics;\n  const onBeforeSendRetryRef = useRef(onBeforeSendRetry);\n  onBeforeSendRetryRef.current = onBeforeSendRetry;\n  const clientRef = useRef<TClient | null>(null);\n\n  // Where the persisted session record lives, for the recovery freshness gate\n  // (read per sweep — undefined means \"no persistence, everything is fresh\").\n  const failureStampsRef = useRef<(() => ReadonlyMap<string, number> | null) | undefined>(\n    undefined\n  );\n  failureStampsRef.current =\n    session === false || session.kind === 'pending'\n      ? undefined\n      : session.kind === 'local-storage'\n        ? canPersistLocalSession\n          ? () => readPersistedFailedSendStamps(session.key(threadOptions.threadId))\n          : undefined\n        : () => readFailedSendStampsFromRecord(loadSessionRecord(session.store));\n\n  // A pending lane parks the thread under an attach identity of its own (see\n  // `DeepAgentPendingSession`), so the attach once the lane is known is new.\n  const sessionPending = session !== false && session.kind === 'pending';\n  const attachKey = sessionPending\n    ? pendingSessionAttachKey(threadOptions.attachKey)\n    : threadOptions.attachKey;\n\n  // The lane's scope, as the host's `key` names it: whose lanes this mount\n  // runs on. A key that starts naming another principal's lanes starts a new\n  // lane epoch, which remounts the whole thread on the new lane instead of\n  // moving the mounted session there (see `DeepAgentSessionPersistence`).\n  // Tracked whether or not this origin can persist: a process-local session\n  // holds the previous principal's journal in memory just the same. A pending\n  // lane keeps the last known scope, so a sign-out and a sign-in as someone\n  // else with a gap between them is still a change.\n  const laneKey = session !== false && session.kind === 'local-storage' ? session.key : null;\n  const [laneEpochState, setLaneEpochState] = useState(() =>\n    nextSessionLaneEpoch({\n      previous: INITIAL_SESSION_LANE_EPOCH,\n      threadId: threadOptions.threadId,\n      key: laneKey,\n    })\n  );\n  const nextLaneEpochState = nextSessionLaneEpoch({\n    previous: laneEpochState,\n    threadId: threadOptions.threadId,\n    key: laneKey,\n  });\n  // React's derived-state update: re-renders at once with the new epoch, and\n  // this render already uses it, so no render pairs the new key with the\n  // mounted thread.\n  if (nextLaneEpochState !== laneEpochState) setLaneEpochState(nextLaneEpochState);\n  const laneEpoch = nextLaneEpochState.epoch;\n\n  // Send recovery, keyed by attach identity exactly like the thread's session\n  // (a switch, re-attach or new lane epoch gets fresh hydration gating and\n  // retry budgets, so it never re-dispatches a previous principal's failed\n  // sends). The controller re-dispatches failed sends the server never judged;\n  // see `send-recovery.ts` for the contract.\n  const attachId = deepAgentAttachId({ threadId: threadOptions.threadId, attachKey, laneEpoch });\n  // biome-ignore lint/correctness/useExhaustiveDependencies: keyed by attach identity on purpose; every other input is read through a per-render ref.\n  const sendRecovery = useMemo(\n    () =>\n      createDeepAgentSendRecovery({\n        lane: () => {\n          const client = clientRef.current;\n          if (!client) return null;\n          return readStatewireFailedSendLane(client.thread().getState().extras);\n        },\n        failureStamps: () => failureStampsRef.current?.() ?? null,\n        diagnostics: () => diagnosticsRef.current,\n        beforeRetry: (messageId) => onBeforeSendRetryRef.current?.(messageId),\n      }),\n    [attachId]\n  );\n  useEffect(() => () => sendRecovery.dispose(), [sendRecovery]);\n  const sendRecoveryRef = useRef(sendRecovery);\n  sendRecoveryRef.current = sendRecovery;\n\n  const thread = useDeepAgentThread({\n    ...threadOptions,\n    ...(attachKey !== undefined && { attachKey }),\n    laneEpoch,\n    // Parked without a message (a host suspension, when one applies, wins):\n    // nothing dials and nothing journals until the lane is known. What paints\n    // the first frame is the real attach's to report, not the park's.\n    ...(sessionPending && {\n      suspended: threadOptions.suspended || {},\n      onAttachSource: undefined,\n    }),\n    // A pooled dial for the thread is the real attach's to take: a park that\n    // only waits for the lane neither takes nor discards it. A host suspension\n    // still discards it, as it does without a pending lane.\n    ...(sessionPending && !threadOptions.suspended && { prewarmPool: undefined }),\n    ...(session !== false &&\n      session.kind === 'local-storage' &&\n      canPersistLocalSession && {\n        storage: {\n          session: QuotaSafeLocalStorageSession({\n            threadId: threadOptions.threadId,\n            key: session.key,\n            ...(session.onStorageDegraded === undefined\n              ? {}\n              : { onStorageDegraded: session.onStorageDegraded }),\n          }),\n        },\n      }),\n    ...(session !== false && session.kind === 'session-store' && { sessionStore: session.store }),\n    onStateChange: (state, ctx) => {\n      sendRecoveryRef.current.observeStateChange(state);\n      onStateChangeRef.current?.(state, ctx);\n    },\n    onCommandChange: (update, ctx) => {\n      sendRecoveryRef.current.observeCommand(update);\n      onCommandChangeRef.current?.(update, ctx);\n    },\n    onError: (error) => {\n      const handler = onErrorRef.current;\n      if (handler) {\n        handler(error);\n        return;\n      }\n      logUnhandledStatewireError(surfaceRef.current, error);\n    },\n  });\n\n  const client = useClient(thread);\n  clientRef.current = client;\n\n  // A locked shared journal can publish failed history after onCommandChange,\n  // with no canonical state change to wake recovery. Observe the client that\n  // owns the visible failed lane; the controller guards in-flight retries.\n  useEffect(() => {\n    const unsubscribe = client.subscribe(() => sendRecovery.observeFailedLaneChange());\n    sendRecovery.observeFailedLaneChange();\n    return unsubscribe;\n  }, [client, sendRecovery]);\n\n  // Commands travel bare, so the runConfig that drives the run rides the\n  // ambient model context: `contextSync: 'command-send'` mirrors it to the\n  // server, which reads `config.runConfig` at command admission. The core pulls\n  // on model-context notifications; the per-render ref ensures each pull uses\n  // the latest closure but does not trigger a pull itself.\n  const getRunConfigRef = useRef(runConfig?.get);\n  getRunConfigRef.current = runConfig?.get;\n  const hasRunConfig = runConfig !== undefined;\n  const runConfigKey = runConfig?.key;\n  // A host's own notifications (inputs that change outside React) pull too.\n  const subscribeRunConfigRef = useRef(runConfig?.subscribe);\n  subscribeRunConfigRef.current = runConfig?.subscribe;\n  const hasRunConfigSubscribe = runConfig?.subscribe !== undefined;\n  useEffect(() => {\n    if (!hasRunConfig) return undefined;\n    return registerDeepAgentRunConfig(\n      client,\n      () => getRunConfigRef.current?.() ?? {},\n      hasRunConfigSubscribe\n        ? (listener) => subscribeRunConfigRef.current?.(listener) ?? (() => {})\n        : undefined\n    );\n  }, [client, hasRunConfig, runConfigKey, hasRunConfigSubscribe]);\n\n  return client;\n}\n\n"],"names":["isStorageQuotaError","isStatewireChannelTeardown","isConfigSyncUnavailableRejection","useState","useRef","readPersistedFailedSendStamps","readFailedSendStampsFromRecord","nextSessionLaneEpoch","INITIAL_SESSION_LANE_EPOCH","deepAgentAttachId","sendRecovery","useMemo","createDeepAgentSendRecovery","client","readStatewireFailedSendLane","useEffect","useDeepAgentThread","QuotaSafeLocalStorageSession","registerDeepAgentRunConfig"],"mappings":";;;;;;;;;;;AAkGO,SAAS,wBAAwB,WAAgD;AACtF,SAAO,mBAAmB,aAAa,EAAE;AAC3C;AA6BO,SAAS,6BAAsC;;AACpD,MAAI;AACF,UAAM,UAAU;AAChB,QAAI,GAAC,aAAQ,cAAR,mBAAmB,OAAO,QAAO;AACtC,UAAM,UAAU,QAAQ;AACxB,QAAI,CAAC,QAAS,QAAO;AACrB,UAAM,WAAW;AACjB,QAAI;AACF,cAAQ,QAAQ,UAAU,QAAQ;AAClC,cAAQ,WAAW,QAAQ;AAAA,IAC7B,SAAS,OAAO;AACd,aAAOA,6BAAAA,oBAAoB,KAAK;AAAA,IAClC;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAIA,SAAS,kBACP,OACmF;AACnF,MAAI;AACF,WAAO,MAAM,KAAA;AAAA,EACf,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAWO,SAAS,2BAA2B,SAAiB,OAAoB;AAC9E,MAAIC,OAAAA,2BAA2B,KAAK,GAAG;AACrC,YAAQ,MAAM,IAAI,OAAO,iCAAiC,KAAK;AAC/D;AAAA,EACF;AACA,MAAIC,mBAAAA,iCAAiC,KAAK,GAAG;AAC3C,YAAQ,MAAM,IAAI,OAAO,uDAAuD,KAAK;AACrF;AAAA,EACF;AACA,UAAQ,MAAM,IAAI,OAAO,gCAAgC,KAAK;AAChE;AAwFO,SAAS,oBAEd,SAAuD;AACvD,QAAM;AAAA,IACJ;AAAA,IACA,UAAU;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EAAA,IACD;AAIJ,QAAM,CAAC,sBAAsB,IAAIC,WAAAA,SAAS,0BAA0B;AAIpE,QAAM,aAAaC,WAAAA,OAAO,OAAO;AACjC,aAAW,UAAU;AACrB,QAAM,aAAaA,WAAAA,OAAO,OAAO;AACjC,aAAW,UAAU;AACrB,QAAM,mBAAmBA,WAAAA,OAAO,aAAa;AAC7C,mBAAiB,UAAU;AAC3B,QAAM,qBAAqBA,WAAAA,OAAO,eAAe;AACjD,qBAAmB,UAAU;AAC7B,QAAM,iBAAiBA,WAAAA,OAAO,cAAc,WAAW;AACvD,iBAAe,UAAU,cAAc;AACvC,QAAM,uBAAuBA,WAAAA,OAAO,iBAAiB;AACrD,uBAAqB,UAAU;AAC/B,QAAM,YAAYA,WAAAA,OAAuB,IAAI;AAI7C,QAAM,mBAAmBA,WAAAA;AAAAA,IACvB;AAAA,EAAA;AAEF,mBAAiB,UACf,YAAY,SAAS,QAAQ,SAAS,YAClC,SACA,QAAQ,SAAS,kBACf,yBACE,MAAMC,6BAAAA,8BAA8B,QAAQ,IAAI,cAAc,QAAQ,CAAC,IACvE,SACF,MAAMC,4DAA+B,kBAAkB,QAAQ,KAAK,CAAC;AAI7E,QAAM,iBAAiB,YAAY,SAAS,QAAQ,SAAS;AAC7D,QAAM,YAAY,iBACd,wBAAwB,cAAc,SAAS,IAC/C,cAAc;AAUlB,QAAM,UAAU,YAAY,SAAS,QAAQ,SAAS,kBAAkB,QAAQ,MAAM;AACtF,QAAM,CAAC,gBAAgB,iBAAiB,IAAIH,WAAAA;AAAAA,IAAS,MACnDI,sCAAqB;AAAA,MACnB,UAAUC,iBAAAA;AAAAA,MACV,UAAU,cAAc;AAAA,MACxB,KAAK;AAAA,IAAA,CACN;AAAA,EAAA;AAEH,QAAM,qBAAqBD,iBAAAA,qBAAqB;AAAA,IAC9C,UAAU;AAAA,IACV,UAAU,cAAc;AAAA,IACxB,KAAK;AAAA,EAAA,CACN;AAID,MAAI,uBAAuB,eAAgB,mBAAkB,kBAAkB;AAC/E,QAAM,YAAY,mBAAmB;AAOrC,QAAM,WAAWE,mBAAAA,kBAAkB,EAAE,UAAU,cAAc,UAAU,WAAW,WAAW;AAE7F,QAAMC,iBAAeC,WAAAA;AAAAA,IACnB,MACEC,yCAA4B;AAAA,MAC1B,MAAM,MAAM;AACV,cAAMC,UAAS,UAAU;AACzB,YAAI,CAACA,QAAQ,QAAO;AACpB,eAAOC,aAAAA,4BAA4BD,QAAO,OAAA,EAAS,SAAA,EAAW,MAAM;AAAA,MACtE;AAAA,MACA,eAAe,MAAA;;AAAM,uCAAiB,YAAjB,8CAAgC;AAAA;AAAA,MACrD,aAAa,MAAM,eAAe;AAAA,MAClC,aAAa,CAAC;;AAAc,0CAAqB,YAArB,8CAA+B;AAAA;AAAA,IAAS,CACrE;AAAA,IACH,CAAC,QAAQ;AAAA,EAAA;AAEXE,aAAAA,UAAU,MAAM,MAAML,eAAa,WAAW,CAACA,cAAY,CAAC;AAC5D,QAAM,kBAAkBN,WAAAA,OAAOM,cAAY;AAC3C,kBAAgB,UAAUA;AAE1B,QAAM,SAASM,mBAAAA,mBAAmB;AAAA,IAChC,GAAG;AAAA,IACH,GAAI,cAAc,UAAa,EAAE,UAAA;AAAA,IACjC;AAAA;AAAA;AAAA;AAAA,IAIA,GAAI,kBAAkB;AAAA,MACpB,WAAW,cAAc,aAAa,CAAA;AAAA,MACtC,gBAAgB;AAAA,IAAA;AAAA;AAAA;AAAA;AAAA,IAKlB,GAAI,kBAAkB,CAAC,cAAc,aAAa,EAAE,aAAa,OAAA;AAAA,IACjE,GAAI,YAAY,SACd,QAAQ,SAAS,mBACjB,0BAA0B;AAAA,MACxB,SAAS;AAAA,QACP,SAASC,6BAAAA,6BAA6B;AAAA,UACpC,UAAU,cAAc;AAAA,UACxB,KAAK,QAAQ;AAAA,UACb,GAAI,QAAQ,sBAAsB,SAC9B,CAAA,IACA,EAAE,mBAAmB,QAAQ,kBAAA;AAAA,QAAkB,CACpD;AAAA,MAAA;AAAA,IACH;AAAA,IAEJ,GAAI,YAAY,SAAS,QAAQ,SAAS,mBAAmB,EAAE,cAAc,QAAQ,MAAA;AAAA,IACrF,eAAe,CAAC,OAAO,QAAQ;;AAC7B,sBAAgB,QAAQ,mBAAmB,KAAK;AAChD,6BAAiB,YAAjB,0CAA2B,OAAO;AAAA,IACpC;AAAA,IACA,iBAAiB,CAAC,QAAQ,QAAQ;;AAChC,sBAAgB,QAAQ,eAAe,MAAM;AAC7C,+BAAmB,YAAnB,4CAA6B,QAAQ;AAAA,IACvC;AAAA,IACA,SAAS,CAAC,UAAU;AAClB,YAAM,UAAU,WAAW;AAC3B,UAAI,SAAS;AACX,gBAAQ,KAAK;AACb;AAAA,MACF;AACA,iCAA2B,WAAW,SAAS,KAAK;AAAA,IACtD;AAAA,EAAA,CACD;AAED,QAAM,SAAS,UAAU,MAAM;AAC/B,YAAU,UAAU;AAKpBF,aAAAA,UAAU,MAAM;AACd,UAAM,cAAc,OAAO,UAAU,MAAML,eAAa,yBAAyB;AACjFA,mBAAa,wBAAA;AACb,WAAO;AAAA,EACT,GAAG,CAAC,QAAQA,cAAY,CAAC;AAOzB,QAAM,kBAAkBN,WAAAA,OAAO,uCAAW,GAAG;AAC7C,kBAAgB,UAAU,uCAAW;AACrC,QAAM,eAAe,cAAc;AACnC,QAAM,eAAe,uCAAW;AAEhC,QAAM,wBAAwBA,WAAAA,OAAO,uCAAW,SAAS;AACzD,wBAAsB,UAAU,uCAAW;AAC3C,QAAM,yBAAwB,uCAAW,eAAc;AACvDW,aAAAA,UAAU,MAAM;AACd,QAAI,CAAC,aAAc,QAAO;AAC1B,WAAOG,aAAAA;AAAAA,MACL;AAAA,MACA;;AAAM,sCAAgB,YAAhB,6CAA+B,CAAA;AAAA;AAAA,MACrC,wBACI,CAAC,aAAA;;AAAa,4CAAsB,YAAtB,+CAAgC,eAAc,MAAM;AAAA,QAAC;AAAA,UACnE;AAAA,IAAA;AAAA,EAER,GAAG,CAAC,QAAQ,cAAc,cAAc,qBAAqB,CAAC;AAE9D,SAAO;AACT;;;;;"}
+{"version":3,"file":"use-deep-agent-runtime.cjs","sources":["../../../../agent-runtime/src/use-deep-agent-runtime.ts"],"sourcesContent":["import { type ResourceElement, resource, useResource } from '@assistant-ui/tap';\nimport { useEffect, useMemo, useRef, useState } from 'react';\nimport type { StatewireClient } from 'statewire';\nimport { createChatOutboxFlushPolicy } from './chat-outbox-policy';\nimport { isStatewireChannelTeardown } from './errors';\nimport { type DeepAgentModelContextHost, registerDeepAgentRunConfig } from './model-context';\nimport {\n  isStorageQuotaError,\n  localStorageSessionKey,\n  QuotaSafeLocalStorageSession,\n  readFailedSendStampsFromRecord,\n  readPersistedFailedSendStamps,\n  type SessionStorageDegradation,\n} from './quota-safe-local-storage-session';\nimport { createDeepAgentSendRecovery } from './send-recovery';\nimport { INITIAL_SESSION_LANE_EPOCH, nextSessionLaneEpoch } from './session-lane-scope';\nimport { readStatewireOutbox } from './statewire-held-sends';\nimport type { StatewireTransportOptions } from './statewire-transport';\nimport { isConfigSyncUnavailableRejection } from './use-deep-agent-config';\nimport {\n  deepAgentAttachId,\n  useDeepAgentThread,\n  type UseDeepAgentThreadOptions,\n} from './use-deep-agent-thread';\n\n/** The thread element `useDeepAgentThread` produces — what the host's `useAui`\n * consumes (`useAui({ thread })`). */\nexport type DeepAgentThreadElement = ReturnType<typeof useDeepAgentThread>;\n\n/**\n * Durable command-lane persistence for the thread — where the lane identity and\n * the commands still awaiting a durable verdict live, so a reload resumes the\n * lane instead of minting a new client.\n *\n * - `local-storage`: browser hosts. Backed by {@link QuotaSafeLocalStorageSession}\n *   (the upstream `LocalStorageSession` contract with Athena keys, legacy\n *   metadata, and retention). A storage failure after mounting — the origin\n *   out of quota after statewire's own sweep, a lockdown-mode write refusal —\n *   degrades the session to memory-only persistence and is reported through\n *   `onStorageDegraded` (default: one console warning); it never stops the\n *   connection. Guarded by a shared availability probe: SSR, storage-blocked\n *   iframes, and locked-down browsers keep the session process-local, exactly\n *   as before the seam existed, while an origin that is merely full mounts the\n *   session and lets it degrade. `namespace` (the sync host) and `principal`\n *   (the signed-in account) scope the stored lane: a thread id is only\n *   meaningful against the backend and the principal that minted it.\n * - `session-store`: React Native hosts pass a hydrated library store backed\n *   by AsyncStorage. Its synchronous `load()` is\n *   also the send-recovery freshness gate's view of the persisted failed lane,\n *   so a store that persists `failed` gets the same 24 h staleness rule as the\n *   browser hosts.\n * - `pending`: the principal the lane is scoped by is not known yet (the\n *   host's signed-in user is still loading). See {@link DeepAgentPendingSession}.\n * - `false`: process-local session (a reload mints a new client).\n *\n * A `local-storage` `namespace` and `principal` name one principal's lanes (and one backend's). The\n * statewire session that mounts on a lane keeps the client id, lane clocks and\n * journal it loaded there, and everything in that journal is sent under\n * whatever credential the transport holds at its next attach. So a mounted\n * session never moves to another key: when the key starts naming another\n * principal's lanes for the same thread (another account signed in under a\n * mounted chat), the runtime starts a new lane epoch\n * (`UseDeepAgentThreadOptions['laneEpoch']`). The whole statewire thread\n * remounts on the new principal's lane and attaches afresh, as that lane's own\n * client, with nothing remembered or pooled from before. The previous\n * principal's record stays where it is, with its client id and whatever it had\n * journaled and not yet delivered: that principal's next mount on this browser\n * resends it as them, and the retention sweep retires it otherwise. It is never\n * sent as anyone else. The same principal again (a token refresh, a fresh\n * persistence object) and a thread switch keep the lane as it is. A host whose\n * principal arrives after mount passes `pending` until it does, never a\n * stand-in key: moving off a stand-in would be a principal change, a second\n * attach.\n */\nexport type DeepAgentSessionPersistence =\n  | {\n      kind: 'local-storage';\n      /** The backend the lanes belong to, as a key prefix: the sync host and `:`. */\n      namespace: string;\n      /** The signed-in account the lanes belong to (`sessionPrincipal(userId)`). */\n      principal: string;\n      /**\n       * Where statewire 0.24 kept this account's lanes (`<syncUrl>:<userId>:`): a thread's lane\n       * there moves under its scoped key on mount (`adoptUnscopedLocalStorageSessions`).\n       */\n      unscopedPrefix?: string;\n      onStorageDegraded?: (degradation: SessionStorageDegradation) => void;\n    }\n  | { kind: 'session-store'; store: NonNullable<StatewireTransportOptions['sessionStore']> }\n  | {\n      kind: 'storage';\n      /**\n       * The thread's mounted session storage (`ChatSessionStorage`: sealed IndexedDB, or page\n       * memory where devices keep no copies), made per thread. The surfaces that keep a chat\n       * outbox use it: the outbox is the session's outbox.\n       */\n      session: (threadId: string) => ResourceElement<StatewireClient.SessionStorage>;\n    }\n  | DeepAgentPendingSession\n  | false;\n\n/**\n * The durable lane's principal is not known yet. A lane belongs to one\n * principal and a mounted session cannot move to another lane (see\n * {@link DeepAgentSessionPersistence}), so nothing is mounted, nothing is\n * journaled and the transport stays parked — no dial — until the host passes\n * the real persistence. The park is an attach identity of its own: the attach\n * that follows makes every per-attach decision afresh (the remembered-snapshot\n * seed, the pooled hello, which the park leaves in the pool) and dials the real\n * lane once, as the thread's first attach. The park carries no connection\n * message, so it reads like a never-started chat rather than a paused one; a\n * host suspension, when one applies, wins.\n */\nexport type DeepAgentPendingSession = { kind: 'pending' };\n\n/**\n * The attach key a pending-lane park runs under. It differs from every key the\n * host passes, so the real attach after it is a new attach identity.\n */\nexport function pendingSessionAttachKey(attachKey: string | number | undefined): string {\n  return `session-pending:${attachKey ?? ''}`;\n}\n\n/** Structural view of the browser storage global — this package compiles\n * without the DOM lib (React Native honesty; see `globals.d.ts`). */\ntype StorageGlobals = {\n  localStorage?: {\n    setItem(key: string, value: string): void;\n    removeItem(key: string): void;\n  };\n  navigator?: { locks?: unknown };\n};\n\n/**\n * Whether a localStorage-backed session can persist here. A write probe, not a\n * `typeof` check: storage-blocked iframes (SDK embeds under third-party-storage\n * blocking) throw from the `localStorage` accessor itself, and lockdown-mode\n * origins throw from `setItem` — each of those must mean \"stay process-local\",\n * never a crash at mount. An origin that is merely out of quota still reads\n * and takes locks, so it mounts the session: {@link QuotaSafeLocalStorageSession}\n * degrades that to memory-only persistence and recovers when room frees,\n * where staying process-local would give up cross-tab sharing for the whole\n * page load over a condition that clears.\n *\n * The Web Locks API is probed too: the session storage serializes the shared\n * record across tabs through `navigator.locks` and refuses to mount without it\n * (the same precondition as the vendor `LocalStorageSession`), so an origin\n * with localStorage but no Web Locks — older WebViews, Safari before 15.4 —\n * must also stay process-local instead of throwing at mount.\n */\nexport function canPersistDeepAgentSession(): boolean {\n  try {\n    const globals = globalThis as StorageGlobals;\n    if (!globals.navigator?.locks) return false;\n    const storage = globals.localStorage;\n    if (!storage) return false;\n    const probeKey = '__athena_statewire_session_probe__';\n    try {\n      storage.setItem(probeKey, probeKey);\n      storage.removeItem(probeKey);\n    } catch (error) {\n      return isStorageQuotaError(error);\n    }\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/** A host session store's current record, or `null` when the read throws —\n * the recovery gate must never take the runtime down over a storage fault. */\nfunction loadSessionRecord(\n  store: NonNullable<StatewireTransportOptions['sessionStore']>\n): ReturnType<NonNullable<StatewireTransportOptions['sessionStore']>['load']> | null {\n  try {\n    return store.load();\n  } catch {\n    return null;\n  }\n}\n\n/**\n * A mounted `storage.session` element that hands its store to `observe`, so the recovery\n * freshness gate can read the stored `ts` of a failed send off the record the session hydrated.\n */\nconst ObservedSessionStorage = resource(function useObservedSessionStorage({\n  element,\n  observe,\n}: {\n  element: ResourceElement<StatewireClient.SessionStorage>;\n  observe: (store: StatewireClient.SessionStorage) => void;\n}): StatewireClient.SessionStorage {\n  const store = useResource(element);\n  observe(store);\n  return store;\n});\n\n/**\n * The shared tail of every surface's transport error policy: channel teardown\n * is lifecycle noise (logged at debug), as is `config_sync_unavailable` — only\n * `config/*` writes emit it, and the host's config sync already handles it\n * through its own command promise (regionally-pinned workspaces run on\n * local-only config); everything else is a real transport error. Hosts with their own error chain\n * (paywall, telemetry, send-failure stores) end it with this so the fallback\n * logging stays uniform per surface.\n */\nexport function logUnhandledStatewireError(surface: string, error: Error): void {\n  if (isStatewireChannelTeardown(error)) {\n    console.debug(`[${surface}] statewire channel teardown:`, error);\n    return;\n  }\n  if (isConfigSyncUnavailableRejection(error)) {\n    console.debug(`[${surface}] config sync unavailable (handled by config sync):`, error);\n    return;\n  }\n  console.error(`[${surface}] statewire transport error:`, error);\n}\n\n/**\n * The imperative thread-state slice of an assistant-ui client — structural so\n * web and native `useAui` results both satisfy it. The send-recovery layer\n * reads the statewire thread extras through it (the sanctioned imperative\n * pattern: `aui.thread().getState()` inside callbacks/effects, never render).\n */\nexport interface DeepAgentThreadStateClientHost {\n  thread: () => { getState: () => { extras?: unknown } };\n  subscribe: (listener: () => void) => () => void;\n}\n\n/** Deep-agent runConfig registration on the ambient model context (see\n * {@link registerDeepAgentRunConfig}). */\nexport interface DeepAgentRunConfigRegistration {\n  /**\n   * Builds the `runConfig` that drives the run. The core pulls it when the\n   * model context notifies (mount and each key change); the server reads that\n   * synced value at command admission. The per-render ref makes each pull use\n   * the latest closure but does not trigger a pull itself.\n   */\n  get: () => Record<string, unknown>;\n  /**\n   * Re-registers the provider and notifies model-context sync when this value\n   * changes (reference equality). Include getter inputs that can change while\n   * mounted; they reach the server only after a key change triggers a pull.\n   */\n  key?: unknown;\n  /**\n   * Notifies when a getter input changes outside React, so model-context sync\n   * pulls `get` at once, before a command sent right after leaves (Olympus\n   * stages a send's named agents right before `composer.send`). Subscribed\n   * when the provider registers; a key change subscribes again.\n   */\n  subscribe?: (listener: () => void) => () => void;\n}\n\nexport interface UseDeepAgentRuntimeOptions<\n  TClient extends DeepAgentModelContextHost & DeepAgentThreadStateClientHost,\n> extends Omit<UseDeepAgentThreadOptions, 'storage' | 'sessionStore' | 'laneEpoch'> {\n  /** Host surface tag for the shared fallback error logging (e.g.\n   * `'AthenaDeepAgent'`, `'AthenaSDK'`, `'ChromeStatewire'`). */\n  surface: string;\n  /** Durable command-lane persistence; defaults to process-local. */\n  session?: DeepAgentSessionPersistence;\n  /**\n   * Builds the host's assistant-ui client from the thread element — pass the\n   * platform `useAui` (web hosts from `@assistant-ui/react`, React Native\n   * hosts from `@assistant-ui/react-native`; this package imports neither).\n   * Called unconditionally on every render, so it MUST be (or call) a hook\n   * following the rules of hooks — define it at module scope with a `use*`\n   * name: `const useHostClient = (thread: DeepAgentThreadElement) =>\n   * useAui({ thread })`.\n   */\n  useClient: (thread: DeepAgentThreadElement) => TClient;\n  /** Registers the deep-agent runConfig on the client's model context. Hosts\n   * that register elsewhere (e.g. a bridge component mounted under the\n   * provider) omit it. */\n  runConfig?: DeepAgentRunConfigRegistration;\n  /**\n   * Called right before send recovery dispatches a failed send again, with its\n   * message id: the host puts back the per-send context that message was sent\n   * with (Olympus stages the agents it named) before its command leaves. A\n   * promise holds that retry (and the ones behind it) until it settles, then\n   * the host is asked again: it can't put the context back while a send with\n   * another one is still on its way (see `DeepAgentSendRecoveryOptions.beforeRetry`).\n   * A function returned is called when the retry does not go after all.\n   */\n  onBeforeSendRetry?: (messageId: string) => void | PromiseLike<void> | (() => void);\n  /**\n   * Whether the app is in front (a visible tab, a focused desktop window). While it says no, the\n   * message sends a flush offers as queued before this page mounted are held, so a hidden tab never\n   * sends a backlog; the visible tab's chat outbox counts them down and sends them. Omitted, every\n   * tab sends them.\n   */\n  foreground?: { get(): boolean };\n}\n\nfunction isPromiseLike(value: unknown): value is PromiseLike<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as { then?: unknown }).then === 'function'\n  );\n}\n\n/**\n * The configurable deep-agent statewire runtime — the one hook every Athena\n * chat surface (Olympus, `@athenaintel/react` SDK, Chrome extension, Office\n * add-in, mobile) mounts its assistant-ui client through.\n *\n * Composes the pieces every surface previously wired by hand:\n * `useDeepAgentThread` (attach lifecycle, auth parking, lane projection,\n * connection/running observers), durable session persistence with the shared\n * availability guard, transport-level send recovery (failed sends the server\n * never judged auto-retry under their original message id — `send-recovery.ts`),\n * the platform client via `useClient`, and the\n * runConfig model-context registration on provider notifications. Everything\n * host-specific — auth headers, run-config building, error policy, adapters,\n * diagnostics recorders — stays an option, so per-surface behavior is\n * configuration, not a fork.\n */\nexport function useDeepAgentRuntime<\n  TClient extends DeepAgentModelContextHost & DeepAgentThreadStateClientHost,\n>(options: UseDeepAgentRuntimeOptions<TClient>): TClient {\n  const {\n    surface,\n    session = false,\n    useClient,\n    runConfig,\n    onBeforeSendRetry,\n    foreground,\n    onError,\n    onStateChange,\n    onCommandChange,\n    ...threadOptions\n  } = options;\n\n  // Probed once per mount, like every browser host did individually: an origin\n  // that cannot persist stays process-local for the mount's lifetime.\n  const [canPersistLocalSession] = useState(canPersistDeepAgentSession);\n\n  // Per-render refs so the transport never remounts on a new closure identity\n  // and always reads the latest policy.\n  const onErrorRef = useRef(onError);\n  onErrorRef.current = onError;\n  const surfaceRef = useRef(surface);\n  surfaceRef.current = surface;\n  const onStateChangeRef = useRef(onStateChange);\n  onStateChangeRef.current = onStateChange;\n  const onCommandChangeRef = useRef(onCommandChange);\n  onCommandChangeRef.current = onCommandChange;\n  const foregroundRef = useRef(foreground);\n  foregroundRef.current = foreground;\n  const holdsHiddenReloads = foreground !== undefined;\n  const diagnosticsRef = useRef(threadOptions.diagnostics);\n  diagnosticsRef.current = threadOptions.diagnostics;\n  const onBeforeSendRetryRef = useRef(onBeforeSendRetry);\n  onBeforeSendRetryRef.current = onBeforeSendRetry;\n  const clientRef = useRef<TClient | null>(null);\n\n  // Where the persisted session record lives, for the recovery freshness gate\n  // (read per sweep — undefined means \"no persistence, everything is fresh\").\n  // The mounted `kind: 'storage'` session's store, so the gate reads the stored `ts` of a\n  // failed send there too (a sealed IndexedDB record has no synchronous reader of its own).\n  const storageSessionRef = useRef<StatewireClient.SessionStorage | null>(null);\n  const observeStorageSession = useRef((store: StatewireClient.SessionStorage) => {\n    storageSessionRef.current = store;\n  }).current;\n  const failureStampsRef = useRef<(() => ReadonlyMap<string, number> | null) | undefined>(\n    undefined\n  );\n  failureStampsRef.current =\n    session === false || session.kind === 'pending'\n      ? undefined\n      : session.kind === 'local-storage'\n        ? canPersistLocalSession\n          ? () =>\n              readPersistedFailedSendStamps(\n                localStorageSessionKey({\n                  namespace: session.namespace,\n                  principal: session.principal,\n                  threadId: threadOptions.threadId,\n                })\n              )\n          : undefined\n        : session.kind === 'session-store'\n          ? () => readFailedSendStampsFromRecord(loadSessionRecord(session.store))\n          : session.kind === 'storage'\n            ? () => {\n                const store = storageSessionRef.current;\n                return store ? readFailedSendStampsFromRecord(loadSessionRecord(store)) : null;\n              }\n            : undefined;\n\n  // A pending lane parks the thread under an attach identity of its own (see\n  // `DeepAgentPendingSession`), so the attach once the lane is known is new.\n  const sessionPending = session !== false && session.kind === 'pending';\n  const attachKey = sessionPending\n    ? pendingSessionAttachKey(threadOptions.attachKey)\n    : threadOptions.attachKey;\n\n  // The lane's scope, as the host's `key` names it: whose lanes this mount\n  // runs on. A key that starts naming another principal's lanes starts a new\n  // lane epoch, which remounts the whole thread on the new lane instead of\n  // moving the mounted session there (see `DeepAgentSessionPersistence`).\n  // Tracked whether or not this origin can persist: a process-local session\n  // holds the previous principal's journal in memory just the same. A pending\n  // lane keeps the last known scope, so a sign-out and a sign-in as someone\n  // else with a gap between them is still a change.\n  const laneNamespace =\n    session !== false && session.kind === 'local-storage' ? session.namespace : null;\n  const lanePrincipal =\n    session !== false && session.kind === 'local-storage' ? session.principal : null;\n  const laneKey = useMemo(\n    () =>\n      laneNamespace === null || lanePrincipal === null\n        ? null\n        : (threadId: string) =>\n            localStorageSessionKey({\n              namespace: laneNamespace,\n              principal: lanePrincipal,\n              threadId,\n            }),\n    [laneNamespace, lanePrincipal]\n  );\n  const [laneEpochState, setLaneEpochState] = useState(() =>\n    nextSessionLaneEpoch({\n      previous: INITIAL_SESSION_LANE_EPOCH,\n      threadId: threadOptions.threadId,\n      key: laneKey,\n    })\n  );\n  const nextLaneEpochState = nextSessionLaneEpoch({\n    previous: laneEpochState,\n    threadId: threadOptions.threadId,\n    key: laneKey,\n  });\n  // React's derived-state update: re-renders at once with the new epoch, and\n  // this render already uses it, so no render pairs the new key with the\n  // mounted thread.\n  if (nextLaneEpochState !== laneEpochState) setLaneEpochState(nextLaneEpochState);\n  const laneEpoch = nextLaneEpochState.epoch;\n\n  // Send recovery, keyed by attach identity exactly like the thread's session\n  // (a switch, re-attach or new lane epoch gets fresh hydration gating and\n  // retry budgets, so it never re-dispatches a previous principal's failed\n  // sends). The controller re-dispatches failed sends the server never judged;\n  // see `send-recovery.ts` for the contract.\n  const attachId = deepAgentAttachId({ threadId: threadOptions.threadId, attachKey, laneEpoch });\n  // biome-ignore lint/correctness/useExhaustiveDependencies: keyed by attach identity on purpose; every other input is read through a per-render ref.\n  const sendRecovery = useMemo(\n    () =>\n      createDeepAgentSendRecovery({\n        outbox: () => {\n          const client = clientRef.current;\n          if (!client) return null;\n          return readStatewireOutbox(client.thread().getState().extras);\n        },\n        failureStamps: () => failureStampsRef.current?.() ?? null,\n        diagnostics: () => diagnosticsRef.current,\n        beforeRetry: (messageId) => onBeforeSendRetryRef.current?.(messageId),\n      }),\n    [attachId]\n  );\n  useEffect(() => () => sendRecovery.dispose(), [sendRecovery]);\n  const sendRecoveryRef = useRef(sendRecovery);\n  sendRecoveryRef.current = sendRecovery;\n\n  const thread = useDeepAgentThread({\n    ...threadOptions,\n    ...(attachKey !== undefined && { attachKey }),\n    laneEpoch,\n    // Parked without a message (a host suspension, when one applies, wins):\n    // nothing dials and nothing journals until the lane is known. What paints\n    // the first frame is the real attach's to report, not the park's.\n    ...(sessionPending && {\n      suspended: threadOptions.suspended || {},\n      onAttachSource: undefined,\n    }),\n    // A pooled dial for the thread is the real attach's to take: a park that\n    // only waits for the lane neither takes nor discards it. A host suspension\n    // still discards it, as it does without a pending lane.\n    ...(sessionPending && !threadOptions.suspended && { prewarmPool: undefined }),\n    ...(session !== false &&\n      session.kind === 'local-storage' &&\n      canPersistLocalSession && {\n        storage: {\n          session: QuotaSafeLocalStorageSession({\n            threadId: threadOptions.threadId,\n            namespace: session.namespace,\n            principal: session.principal,\n            ...(session.unscopedPrefix !== undefined && { unscopedPrefix: session.unscopedPrefix }),\n            ...(session.onStorageDegraded === undefined\n              ? {}\n              : { onStorageDegraded: session.onStorageDegraded }),\n          }),\n        },\n      }),\n    ...(session !== false && session.kind === 'session-store' && { sessionStore: session.store }),\n    ...(session !== false &&\n      session.kind === 'storage' && {\n        storage: {\n          session: ObservedSessionStorage({\n            element: session.session(threadOptions.threadId),\n            observe: observeStorageSession,\n          }),\n        },\n      }),\n    ...(holdsHiddenReloads && {\n      onFlush: createChatOutboxFlushPolicy({\n        foreground: () => foregroundRef.current?.get() ?? true,\n        outbox: () => {\n          const client = clientRef.current;\n          if (!client) return null;\n          const outbox = (client.thread().getState().extras as { outbox?: { hold?: unknown } } | undefined)?.outbox;\n          return outbox && typeof outbox.hold === 'function' ? (outbox as { hold(id: string): void }) : null;\n        },\n      }),\n    }),\n    onStateChange: (state, ctx) => {\n      onStateChangeRef.current?.(state, ctx);\n    },\n    // A durable `settled` update is acked once the returned promise resolves:\n    // the host's handler and send recovery both finish before it is.\n    onCommandChange: (update, ctx) => {\n      const recovered = sendRecoveryRef.current.onCommandChange(update, ctx);\n      const observed = onCommandChangeRef.current?.(update, ctx);\n      if (recovered === undefined && !isPromiseLike(observed)) return observed;\n      const settled = Promise.all([recovered, observed]).then(() => undefined);\n      // Only a durable update's promise is awaited; never leave one unhandled.\n      settled.catch(() => undefined);\n      return settled;\n    },\n    onError: (error) => {\n      const handler = onErrorRef.current;\n      if (handler) {\n        handler(error);\n        return;\n      }\n      logUnhandledStatewireError(surfaceRef.current, error);\n    },\n  });\n\n  const client = useClient(thread);\n  clientRef.current = client;\n\n\n  // Commands travel bare, so the runConfig that drives the run rides the\n  // ambient model context: `contextSync: 'command-send'` mirrors it to the\n  // server, which reads `config.runConfig` at command admission. The core pulls\n  // on model-context notifications; the per-render ref ensures each pull uses\n  // the latest closure but does not trigger a pull itself.\n  const getRunConfigRef = useRef(runConfig?.get);\n  getRunConfigRef.current = runConfig?.get;\n  const hasRunConfig = runConfig !== undefined;\n  const runConfigKey = runConfig?.key;\n  // A host's own notifications (inputs that change outside React) pull too.\n  const subscribeRunConfigRef = useRef(runConfig?.subscribe);\n  subscribeRunConfigRef.current = runConfig?.subscribe;\n  const hasRunConfigSubscribe = runConfig?.subscribe !== undefined;\n  useEffect(() => {\n    if (!hasRunConfig) return undefined;\n    return registerDeepAgentRunConfig(\n      client,\n      () => getRunConfigRef.current?.() ?? {},\n      hasRunConfigSubscribe\n        ? (listener) => subscribeRunConfigRef.current?.(listener) ?? (() => {})\n        : undefined\n    );\n  }, [client, hasRunConfig, runConfigKey, hasRunConfigSubscribe]);\n\n  return client;\n}\n\n"],"names":["isStorageQuotaError","resource","useResource","isStatewireChannelTeardown","isConfigSyncUnavailableRejection","useState","useRef","readPersistedFailedSendStamps","localStorageSessionKey","readFailedSendStampsFromRecord","useMemo","nextSessionLaneEpoch","INITIAL_SESSION_LANE_EPOCH","deepAgentAttachId","sendRecovery","createDeepAgentSendRecovery","client","readStatewireOutbox","useEffect","useDeepAgentThread","QuotaSafeLocalStorageSession","createChatOutboxFlushPolicy","registerDeepAgentRunConfig"],"mappings":"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"}

package/dist/agent-runtime/src/use-deep-agent-runtime.d.ts

@@ -1,3 +1,5 @@
+import { type ResourceElement } from '@assistant-ui/tap';
+import type { StatewireClient } from 'statewire';
 import { type DeepAgentModelContextHost } from './model-context';
 import { type SessionStorageDegradation } from './quota-safe-local-storage-session';
 import type { StatewireTransportOptions } from './statewire-transport';
@@ -19,9 +21,9 @@ export type DeepAgentThreadElement = ReturnType<typeof useDeepAgentThread>;
  *   connection. Guarded by a shared availability probe: SSR, storage-blocked
  *   iframes, and locked-down browsers keep the session process-local, exactly
  *   as before the seam existed, while an origin that is merely full mounts the
- *   session and lets it degrade. `key` scopes the stored lane — a thread id is
- *   only meaningful against the backend (and, where relevant, principal) that
- *   minted it, so include the sync-host URL.
+ *   session and lets it degrade. `namespace` (the sync host) and `principal`
+ *   (the signed-in account) scope the stored lane: a thread id is only
+ *   meaningful against the backend and the principal that minted it.
  * - `session-store`: React Native hosts pass a hydrated library store backed
  *   by AsyncStorage. Its synchronous `load()` is
  *   also the send-recovery freshness gate's view of the persisted failed lane,
@@ -31,7 +33,7 @@ export type DeepAgentThreadElement = ReturnType<typeof useDeepAgentThread>;
  *   host's signed-in user is still loading). See {@link DeepAgentPendingSession}.
  * - `false`: process-local session (a reload mints a new client).
  *
- * A `local-storage` `key` names one principal's lanes (and one backend's). The
+ * A `local-storage` `namespace` and `principal` name one principal's lanes (and one backend's). The
  * statewire session that mounts on a lane keeps the client id, lane clocks and
  * journal it loaded there, and everything in that journal is sent under
  * whatever credential the transport holds at its next attach. So a mounted
@@ -44,19 +46,35 @@ export type DeepAgentThreadElement = ReturnType<typeof useDeepAgentThread>;
  * principal's record stays where it is, with its client id and whatever it had
  * journaled and not yet delivered: that principal's next mount on this browser
  * resends it as them, and the retention sweep retires it otherwise. It is never
- * sent as anyone else. A key for the same principal (a token refresh, a fresh
- * `key` function) and a thread switch keep the lane as it is. A host whose
+ * sent as anyone else. The same principal again (a token refresh, a fresh
+ * persistence object) and a thread switch keep the lane as it is. A host whose
  * principal arrives after mount passes `pending` until it does, never a
  * stand-in key: moving off a stand-in would be a principal change, a second
  * attach.
  */
 export type DeepAgentSessionPersistence = {
     kind: 'local-storage';
-    key: (threadId: string) => string;
+    /** The backend the lanes belong to, as a key prefix: the sync host and `:`. */
+    namespace: string;
+    /** The signed-in account the lanes belong to (`sessionPrincipal(userId)`). */
+    principal: string;
+    /**
+     * Where statewire 0.24 kept this account's lanes (`<syncUrl>:<userId>:`): a thread's lane
+     * there moves under its scoped key on mount (`adoptUnscopedLocalStorageSessions`).
+     */
+    unscopedPrefix?: string;
     onStorageDegraded?: (degradation: SessionStorageDegradation) => void;
 } | {
     kind: 'session-store';
     store: NonNullable<StatewireTransportOptions['sessionStore']>;
+} | {
+    kind: 'storage';
+    /**
+     * The thread's mounted session storage (`ChatSessionStorage`: sealed IndexedDB, or page
+     * memory where devices keep no copies), made per thread. The surfaces that keep a chat
+     * outbox use it: the outbox is the session's outbox.
+     */
+    session: (threadId: string) => ResourceElement<StatewireClient.SessionStorage>;
 } | DeepAgentPendingSession | false;
 /**
  * The durable lane's principal is not known yet. A lane belongs to one
@@ -174,6 +192,15 @@ export interface UseDeepAgentRuntimeOptions<TClient extends DeepAgentModelContex
      * A function returned is called when the retry does not go after all.
      */
     onBeforeSendRetry?: (messageId: string) => void | PromiseLike<void> | (() => void);
+    /**
+     * Whether the app is in front (a visible tab, a focused desktop window). While it says no, the
+     * message sends a flush offers as queued before this page mounted are held, so a hidden tab never
+     * sends a backlog; the visible tab's chat outbox counts them down and sends them. Omitted, every
+     * tab sends them.
+     */
+    foreground?: {
+        get(): boolean;
+    };
 }
 /**
  * The configurable deep-agent statewire runtime — the one hook every Athena