@athenaintel/react 0.57.2 → 0.59.0

package/dist/agent-runtime/src/chat-outbox-storage.cjs

@@ -0,0 +1,306 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const tap = require("@assistant-ui/tap");
+const storage = require("statewire/storage");
+const require$$0 = require("react");
+const chatOutboxEntry = require("./chat-outbox-entry.cjs");
+const sealedIdb = require("./sealed-idb.cjs");
+const statewireTransport = require("./statewire-transport.cjs");
+const CHAT_SESSION_DATABASE = "athena-chat-sessions";
+const SEALED_SESSION_PREFIX = "athena-sealed:1:";
+function createSealedSessionCodec(options) {
+  const aad = `athena-chat-session|1|${options.scope}`;
+  const { cipher } = options;
+  if (cipher) {
+    return {
+      async encode(plain) {
+        return SEALED_SESSION_PREFIX + await cipher.seal({ text: plain, aad, purpose: "write" });
+      },
+      async decode(stored) {
+        if (!stored.startsWith(SEALED_SESSION_PREFIX)) throw new Error("athena: chat session record is not sealed");
+        return cipher.open({ sealed: stored.slice(SEALED_SESSION_PREFIX.length), aad, purpose: "read" });
+      }
+    };
+  }
+  const { getKey } = options;
+  return {
+    async encode(plain) {
+      const key = await getKey("write");
+      if (!key) throw new Error("athena: no key to keep chat sessions on this device");
+      return SEALED_SESSION_PREFIX + sealedIdb.bytesToBase64(await sealedIdb.sealText({ key, text: plain, aad }));
+    },
+    async decode(stored) {
+      if (!stored.startsWith(SEALED_SESSION_PREFIX)) throw new Error("athena: chat session record is not sealed");
+      const key = await getKey("read");
+      if (!key) throw new Error("athena: no key to open chat sessions on this device");
+      return sealedIdb.openText({ key, sealed: sealedIdb.base64ToBytes(stored.slice(SEALED_SESSION_PREFIX.length)), aad });
+    }
+  };
+}
+async function chatSessionNamespace({
+  environment,
+  ownerId,
+  sha256 = sealedIdb.sha256Hex
+}) {
+  return `athena-chat:${(await sha256(`${environment}|${ownerId}`)).slice(0, 32)}:`;
+}
+function chatSessionKey({
+  namespace,
+  principal,
+  threadId
+}) {
+  return storage.sessionNamespace(namespace, principal) + threadId;
+}
+async function adoptUnscopedChatSessions({
+  backend,
+  namespace,
+  principal
+}) {
+  var _a;
+  let moved = 0;
+  for (const key of await ((_a = backend.getAllKeys) == null ? void 0 : _a.call(backend)) ?? []) {
+    if (!key.startsWith(namespace)) continue;
+    const threadId = key.slice(namespace.length);
+    if (threadId === "" || threadId.includes(":")) continue;
+    const raw = await backend.getItem(key);
+    if (raw === null) continue;
+    const target = chatSessionKey({ namespace, principal, threadId });
+    if (await backend.getItem(target) !== null) continue;
+    await backend.setItem(target, raw);
+    await backend.removeItem(key);
+    moved += 1;
+  }
+  return moved;
+}
+const PAGE_MEMORY_FORMAT = 5;
+const memoryRecords = /* @__PURE__ */ new Map();
+const memoryListeners = /* @__PURE__ */ new Set();
+function announceMemory(key) {
+  for (const listener of [...memoryListeners]) {
+    try {
+      listener(key);
+    } catch {
+    }
+  }
+}
+const memoryBackend = {
+  getItem: (key) => {
+    const record = memoryRecords.get(key);
+    return record === void 0 ? null : JSON.stringify({ statewireStorageVersion: PAGE_MEMORY_FORMAT, ...record });
+  },
+  setItem: () => {
+    throw new Error("athena: page-memory chat sessions are written by their sessions only");
+  },
+  removeItem: (key) => {
+    if (memoryRecords.delete(key)) announceMemory(key);
+  },
+  getAllKeys: () => [...memoryRecords.keys()],
+  subscribe: (listener) => {
+    memoryListeners.add(listener);
+    return () => {
+      memoryListeners.delete(listener);
+    };
+  }
+};
+function chatSessionMemoryBackend() {
+  return memoryBackend;
+}
+function chatSessionMemoryNamespace(scope) {
+  return `${scope}:`;
+}
+const PageMemorySession = tap.resource(function usePageMemorySession({
+  key
+}) {
+  return require$$0.useMemo(
+    () => ({
+      durable: false,
+      load: () => memoryRecords.get(key) ?? null,
+      save: (record) => {
+        memoryRecords.set(key, record);
+        announceMemory(key);
+      }
+    }),
+    [key]
+  );
+});
+const CHAT_SESSION_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+const CHAT_SESSION_MAX_ENTRIES = 50;
+function ChatSessionStorage(options) {
+  if (options.kind === "memory") {
+    return PageMemorySession({
+      key: chatSessionKey({
+        namespace: chatSessionMemoryNamespace(options.scope),
+        principal: options.principal,
+        threadId: options.threadId
+      })
+    });
+  }
+  return storage.IndexedDbSession({
+    database: options.database ?? CHAT_SESSION_DATABASE,
+    namespace: options.namespace,
+    principal: options.principal,
+    key: options.threadId,
+    codec: options.codec,
+    protocol: statewireTransport.DEEP_AGENT_STATEWIRE_PROTOCOL,
+    retention: options.retention ?? { maxAgeMs: CHAT_SESSION_MAX_AGE_MS, maxEntries: CHAT_SESSION_MAX_ENTRIES },
+    ...options.onError && { onError: options.onError },
+    ...options.onEvict && { onEvict: options.onEvict }
+  });
+}
+function chatSessionBackend(database = CHAT_SESSION_DATABASE) {
+  return storage.indexedDbBackend(database);
+}
+function legacyEntry(message) {
+  return {
+    state: "held",
+    failed: message.failure !== void 0,
+    id: message.id,
+    threadId: message.threadId,
+    text: message.text,
+    queuedAt: message.queuedAt,
+    newChat: message.newChat,
+    durable: true,
+    ...message.composerMarkdown !== void 0 && { composerMarkdown: message.composerMarkdown },
+    ...message.composerHtml !== void 0 && { composerHtml: message.composerHtml },
+    ...message.metadata !== void 0 && { metadata: message.metadata },
+    ...message.files !== void 0 && { files: message.files },
+    ...message.attachments !== void 0 && { attachments: message.attachments }
+  };
+}
+async function listChatOutboxes({
+  backend,
+  namespace,
+  principal,
+  codec,
+  legacy
+}) {
+  var _a;
+  const keys = await ((_a = backend.getAllKeys) == null ? void 0 : _a.call(backend)) ?? [];
+  const scope = storage.sessionNamespace(namespace, principal);
+  const byThread = /* @__PURE__ */ new Map();
+  let unreadable = 0;
+  for (const key of keys) {
+    if (!key.startsWith(scope)) continue;
+    const threadId = key.slice(scope.length);
+    let outboxes;
+    try {
+      outboxes = await storage.readOutboxes(
+        { ...backend, getAllKeys: () => [key] },
+        { namespace, principal, protocol: statewireTransport.DEEP_AGENT_STATEWIRE_PROTOCOL, ...codec && { codec } }
+      );
+    } catch {
+      unreadable += 1;
+      continue;
+    }
+    for (const outbox of outboxes) {
+      const entries = outbox.entries.flatMap((entry) => {
+        const chat = chatOutboxEntry.chatOutboxEntryOf(entry, threadId);
+        if (!chat) return [];
+        const failed = chatOutboxEntry.readChatOutboxLocalMeta(entry.localMeta).error !== void 0;
+        return [{ ...chat, state: entry.state, failed }];
+      });
+      if (entries.length > 0) byThread.set(threadId, [...byThread.get(threadId) ?? [], ...entries]);
+    }
+  }
+  if (legacy) {
+    for (const message of await legacy.listAll().catch(() => [])) {
+      const list = byThread.get(message.threadId) ?? [];
+      if (list.some((entry) => entry.id === message.id)) continue;
+      byThread.set(message.threadId, [...list, legacyEntry(message)]);
+    }
+  }
+  const threads = [...byThread].map(([threadId, entries]) => ({ threadId, entries: [...entries].sort((a, b) => a.queuedAt - b.queuedAt) })).sort((a, b) => {
+    var _a2, _b;
+    return (((_a2 = a.entries[0]) == null ? void 0 : _a2.queuedAt) ?? 0) - (((_b = b.entries[0]) == null ? void 0 : _b.queuedAt) ?? 0);
+  });
+  return { threads, unreadable };
+}
+async function countChatOutboxMessages(source) {
+  const { legacy, ...rest } = source;
+  const listing = await listChatOutboxes(rest);
+  const legacyCount = legacy ? await legacy.count().catch(() => 0) : 0;
+  return listing.threads.reduce((sum, thread) => sum + thread.entries.length, 0) + listing.unreadable + legacyCount;
+}
+async function clearChatOutboxes({ backend, namespace, legacy }) {
+  var _a;
+  const keys = await ((_a = backend.getAllKeys) == null ? void 0 : _a.call(backend)) ?? [];
+  for (const key of keys) if (key.startsWith(namespace)) await backend.removeItem(key);
+  await (legacy == null ? void 0 : legacy.clear());
+}
+const EMPTY_LISTING = { threads: [], unreadable: 0 };
+function createChatOutboxDirectory(source) {
+  const listeners = /* @__PURE__ */ new Set();
+  let snapshot = EMPTY_LISTING;
+  let stopRemote;
+  let reading = Promise.resolve();
+  const refresh = () => {
+    reading = reading.then(async () => {
+      var _a;
+      try {
+        snapshot = await listChatOutboxes(source);
+      } catch (error) {
+        (_a = source.onError) == null ? void 0 : _a.call(source, error);
+        return;
+      }
+      for (const listener of listeners) {
+        try {
+          listener();
+        } catch {
+        }
+      }
+    });
+  };
+  return {
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      if (listeners.size === 1) {
+        const { codec } = source;
+        stopRemote = storage.subscribeOutboxes(
+          source.backend,
+          {
+            namespace: source.namespace,
+            principal: source.principal,
+            protocol: statewireTransport.DEEP_AGENT_STATEWIRE_PROTOCOL,
+            ...codec && {
+              codec: {
+                encode: (plain) => codec.encode(plain),
+                decode: (stored) => codec.decode(stored).catch(() => "null")
+              }
+            }
+          },
+          () => refresh(),
+          (error) => {
+            var _a;
+            return (_a = source.onError) == null ? void 0 : _a.call(source, error);
+          }
+        );
+      }
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          stopRemote == null ? void 0 : stopRemote();
+          stopRemote = void 0;
+        }
+      };
+    },
+    refresh
+  };
+}
+exports.CHAT_SESSION_DATABASE = CHAT_SESSION_DATABASE;
+exports.CHAT_SESSION_MAX_AGE_MS = CHAT_SESSION_MAX_AGE_MS;
+exports.CHAT_SESSION_MAX_ENTRIES = CHAT_SESSION_MAX_ENTRIES;
+exports.ChatSessionStorage = ChatSessionStorage;
+exports.SEALED_SESSION_PREFIX = SEALED_SESSION_PREFIX;
+exports.adoptUnscopedChatSessions = adoptUnscopedChatSessions;
+exports.chatSessionBackend = chatSessionBackend;
+exports.chatSessionKey = chatSessionKey;
+exports.chatSessionMemoryBackend = chatSessionMemoryBackend;
+exports.chatSessionMemoryNamespace = chatSessionMemoryNamespace;
+exports.chatSessionNamespace = chatSessionNamespace;
+exports.clearChatOutboxes = clearChatOutboxes;
+exports.countChatOutboxMessages = countChatOutboxMessages;
+exports.createChatOutboxDirectory = createChatOutboxDirectory;
+exports.createSealedSessionCodec = createSealedSessionCodec;
+exports.listChatOutboxes = listChatOutboxes;
+//# sourceMappingURL=chat-outbox-storage.cjs.map

package/dist/agent-runtime/src/chat-outbox-storage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-outbox-storage.cjs","sources":["../../../../agent-runtime/src/chat-outbox-storage.ts"],"sourcesContent":["import { type ResourceElement, resource } from \"@assistant-ui/tap\";\nimport type { StatewireClient } from \"statewire\";\nimport {\n  IndexedDbSession,\n  indexedDbBackend,\n  type KeyValueSessionStorage,\n  type ReadOutboxes,\n  readOutboxes,\n  sessionNamespace,\n  subscribeOutboxes,\n} from \"statewire/storage\";\nimport { useMemo } from \"react\";\nimport { type ChatOutboxEntry, chatOutboxEntryOf, readChatOutboxLocalMeta } from \"./chat-outbox-entry\";\nimport type { LegacyChatOutboxMessage, LegacyChatOutboxReader } from \"./chat-outbox-legacy\";\nimport { base64ToBytes, bytesToBase64, openText, sealText, sha256Hex } from \"./sealed-idb\";\nimport { DEEP_AGENT_STATEWIRE_PROTOCOL } from \"./statewire-transport\";\n\n/**\n * Where a chat thread's statewire session lives on a surface that keeps messages typed while\n * Athena can't be reached (the chat outbox is the session's outbox, so its storage is the\n * session's):\n *\n * - **Sealed** ({@link ChatSessionStorage} `kind: \"sealed\"`): statewire's `IndexedDbSession`, one\n *   record per thread under a per-person namespace, every record sealed with AES-GCM-256 under the\n *   person's key ({@link createSealedSessionCodec}). Olympus and the desktop app.\n * - **Memory** (`kind: \"memory\"`): page memory, for a deployment that lets devices keep no copies:\n *   what waits survives thread switches and remounts, not a reload, and its rows say so\n *   (`durable: false`). {@link chatSessionMemoryBackend} lists those records too.\n *\n * Cross-thread lists (the tray's \"waiting elsewhere\", sign-out counts) read the same backend,\n * namespace and codec ({@link createChatOutboxDirectory}).\n */\n\n/** The IndexedDB database sealed chat sessions are kept in. */\nexport const CHAT_SESSION_DATABASE = \"athena-chat-sessions\";\n\n/** Prefix of a sealed record; anything else is refused rather than read as plaintext. */\nexport const SEALED_SESSION_PREFIX = \"athena-sealed:1:\";\n\n/** What a codec asks the key for: opening what is kept, or keeping something new. */\nexport type ChatSessionKeyPurpose = \"read\" | \"write\";\n\n/**\n * The person's AES-GCM key: `read` opens what is already kept (any key that exists), `write` keeps\n * something new (a key only while the deployment lets devices keep copies). `null`: none.\n */\nexport type ChatSessionKeyProvider = (purpose: ChatSessionKeyPurpose) => Promise<CryptoKey | null>;\n\n/**\n * Seals and opens record text without WebCrypto, for a runtime that has none (React Native's\n * Hermes): the host's own cipher (an XChaCha20-Poly1305 vault, say). `aad` must be bound as\n * additional data; `open` throws for the wrong key, the wrong `aad` or a damaged record.\n */\nexport interface SealedSessionCipher {\n  seal(args: { text: string; aad: string; purpose: \"write\" }): Promise<string>;\n  open(args: { sealed: string; aad: string; purpose: \"read\" }): Promise<string>;\n}\n\n/**\n * A `KeyValueSessionStorage` codec sealing each stored record (the `scope` bound as additional\n * data, so a record copied under another person's scope does not open): AES-GCM-256 with a fresh\n * IV through WebCrypto (`getKey`), or the host's {@link SealedSessionCipher} where WebCrypto is\n * missing (`cipher`). Encoding without a write key, or decoding a record that does not open,\n * throws: statewire then reports a storage error and leaves the stored record where it is. Create\n * one per person and keep it: the session resource is keyed by the codec's identity.\n */\nexport function createSealedSessionCodec(\n  options:\n    | { getKey: ChatSessionKeyProvider; scope: string; cipher?: never }\n    | { cipher: SealedSessionCipher; scope: string; getKey?: never },\n): KeyValueSessionStorage.Codec {\n  const aad = `athena-chat-session|1|${options.scope}`;\n  const { cipher } = options;\n  if (cipher) {\n    return {\n      async encode(plain) {\n        return SEALED_SESSION_PREFIX + (await cipher.seal({ text: plain, aad, purpose: \"write\" }));\n      },\n      async decode(stored) {\n        if (!stored.startsWith(SEALED_SESSION_PREFIX)) throw new Error(\"athena: chat session record is not sealed\");\n        return cipher.open({ sealed: stored.slice(SEALED_SESSION_PREFIX.length), aad, purpose: \"read\" });\n      },\n    };\n  }\n  const { getKey } = options;\n  return {\n    async encode(plain) {\n      const key = await getKey(\"write\");\n      if (!key) throw new Error(\"athena: no key to keep chat sessions on this device\");\n      return SEALED_SESSION_PREFIX + bytesToBase64(await sealText({ key, text: plain, aad }));\n    },\n    async decode(stored) {\n      if (!stored.startsWith(SEALED_SESSION_PREFIX)) throw new Error(\"athena: chat session record is not sealed\");\n      const key = await getKey(\"read\");\n      if (!key) throw new Error(\"athena: no key to open chat sessions on this device\");\n      return openText({ key, sealed: base64ToBytes(stored.slice(SEALED_SESSION_PREFIX.length)), aad });\n    },\n  };\n}\n\n/**\n * The namespace a person's chat sessions are kept under: their scope hashed, so the database names\n * no one. `environment` keeps deployments that share an origin apart.\n */\nexport async function chatSessionNamespace({\n  environment,\n  ownerId,\n  sha256 = sha256Hex,\n}: {\n  environment: string;\n  ownerId: string;\n  /** Hex SHA-256 of a string; pass the host's own where WebCrypto is missing (React Native). */\n  sha256?: (value: string) => Promise<string>;\n}): Promise<string> {\n  return `athena-chat:${(await sha256(`${environment}|${ownerId}`)).slice(0, 32)}:`;\n}\n\n/**\n * The key a thread's chat session is stored under: `<namespace><principal>:<threadId>`, the layout\n * statewire 0.25 keeps session records in.\n */\nexport function chatSessionKey({\n  namespace,\n  principal,\n  threadId,\n}: {\n  namespace: string;\n  principal: string;\n  threadId: string;\n}): string {\n  return sessionNamespace(namespace, principal) + threadId;\n}\n\n/**\n * Moves the sealed chat sessions statewire 0.24 kept under `namespace + threadId` to\n * `principal`'s scoped keys ({@link chatSessionKey}). `namespace` is one person's\n * ({@link chatSessionNamespace} hashes their scope), so its unscoped records are theirs: call it\n * with the signed-in person's own namespace and principal only. Records move as stored (sealed;\n * the codec binds the person's scope, not the key). A key with a `:` after the namespace is a\n * scoped one (an encoded principal has none) and is never touched. An unscoped record whose\n * scoped key already holds one is left where it is (a 0.24 tab still open can write there), never\n * written over the newer record; a sign-out the person chose clears it with the rest of the\n * namespace. Returns how many records moved.\n */\nexport async function adoptUnscopedChatSessions({\n  backend,\n  namespace,\n  principal,\n}: {\n  backend: KeyValueSessionStorage.Backend;\n  namespace: string;\n  principal: string;\n}): Promise<number> {\n  let moved = 0;\n  for (const key of (await backend.getAllKeys?.()) ?? []) {\n    if (!key.startsWith(namespace)) continue;\n    const threadId = key.slice(namespace.length);\n    if (threadId === \"\" || threadId.includes(\":\")) continue;\n    const raw = await backend.getItem(key);\n    if (raw === null) continue;\n    const target = chatSessionKey({ namespace, principal, threadId });\n    if ((await backend.getItem(target)) !== null) continue;\n    await backend.setItem(target, raw);\n    await backend.removeItem(key);\n    moved += 1;\n  }\n  return moved;\n}\n\nexport type ChatSessionStorageOptions =\n  | {\n      kind: \"sealed\";\n      threadId: string;\n      /** {@link chatSessionNamespace}; one per person. */\n      namespace: string;\n      /** The signed-in account (`sessionPrincipal(userId)`): records live under its scoped keys. */\n      principal: string;\n      /** {@link createSealedSessionCodec}; one per person, kept for the life of the sign-in. */\n      codec: KeyValueSessionStorage.Codec;\n      database?: string;\n      retention?: KeyValueSessionStorage.Options[\"retention\"];\n      onError?: (error: unknown) => void;\n      onEvict?: (event: KeyValueSessionStorage.EvictEvent) => void;\n    }\n  | {\n      kind: \"memory\";\n      threadId: string;\n      /**\n       * Names the person: another person's thread never shares a record. The records list under\n       * {@link chatSessionMemoryNamespace} of it.\n       */\n      scope: string;\n      /** The signed-in account (`sessionPrincipal(userId)`), as for sealed sessions. */\n      principal: string;\n    };\n\n/** The stored format page-memory records list in: statewire's session record, untagged. */\nconst PAGE_MEMORY_FORMAT = 5;\n\n// process-local by design: page memory is the store (\"memory\" sessions survive remounts, not reloads).\nconst memoryRecords = new Map<string, StatewireClient.SessionRecord>();\nconst memoryListeners = new Set<(key: string) => void>();\n\nfunction announceMemory(key: string): void {\n  for (const listener of [...memoryListeners]) {\n    try {\n      listener(key);\n    } catch {\n      // A listener's fault never reaches the session.\n    }\n  }\n}\n\n/**\n * The page-memory records of `kind: \"memory\"` sessions as a key-value backend, so the cross-thread\n * listing reads them as it reads sealed ones (stored format, no codec). Only `removeItem` writes.\n */\nconst memoryBackend: KeyValueSessionStorage.Backend = {\n  getItem: (key) => {\n    const record = memoryRecords.get(key);\n    // Format 5: the record without a principal tag, which the scoped key already names.\n    return record === undefined ? null : JSON.stringify({ statewireStorageVersion: PAGE_MEMORY_FORMAT, ...record });\n  },\n  setItem: () => {\n    throw new Error(\"athena: page-memory chat sessions are written by their sessions only\");\n  },\n  removeItem: (key) => {\n    if (memoryRecords.delete(key)) announceMemory(key);\n  },\n  getAllKeys: () => [...memoryRecords.keys()],\n  subscribe: (listener) => {\n    memoryListeners.add(listener);\n    return () => {\n      memoryListeners.delete(listener);\n    };\n  },\n};\n\n/** The backend that lists every `kind: \"memory\"` chat session of this page (read and remove only). */\nexport function chatSessionMemoryBackend(): KeyValueSessionStorage.Backend {\n  return memoryBackend;\n}\n\n/** The namespace `scope`'s page-memory chat sessions list under ({@link chatSessionMemoryBackend}). */\nexport function chatSessionMemoryNamespace(scope: string): string {\n  return `${scope}:`;\n}\n\nconst PageMemorySession = resource(function usePageMemorySession({\n  key,\n}: {\n  key: string;\n}): StatewireClient.SessionStorage {\n  return useMemo(\n    () => ({\n      durable: false,\n      load: () => memoryRecords.get(key) ?? null,\n      save: (record) => {\n        memoryRecords.set(key, record);\n        announceMemory(key);\n      },\n    }),\n    [key],\n  );\n});\n\n/** Records no tab has mounted go after this long, sends and all (statewire 0.27.1 retention). */\nexport const CHAT_SESSION_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;\n/** Inactive records kept per person. */\nexport const CHAT_SESSION_MAX_ENTRIES = 50;\n\n/** The thread's session storage element (`storage.session`) for the surface's mode. */\nexport function ChatSessionStorage(\n  options: ChatSessionStorageOptions,\n): ResourceElement<StatewireClient.SessionStorage> {\n  if (options.kind === \"memory\") {\n    return PageMemorySession({\n      key: chatSessionKey({\n        namespace: chatSessionMemoryNamespace(options.scope),\n        principal: options.principal,\n        threadId: options.threadId,\n      }),\n    });\n  }\n  return IndexedDbSession({\n    database: options.database ?? CHAT_SESSION_DATABASE,\n    namespace: options.namespace,\n    principal: options.principal,\n    key: options.threadId,\n    codec: options.codec,\n    protocol: DEEP_AGENT_STATEWIRE_PROTOCOL,\n    retention: options.retention ?? { maxAgeMs: CHAT_SESSION_MAX_AGE_MS, maxEntries: CHAT_SESSION_MAX_ENTRIES },\n    ...(options.onError && { onError: options.onError }),\n    ...(options.onEvict && { onEvict: options.onEvict }),\n  });\n}\n\n/** The key-value backend sealed chat sessions write through (`indexedDbBackend`). */\nexport function chatSessionBackend(database = CHAT_SESSION_DATABASE): KeyValueSessionStorage.Backend {\n  return indexedDbBackend(database);\n}\n\n/** A waiting message as a listing reads it: the entry, and where it stands in its outbox. */\nexport interface ChatOutboxListedEntry extends ChatOutboxEntry {\n  /** Held (waiting here), queued to go, or sent and not answered yet. Legacy records read as held. */\n  state?: StatewireClient.OutboxEntry[\"state\"];\n  /** It failed (a held entry carrying `localMeta.error`): Retry, Edit or Discard. */\n  failed?: boolean;\n}\n\n/** One thread's waiting messages, as the device keeps them. */\nexport interface ChatOutboxDirectoryThread {\n  threadId: string;\n  /** Its messages still to be sent (held, queued or sending), in queue order. */\n  entries: readonly ChatOutboxListedEntry[];\n}\n\nexport interface ChatOutboxListing {\n  threads: readonly ChatOutboxDirectoryThread[];\n  /** Records that would not open (another key, a damaged record): they may hold messages too. */\n  unreadable: number;\n}\n\nexport interface ChatOutboxStorageSource {\n  backend: KeyValueSessionStorage.Backend;\n  namespace: string;\n  /** Whose sessions: only records under its scoped keys ({@link chatSessionKey}) are listed. */\n  principal: string;\n  codec?: KeyValueSessionStorage.Codec;\n  /** The previous store, read until each thread's records are migrated. */\n  legacy?: LegacyChatOutboxReader;\n}\n\nfunction legacyEntry(message: LegacyChatOutboxMessage): ChatOutboxListedEntry {\n  return {\n    state: \"held\",\n    failed: message.failure !== undefined,\n    id: message.id,\n    threadId: message.threadId,\n    text: message.text,\n    queuedAt: message.queuedAt,\n    newChat: message.newChat,\n    durable: true,\n    ...(message.composerMarkdown !== undefined && { composerMarkdown: message.composerMarkdown }),\n    ...(message.composerHtml !== undefined && { composerHtml: message.composerHtml }),\n    ...(message.metadata !== undefined && { metadata: message.metadata }),\n    ...(message.files !== undefined && { files: message.files }),\n    ...(message.attachments !== undefined && { attachments: message.attachments }),\n  };\n}\n\n/**\n * Every thread's waiting messages `principal` keeps under `namespace`, mounted or not\n * (`readOutboxes`, one record at a time so a record that does not open is counted, not fatal),\n * merged with the legacy store's records not migrated yet. Threads are ordered by their oldest\n * message.\n */\nexport async function listChatOutboxes({\n  backend,\n  namespace,\n  principal,\n  codec,\n  legacy,\n}: ChatOutboxStorageSource): Promise<ChatOutboxListing> {\n  const keys = (await backend.getAllKeys?.()) ?? [];\n  const scope = sessionNamespace(namespace, principal);\n  const byThread = new Map<string, ChatOutboxListedEntry[]>();\n  let unreadable = 0;\n  for (const key of keys) {\n    if (!key.startsWith(scope)) continue;\n    const threadId = key.slice(scope.length);\n    let outboxes: readonly ReadOutboxes.Outbox[];\n    try {\n      outboxes = await readOutboxes(\n        { ...backend, getAllKeys: () => [key] },\n        { namespace, principal, protocol: DEEP_AGENT_STATEWIRE_PROTOCOL, ...(codec && { codec }) },\n      );\n    } catch {\n      unreadable += 1;\n      continue;\n    }\n    for (const outbox of outboxes) {\n      const entries = outbox.entries.flatMap((entry) => {\n        const chat = chatOutboxEntryOf(entry, threadId);\n        if (!chat) return [];\n        const failed = readChatOutboxLocalMeta(entry.localMeta).error !== undefined;\n        return [{ ...chat, state: entry.state, failed }];\n      });\n      if (entries.length > 0) byThread.set(threadId, [...(byThread.get(threadId) ?? []), ...entries]);\n    }\n  }\n  if (legacy) {\n    for (const message of await legacy.listAll().catch(() => [])) {\n      const list = byThread.get(message.threadId) ?? [];\n      if (list.some((entry) => entry.id === message.id)) continue;\n      byThread.set(message.threadId, [...list, legacyEntry(message)]);\n    }\n  }\n  const threads = [...byThread]\n    .map(([threadId, entries]) => ({ threadId, entries: [...entries].sort((a, b) => a.queuedAt - b.queuedAt) }))\n    .sort((a, b) => (a.entries[0]?.queuedAt ?? 0) - (b.entries[0]?.queuedAt ?? 0));\n  return { threads, unreadable };\n}\n\n/**\n * How many messages wait across every thread (a sign-out asks first while any do). Records that do\n * not open count as one each: they may hold someone's only copy. Legacy records count unopened.\n */\nexport async function countChatOutboxMessages(source: ChatOutboxStorageSource): Promise<number> {\n  const { legacy, ...rest } = source;\n  const listing = await listChatOutboxes(rest);\n  const legacyCount = legacy ? await legacy.count().catch(() => 0) : 0;\n  return listing.threads.reduce((sum, thread) => sum + thread.entries.length, 0) + listing.unreadable + legacyCount;\n}\n\n/**\n * Every chat session record under `namespace` (every principal's, and records 0.24 left unscoped),\n * and the legacy store's records, gone (a sign-out the person chose).\n */\nexport async function clearChatOutboxes({ backend, namespace, legacy }: ChatOutboxStorageSource): Promise<void> {\n  const keys = (await backend.getAllKeys?.()) ?? [];\n  for (const key of keys) if (key.startsWith(namespace)) await backend.removeItem(key);\n  await legacy?.clear();\n}\n\n/** A live view of every thread's waiting messages, for the tray and the \"waiting to sync\" panels. */\nexport interface ChatOutboxDirectory {\n  getSnapshot(): ChatOutboxListing;\n  subscribe(listener: () => void): () => void;\n  /** Read again now (after a migration, a sign-out). */\n  refresh(): void;\n}\n\nconst EMPTY_LISTING: ChatOutboxListing = { threads: [], unreadable: 0 };\n\n/**\n * {@link listChatOutboxes}, re-read whenever a record under `namespace` is saved here or in another\n * tab (`backend.subscribe`), while anything listens. One per person.\n */\nexport function createChatOutboxDirectory(\n  source: ChatOutboxStorageSource & { onError?: (error: unknown) => void },\n): ChatOutboxDirectory {\n  const listeners = new Set<() => void>();\n  let snapshot = EMPTY_LISTING;\n  let stopRemote: (() => void) | undefined;\n  let reading = Promise.resolve();\n  const refresh = () => {\n    reading = reading.then(async () => {\n      try {\n        snapshot = await listChatOutboxes(source);\n      } catch (error) {\n        source.onError?.(error);\n        return;\n      }\n      for (const listener of listeners) {\n        try {\n          listener();\n        } catch {\n          // A listener's fault never reaches the directory.\n        }\n      }\n    });\n  };\n  return {\n    getSnapshot: () => snapshot,\n    subscribe(listener) {\n      listeners.add(listener);\n      if (listeners.size === 1) {\n        // subscribeOutboxes hears saves in this runtime and, through the backend, in others; its\n        // own read only signals (a record that does not open reads as empty there).\n        const { codec } = source;\n        stopRemote = subscribeOutboxes(\n          source.backend,\n          {\n            namespace: source.namespace,\n            principal: source.principal,\n            protocol: DEEP_AGENT_STATEWIRE_PROTOCOL,\n            ...(codec && {\n              codec: {\n                encode: (plain: string) => codec.encode(plain),\n                decode: (stored: string) => codec.decode(stored).catch(() => \"null\"),\n              },\n            }),\n          },\n          () => refresh(),\n          (error) => source.onError?.(error),\n        );\n      }\n      return () => {\n        listeners.delete(listener);\n        if (listeners.size === 0) {\n          stopRemote?.();\n          stopRemote = undefined;\n        }\n      };\n    },\n    refresh,\n  };\n}\n"],"names":["bytesToBase64","sealText","openText","base64ToBytes","sha256Hex","sessionNamespace","resource","useMemo","IndexedDbSession","DEEP_AGENT_STATEWIRE_PROTOCOL","indexedDbBackend","readOutboxes","chatOutboxEntryOf","readChatOutboxLocalMeta","_a","subscribeOutboxes"],"mappings":";;;;;;;;AAkCO,MAAM,wBAAwB;AAG9B,MAAM,wBAAwB;AA6B9B,SAAS,yBACd,SAG8B;AAC9B,QAAM,MAAM,yBAAyB,QAAQ,KAAK;AAClD,QAAM,EAAE,WAAW;AACnB,MAAI,QAAQ;AACV,WAAO;AAAA,MACL,MAAM,OAAO,OAAO;AAClB,eAAO,wBAAyB,MAAM,OAAO,KAAK,EAAE,MAAM,OAAO,KAAK,SAAS,SAAS;AAAA,MAC1F;AAAA,MACA,MAAM,OAAO,QAAQ;AACnB,YAAI,CAAC,OAAO,WAAW,qBAAqB,EAAG,OAAM,IAAI,MAAM,2CAA2C;AAC1G,eAAO,OAAO,KAAK,EAAE,QAAQ,OAAO,MAAM,sBAAsB,MAAM,GAAG,KAAK,SAAS,OAAA,CAAQ;AAAA,MACjG;AAAA,IAAA;AAAA,EAEJ;AACA,QAAM,EAAE,WAAW;AACnB,SAAO;AAAA,IACL,MAAM,OAAO,OAAO;AAClB,YAAM,MAAM,MAAM,OAAO,OAAO;AAChC,UAAI,CAAC,IAAK,OAAM,IAAI,MAAM,qDAAqD;AAC/E,aAAO,wBAAwBA,wBAAc,MAAMC,mBAAS,EAAE,KAAK,MAAM,OAAO,IAAA,CAAK,CAAC;AAAA,IACxF;AAAA,IACA,MAAM,OAAO,QAAQ;AACnB,UAAI,CAAC,OAAO,WAAW,qBAAqB,EAAG,OAAM,IAAI,MAAM,2CAA2C;AAC1G,YAAM,MAAM,MAAM,OAAO,MAAM;AAC/B,UAAI,CAAC,IAAK,OAAM,IAAI,MAAM,qDAAqD;AAC/E,aAAOC,mBAAS,EAAE,KAAK,QAAQC,UAAAA,cAAc,OAAO,MAAM,sBAAsB,MAAM,CAAC,GAAG,IAAA,CAAK;AAAA,IACjG;AAAA,EAAA;AAEJ;AAMA,eAAsB,qBAAqB;AAAA,EACzC;AAAA,EACA;AAAA,EACA,SAASC,UAAAA;AACX,GAKoB;AAClB,SAAO,gBAAgB,MAAM,OAAO,GAAG,WAAW,IAAI,OAAO,EAAE,GAAG,MAAM,GAAG,EAAE,CAAC;AAChF;AAMO,SAAS,eAAe;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AACF,GAIW;AACT,SAAOC,yBAAiB,WAAW,SAAS,IAAI;AAClD;AAaA,eAAsB,0BAA0B;AAAA,EAC9C;AAAA,EACA;AAAA,EACA;AACF,GAIoB;;AAClB,MAAI,QAAQ;AACZ,aAAW,OAAQ,QAAM,aAAQ,eAAR,qCAA2B,CAAA,GAAI;AACtD,QAAI,CAAC,IAAI,WAAW,SAAS,EAAG;AAChC,UAAM,WAAW,IAAI,MAAM,UAAU,MAAM;AAC3C,QAAI,aAAa,MAAM,SAAS,SAAS,GAAG,EAAG;AAC/C,UAAM,MAAM,MAAM,QAAQ,QAAQ,GAAG;AACrC,QAAI,QAAQ,KAAM;AAClB,UAAM,SAAS,eAAe,EAAE,WAAW,WAAW,UAAU;AAChE,QAAK,MAAM,QAAQ,QAAQ,MAAM,MAAO,KAAM;AAC9C,UAAM,QAAQ,QAAQ,QAAQ,GAAG;AACjC,UAAM,QAAQ,WAAW,GAAG;AAC5B,aAAS;AAAA,EACX;AACA,SAAO;AACT;AA8BA,MAAM,qBAAqB;AAG3B,MAAM,oCAAoB,IAAA;AAC1B,MAAM,sCAAsB,IAAA;AAE5B,SAAS,eAAe,KAAmB;AACzC,aAAW,YAAY,CAAC,GAAG,eAAe,GAAG;AAC3C,QAAI;AACF,eAAS,GAAG;AAAA,IACd,QAAQ;AAAA,IAER;AAAA,EACF;AACF;AAMA,MAAM,gBAAgD;AAAA,EACpD,SAAS,CAAC,QAAQ;AAChB,UAAM,SAAS,cAAc,IAAI,GAAG;AAEpC,WAAO,WAAW,SAAY,OAAO,KAAK,UAAU,EAAE,yBAAyB,oBAAoB,GAAG,QAAQ;AAAA,EAChH;AAAA,EACA,SAAS,MAAM;AACb,UAAM,IAAI,MAAM,sEAAsE;AAAA,EACxF;AAAA,EACA,YAAY,CAAC,QAAQ;AACnB,QAAI,cAAc,OAAO,GAAG,kBAAkB,GAAG;AAAA,EACnD;AAAA,EACA,YAAY,MAAM,CAAC,GAAG,cAAc,MAAM;AAAA,EAC1C,WAAW,CAAC,aAAa;AACvB,oBAAgB,IAAI,QAAQ;AAC5B,WAAO,MAAM;AACX,sBAAgB,OAAO,QAAQ;AAAA,IACjC;AAAA,EACF;AACF;AAGO,SAAS,2BAA2D;AACzE,SAAO;AACT;AAGO,SAAS,2BAA2B,OAAuB;AAChE,SAAO,GAAG,KAAK;AACjB;AAEA,MAAM,oBAAoBC,IAAAA,SAAS,SAAS,qBAAqB;AAAA,EAC/D;AACF,GAEmC;AACjC,SAAOC,WAAAA;AAAAA,IACL,OAAO;AAAA,MACL,SAAS;AAAA,MACT,MAAM,MAAM,cAAc,IAAI,GAAG,KAAK;AAAA,MACtC,MAAM,CAAC,WAAW;AAChB,sBAAc,IAAI,KAAK,MAAM;AAC7B,uBAAe,GAAG;AAAA,MACpB;AAAA,IAAA;AAAA,IAEF,CAAC,GAAG;AAAA,EAAA;AAER,CAAC;AAGM,MAAM,0BAA0B,IAAI,KAAK,KAAK,KAAK;AAEnD,MAAM,2BAA2B;AAGjC,SAAS,mBACd,SACiD;AACjD,MAAI,QAAQ,SAAS,UAAU;AAC7B,WAAO,kBAAkB;AAAA,MACvB,KAAK,eAAe;AAAA,QAClB,WAAW,2BAA2B,QAAQ,KAAK;AAAA,QACnD,WAAW,QAAQ;AAAA,QACnB,UAAU,QAAQ;AAAA,MAAA,CACnB;AAAA,IAAA,CACF;AAAA,EACH;AACA,SAAOC,yBAAiB;AAAA,IACtB,UAAU,QAAQ,YAAY;AAAA,IAC9B,WAAW,QAAQ;AAAA,IACnB,WAAW,QAAQ;AAAA,IACnB,KAAK,QAAQ;AAAA,IACb,OAAO,QAAQ;AAAA,IACf,UAAUC,mBAAAA;AAAAA,IACV,WAAW,QAAQ,aAAa,EAAE,UAAU,yBAAyB,YAAY,yBAAA;AAAA,IACjF,GAAI,QAAQ,WAAW,EAAE,SAAS,QAAQ,QAAA;AAAA,IAC1C,GAAI,QAAQ,WAAW,EAAE,SAAS,QAAQ,QAAA;AAAA,EAAQ,CACnD;AACH;AAGO,SAAS,mBAAmB,WAAW,uBAAuD;AACnG,SAAOC,QAAAA,iBAAiB,QAAQ;AAClC;AAiCA,SAAS,YAAY,SAAyD;AAC5E,SAAO;AAAA,IACL,OAAO;AAAA,IACP,QAAQ,QAAQ,YAAY;AAAA,IAC5B,IAAI,QAAQ;AAAA,IACZ,UAAU,QAAQ;AAAA,IAClB,MAAM,QAAQ;AAAA,IACd,UAAU,QAAQ;AAAA,IAClB,SAAS,QAAQ;AAAA,IACjB,SAAS;AAAA,IACT,GAAI,QAAQ,qBAAqB,UAAa,EAAE,kBAAkB,QAAQ,iBAAA;AAAA,IAC1E,GAAI,QAAQ,iBAAiB,UAAa,EAAE,cAAc,QAAQ,aAAA;AAAA,IAClE,GAAI,QAAQ,aAAa,UAAa,EAAE,UAAU,QAAQ,SAAA;AAAA,IAC1D,GAAI,QAAQ,UAAU,UAAa,EAAE,OAAO,QAAQ,MAAA;AAAA,IACpD,GAAI,QAAQ,gBAAgB,UAAa,EAAE,aAAa,QAAQ,YAAA;AAAA,EAAY;AAEhF;AAQA,eAAsB,iBAAiB;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAwD;;AACtD,QAAM,OAAQ,QAAM,aAAQ,eAAR,qCAA2B,CAAA;AAC/C,QAAM,QAAQL,QAAAA,iBAAiB,WAAW,SAAS;AACnD,QAAM,+BAAe,IAAA;AACrB,MAAI,aAAa;AACjB,aAAW,OAAO,MAAM;AACtB,QAAI,CAAC,IAAI,WAAW,KAAK,EAAG;AAC5B,UAAM,WAAW,IAAI,MAAM,MAAM,MAAM;AACvC,QAAI;AACJ,QAAI;AACF,iBAAW,MAAMM,QAAAA;AAAAA,QACf,EAAE,GAAG,SAAS,YAAY,MAAM,CAAC,GAAG,EAAA;AAAA,QACpC,EAAE,WAAW,WAAW,UAAUF,mBAAAA,+BAA+B,GAAI,SAAS,EAAE,MAAA,EAAM;AAAA,MAAG;AAAA,IAE7F,QAAQ;AACN,oBAAc;AACd;AAAA,IACF;AACA,eAAW,UAAU,UAAU;AAC7B,YAAM,UAAU,OAAO,QAAQ,QAAQ,CAAC,UAAU;AAChD,cAAM,OAAOG,gBAAAA,kBAAkB,OAAO,QAAQ;AAC9C,YAAI,CAAC,KAAM,QAAO,CAAA;AAClB,cAAM,SAASC,gBAAAA,wBAAwB,MAAM,SAAS,EAAE,UAAU;AAClE,eAAO,CAAC,EAAE,GAAG,MAAM,OAAO,MAAM,OAAO,QAAQ;AAAA,MACjD,CAAC;AACD,UAAI,QAAQ,SAAS,EAAG,UAAS,IAAI,UAAU,CAAC,GAAI,SAAS,IAAI,QAAQ,KAAK,CAAA,GAAK,GAAG,OAAO,CAAC;AAAA,IAChG;AAAA,EACF;AACA,MAAI,QAAQ;AACV,eAAW,WAAW,MAAM,OAAO,QAAA,EAAU,MAAM,MAAM,CAAA,CAAE,GAAG;AAC5D,YAAM,OAAO,SAAS,IAAI,QAAQ,QAAQ,KAAK,CAAA;AAC/C,UAAI,KAAK,KAAK,CAAC,UAAU,MAAM,OAAO,QAAQ,EAAE,EAAG;AACnD,eAAS,IAAI,QAAQ,UAAU,CAAC,GAAG,MAAM,YAAY,OAAO,CAAC,CAAC;AAAA,IAChE;AAAA,EACF;AACA,QAAM,UAAU,CAAC,GAAG,QAAQ,EACzB,IAAI,CAAC,CAAC,UAAU,OAAO,OAAO,EAAE,UAAU,SAAS,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAA,EAAI,EAC1G,KAAK,CAAC,GAAG,MAAA;;AAAO,cAAAC,MAAA,EAAE,QAAQ,CAAC,MAAX,gBAAAA,IAAc,aAAY,QAAM,OAAE,QAAQ,CAAC,MAAX,mBAAc,aAAY;AAAA,GAAE;AAC/E,SAAO,EAAE,SAAS,WAAA;AACpB;AAMA,eAAsB,wBAAwB,QAAkD;AAC9F,QAAM,EAAE,QAAQ,GAAG,KAAA,IAAS;AAC5B,QAAM,UAAU,MAAM,iBAAiB,IAAI;AAC3C,QAAM,cAAc,SAAS,MAAM,OAAO,QAAQ,MAAM,MAAM,CAAC,IAAI;AACnE,SAAO,QAAQ,QAAQ,OAAO,CAAC,KAAK,WAAW,MAAM,OAAO,QAAQ,QAAQ,CAAC,IAAI,QAAQ,aAAa;AACxG;AAMA,eAAsB,kBAAkB,EAAE,SAAS,WAAW,UAAkD;;AAC9G,QAAM,OAAQ,QAAM,aAAQ,eAAR,qCAA2B,CAAA;AAC/C,aAAW,OAAO,KAAM,KAAI,IAAI,WAAW,SAAS,EAAG,OAAM,QAAQ,WAAW,GAAG;AACnF,SAAM,iCAAQ;AAChB;AAUA,MAAM,gBAAmC,EAAE,SAAS,IAAI,YAAY,EAAA;AAM7D,SAAS,0BACd,QACqB;AACrB,QAAM,gCAAgB,IAAA;AACtB,MAAI,WAAW;AACf,MAAI;AACJ,MAAI,UAAU,QAAQ,QAAA;AACtB,QAAM,UAAU,MAAM;AACpB,cAAU,QAAQ,KAAK,YAAY;;AACjC,UAAI;AACF,mBAAW,MAAM,iBAAiB,MAAM;AAAA,MAC1C,SAAS,OAAO;AACd,qBAAO,YAAP,gCAAiB;AACjB;AAAA,MACF;AACA,iBAAW,YAAY,WAAW;AAChC,YAAI;AACF,mBAAA;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF,CAAC;AAAA,EACH;AACA,SAAO;AAAA,IACL,aAAa,MAAM;AAAA,IACnB,UAAU,UAAU;AAClB,gBAAU,IAAI,QAAQ;AACtB,UAAI,UAAU,SAAS,GAAG;AAGxB,cAAM,EAAE,UAAU;AAClB,qBAAaC,QAAAA;AAAAA,UACX,OAAO;AAAA,UACP;AAAA,YACE,WAAW,OAAO;AAAA,YAClB,WAAW,OAAO;AAAA,YAClB,UAAUN,mBAAAA;AAAAA,YACV,GAAI,SAAS;AAAA,cACX,OAAO;AAAA,gBACL,QAAQ,CAAC,UAAkB,MAAM,OAAO,KAAK;AAAA,gBAC7C,QAAQ,CAAC,WAAmB,MAAM,OAAO,MAAM,EAAE,MAAM,MAAM,MAAM;AAAA,cAAA;AAAA,YACrE;AAAA,UACF;AAAA,UAEF,MAAM,QAAA;AAAA,UACN,CAAC,UAAA;;AAAU,gCAAO,YAAP,gCAAiB;AAAA;AAAA,QAAK;AAAA,MAErC;AACA,aAAO,MAAM;AACX,kBAAU,OAAO,QAAQ;AACzB,YAAI,UAAU,SAAS,GAAG;AACxB;AACA,uBAAa;AAAA,QACf;AAAA,MACF;AAAA,IACF;AAAA,IACA;AAAA,EAAA;AAEJ;;;;;;;;;;;;;;;;;"}

package/dist/agent-runtime/src/chat-outbox-storage.d.ts

@@ -0,0 +1,194 @@
+import { type ResourceElement } from "@assistant-ui/tap";
+import type { StatewireClient } from "statewire";
+import { type KeyValueSessionStorage } from "statewire/storage";
+import { type ChatOutboxEntry } from "./chat-outbox-entry";
+import type { LegacyChatOutboxReader } from "./chat-outbox-legacy";
+/**
+ * Where a chat thread's statewire session lives on a surface that keeps messages typed while
+ * Athena can't be reached (the chat outbox is the session's outbox, so its storage is the
+ * session's):
+ *
+ * - **Sealed** ({@link ChatSessionStorage} `kind: "sealed"`): statewire's `IndexedDbSession`, one
+ *   record per thread under a per-person namespace, every record sealed with AES-GCM-256 under the
+ *   person's key ({@link createSealedSessionCodec}). Olympus and the desktop app.
+ * - **Memory** (`kind: "memory"`): page memory, for a deployment that lets devices keep no copies:
+ *   what waits survives thread switches and remounts, not a reload, and its rows say so
+ *   (`durable: false`). {@link chatSessionMemoryBackend} lists those records too.
+ *
+ * Cross-thread lists (the tray's "waiting elsewhere", sign-out counts) read the same backend,
+ * namespace and codec ({@link createChatOutboxDirectory}).
+ */
+/** The IndexedDB database sealed chat sessions are kept in. */
+export declare const CHAT_SESSION_DATABASE = "athena-chat-sessions";
+/** Prefix of a sealed record; anything else is refused rather than read as plaintext. */
+export declare const SEALED_SESSION_PREFIX = "athena-sealed:1:";
+/** What a codec asks the key for: opening what is kept, or keeping something new. */
+export type ChatSessionKeyPurpose = "read" | "write";
+/**
+ * The person's AES-GCM key: `read` opens what is already kept (any key that exists), `write` keeps
+ * something new (a key only while the deployment lets devices keep copies). `null`: none.
+ */
+export type ChatSessionKeyProvider = (purpose: ChatSessionKeyPurpose) => Promise<CryptoKey | null>;
+/**
+ * Seals and opens record text without WebCrypto, for a runtime that has none (React Native's
+ * Hermes): the host's own cipher (an XChaCha20-Poly1305 vault, say). `aad` must be bound as
+ * additional data; `open` throws for the wrong key, the wrong `aad` or a damaged record.
+ */
+export interface SealedSessionCipher {
+    seal(args: {
+        text: string;
+        aad: string;
+        purpose: "write";
+    }): Promise<string>;
+    open(args: {
+        sealed: string;
+        aad: string;
+        purpose: "read";
+    }): Promise<string>;
+}
+/**
+ * A `KeyValueSessionStorage` codec sealing each stored record (the `scope` bound as additional
+ * data, so a record copied under another person's scope does not open): AES-GCM-256 with a fresh
+ * IV through WebCrypto (`getKey`), or the host's {@link SealedSessionCipher} where WebCrypto is
+ * missing (`cipher`). Encoding without a write key, or decoding a record that does not open,
+ * throws: statewire then reports a storage error and leaves the stored record where it is. Create
+ * one per person and keep it: the session resource is keyed by the codec's identity.
+ */
+export declare function createSealedSessionCodec(options: {
+    getKey: ChatSessionKeyProvider;
+    scope: string;
+    cipher?: never;
+} | {
+    cipher: SealedSessionCipher;
+    scope: string;
+    getKey?: never;
+}): KeyValueSessionStorage.Codec;
+/**
+ * The namespace a person's chat sessions are kept under: their scope hashed, so the database names
+ * no one. `environment` keeps deployments that share an origin apart.
+ */
+export declare function chatSessionNamespace({ environment, ownerId, sha256, }: {
+    environment: string;
+    ownerId: string;
+    /** Hex SHA-256 of a string; pass the host's own where WebCrypto is missing (React Native). */
+    sha256?: (value: string) => Promise<string>;
+}): Promise<string>;
+/**
+ * The key a thread's chat session is stored under: `<namespace><principal>:<threadId>`, the layout
+ * statewire 0.25 keeps session records in.
+ */
+export declare function chatSessionKey({ namespace, principal, threadId, }: {
+    namespace: string;
+    principal: string;
+    threadId: string;
+}): string;
+/**
+ * Moves the sealed chat sessions statewire 0.24 kept under `namespace + threadId` to
+ * `principal`'s scoped keys ({@link chatSessionKey}). `namespace` is one person's
+ * ({@link chatSessionNamespace} hashes their scope), so its unscoped records are theirs: call it
+ * with the signed-in person's own namespace and principal only. Records move as stored (sealed;
+ * the codec binds the person's scope, not the key). A key with a `:` after the namespace is a
+ * scoped one (an encoded principal has none) and is never touched. An unscoped record whose
+ * scoped key already holds one is left where it is (a 0.24 tab still open can write there), never
+ * written over the newer record; a sign-out the person chose clears it with the rest of the
+ * namespace. Returns how many records moved.
+ */
+export declare function adoptUnscopedChatSessions({ backend, namespace, principal, }: {
+    backend: KeyValueSessionStorage.Backend;
+    namespace: string;
+    principal: string;
+}): Promise<number>;
+export type ChatSessionStorageOptions = {
+    kind: "sealed";
+    threadId: string;
+    /** {@link chatSessionNamespace}; one per person. */
+    namespace: string;
+    /** The signed-in account (`sessionPrincipal(userId)`): records live under its scoped keys. */
+    principal: string;
+    /** {@link createSealedSessionCodec}; one per person, kept for the life of the sign-in. */
+    codec: KeyValueSessionStorage.Codec;
+    database?: string;
+    retention?: KeyValueSessionStorage.Options["retention"];
+    onError?: (error: unknown) => void;
+    onEvict?: (event: KeyValueSessionStorage.EvictEvent) => void;
+} | {
+    kind: "memory";
+    threadId: string;
+    /**
+     * Names the person: another person's thread never shares a record. The records list under
+     * {@link chatSessionMemoryNamespace} of it.
+     */
+    scope: string;
+    /** The signed-in account (`sessionPrincipal(userId)`), as for sealed sessions. */
+    principal: string;
+};
+/** The backend that lists every `kind: "memory"` chat session of this page (read and remove only). */
+export declare function chatSessionMemoryBackend(): KeyValueSessionStorage.Backend;
+/** The namespace `scope`'s page-memory chat sessions list under ({@link chatSessionMemoryBackend}). */
+export declare function chatSessionMemoryNamespace(scope: string): string;
+/** Records no tab has mounted go after this long, sends and all (statewire 0.27.1 retention). */
+export declare const CHAT_SESSION_MAX_AGE_MS: number;
+/** Inactive records kept per person. */
+export declare const CHAT_SESSION_MAX_ENTRIES = 50;
+/** The thread's session storage element (`storage.session`) for the surface's mode. */
+export declare function ChatSessionStorage(options: ChatSessionStorageOptions): ResourceElement<StatewireClient.SessionStorage>;
+/** The key-value backend sealed chat sessions write through (`indexedDbBackend`). */
+export declare function chatSessionBackend(database?: string): KeyValueSessionStorage.Backend;
+/** A waiting message as a listing reads it: the entry, and where it stands in its outbox. */
+export interface ChatOutboxListedEntry extends ChatOutboxEntry {
+    /** Held (waiting here), queued to go, or sent and not answered yet. Legacy records read as held. */
+    state?: StatewireClient.OutboxEntry["state"];
+    /** It failed (a held entry carrying `localMeta.error`): Retry, Edit or Discard. */
+    failed?: boolean;
+}
+/** One thread's waiting messages, as the device keeps them. */
+export interface ChatOutboxDirectoryThread {
+    threadId: string;
+    /** Its messages still to be sent (held, queued or sending), in queue order. */
+    entries: readonly ChatOutboxListedEntry[];
+}
+export interface ChatOutboxListing {
+    threads: readonly ChatOutboxDirectoryThread[];
+    /** Records that would not open (another key, a damaged record): they may hold messages too. */
+    unreadable: number;
+}
+export interface ChatOutboxStorageSource {
+    backend: KeyValueSessionStorage.Backend;
+    namespace: string;
+    /** Whose sessions: only records under its scoped keys ({@link chatSessionKey}) are listed. */
+    principal: string;
+    codec?: KeyValueSessionStorage.Codec;
+    /** The previous store, read until each thread's records are migrated. */
+    legacy?: LegacyChatOutboxReader;
+}
+/**
+ * Every thread's waiting messages `principal` keeps under `namespace`, mounted or not
+ * (`readOutboxes`, one record at a time so a record that does not open is counted, not fatal),
+ * merged with the legacy store's records not migrated yet. Threads are ordered by their oldest
+ * message.
+ */
+export declare function listChatOutboxes({ backend, namespace, principal, codec, legacy, }: ChatOutboxStorageSource): Promise<ChatOutboxListing>;
+/**
+ * How many messages wait across every thread (a sign-out asks first while any do). Records that do
+ * not open count as one each: they may hold someone's only copy. Legacy records count unopened.
+ */
+export declare function countChatOutboxMessages(source: ChatOutboxStorageSource): Promise<number>;
+/**
+ * Every chat session record under `namespace` (every principal's, and records 0.24 left unscoped),
+ * and the legacy store's records, gone (a sign-out the person chose).
+ */
+export declare function clearChatOutboxes({ backend, namespace, legacy }: ChatOutboxStorageSource): Promise<void>;
+/** A live view of every thread's waiting messages, for the tray and the "waiting to sync" panels. */
+export interface ChatOutboxDirectory {
+    getSnapshot(): ChatOutboxListing;
+    subscribe(listener: () => void): () => void;
+    /** Read again now (after a migration, a sign-out). */
+    refresh(): void;
+}
+/**
+ * {@link listChatOutboxes}, re-read whenever a record under `namespace` is saved here or in another
+ * tab (`backend.subscribe`), while anything listens. One per person.
+ */
+export declare function createChatOutboxDirectory(source: ChatOutboxStorageSource & {
+    onError?: (error: unknown) => void;
+}): ChatOutboxDirectory;