@athenaintel/react 0.41.2 → 0.42.1

package/dist/agent-runtime/src/thread-snapshot-mirror.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-snapshot-mirror.cjs","sources":["../../../../agent-runtime/src/thread-snapshot-mirror.ts"],"sourcesContent":["import {\n  type IdbDatabase,\n  idbGlobals,\n  lazySealedDatabase,\n  openJson,\n  requestToPromise,\n  sealJson,\n  sha256Hex,\n  transactionDone,\n} from \"./sealed-idb\";\nimport type { DeepAgentStreamValues } from \"./types\";\n\n/**\n * A durable, encrypted mirror of the thread snapshot cache (`thread-snapshot-cache.ts`) in the\n * browser's IndexedDB, so a reload paints a recently visited thread from its last-known messages,\n * and a thread can be read while the transport cannot connect at all.\n *\n * - **Sealed.** Each record is AES-GCM-256 with a fresh IV under the host's key for its owner\n *   (`getKey`: Olympus a non-extractable key in its own keystore, Midas a key main keeps with the\n *   OS keychain). The owner and the thread are hashed for the index and bound to the record as\n *   additional data, so the database names no one and a record moved to another owner or thread\n *   fails to open (and is dropped). No key, no mirror: every write and read is then a no-op.\n * - **Bounded.** Writes are debounced per thread and never taken mid-stream (a state with a live\n *   run is replaced by its resting successor within seconds), transcripts longer than\n *   `maxMessages` are not kept (an older, shorter record is removed rather than left to seed),\n *   and an owner keeps its `maxPerOwner` most recent threads.\n * - **Never in the way.** Every failure degrades to \"no mirror\": a blocked or missing IndexedDB\n *   (private browsing, quota, SSR) must never break the wire path.\n * - **Versioned.** A record a newer build wrote is never read, overwritten or pruned by this one;\n *   only removing the person's records altogether (an identity change, a sign-out) removes it.\n */\n\nexport const THREAD_SNAPSHOT_MIRROR_DATABASE = \"athena-thread-snapshots:v2\";\n/** The sealed record's format; older builds leave a newer one alone. */\nexport const THREAD_SNAPSHOT_MIRROR_FORMAT = 1;\n/** Threads mirrored per owner; the least recently captured beyond this is pruned after each write. */\nexport const MAX_MIRRORED_SNAPSHOTS_PER_OWNER = 30;\n/** Transcripts longer than this are not mirrored — sealing them would cost more than the seed saves. */\nexport const MAX_MIRRORED_SNAPSHOT_MESSAGES = 150;\n/** Trailing debounce per thread: a streaming thread remembers a state per token. */\nexport const SNAPSHOT_MIRROR_DEBOUNCE_MS = 1_500;\n\nconst DATABASE_VERSION = 1;\nconst SNAPSHOTS_STORE = \"snapshots\";\nconst LISTS_STORE = \"lists\";\nconst BY_OWNER = \"byOwner\";\nconst BY_OWNER_AT = \"byOwnerAt\";\n\nexport interface MirroredThreadSnapshot {\n  threadId: string;\n  state: DeepAgentStreamValues;\n  /** Capture time (epoch ms). */\n  at: number;\n}\n\nexport interface MirroredList {\n  value: unknown;\n  /** When it was written (epoch ms). */\n  at: number;\n}\n\nexport interface ThreadSnapshotMirror {\n  /** The owner's mirrored snapshots, oldest first. Resolves `[]` on any fault. */\n  load(ownerId: string): Promise<MirroredThreadSnapshot[]>;\n  /** Mirror a remembered state (debounced per thread; mid-stream states are skipped). */\n  write(input: { ownerId: string; threadId: string; state: DeepAgentStreamValues; at: number }): void;\n  remove(input: { ownerId: string; threadId: string }): void;\n  /** A session list's page as the host last read it, for reading it offline. */\n  writeList(input: { ownerId: string; listKey: string; value: unknown }): void;\n  loadList(input: { ownerId: string; listKey: string }): Promise<MirroredList | null>;\n  /** Drop every record of one owner (an identity change). */\n  clearOwner(ownerId: string): Promise<void>;\n  /** Drop every record (a sign-out, a workspace switch). */\n  clearAll(): Promise<void>;\n  /** Write debounced records now (tests, page hide). */\n  flush(): Promise<void>;\n}\n\n/**\n * What a key is asked for: reading what is already kept (`read`) or keeping something new\n * (`write`). A host may let what it kept be read where it would keep nothing new, e.g. while its\n * deployment's policy for device copies is not known yet.\n */\nexport type ThreadSnapshotKeyPurpose = \"read\" | \"write\";\n\nexport interface ThreadSnapshotMirrorOptions {\n  /** The owner's AES-GCM key, or `null` when the host keeps no mirror for it (no key, policy off). */\n  getKey: (ownerId: string, purpose: ThreadSnapshotKeyPurpose) => Promise<CryptoKey | null>;\n  /** An `IDBFactory` (the browser's `indexedDB` by default; a fake one in tests). */\n  factory?: object;\n  databaseName?: string;\n  debounceMs?: number;\n  maxPerOwner?: number;\n  maxMessages?: number;\n}\n\ninterface SnapshotRecord {\n  key: string;\n  owner: string;\n  at: number;\n  format: number;\n  sealed: Uint8Array;\n}\n\ninterface ListRecord {\n  key: string;\n  owner: string;\n  at: number;\n  format: number;\n  sealed: Uint8Array;\n}\n\nfunction upgradeMirrorDatabase(db: IdbDatabase): void {\n  if (!db.objectStoreNames.contains(SNAPSHOTS_STORE)) {\n    const store = db.createObjectStore(SNAPSHOTS_STORE, { keyPath: \"key\" });\n    store.createIndex(BY_OWNER, \"owner\", { unique: false });\n    store.createIndex(BY_OWNER_AT, [\"owner\", \"at\"], { unique: false });\n  }\n  if (!db.objectStoreNames.contains(LISTS_STORE)) {\n    const lists = db.createObjectStore(LISTS_STORE, { keyPath: \"key\" });\n    lists.createIndex(BY_OWNER, \"owner\", { unique: false });\n  }\n}\n\n/**\n * Whether a remembered state is a resting transcript: no run in flight (its own or an out-of-band\n * one) and its messages present. Only such a state is kept, and read while Athena can't be reached;\n * a mid-stream state is a partial transcript.\n */\nexport function isRestingThreadSnapshot(state: DeepAgentStreamValues): boolean {\n  const run = state.runs?.[0];\n  if (run && run.status === \"running\") return false;\n  if (state.outOfBandRunActive === true) return false;\n  return Array.isArray(state.messages);\n}\n\n/**\n * What the mirror does with a remembered state: `persist` a resting transcript within the size\n * bound; `skip` a mid-stream state (it arrives per token and its resting successor follows within\n * seconds — the last resting record stays); `invalidate` when the transcript has outgrown the\n * mirror — a stale, shorter record would otherwise seed the next reload until the hello.\n */\nexport function classifyThreadSnapshotForMirror(\n  state: DeepAgentStreamValues,\n  maxMessages: number = MAX_MIRRORED_SNAPSHOT_MESSAGES,\n): \"persist\" | \"skip\" | \"invalidate\" {\n  if (!isRestingThreadSnapshot(state)) return \"skip\";\n  return (state.messages?.length ?? 0) <= maxMessages ? \"persist\" : \"invalidate\";\n}\n\n/** A record this build may replace or delete: none, or one in a format it writes itself. */\nfunction isOwnFormat(record: unknown): boolean {\n  if (typeof record !== \"object\" || record === null) return true;\n  const format = (record as { format?: unknown }).format;\n  return typeof format !== \"number\" || format <= THREAD_SNAPSHOT_MIRROR_FORMAT;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\nexport function createThreadSnapshotMirror({\n  getKey,\n  factory = idbGlobals.indexedDB,\n  databaseName = THREAD_SNAPSHOT_MIRROR_DATABASE,\n  debounceMs = SNAPSHOT_MIRROR_DEBOUNCE_MS,\n  maxPerOwner = MAX_MIRRORED_SNAPSHOTS_PER_OWNER,\n  maxMessages = MAX_MIRRORED_SNAPSHOT_MESSAGES,\n}: ThreadSnapshotMirrorOptions): ThreadSnapshotMirror {\n  const database = lazySealedDatabase({\n    factory,\n    name: databaseName,\n    version: DATABASE_VERSION,\n    upgrade: upgradeMirrorDatabase,\n  });\n  const keyOf = async (ownerId: string, purpose: ThreadSnapshotKeyPurpose): Promise<CryptoKey | null> => {\n    try {\n      return await getKey(ownerId, purpose);\n    } catch {\n      return null;\n    }\n  };\n  const aadOf = (kind: string, owner: string, key: string): string =>\n    `athena-thread-snapshot|${THREAD_SNAPSHOT_MIRROR_FORMAT}|${kind}|${owner}|${key}`;\n\n  const pending = new Map<\n    string,\n    { input: { ownerId: string; threadId: string; state: DeepAgentStreamValues; at: number }; timer: ReturnType<typeof setTimeout> }\n  >();\n  const pendingLists = new Map<\n    string,\n    { input: { ownerId: string; listKey: string; value: unknown }; timer: ReturnType<typeof setTimeout> }\n  >();\n  // Writes are serialized so a flush never races a clear.\n  let queue: Promise<void> = Promise.resolve();\n  const enqueue = (task: () => Promise<void>): Promise<void> => {\n    queue = queue.then(task, task).catch(() => {});\n    return queue;\n  };\n\n  const pruneOwner = async (db: IdbDatabase, owner: string): Promise<void> => {\n    const KeyRange = idbGlobals.IDBKeyRange;\n    if (!KeyRange) return;\n    const tx = db.transaction(SNAPSHOTS_STORE, \"readwrite\");\n    const store = tx.objectStore(SNAPSHOTS_STORE);\n    const index = store.index(BY_OWNER_AT);\n    // Key cursor, newest first: bookkeeping never loads the sealed payloads of the records it keeps.\n    const range = KeyRange.bound([owner, Number.NEGATIVE_INFINITY], [owner, Number.POSITIVE_INFINITY]);\n    const beyond: unknown[] = [];\n    await new Promise<void>((resolve, reject) => {\n      let kept = 0;\n      const request = index.openKeyCursor(range, \"prev\");\n      request.onsuccess = () => {\n        const cursor = request.result;\n        if (!cursor) {\n          resolve();\n          return;\n        }\n        kept += 1;\n        if (kept > maxPerOwner) beyond.push(cursor.primaryKey);\n        cursor.continue();\n      };\n      request.onerror = () => reject(request.error ?? new Error(\"IndexedDB cursor failed\"));\n    });\n    // A newer build's record is left to that build's own bound.\n    for (const key of beyond) {\n      if (isOwnFormat(await requestToPromise(store.get(key)))) store.delete(key);\n    }\n    await transactionDone(tx);\n  };\n\n  const put = (input: { ownerId: string; threadId: string; state: DeepAgentStreamValues; at: number }) =>\n    enqueue(async () => {\n      const db = await database();\n      if (!db) return;\n      const cryptoKey = await keyOf(input.ownerId, \"write\");\n      if (!cryptoKey) return;\n      const owner = await sha256Hex(input.ownerId);\n      const key = await sha256Hex(`${input.ownerId}|${input.threadId}`);\n      const sealed = await sealJson({\n        key: cryptoKey,\n        value: { threadId: input.threadId, state: input.state },\n        aad: aadOf(\"snapshot\", owner, key),\n      });\n      const tx = db.transaction(SNAPSHOTS_STORE, \"readwrite\");\n      const store = tx.objectStore(SNAPSHOTS_STORE);\n      // A newer build's record of the thread stays as that build wrote it.\n      if (isOwnFormat(await requestToPromise(store.get(key)))) {\n        store.put({\n          key,\n          owner,\n          at: input.at,\n          format: THREAD_SNAPSHOT_MIRROR_FORMAT,\n          sealed,\n        } satisfies SnapshotRecord);\n      }\n      await transactionDone(tx);\n      await pruneOwner(db, owner);\n    });\n\n  const deleteSnapshot = (input: { ownerId: string; threadId: string }) =>\n    enqueue(async () => {\n      const db = await database();\n      if (!db) return;\n      const key = await sha256Hex(`${input.ownerId}|${input.threadId}`);\n      const tx = db.transaction(SNAPSHOTS_STORE, \"readwrite\");\n      const store = tx.objectStore(SNAPSHOTS_STORE);\n      if (isOwnFormat(await requestToPromise(store.get(key)))) store.delete(key);\n      await transactionDone(tx);\n    });\n\n  const pendingKey = (ownerId: string, threadId: string) => `${ownerId}\\u0000${threadId}`;\n\n  const flushPending = (key: string): Promise<void> => {\n    const entry = pending.get(key);\n    if (!entry) return Promise.resolve();\n    pending.delete(key);\n    clearTimeout(entry.timer);\n    return put(entry.input);\n  };\n\n  const putList = (input: { ownerId: string; listKey: string; value: unknown }) =>\n    enqueue(async () => {\n      const db = await database();\n      if (!db) return;\n      const cryptoKey = await keyOf(input.ownerId, \"write\");\n      if (!cryptoKey) return;\n      const owner = await sha256Hex(input.ownerId);\n      const key = await sha256Hex(`${input.ownerId}|list|${input.listKey}`);\n      const sealed = await sealJson({ key: cryptoKey, value: input.value, aad: aadOf(\"list\", owner, key) });\n      const tx = db.transaction(LISTS_STORE, \"readwrite\");\n      const store = tx.objectStore(LISTS_STORE);\n      if (isOwnFormat(await requestToPromise(store.get(key)))) {\n        store.put({\n          key,\n          owner,\n          at: Date.now(),\n          format: THREAD_SNAPSHOT_MIRROR_FORMAT,\n          sealed,\n        } satisfies ListRecord);\n      }\n      await transactionDone(tx);\n    });\n\n  const flushList = (key: string): Promise<void> => {\n    const entry = pendingLists.get(key);\n    if (!entry) return Promise.resolve();\n    pendingLists.delete(key);\n    clearTimeout(entry.timer);\n    return putList(entry.input);\n  };\n\n  const dropPendingOf = (ownerId: string | null): void => {\n    for (const [key, entry] of pending) {\n      if (ownerId === null || entry.input.ownerId === ownerId) {\n        clearTimeout(entry.timer);\n        pending.delete(key);\n      }\n    }\n    for (const [key, entry] of pendingLists) {\n      if (ownerId === null || entry.input.ownerId === ownerId) {\n        clearTimeout(entry.timer);\n        pendingLists.delete(key);\n      }\n    }\n  };\n\n  return {\n    async load(ownerId) {\n      try {\n        const db = await database();\n        if (!db) return [];\n        const cryptoKey = await keyOf(ownerId, \"read\");\n        if (!cryptoKey) return [];\n        const owner = await sha256Hex(ownerId);\n        const records = (await requestToPromise(\n          db.transaction(SNAPSHOTS_STORE, \"readonly\").objectStore(SNAPSHOTS_STORE).index(BY_OWNER).getAll(owner),\n        )) as SnapshotRecord[];\n        const loaded: MirroredThreadSnapshot[] = [];\n        const unreadable: string[] = [];\n        for (const record of records) {\n          if (!record || record.format > THREAD_SNAPSHOT_MIRROR_FORMAT) continue;\n          try {\n            const value = await openJson({\n              key: cryptoKey,\n              sealed: record.sealed,\n              aad: aadOf(\"snapshot\", owner, record.key),\n            });\n            if (\n              isRecord(value) &&\n              typeof value.threadId === \"string\" &&\n              isRecord(value.state) &&\n              typeof record.at === \"number\"\n            ) {\n              loaded.push({ threadId: value.threadId, state: value.state as DeepAgentStreamValues, at: record.at });\n            }\n          } catch {\n            unreadable.push(record.key);\n          }\n        }\n        if (unreadable.length > 0) {\n          void enqueue(async () => {\n            const tx = db.transaction(SNAPSHOTS_STORE, \"readwrite\");\n            for (const key of unreadable) tx.objectStore(SNAPSHOTS_STORE).delete(key);\n            await transactionDone(tx);\n          });\n        }\n        return loaded.sort((a, b) => a.at - b.at);\n      } catch {\n        return [];\n      }\n    },\n    write(input) {\n      const key = pendingKey(input.ownerId, input.threadId);\n      const verdict = classifyThreadSnapshotForMirror(input.state, maxMessages);\n      if (verdict === \"invalidate\") {\n        const existing = pending.get(key);\n        if (existing) clearTimeout(existing.timer);\n        pending.delete(key);\n        void deleteSnapshot(input);\n        return;\n      }\n      if (verdict === \"skip\") return;\n      const existing = pending.get(key);\n      if (existing) clearTimeout(existing.timer);\n      pending.set(key, {\n        input,\n        timer: setTimeout(() => {\n          void flushPending(key);\n        }, debounceMs),\n      });\n    },\n    remove(input) {\n      const key = pendingKey(input.ownerId, input.threadId);\n      const existing = pending.get(key);\n      if (existing) clearTimeout(existing.timer);\n      pending.delete(key);\n      void deleteSnapshot(input);\n    },\n    writeList(input) {\n      const key = pendingKey(input.ownerId, `list:${input.listKey}`);\n      const existing = pendingLists.get(key);\n      if (existing) clearTimeout(existing.timer);\n      pendingLists.set(key, {\n        input,\n        timer: setTimeout(() => {\n          void flushList(key);\n        }, debounceMs),\n      });\n    },\n    async loadList({ ownerId, listKey }) {\n      try {\n        const db = await database();\n        if (!db) return null;\n        const cryptoKey = await keyOf(ownerId, \"read\");\n        if (!cryptoKey) return null;\n        const owner = await sha256Hex(ownerId);\n        const key = await sha256Hex(`${ownerId}|list|${listKey}`);\n        const record = (await requestToPromise(\n          db.transaction(LISTS_STORE, \"readonly\").objectStore(LISTS_STORE).get(key),\n        )) as ListRecord | undefined;\n        if (!record || record.format > THREAD_SNAPSHOT_MIRROR_FORMAT || record.owner !== owner) return null;\n        try {\n          const value = await openJson({ key: cryptoKey, sealed: record.sealed, aad: aadOf(\"list\", owner, key) });\n          return { value, at: record.at };\n        } catch {\n          return null;\n        }\n      } catch {\n        return null;\n      }\n    },\n    clearOwner(ownerId) {\n      dropPendingOf(ownerId);\n      return enqueue(async () => {\n        const db = await database();\n        if (!db) return;\n        const owner = await sha256Hex(ownerId);\n        const tx = db.transaction([SNAPSHOTS_STORE, LISTS_STORE], \"readwrite\");\n        for (const storeName of [SNAPSHOTS_STORE, LISTS_STORE]) {\n          const store = tx.objectStore(storeName);\n          const keys = await requestToPromise(store.index(BY_OWNER).getAllKeys(owner));\n          for (const key of keys) store.delete(key);\n        }\n        await transactionDone(tx);\n      });\n    },\n    clearAll() {\n      dropPendingOf(null);\n      return enqueue(async () => {\n        const db = await database();\n        if (!db) return;\n        const tx = db.transaction([SNAPSHOTS_STORE, LISTS_STORE], \"readwrite\");\n        tx.objectStore(SNAPSHOTS_STORE).clear();\n        tx.objectStore(LISTS_STORE).clear();\n        await transactionDone(tx);\n      });\n    },\n    async flush() {\n      await Promise.all([...pending.keys()].map(flushPending));\n      await Promise.all([...pendingLists.keys()].map(flushList));\n      await queue;\n    },\n  };\n}\n"],"names":["idbGlobals","lazySealedDatabase","requestToPromise","transactionDone","sha256Hex","sealJson","openJson","existing"],"mappings":"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"}

package/dist/agent-runtime/src/thread-snapshot-mirror.d.ts

@@ -0,0 +1,101 @@
+import type { DeepAgentStreamValues } from "./types";
+/**
+ * A durable, encrypted mirror of the thread snapshot cache (`thread-snapshot-cache.ts`) in the
+ * browser's IndexedDB, so a reload paints a recently visited thread from its last-known messages,
+ * and a thread can be read while the transport cannot connect at all.
+ *
+ * - **Sealed.** Each record is AES-GCM-256 with a fresh IV under the host's key for its owner
+ *   (`getKey`: Olympus a non-extractable key in its own keystore, Midas a key main keeps with the
+ *   OS keychain). The owner and the thread are hashed for the index and bound to the record as
+ *   additional data, so the database names no one and a record moved to another owner or thread
+ *   fails to open (and is dropped). No key, no mirror: every write and read is then a no-op.
+ * - **Bounded.** Writes are debounced per thread and never taken mid-stream (a state with a live
+ *   run is replaced by its resting successor within seconds), transcripts longer than
+ *   `maxMessages` are not kept (an older, shorter record is removed rather than left to seed),
+ *   and an owner keeps its `maxPerOwner` most recent threads.
+ * - **Never in the way.** Every failure degrades to "no mirror": a blocked or missing IndexedDB
+ *   (private browsing, quota, SSR) must never break the wire path.
+ * - **Versioned.** A record a newer build wrote is never read, overwritten or pruned by this one;
+ *   only removing the person's records altogether (an identity change, a sign-out) removes it.
+ */
+export declare const THREAD_SNAPSHOT_MIRROR_DATABASE = "athena-thread-snapshots:v2";
+/** The sealed record's format; older builds leave a newer one alone. */
+export declare const THREAD_SNAPSHOT_MIRROR_FORMAT = 1;
+/** Threads mirrored per owner; the least recently captured beyond this is pruned after each write. */
+export declare const MAX_MIRRORED_SNAPSHOTS_PER_OWNER = 30;
+/** Transcripts longer than this are not mirrored — sealing them would cost more than the seed saves. */
+export declare const MAX_MIRRORED_SNAPSHOT_MESSAGES = 150;
+/** Trailing debounce per thread: a streaming thread remembers a state per token. */
+export declare const SNAPSHOT_MIRROR_DEBOUNCE_MS = 1500;
+export interface MirroredThreadSnapshot {
+    threadId: string;
+    state: DeepAgentStreamValues;
+    /** Capture time (epoch ms). */
+    at: number;
+}
+export interface MirroredList {
+    value: unknown;
+    /** When it was written (epoch ms). */
+    at: number;
+}
+export interface ThreadSnapshotMirror {
+    /** The owner's mirrored snapshots, oldest first. Resolves `[]` on any fault. */
+    load(ownerId: string): Promise<MirroredThreadSnapshot[]>;
+    /** Mirror a remembered state (debounced per thread; mid-stream states are skipped). */
+    write(input: {
+        ownerId: string;
+        threadId: string;
+        state: DeepAgentStreamValues;
+        at: number;
+    }): void;
+    remove(input: {
+        ownerId: string;
+        threadId: string;
+    }): void;
+    /** A session list's page as the host last read it, for reading it offline. */
+    writeList(input: {
+        ownerId: string;
+        listKey: string;
+        value: unknown;
+    }): void;
+    loadList(input: {
+        ownerId: string;
+        listKey: string;
+    }): Promise<MirroredList | null>;
+    /** Drop every record of one owner (an identity change). */
+    clearOwner(ownerId: string): Promise<void>;
+    /** Drop every record (a sign-out, a workspace switch). */
+    clearAll(): Promise<void>;
+    /** Write debounced records now (tests, page hide). */
+    flush(): Promise<void>;
+}
+/**
+ * What a key is asked for: reading what is already kept (`read`) or keeping something new
+ * (`write`). A host may let what it kept be read where it would keep nothing new, e.g. while its
+ * deployment's policy for device copies is not known yet.
+ */
+export type ThreadSnapshotKeyPurpose = "read" | "write";
+export interface ThreadSnapshotMirrorOptions {
+    /** The owner's AES-GCM key, or `null` when the host keeps no mirror for it (no key, policy off). */
+    getKey: (ownerId: string, purpose: ThreadSnapshotKeyPurpose) => Promise<CryptoKey | null>;
+    /** An `IDBFactory` (the browser's `indexedDB` by default; a fake one in tests). */
+    factory?: object;
+    databaseName?: string;
+    debounceMs?: number;
+    maxPerOwner?: number;
+    maxMessages?: number;
+}
+/**
+ * Whether a remembered state is a resting transcript: no run in flight (its own or an out-of-band
+ * one) and its messages present. Only such a state is kept, and read while Athena can't be reached;
+ * a mid-stream state is a partial transcript.
+ */
+export declare function isRestingThreadSnapshot(state: DeepAgentStreamValues): boolean;
+/**
+ * What the mirror does with a remembered state: `persist` a resting transcript within the size
+ * bound; `skip` a mid-stream state (it arrives per token and its resting successor follows within
+ * seconds — the last resting record stays); `invalidate` when the transcript has outgrown the
+ * mirror — a stale, shorter record would otherwise seed the next reload until the hello.
+ */
+export declare function classifyThreadSnapshotForMirror(state: DeepAgentStreamValues, maxMessages?: number): "persist" | "skip" | "invalidate";
+export declare function createThreadSnapshotMirror({ getKey, factory, databaseName, debounceMs, maxPerOwner, maxMessages, }: ThreadSnapshotMirrorOptions): ThreadSnapshotMirror;

package/dist/agent-runtime/src/thread-snapshot-mirror.js

@@ -0,0 +1,329 @@
+import { sha256Hex, requestToPromise, openJson, transactionDone, idbGlobals, lazySealedDatabase, sealJson } from "./sealed-idb.js";
+const THREAD_SNAPSHOT_MIRROR_DATABASE = "athena-thread-snapshots:v2";
+const THREAD_SNAPSHOT_MIRROR_FORMAT = 1;
+const MAX_MIRRORED_SNAPSHOTS_PER_OWNER = 30;
+const MAX_MIRRORED_SNAPSHOT_MESSAGES = 150;
+const SNAPSHOT_MIRROR_DEBOUNCE_MS = 1500;
+const DATABASE_VERSION = 1;
+const SNAPSHOTS_STORE = "snapshots";
+const LISTS_STORE = "lists";
+const BY_OWNER = "byOwner";
+const BY_OWNER_AT = "byOwnerAt";
+function upgradeMirrorDatabase(db) {
+  if (!db.objectStoreNames.contains(SNAPSHOTS_STORE)) {
+    const store = db.createObjectStore(SNAPSHOTS_STORE, { keyPath: "key" });
+    store.createIndex(BY_OWNER, "owner", { unique: false });
+    store.createIndex(BY_OWNER_AT, ["owner", "at"], { unique: false });
+  }
+  if (!db.objectStoreNames.contains(LISTS_STORE)) {
+    const lists = db.createObjectStore(LISTS_STORE, { keyPath: "key" });
+    lists.createIndex(BY_OWNER, "owner", { unique: false });
+  }
+}
+function isRestingThreadSnapshot(state) {
+  var _a;
+  const run = (_a = state.runs) == null ? void 0 : _a[0];
+  if (run && run.status === "running") return false;
+  if (state.outOfBandRunActive === true) return false;
+  return Array.isArray(state.messages);
+}
+function classifyThreadSnapshotForMirror(state, maxMessages = MAX_MIRRORED_SNAPSHOT_MESSAGES) {
+  var _a;
+  if (!isRestingThreadSnapshot(state)) return "skip";
+  return (((_a = state.messages) == null ? void 0 : _a.length) ?? 0) <= maxMessages ? "persist" : "invalidate";
+}
+function isOwnFormat(record) {
+  if (typeof record !== "object" || record === null) return true;
+  const format = record.format;
+  return typeof format !== "number" || format <= THREAD_SNAPSHOT_MIRROR_FORMAT;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function createThreadSnapshotMirror({
+  getKey,
+  factory = idbGlobals.indexedDB,
+  databaseName = THREAD_SNAPSHOT_MIRROR_DATABASE,
+  debounceMs = SNAPSHOT_MIRROR_DEBOUNCE_MS,
+  maxPerOwner = MAX_MIRRORED_SNAPSHOTS_PER_OWNER,
+  maxMessages = MAX_MIRRORED_SNAPSHOT_MESSAGES
+}) {
+  const database = lazySealedDatabase({
+    factory,
+    name: databaseName,
+    version: DATABASE_VERSION,
+    upgrade: upgradeMirrorDatabase
+  });
+  const keyOf = async (ownerId, purpose) => {
+    try {
+      return await getKey(ownerId, purpose);
+    } catch {
+      return null;
+    }
+  };
+  const aadOf = (kind, owner, key) => `athena-thread-snapshot|${THREAD_SNAPSHOT_MIRROR_FORMAT}|${kind}|${owner}|${key}`;
+  const pending = /* @__PURE__ */ new Map();
+  const pendingLists = /* @__PURE__ */ new Map();
+  let queue = Promise.resolve();
+  const enqueue = (task) => {
+    queue = queue.then(task, task).catch(() => {
+    });
+    return queue;
+  };
+  const pruneOwner = async (db, owner) => {
+    const KeyRange = idbGlobals.IDBKeyRange;
+    if (!KeyRange) return;
+    const tx = db.transaction(SNAPSHOTS_STORE, "readwrite");
+    const store = tx.objectStore(SNAPSHOTS_STORE);
+    const index = store.index(BY_OWNER_AT);
+    const range = KeyRange.bound([owner, Number.NEGATIVE_INFINITY], [owner, Number.POSITIVE_INFINITY]);
+    const beyond = [];
+    await new Promise((resolve, reject) => {
+      let kept = 0;
+      const request = index.openKeyCursor(range, "prev");
+      request.onsuccess = () => {
+        const cursor = request.result;
+        if (!cursor) {
+          resolve();
+          return;
+        }
+        kept += 1;
+        if (kept > maxPerOwner) beyond.push(cursor.primaryKey);
+        cursor.continue();
+      };
+      request.onerror = () => reject(request.error ?? new Error("IndexedDB cursor failed"));
+    });
+    for (const key of beyond) {
+      if (isOwnFormat(await requestToPromise(store.get(key)))) store.delete(key);
+    }
+    await transactionDone(tx);
+  };
+  const put = (input) => enqueue(async () => {
+    const db = await database();
+    if (!db) return;
+    const cryptoKey = await keyOf(input.ownerId, "write");
+    if (!cryptoKey) return;
+    const owner = await sha256Hex(input.ownerId);
+    const key = await sha256Hex(`${input.ownerId}|${input.threadId}`);
+    const sealed = await sealJson({
+      key: cryptoKey,
+      value: { threadId: input.threadId, state: input.state },
+      aad: aadOf("snapshot", owner, key)
+    });
+    const tx = db.transaction(SNAPSHOTS_STORE, "readwrite");
+    const store = tx.objectStore(SNAPSHOTS_STORE);
+    if (isOwnFormat(await requestToPromise(store.get(key)))) {
+      store.put({
+        key,
+        owner,
+        at: input.at,
+        format: THREAD_SNAPSHOT_MIRROR_FORMAT,
+        sealed
+      });
+    }
+    await transactionDone(tx);
+    await pruneOwner(db, owner);
+  });
+  const deleteSnapshot = (input) => enqueue(async () => {
+    const db = await database();
+    if (!db) return;
+    const key = await sha256Hex(`${input.ownerId}|${input.threadId}`);
+    const tx = db.transaction(SNAPSHOTS_STORE, "readwrite");
+    const store = tx.objectStore(SNAPSHOTS_STORE);
+    if (isOwnFormat(await requestToPromise(store.get(key)))) store.delete(key);
+    await transactionDone(tx);
+  });
+  const pendingKey = (ownerId, threadId) => `${ownerId}\0${threadId}`;
+  const flushPending = (key) => {
+    const entry = pending.get(key);
+    if (!entry) return Promise.resolve();
+    pending.delete(key);
+    clearTimeout(entry.timer);
+    return put(entry.input);
+  };
+  const putList = (input) => enqueue(async () => {
+    const db = await database();
+    if (!db) return;
+    const cryptoKey = await keyOf(input.ownerId, "write");
+    if (!cryptoKey) return;
+    const owner = await sha256Hex(input.ownerId);
+    const key = await sha256Hex(`${input.ownerId}|list|${input.listKey}`);
+    const sealed = await sealJson({ key: cryptoKey, value: input.value, aad: aadOf("list", owner, key) });
+    const tx = db.transaction(LISTS_STORE, "readwrite");
+    const store = tx.objectStore(LISTS_STORE);
+    if (isOwnFormat(await requestToPromise(store.get(key)))) {
+      store.put({
+        key,
+        owner,
+        at: Date.now(),
+        format: THREAD_SNAPSHOT_MIRROR_FORMAT,
+        sealed
+      });
+    }
+    await transactionDone(tx);
+  });
+  const flushList = (key) => {
+    const entry = pendingLists.get(key);
+    if (!entry) return Promise.resolve();
+    pendingLists.delete(key);
+    clearTimeout(entry.timer);
+    return putList(entry.input);
+  };
+  const dropPendingOf = (ownerId) => {
+    for (const [key, entry] of pending) {
+      if (ownerId === null || entry.input.ownerId === ownerId) {
+        clearTimeout(entry.timer);
+        pending.delete(key);
+      }
+    }
+    for (const [key, entry] of pendingLists) {
+      if (ownerId === null || entry.input.ownerId === ownerId) {
+        clearTimeout(entry.timer);
+        pendingLists.delete(key);
+      }
+    }
+  };
+  return {
+    async load(ownerId) {
+      try {
+        const db = await database();
+        if (!db) return [];
+        const cryptoKey = await keyOf(ownerId, "read");
+        if (!cryptoKey) return [];
+        const owner = await sha256Hex(ownerId);
+        const records = await requestToPromise(
+          db.transaction(SNAPSHOTS_STORE, "readonly").objectStore(SNAPSHOTS_STORE).index(BY_OWNER).getAll(owner)
+        );
+        const loaded = [];
+        const unreadable = [];
+        for (const record of records) {
+          if (!record || record.format > THREAD_SNAPSHOT_MIRROR_FORMAT) continue;
+          try {
+            const value = await openJson({
+              key: cryptoKey,
+              sealed: record.sealed,
+              aad: aadOf("snapshot", owner, record.key)
+            });
+            if (isRecord(value) && typeof value.threadId === "string" && isRecord(value.state) && typeof record.at === "number") {
+              loaded.push({ threadId: value.threadId, state: value.state, at: record.at });
+            }
+          } catch {
+            unreadable.push(record.key);
+          }
+        }
+        if (unreadable.length > 0) {
+          void enqueue(async () => {
+            const tx = db.transaction(SNAPSHOTS_STORE, "readwrite");
+            for (const key of unreadable) tx.objectStore(SNAPSHOTS_STORE).delete(key);
+            await transactionDone(tx);
+          });
+        }
+        return loaded.sort((a, b) => a.at - b.at);
+      } catch {
+        return [];
+      }
+    },
+    write(input) {
+      const key = pendingKey(input.ownerId, input.threadId);
+      const verdict = classifyThreadSnapshotForMirror(input.state, maxMessages);
+      if (verdict === "invalidate") {
+        const existing2 = pending.get(key);
+        if (existing2) clearTimeout(existing2.timer);
+        pending.delete(key);
+        void deleteSnapshot(input);
+        return;
+      }
+      if (verdict === "skip") return;
+      const existing = pending.get(key);
+      if (existing) clearTimeout(existing.timer);
+      pending.set(key, {
+        input,
+        timer: setTimeout(() => {
+          void flushPending(key);
+        }, debounceMs)
+      });
+    },
+    remove(input) {
+      const key = pendingKey(input.ownerId, input.threadId);
+      const existing = pending.get(key);
+      if (existing) clearTimeout(existing.timer);
+      pending.delete(key);
+      void deleteSnapshot(input);
+    },
+    writeList(input) {
+      const key = pendingKey(input.ownerId, `list:${input.listKey}`);
+      const existing = pendingLists.get(key);
+      if (existing) clearTimeout(existing.timer);
+      pendingLists.set(key, {
+        input,
+        timer: setTimeout(() => {
+          void flushList(key);
+        }, debounceMs)
+      });
+    },
+    async loadList({ ownerId, listKey }) {
+      try {
+        const db = await database();
+        if (!db) return null;
+        const cryptoKey = await keyOf(ownerId, "read");
+        if (!cryptoKey) return null;
+        const owner = await sha256Hex(ownerId);
+        const key = await sha256Hex(`${ownerId}|list|${listKey}`);
+        const record = await requestToPromise(
+          db.transaction(LISTS_STORE, "readonly").objectStore(LISTS_STORE).get(key)
+        );
+        if (!record || record.format > THREAD_SNAPSHOT_MIRROR_FORMAT || record.owner !== owner) return null;
+        try {
+          const value = await openJson({ key: cryptoKey, sealed: record.sealed, aad: aadOf("list", owner, key) });
+          return { value, at: record.at };
+        } catch {
+          return null;
+        }
+      } catch {
+        return null;
+      }
+    },
+    clearOwner(ownerId) {
+      dropPendingOf(ownerId);
+      return enqueue(async () => {
+        const db = await database();
+        if (!db) return;
+        const owner = await sha256Hex(ownerId);
+        const tx = db.transaction([SNAPSHOTS_STORE, LISTS_STORE], "readwrite");
+        for (const storeName of [SNAPSHOTS_STORE, LISTS_STORE]) {
+          const store = tx.objectStore(storeName);
+          const keys = await requestToPromise(store.index(BY_OWNER).getAllKeys(owner));
+          for (const key of keys) store.delete(key);
+        }
+        await transactionDone(tx);
+      });
+    },
+    clearAll() {
+      dropPendingOf(null);
+      return enqueue(async () => {
+        const db = await database();
+        if (!db) return;
+        const tx = db.transaction([SNAPSHOTS_STORE, LISTS_STORE], "readwrite");
+        tx.objectStore(SNAPSHOTS_STORE).clear();
+        tx.objectStore(LISTS_STORE).clear();
+        await transactionDone(tx);
+      });
+    },
+    async flush() {
+      await Promise.all([...pending.keys()].map(flushPending));
+      await Promise.all([...pendingLists.keys()].map(flushList));
+      await queue;
+    }
+  };
+}
+export {
+  MAX_MIRRORED_SNAPSHOTS_PER_OWNER,
+  MAX_MIRRORED_SNAPSHOT_MESSAGES,
+  SNAPSHOT_MIRROR_DEBOUNCE_MS,
+  THREAD_SNAPSHOT_MIRROR_DATABASE,
+  THREAD_SNAPSHOT_MIRROR_FORMAT,
+  classifyThreadSnapshotForMirror,
+  createThreadSnapshotMirror,
+  isRestingThreadSnapshot
+};
+//# sourceMappingURL=thread-snapshot-mirror.js.map

package/dist/agent-runtime/src/thread-snapshot-mirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-snapshot-mirror.js","sources":["../../../../agent-runtime/src/thread-snapshot-mirror.ts"],"sourcesContent":["import {\n  type IdbDatabase,\n  idbGlobals,\n  lazySealedDatabase,\n  openJson,\n  requestToPromise,\n  sealJson,\n  sha256Hex,\n  transactionDone,\n} from \"./sealed-idb\";\nimport type { DeepAgentStreamValues } from \"./types\";\n\n/**\n * A durable, encrypted mirror of the thread snapshot cache (`thread-snapshot-cache.ts`) in the\n * browser's IndexedDB, so a reload paints a recently visited thread from its last-known messages,\n * and a thread can be read while the transport cannot connect at all.\n *\n * - **Sealed.** Each record is AES-GCM-256 with a fresh IV under the host's key for its owner\n *   (`getKey`: Olympus a non-extractable key in its own keystore, Midas a key main keeps with the\n *   OS keychain). The owner and the thread are hashed for the index and bound to the record as\n *   additional data, so the database names no one and a record moved to another owner or thread\n *   fails to open (and is dropped). No key, no mirror: every write and read is then a no-op.\n * - **Bounded.** Writes are debounced per thread and never taken mid-stream (a state with a live\n *   run is replaced by its resting successor within seconds), transcripts longer than\n *   `maxMessages` are not kept (an older, shorter record is removed rather than left to seed),\n *   and an owner keeps its `maxPerOwner` most recent threads.\n * - **Never in the way.** Every failure degrades to \"no mirror\": a blocked or missing IndexedDB\n *   (private browsing, quota, SSR) must never break the wire path.\n * - **Versioned.** A record a newer build wrote is never read, overwritten or pruned by this one;\n *   only removing the person's records altogether (an identity change, a sign-out) removes it.\n */\n\nexport const THREAD_SNAPSHOT_MIRROR_DATABASE = \"athena-thread-snapshots:v2\";\n/** The sealed record's format; older builds leave a newer one alone. */\nexport const THREAD_SNAPSHOT_MIRROR_FORMAT = 1;\n/** Threads mirrored per owner; the least recently captured beyond this is pruned after each write. */\nexport const MAX_MIRRORED_SNAPSHOTS_PER_OWNER = 30;\n/** Transcripts longer than this are not mirrored — sealing them would cost more than the seed saves. */\nexport const MAX_MIRRORED_SNAPSHOT_MESSAGES = 150;\n/** Trailing debounce per thread: a streaming thread remembers a state per token. */\nexport const SNAPSHOT_MIRROR_DEBOUNCE_MS = 1_500;\n\nconst DATABASE_VERSION = 1;\nconst SNAPSHOTS_STORE = \"snapshots\";\nconst LISTS_STORE = \"lists\";\nconst BY_OWNER = \"byOwner\";\nconst BY_OWNER_AT = \"byOwnerAt\";\n\nexport interface MirroredThreadSnapshot {\n  threadId: string;\n  state: DeepAgentStreamValues;\n  /** Capture time (epoch ms). */\n  at: number;\n}\n\nexport interface MirroredList {\n  value: unknown;\n  /** When it was written (epoch ms). */\n  at: number;\n}\n\nexport interface ThreadSnapshotMirror {\n  /** The owner's mirrored snapshots, oldest first. Resolves `[]` on any fault. */\n  load(ownerId: string): Promise<MirroredThreadSnapshot[]>;\n  /** Mirror a remembered state (debounced per thread; mid-stream states are skipped). */\n  write(input: { ownerId: string; threadId: string; state: DeepAgentStreamValues; at: number }): void;\n  remove(input: { ownerId: string; threadId: string }): void;\n  /** A session list's page as the host last read it, for reading it offline. */\n  writeList(input: { ownerId: string; listKey: string; value: unknown }): void;\n  loadList(input: { ownerId: string; listKey: string }): Promise<MirroredList | null>;\n  /** Drop every record of one owner (an identity change). */\n  clearOwner(ownerId: string): Promise<void>;\n  /** Drop every record (a sign-out, a workspace switch). */\n  clearAll(): Promise<void>;\n  /** Write debounced records now (tests, page hide). */\n  flush(): Promise<void>;\n}\n\n/**\n * What a key is asked for: reading what is already kept (`read`) or keeping something new\n * (`write`). A host may let what it kept be read where it would keep nothing new, e.g. while its\n * deployment's policy for device copies is not known yet.\n */\nexport type ThreadSnapshotKeyPurpose = \"read\" | \"write\";\n\nexport interface ThreadSnapshotMirrorOptions {\n  /** The owner's AES-GCM key, or `null` when the host keeps no mirror for it (no key, policy off). */\n  getKey: (ownerId: string, purpose: ThreadSnapshotKeyPurpose) => Promise<CryptoKey | null>;\n  /** An `IDBFactory` (the browser's `indexedDB` by default; a fake one in tests). */\n  factory?: object;\n  databaseName?: string;\n  debounceMs?: number;\n  maxPerOwner?: number;\n  maxMessages?: number;\n}\n\ninterface SnapshotRecord {\n  key: string;\n  owner: string;\n  at: number;\n  format: number;\n  sealed: Uint8Array;\n}\n\ninterface ListRecord {\n  key: string;\n  owner: string;\n  at: number;\n  format: number;\n  sealed: Uint8Array;\n}\n\nfunction upgradeMirrorDatabase(db: IdbDatabase): void {\n  if (!db.objectStoreNames.contains(SNAPSHOTS_STORE)) {\n    const store = db.createObjectStore(SNAPSHOTS_STORE, { keyPath: \"key\" });\n    store.createIndex(BY_OWNER, \"owner\", { unique: false });\n    store.createIndex(BY_OWNER_AT, [\"owner\", \"at\"], { unique: false });\n  }\n  if (!db.objectStoreNames.contains(LISTS_STORE)) {\n    const lists = db.createObjectStore(LISTS_STORE, { keyPath: \"key\" });\n    lists.createIndex(BY_OWNER, \"owner\", { unique: false });\n  }\n}\n\n/**\n * Whether a remembered state is a resting transcript: no run in flight (its own or an out-of-band\n * one) and its messages present. Only such a state is kept, and read while Athena can't be reached;\n * a mid-stream state is a partial transcript.\n */\nexport function isRestingThreadSnapshot(state: DeepAgentStreamValues): boolean {\n  const run = state.runs?.[0];\n  if (run && run.status === \"running\") return false;\n  if (state.outOfBandRunActive === true) return false;\n  return Array.isArray(state.messages);\n}\n\n/**\n * What the mirror does with a remembered state: `persist` a resting transcript within the size\n * bound; `skip` a mid-stream state (it arrives per token and its resting successor follows within\n * seconds — the last resting record stays); `invalidate` when the transcript has outgrown the\n * mirror — a stale, shorter record would otherwise seed the next reload until the hello.\n */\nexport function classifyThreadSnapshotForMirror(\n  state: DeepAgentStreamValues,\n  maxMessages: number = MAX_MIRRORED_SNAPSHOT_MESSAGES,\n): \"persist\" | \"skip\" | \"invalidate\" {\n  if (!isRestingThreadSnapshot(state)) return \"skip\";\n  return (state.messages?.length ?? 0) <= maxMessages ? \"persist\" : \"invalidate\";\n}\n\n/** A record this build may replace or delete: none, or one in a format it writes itself. */\nfunction isOwnFormat(record: unknown): boolean {\n  if (typeof record !== \"object\" || record === null) return true;\n  const format = (record as { format?: unknown }).format;\n  return typeof format !== \"number\" || format <= THREAD_SNAPSHOT_MIRROR_FORMAT;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\nexport function createThreadSnapshotMirror({\n  getKey,\n  factory = idbGlobals.indexedDB,\n  databaseName = THREAD_SNAPSHOT_MIRROR_DATABASE,\n  debounceMs = SNAPSHOT_MIRROR_DEBOUNCE_MS,\n  maxPerOwner = MAX_MIRRORED_SNAPSHOTS_PER_OWNER,\n  maxMessages = MAX_MIRRORED_SNAPSHOT_MESSAGES,\n}: ThreadSnapshotMirrorOptions): ThreadSnapshotMirror {\n  const database = lazySealedDatabase({\n    factory,\n    name: databaseName,\n    version: DATABASE_VERSION,\n    upgrade: upgradeMirrorDatabase,\n  });\n  const keyOf = async (ownerId: string, purpose: ThreadSnapshotKeyPurpose): Promise<CryptoKey | null> => {\n    try {\n      return await getKey(ownerId, purpose);\n    } catch {\n      return null;\n    }\n  };\n  const aadOf = (kind: string, owner: string, key: string): string =>\n    `athena-thread-snapshot|${THREAD_SNAPSHOT_MIRROR_FORMAT}|${kind}|${owner}|${key}`;\n\n  const pending = new Map<\n    string,\n    { input: { ownerId: string; threadId: string; state: DeepAgentStreamValues; at: number }; timer: ReturnType<typeof setTimeout> }\n  >();\n  const pendingLists = new Map<\n    string,\n    { input: { ownerId: string; listKey: string; value: unknown }; timer: ReturnType<typeof setTimeout> }\n  >();\n  // Writes are serialized so a flush never races a clear.\n  let queue: Promise<void> = Promise.resolve();\n  const enqueue = (task: () => Promise<void>): Promise<void> => {\n    queue = queue.then(task, task).catch(() => {});\n    return queue;\n  };\n\n  const pruneOwner = async (db: IdbDatabase, owner: string): Promise<void> => {\n    const KeyRange = idbGlobals.IDBKeyRange;\n    if (!KeyRange) return;\n    const tx = db.transaction(SNAPSHOTS_STORE, \"readwrite\");\n    const store = tx.objectStore(SNAPSHOTS_STORE);\n    const index = store.index(BY_OWNER_AT);\n    // Key cursor, newest first: bookkeeping never loads the sealed payloads of the records it keeps.\n    const range = KeyRange.bound([owner, Number.NEGATIVE_INFINITY], [owner, Number.POSITIVE_INFINITY]);\n    const beyond: unknown[] = [];\n    await new Promise<void>((resolve, reject) => {\n      let kept = 0;\n      const request = index.openKeyCursor(range, \"prev\");\n      request.onsuccess = () => {\n        const cursor = request.result;\n        if (!cursor) {\n          resolve();\n          return;\n        }\n        kept += 1;\n        if (kept > maxPerOwner) beyond.push(cursor.primaryKey);\n        cursor.continue();\n      };\n      request.onerror = () => reject(request.error ?? new Error(\"IndexedDB cursor failed\"));\n    });\n    // A newer build's record is left to that build's own bound.\n    for (const key of beyond) {\n      if (isOwnFormat(await requestToPromise(store.get(key)))) store.delete(key);\n    }\n    await transactionDone(tx);\n  };\n\n  const put = (input: { ownerId: string; threadId: string; state: DeepAgentStreamValues; at: number }) =>\n    enqueue(async () => {\n      const db = await database();\n      if (!db) return;\n      const cryptoKey = await keyOf(input.ownerId, \"write\");\n      if (!cryptoKey) return;\n      const owner = await sha256Hex(input.ownerId);\n      const key = await sha256Hex(`${input.ownerId}|${input.threadId}`);\n      const sealed = await sealJson({\n        key: cryptoKey,\n        value: { threadId: input.threadId, state: input.state },\n        aad: aadOf(\"snapshot\", owner, key),\n      });\n      const tx = db.transaction(SNAPSHOTS_STORE, \"readwrite\");\n      const store = tx.objectStore(SNAPSHOTS_STORE);\n      // A newer build's record of the thread stays as that build wrote it.\n      if (isOwnFormat(await requestToPromise(store.get(key)))) {\n        store.put({\n          key,\n          owner,\n          at: input.at,\n          format: THREAD_SNAPSHOT_MIRROR_FORMAT,\n          sealed,\n        } satisfies SnapshotRecord);\n      }\n      await transactionDone(tx);\n      await pruneOwner(db, owner);\n    });\n\n  const deleteSnapshot = (input: { ownerId: string; threadId: string }) =>\n    enqueue(async () => {\n      const db = await database();\n      if (!db) return;\n      const key = await sha256Hex(`${input.ownerId}|${input.threadId}`);\n      const tx = db.transaction(SNAPSHOTS_STORE, \"readwrite\");\n      const store = tx.objectStore(SNAPSHOTS_STORE);\n      if (isOwnFormat(await requestToPromise(store.get(key)))) store.delete(key);\n      await transactionDone(tx);\n    });\n\n  const pendingKey = (ownerId: string, threadId: string) => `${ownerId}\\u0000${threadId}`;\n\n  const flushPending = (key: string): Promise<void> => {\n    const entry = pending.get(key);\n    if (!entry) return Promise.resolve();\n    pending.delete(key);\n    clearTimeout(entry.timer);\n    return put(entry.input);\n  };\n\n  const putList = (input: { ownerId: string; listKey: string; value: unknown }) =>\n    enqueue(async () => {\n      const db = await database();\n      if (!db) return;\n      const cryptoKey = await keyOf(input.ownerId, \"write\");\n      if (!cryptoKey) return;\n      const owner = await sha256Hex(input.ownerId);\n      const key = await sha256Hex(`${input.ownerId}|list|${input.listKey}`);\n      const sealed = await sealJson({ key: cryptoKey, value: input.value, aad: aadOf(\"list\", owner, key) });\n      const tx = db.transaction(LISTS_STORE, \"readwrite\");\n      const store = tx.objectStore(LISTS_STORE);\n      if (isOwnFormat(await requestToPromise(store.get(key)))) {\n        store.put({\n          key,\n          owner,\n          at: Date.now(),\n          format: THREAD_SNAPSHOT_MIRROR_FORMAT,\n          sealed,\n        } satisfies ListRecord);\n      }\n      await transactionDone(tx);\n    });\n\n  const flushList = (key: string): Promise<void> => {\n    const entry = pendingLists.get(key);\n    if (!entry) return Promise.resolve();\n    pendingLists.delete(key);\n    clearTimeout(entry.timer);\n    return putList(entry.input);\n  };\n\n  const dropPendingOf = (ownerId: string | null): void => {\n    for (const [key, entry] of pending) {\n      if (ownerId === null || entry.input.ownerId === ownerId) {\n        clearTimeout(entry.timer);\n        pending.delete(key);\n      }\n    }\n    for (const [key, entry] of pendingLists) {\n      if (ownerId === null || entry.input.ownerId === ownerId) {\n        clearTimeout(entry.timer);\n        pendingLists.delete(key);\n      }\n    }\n  };\n\n  return {\n    async load(ownerId) {\n      try {\n        const db = await database();\n        if (!db) return [];\n        const cryptoKey = await keyOf(ownerId, \"read\");\n        if (!cryptoKey) return [];\n        const owner = await sha256Hex(ownerId);\n        const records = (await requestToPromise(\n          db.transaction(SNAPSHOTS_STORE, \"readonly\").objectStore(SNAPSHOTS_STORE).index(BY_OWNER).getAll(owner),\n        )) as SnapshotRecord[];\n        const loaded: MirroredThreadSnapshot[] = [];\n        const unreadable: string[] = [];\n        for (const record of records) {\n          if (!record || record.format > THREAD_SNAPSHOT_MIRROR_FORMAT) continue;\n          try {\n            const value = await openJson({\n              key: cryptoKey,\n              sealed: record.sealed,\n              aad: aadOf(\"snapshot\", owner, record.key),\n            });\n            if (\n              isRecord(value) &&\n              typeof value.threadId === \"string\" &&\n              isRecord(value.state) &&\n              typeof record.at === \"number\"\n            ) {\n              loaded.push({ threadId: value.threadId, state: value.state as DeepAgentStreamValues, at: record.at });\n            }\n          } catch {\n            unreadable.push(record.key);\n          }\n        }\n        if (unreadable.length > 0) {\n          void enqueue(async () => {\n            const tx = db.transaction(SNAPSHOTS_STORE, \"readwrite\");\n            for (const key of unreadable) tx.objectStore(SNAPSHOTS_STORE).delete(key);\n            await transactionDone(tx);\n          });\n        }\n        return loaded.sort((a, b) => a.at - b.at);\n      } catch {\n        return [];\n      }\n    },\n    write(input) {\n      const key = pendingKey(input.ownerId, input.threadId);\n      const verdict = classifyThreadSnapshotForMirror(input.state, maxMessages);\n      if (verdict === \"invalidate\") {\n        const existing = pending.get(key);\n        if (existing) clearTimeout(existing.timer);\n        pending.delete(key);\n        void deleteSnapshot(input);\n        return;\n      }\n      if (verdict === \"skip\") return;\n      const existing = pending.get(key);\n      if (existing) clearTimeout(existing.timer);\n      pending.set(key, {\n        input,\n        timer: setTimeout(() => {\n          void flushPending(key);\n        }, debounceMs),\n      });\n    },\n    remove(input) {\n      const key = pendingKey(input.ownerId, input.threadId);\n      const existing = pending.get(key);\n      if (existing) clearTimeout(existing.timer);\n      pending.delete(key);\n      void deleteSnapshot(input);\n    },\n    writeList(input) {\n      const key = pendingKey(input.ownerId, `list:${input.listKey}`);\n      const existing = pendingLists.get(key);\n      if (existing) clearTimeout(existing.timer);\n      pendingLists.set(key, {\n        input,\n        timer: setTimeout(() => {\n          void flushList(key);\n        }, debounceMs),\n      });\n    },\n    async loadList({ ownerId, listKey }) {\n      try {\n        const db = await database();\n        if (!db) return null;\n        const cryptoKey = await keyOf(ownerId, \"read\");\n        if (!cryptoKey) return null;\n        const owner = await sha256Hex(ownerId);\n        const key = await sha256Hex(`${ownerId}|list|${listKey}`);\n        const record = (await requestToPromise(\n          db.transaction(LISTS_STORE, \"readonly\").objectStore(LISTS_STORE).get(key),\n        )) as ListRecord | undefined;\n        if (!record || record.format > THREAD_SNAPSHOT_MIRROR_FORMAT || record.owner !== owner) return null;\n        try {\n          const value = await openJson({ key: cryptoKey, sealed: record.sealed, aad: aadOf(\"list\", owner, key) });\n          return { value, at: record.at };\n        } catch {\n          return null;\n        }\n      } catch {\n        return null;\n      }\n    },\n    clearOwner(ownerId) {\n      dropPendingOf(ownerId);\n      return enqueue(async () => {\n        const db = await database();\n        if (!db) return;\n        const owner = await sha256Hex(ownerId);\n        const tx = db.transaction([SNAPSHOTS_STORE, LISTS_STORE], \"readwrite\");\n        for (const storeName of [SNAPSHOTS_STORE, LISTS_STORE]) {\n          const store = tx.objectStore(storeName);\n          const keys = await requestToPromise(store.index(BY_OWNER).getAllKeys(owner));\n          for (const key of keys) store.delete(key);\n        }\n        await transactionDone(tx);\n      });\n    },\n    clearAll() {\n      dropPendingOf(null);\n      return enqueue(async () => {\n        const db = await database();\n        if (!db) return;\n        const tx = db.transaction([SNAPSHOTS_STORE, LISTS_STORE], \"readwrite\");\n        tx.objectStore(SNAPSHOTS_STORE).clear();\n        tx.objectStore(LISTS_STORE).clear();\n        await transactionDone(tx);\n      });\n    },\n    async flush() {\n      await Promise.all([...pending.keys()].map(flushPending));\n      await Promise.all([...pendingLists.keys()].map(flushList));\n      await queue;\n    },\n  };\n}\n"],"names":["existing"],"mappings":"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"}

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

@@ -0,0 +1,53 @@
+import type { StatewireThread } from '@assistant-ui/react-statewire';
+import type { DeepAgentConnectionState } from './types';
+export type DeepAgentThreadStatus = StatewireThread.ThreadStatus;
+/**
+ * Runtime-scoped thread status, as the library presents it: `"loading"` /
+ * `"ready"` / the run's status replicated by the host, with a mid-run
+ * connection loss presented as `"evicted"` (server-update pod drain) or
+ * `"disconnected"` instead of `"running"`. Throws outside a statewire aui
+ * provider, matching react-statewire 0.13's removed `useStatewireThreadStatus`.
+ */
+export declare function useDeepAgentThreadStatus(): DeepAgentThreadStatus;
+/** The two presented statuses that hide a live run behind a channel problem. */
+export type DeepAgentStaleRunReason = Extract<DeepAgentThreadStatus, 'disconnected' | 'evicted'>;
+/** A first connection attempt can present an optimistic run without a stale warning. */
+export declare function resolveStaleRunReason({ status, connection, }: {
+    status: DeepAgentThreadStatus;
+    connection?: DeepAgentConnectionState | null;
+}): DeepAgentStaleRunReason | null;
+/**
+ * Whether the thread has a live run to present — the composer's Running bar
+ * and its Stop/Queue slot.
+ *
+ * The library derives `thread.isRunning` from the PRESENTED status, so a run
+ * that is live on the host but sits behind a channel that has not connected
+ * yet reads as not running. Behind a first dial that is exactly the run the
+ * client just seeded — switching back to a thread that was running when you
+ * left, or a brand-new chat's optimistic first send — and nothing is stale:
+ * the channel is still attaching. Hiding the run for that round-trip flashes
+ * Ready and a Send button before Running comes back. A run behind a reconnect
+ * or an eviction is presented by the stale treatment (`resolveStaleRunReason`),
+ * never as live.
+ */
+export declare function resolveRunLive({ status, connection, }: {
+    status: DeepAgentThreadStatus;
+    connection?: DeepAgentConnectionState | null;
+}): boolean;
+/**
+ * `thread.isRunning` for a `useAuiState` selector, folded through
+ * `resolveRunLive` when the thread is a statewire thread. A thread without a
+ * statewire status (another runtime, a test stub) keeps the library's answer.
+ */
+export declare function readRunLive(thread: {
+    isRunning: boolean;
+    extras?: unknown;
+}, connection: DeepAgentConnectionState | null): boolean;
+/**
+ * The active thread's channel, for `readRunLive`'s first-dial verdict. Each
+ * host provides it from its own lifecycle state (`AthenaProvider`, the
+ * Chrome extension's lifecycle provider); `null` means "no channel known",
+ * which folds a `disconnected` status as stale.
+ */
+export declare const DeepAgentConnectionContext: import("react").Context<DeepAgentConnectionState | null>;
+export declare function useDeepAgentConnection(): DeepAgentConnectionState | null;