@athenaintel/react 0.41.2 → 0.42.1

package/dist/agent-runtime/src/deep-agent-transport-recipe.js.map

@@ -1 +1 @@
-{"version":3,"file":"deep-agent-transport-recipe.js","sources":["../../../../agent-runtime/src/deep-agent-transport-recipe.ts"],"sourcesContent":["import type { ResourceElement } from \"@assistant-ui/tap\";\nimport type { Statewire, StatewireClient } from \"statewire\";\nimport {\n  type DeepAgentMessageWindowDeclaration,\n  withDeclaredMessageWindow,\n} from \"./message-window\";\nimport { withDeclaredProtocolVersion } from \"./protocol\";\nimport {\n  attachRetryGate,\n  type AttachRetryGate,\n  createAttachInstrumentation,\n  type DeepAgentAttachTimingEvent,\n  type DeepAgentWakeRefusal,\n  parseRetryAfterHeaderMs,\n} from \"./statewire-attach-observer\";\nimport {\n  resolveStatewireTransportKind,\n  statewireTransport,\n  type StatewireTransportOptions,\n} from \"./statewire-transport\";\n\n/** Auth-header resolver for the transport; `staleAuth` is true right after an\n * auth rejection, so resolvers that can force-renew should honor it. */\nexport type DeepAgentHeadersResolver = (ctx: {\n  staleAuth: boolean;\n}) => Record<string, string> | Promise<Record<string, string>>;\n\n/** The statewire attach URL for a thread: the host's `…/v2/threads` mount plus the id. */\nexport function deepAgentThreadUrl({\n  baseUrl,\n  threadId,\n}: {\n  baseUrl: string;\n  threadId: string;\n}): string {\n  return `${baseUrl.replace(/\\/+$/, \"\")}/${encodeURIComponent(threadId)}`;\n}\n\nexport interface DeepAgentAttachTransportOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  /** SSE when true, WebSocket otherwise (`resolveStatewireTransportKind`). */\n  sse?: boolean;\n  /** A never-started chat: the transport makes no network calls until the first command send. */\n  isNew?: boolean;\n  /** Host session store (mobile); browser hosts mount `storage.session` on the thread instead. */\n  sessionStore?: StatewireClient.SessionStorage | undefined;\n  /** Observes every headers resolve (the diagnostics recorder's stale-auth seam). */\n  onAuthResolve?: ((ctx: { staleAuth: boolean }) => void) | undefined;\n  /** Attach timing + retry hints (see `statewire-attach-observer`). */\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  /**\n   * The head window declared on the attach (`x-athena-deep-agent-window`,\n   * see `message-window.ts`): the hello of a client the host does not\n   * remember carries the newest `size` messages. Part of the recipe so a\n   * pooled dial asks for the same shape as the thread's own attach — a pooled\n   * hello then seeds the very state the attach will reconcile. Omitted, the\n   * shared default is declared.\n   */\n  messageWindow?: DeepAgentMessageWindowDeclaration | undefined;\n}\n\n/**\n * The ONE recipe for a deep-agent thread transport — shared by the mounted\n * thread (`useDeepAgentThread`) and the prewarm pool, so a pre-dialed\n * connection is byte-for-byte the connection the thread would have opened\n * itself: same URL, same auth + wire-contract headers, same session lane, same\n * instrumentation.\n *\n * Every attach declares this build's wire-contract version alongside the\n * host's auth headers (first WS frame / SSE request headers) — the server\n * half of version negotiation reads it in `authorize`. The headers resolve\n * also waits out any server `Retry-After` floor for the thread: both statewire\n * attach paths resolve headers before they dial, so this is the seam where a\n * hint can hold the next dial without touching the library's backoff.\n */\nexport function createDeepAgentAttachTransport<TState = unknown>({\n  baseUrl,\n  threadId,\n  headers,\n  sse = false,\n  isNew = false,\n  sessionStore,\n  onAuthResolve,\n  onAttachTiming,\n  retryGate = attachRetryGate,\n  messageWindow,\n}: DeepAgentAttachTransportOptions): ResourceElement<\n  Statewire<TState | undefined>\n> {\n  const url = deepAgentThreadUrl({ baseUrl, threadId });\n  // The instrumentation wraps the transport actually built: SSE needs the\n  // fetch wrapper that reads a refused attach's `Retry-After`.\n  const useSse = resolveStatewireTransportKind({ sse }) === \"sse\";\n  const instrumentation = createAttachInstrumentation({\n    url,\n    sse: useSse,\n    onEvent: onAttachTiming,\n    retryGate,\n  });\n  const options: StatewireTransportOptions = {\n    url,\n    ...(isNew && { isNew: true }),\n    headers: async (ctx: { staleAuth: boolean }) => {\n      await retryGate.waitForDial(url);\n      onAuthResolve?.(ctx);\n      return withDeclaredMessageWindow(\n        withDeclaredProtocolVersion(await headers(ctx)),\n        messageWindow,\n      );\n    },\n    ...(sessionStore && { sessionStore }),\n    // Structural types: this package compiles without the DOM lib, while\n    // statewire's option types name the browser `WebSocket`/`fetch`.\n    ...(instrumentation.webSocket && {\n      webSocket:\n        instrumentation.webSocket as unknown as StatewireTransportOptions[\"webSocket\"],\n    }),\n    ...(instrumentation.fetch && {\n      fetch:\n        instrumentation.fetch as unknown as StatewireTransportOptions[\"fetch\"],\n    }),\n  };\n  return statewireTransport<TState>(options, { sse: useSse });\n}\n\n/** What `POST …/prewarm` answered. */\nexport interface DeepAgentWakeResult {\n  status: number;\n  /** The host activated the thread and its history is resident. */\n  warm: boolean;\n  /**\n   * `'warm'` when the history was already memoized, `'fresh_load'` when this\n   * call loaded it; `null` when the host did not say (a refusal, or a host\n   * without the route).\n   */\n  history: \"fresh_load\" | \"warm\" | null;\n  /**\n   * The dial floor recorded for the thread off a 503/429 `Retry-After` — the\n   * header's value, except a 503 `\"worker\"` refusal, capped at\n   * {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n   */\n  retryAfterMs: number | null;\n  /** Who refused a 503/429 (see {@link DeepAgentWakeRefusal}); `null` for any other answer. */\n  refusal: DeepAgentWakeRefusal;\n  durationMs: number;\n}\n\n/**\n * Dial floor for a 503 the pinned worker produced about one instance's\n * lifecycle. Pinned answers every retriable 503 with a blanket\n * `Retry-After: 1`, but what those name — an instance record mid-teardown\n * (\"instance closing; retry\": fence release + placement release, ≈100 ms), a\n * full activation queue — clears far sooner than that, and the thread's own\n * attach is the request that carries the next activation. Holding it a full\n * second traded a ≈100 ms gap for a ≈1 s stall on every refused wake. A 429\n * is rate limiting and keeps its hint whatever the body says.\n */\nexport const WAKE_WORKER_REFUSAL_FLOOR_MS = 250;\n\n/**\n * The pinboard's own placement-refusal vocabulary — the `error` strings of\n * `@assistant-ui/pinboard` (`src/refusals.ts` plus the two inline refusals in\n * `src/server.ts`). Mirrors `PINBOARD_PLACEMENT_REFUSAL_ERRORS` in\n * `iris/scaler/src/v2AccessLog.ts`, whose test pins it to the installed\n * library; keep the two lists identical. A body with any other `error`\n * string is `\"unknown\"`, never `\"placement\"`.\n */\nexport const PINBOARD_PLACEMENT_REFUSAL_ERRORS: ReadonlySet<string> = new Set([\n  \"no live backends for namespace\",\n  \"registry cold start, retry\",\n  \"not the serving fleet\",\n  \"no live workers for hostname\",\n  \"hostname binding displaced, retry\",\n  \"hostname bindings inconsistent, retry\",\n  \"takeover in progress, retry\",\n  \"placement held by another hostname\",\n  \"worker inflight cap exceeded, retry\",\n  \"worker refused activation, retry\",\n]);\n\n/**\n * Pinned's instance-lifecycle refusals (`pinned/hosting/directory.py`,\n * `pinned/hosting/_records.py`): each names one instance on the worker the\n * thread is already placed on and clears in the time a teardown or an\n * activation slot takes. Anything else the worker answers 503 with — \"Thread\n * history load failed\", \"The regional conversation store is temporarily\n * unavailable\", a lease that expired — is not about one instance and keeps\n * the full hint.\n */\nexport const PINNED_TRANSIENT_WORKER_REFUSALS: ReadonlySet<string> = new Set([\n  \"instance closing; retry\",\n  \"instance aborted\",\n  \"activation queue full; retry\",\n  \"host draining; retry\",\n  \"instance capacity reached; retry\",\n  \"instance past its wind-down deadline; retry\",\n]);\n\n/**\n * Classify a 503/429 body (see {@link DeepAgentWakeRefusal}): a known pinboard\n * `error` is `\"placement\"`, a known pinned `detail` is `\"worker\"`, everything\n * else — including unfamiliar strings in either field — is `\"unknown\"`.\n */\nexport function classifyWakeRefusal(\n  body: unknown,\n): Exclude<DeepAgentWakeRefusal, null> {\n  if (typeof body === \"object\" && body !== null) {\n    const record = body as Record<string, unknown>;\n    if (\n      typeof record.error === \"string\" &&\n      PINBOARD_PLACEMENT_REFUSAL_ERRORS.has(record.error)\n    ) {\n      return \"placement\";\n    }\n    if (\n      typeof record.detail === \"string\" &&\n      PINNED_TRANSIENT_WORKER_REFUSALS.has(record.detail)\n    ) {\n      return \"worker\";\n    }\n  }\n  return \"unknown\";\n}\n\n/** Structural `fetch` for the wake call — this package compiles without the DOM lib. */\nexport type DeepAgentWakeFetch = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    keepalive?: boolean;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n}>;\n\nexport interface DeepAgentWakeOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  fetch?: DeepAgentWakeFetch | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  now?: () => number;\n}\n\n/**\n * Wake a thread's server instance ahead of its attach. `POST …/prewarm` runs\n * the host's `authorize` and history load — the fence adopt, graph compile and\n * checkpoint read that make a cold attach's hello take ≈1 s — and answers with\n * no thread content, only whether the history was already resident. Fire it\n * on hover intent, before a pooled attach or the click's own dial, so the\n * activation overlaps the handshake and the attach that follows finds the\n * instance warm.\n *\n * Fire-and-forget by contract: every failure resolves `null`, and a host\n * without the route (404) is reported like any other non-OK answer. A 503/429\n * `Retry-After` is recorded as a dial floor for the thread, so the attach that\n * follows waits it out instead of bouncing — in full, except a 503 that names\n * one of pinned's instance-lifecycle refusals (one instance mid-teardown on\n * the worker the thread already has; see {@link DeepAgentWakeRefusal}), whose\n * floor is capped at {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n */\nexport async function wakeDeepAgentThread({\n  baseUrl,\n  threadId,\n  headers,\n  fetch: fetchOverride,\n  retryGate = attachRetryGate,\n  onAttachTiming,\n  now = () => Date.now(),\n}: DeepAgentWakeOptions): Promise<DeepAgentWakeResult | null> {\n  const fetchImpl =\n    fetchOverride ?? (globalThis as { fetch?: DeepAgentWakeFetch }).fetch;\n  if (typeof fetchImpl !== \"function\") return null;\n  const threadUrl = deepAgentThreadUrl({ baseUrl, threadId });\n  const emit = (event: DeepAgentAttachTimingEvent): void => {\n    try {\n      onAttachTiming?.(event);\n    } catch {\n      // Observers are best-effort.\n    }\n  };\n  const startedAt = now();\n  try {\n    const resolved = withDeclaredProtocolVersion(\n      await headers({ staleAuth: false }),\n    );\n    const response = await fetchImpl(`${threadUrl}/prewarm`, {\n      method: \"POST\",\n      headers: resolved,\n      keepalive: true,\n    });\n    const durationMs = now() - startedAt;\n    let retryAfterMs: number | null = null;\n    let refusal: DeepAgentWakeRefusal = null;\n    if (response.status === 503 || response.status === 429) {\n      let body: unknown = null;\n      try {\n        body = await response.json();\n      } catch {\n        // A refusal without a readable body is classified by nothing.\n      }\n      refusal = classifyWakeRefusal(body);\n      const hinted = parseRetryAfterHeaderMs(\n        response.headers.get(\"retry-after\"),\n        now,\n      );\n      if (hinted !== null) {\n        retryAfterMs =\n          response.status === 503 && refusal === \"worker\"\n            ? Math.min(hinted, WAKE_WORKER_REFUSAL_FLOOR_MS)\n            : hinted;\n        if (retryAfterMs > 0) {\n          retryGate.noteRetryAfter(threadUrl, retryAfterMs);\n          emit({\n            type: \"retry-after\",\n            url: threadUrl,\n            delayMs: retryAfterMs,\n            source: \"http-header\",\n          });\n        }\n      }\n    }\n    let warm = false;\n    let history: DeepAgentWakeResult[\"history\"] = null;\n    if (response.ok) {\n      try {\n        const body = (await response.json()) as {\n          warm?: unknown;\n          history?: unknown;\n        } | null;\n        warm = body?.warm === true;\n        history =\n          body?.history === \"warm\" || body?.history === \"fresh_load\"\n            ? body.history\n            : null;\n      } catch {\n        // A 200 without a JSON body still means the instance is up.\n        warm = true;\n      }\n    }\n    emit({\n      type: \"wake\",\n      url: threadUrl,\n      status: response.status,\n      durationMs,\n      history,\n      refusal,\n    });\n    return {\n      status: response.status,\n      warm,\n      history,\n      retryAfterMs,\n      refusal,\n      durationMs,\n    };\n  } catch {\n    return null;\n  }\n}\n"],"names":[],"mappings":";;;;AA4BO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AACF,GAGW;AACT,SAAO,GAAG,QAAQ,QAAQ,QAAQ,EAAE,CAAC,IAAI,mBAAmB,QAAQ,CAAC;AACvE;AA4CO,SAAS,+BAAiD;AAAA,EAC/D;AAAA,EACA;AAAA,EACA;AAAA,EACA,MAAM;AAAA,EACN,QAAQ;AAAA,EACR;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AAAA,EACZ;AACF,GAEE;AACA,QAAM,MAAM,mBAAmB,EAAE,SAAS,UAAU;AAGpD,QAAM,SAAS,8BAA8B,EAAE,IAAA,CAAK,MAAM;AAC1D,QAAM,kBAAkB,4BAA4B;AAAA,IAClD;AAAA,IACA,KAAK;AAAA,IACL,SAAS;AAAA,IACT;AAAA,EAAA,CACD;AACD,QAAM,UAAqC;AAAA,IACzC;AAAA,IACA,GAAI,SAAS,EAAE,OAAO,KAAA;AAAA,IACtB,SAAS,OAAO,QAAgC;AAC9C,YAAM,UAAU,YAAY,GAAG;AAC/B,qDAAgB;AAChB,aAAO;AAAA,QACL,4BAA4B,MAAM,QAAQ,GAAG,CAAC;AAAA,QAC9C;AAAA,MAAA;AAAA,IAEJ;AAAA,IACA,GAAI,gBAAgB,EAAE,aAAA;AAAA;AAAA;AAAA,IAGtB,GAAI,gBAAgB,aAAa;AAAA,MAC/B,WACE,gBAAgB;AAAA,IAAA;AAAA,IAEpB,GAAI,gBAAgB,SAAS;AAAA,MAC3B,OACE,gBAAgB;AAAA,IAAA;AAAA,EACpB;AAEF,SAAO,mBAA2B,SAAS,EAAE,KAAK,QAAQ;AAC5D;"}
+{"version":3,"file":"deep-agent-transport-recipe.js","sources":["../../../../agent-runtime/src/deep-agent-transport-recipe.ts"],"sourcesContent":["import type { ResourceElement } from \"@assistant-ui/tap\";\nimport type { Statewire, StatewireClient } from \"statewire\";\nimport {\n  type DeepAgentMessageWindowDeclaration,\n  withDeclaredMessageWindow,\n} from \"./message-window\";\nimport { withDeclaredProtocolVersion } from \"./protocol\";\nimport {\n  attachRetryGate,\n  type AttachRetryGate,\n  createAttachInstrumentation,\n  type DeepAgentAttachTimingEvent,\n  type DeepAgentWakeRefusal,\n  parseRetryAfterHeaderMs,\n} from \"./statewire-attach-observer\";\nimport {\n  resolveStatewireTransportKind,\n  statewireTransport,\n  type StatewireTransportOptions,\n} from \"./statewire-transport\";\n\n/** Auth-header resolver for the transport; `staleAuth` is true right after an\n * auth rejection, so resolvers that can force-renew should honor it. */\nexport type DeepAgentHeadersResolver = (ctx: {\n  staleAuth: boolean;\n}) => Record<string, string> | Promise<Record<string, string>>;\n\n/** The statewire attach URL for a thread: the host's `…/v2/threads` mount plus the id. */\nexport function deepAgentThreadUrl({\n  baseUrl,\n  threadId,\n}: {\n  baseUrl: string;\n  threadId: string;\n}): string {\n  return `${baseUrl.replace(/\\/+$/, \"\")}/${encodeURIComponent(threadId)}`;\n}\n\nexport interface DeepAgentAttachTransportOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  /** SSE when true, WebSocket otherwise (`resolveStatewireTransportKind`). */\n  sse?: boolean;\n  /** A never-started chat: the transport makes no network calls until the first command send. */\n  isNew?: boolean;\n  /** Host session store (mobile); browser hosts mount `storage.session` on the thread instead. */\n  sessionStore?: StatewireClient.SessionStorage | undefined;\n  /** Observes every headers resolve (the diagnostics recorder's stale-auth seam). */\n  onAuthResolve?: ((ctx: { staleAuth: boolean }) => void) | undefined;\n  /** Attach timing + retry hints (see `statewire-attach-observer`). */\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  /**\n   * The head window declared on the attach (`x-athena-deep-agent-window`,\n   * see `message-window.ts`): the hello of a client the host does not\n   * remember carries the newest `size` messages. Part of the recipe so a\n   * pooled dial asks for the same shape as the thread's own attach — a pooled\n   * hello then seeds the very state the attach will reconcile. Omitted, the\n   * shared default is declared.\n   */\n  messageWindow?: DeepAgentMessageWindowDeclaration | undefined;\n  /**\n   * The surface pages cut lanes (see `DeepAgentProtocolDeclaration`), so its\n   * attach declares the lane-cut contract version. Part of the recipe so a\n   * pooled dial declares what the thread's own attach would; omitted, the\n   * default version is declared.\n   */\n  laneHistory?: boolean | undefined;\n}\n\n/**\n * The ONE recipe for a deep-agent thread transport — shared by the mounted\n * thread (`useDeepAgentThread`) and the prewarm pool, so a pre-dialed\n * connection is byte-for-byte the connection the thread would have opened\n * itself: same URL, same auth + wire-contract headers, same session lane, same\n * instrumentation.\n *\n * Every attach declares the surface's wire-contract version alongside the\n * host's auth headers (first WS frame / SSE request headers) — the server\n * half of version negotiation reads it in `authorize`. The headers resolve\n * also waits out any server `Retry-After` floor for the thread: both statewire\n * attach paths resolve headers before they dial, so this is the seam where a\n * hint can hold the next dial without touching the library's backoff.\n */\nexport function createDeepAgentAttachTransport<TState = unknown>({\n  baseUrl,\n  threadId,\n  headers,\n  sse = false,\n  isNew = false,\n  sessionStore,\n  onAuthResolve,\n  onAttachTiming,\n  retryGate = attachRetryGate,\n  messageWindow,\n  laneHistory = false,\n}: DeepAgentAttachTransportOptions): ResourceElement<\n  Statewire<TState | undefined>\n> {\n  const url = deepAgentThreadUrl({ baseUrl, threadId });\n  // The instrumentation wraps the transport actually built: SSE needs the\n  // fetch wrapper that reads a refused attach's `Retry-After`.\n  const useSse = resolveStatewireTransportKind({ sse }) === \"sse\";\n  const instrumentation = createAttachInstrumentation({\n    url,\n    sse: useSse,\n    onEvent: onAttachTiming,\n    retryGate,\n  });\n  const options: StatewireTransportOptions = {\n    url,\n    ...(isNew && { isNew: true }),\n    headers: async (ctx: { staleAuth: boolean }) => {\n      await retryGate.waitForDial(url);\n      onAuthResolve?.(ctx);\n      return withDeclaredMessageWindow(\n        withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),\n        messageWindow,\n      );\n    },\n    ...(sessionStore && { sessionStore }),\n    // Structural types: this package compiles without the DOM lib, while\n    // statewire's option types name the browser `WebSocket`/`fetch`.\n    ...(instrumentation.webSocket && {\n      webSocket:\n        instrumentation.webSocket as unknown as StatewireTransportOptions[\"webSocket\"],\n    }),\n    ...(instrumentation.fetch && {\n      fetch:\n        instrumentation.fetch as unknown as StatewireTransportOptions[\"fetch\"],\n    }),\n  };\n  return statewireTransport<TState>(options, { sse: useSse });\n}\n\n/** What `POST …/prewarm` answered. */\nexport interface DeepAgentWakeResult {\n  status: number;\n  /** The host activated the thread and its history is resident. */\n  warm: boolean;\n  /**\n   * `'warm'` when the history was already memoized, `'fresh_load'` when this\n   * call loaded it; `null` when the host did not say (a refusal, or a host\n   * without the route).\n   */\n  history: \"fresh_load\" | \"warm\" | null;\n  /**\n   * The dial floor recorded for the thread off a 503/429 `Retry-After` — the\n   * header's value, except a 503 `\"worker\"` refusal, capped at\n   * {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n   */\n  retryAfterMs: number | null;\n  /** Who refused a 503/429 (see {@link DeepAgentWakeRefusal}); `null` for any other answer. */\n  refusal: DeepAgentWakeRefusal;\n  durationMs: number;\n}\n\n/**\n * Dial floor for a 503 the pinned worker produced about one instance's\n * lifecycle. Pinned answers every retriable 503 with a blanket\n * `Retry-After: 1`, but what those name — an instance record mid-teardown\n * (\"instance closing; retry\": fence release + placement release, ≈100 ms), a\n * full activation queue — clears far sooner than that, and the thread's own\n * attach is the request that carries the next activation. Holding it a full\n * second traded a ≈100 ms gap for a ≈1 s stall on every refused wake. A 429\n * is rate limiting and keeps its hint whatever the body says.\n */\nexport const WAKE_WORKER_REFUSAL_FLOOR_MS = 250;\n\n/**\n * The pinboard's own placement-refusal vocabulary — the `error` strings of\n * `@assistant-ui/pinboard` (`src/refusals.ts` plus the two inline refusals in\n * `src/server.ts`). Mirrors `PINBOARD_PLACEMENT_REFUSAL_ERRORS` in\n * `iris/scaler/src/v2AccessLog.ts`, whose test pins it to the installed\n * library; keep the two lists identical. A body with any other `error`\n * string is `\"unknown\"`, never `\"placement\"`.\n */\nexport const PINBOARD_PLACEMENT_REFUSAL_ERRORS: ReadonlySet<string> = new Set([\n  \"no live backends for namespace\",\n  \"registry cold start, retry\",\n  \"not the serving fleet\",\n  \"no live workers for hostname\",\n  \"hostname binding displaced, retry\",\n  \"hostname bindings inconsistent, retry\",\n  \"takeover in progress, retry\",\n  \"placement held by another hostname\",\n  \"worker inflight cap exceeded, retry\",\n  \"worker refused activation, retry\",\n]);\n\n/**\n * Pinned's instance-lifecycle refusals (`pinned/hosting/directory.py`,\n * `pinned/hosting/_records.py`): each names one instance on the worker the\n * thread is already placed on and clears in the time a teardown or an\n * activation slot takes. Anything else the worker answers 503 with — \"Thread\n * history load failed\", \"The regional conversation store is temporarily\n * unavailable\", a lease that expired — is not about one instance and keeps\n * the full hint.\n */\nexport const PINNED_TRANSIENT_WORKER_REFUSALS: ReadonlySet<string> = new Set([\n  \"instance closing; retry\",\n  \"instance aborted\",\n  \"activation queue full; retry\",\n  \"host draining; retry\",\n  \"instance capacity reached; retry\",\n  \"instance past its wind-down deadline; retry\",\n]);\n\n/**\n * Classify a 503/429 body (see {@link DeepAgentWakeRefusal}): a known pinboard\n * `error` is `\"placement\"`, a known pinned `detail` is `\"worker\"`, everything\n * else — including unfamiliar strings in either field — is `\"unknown\"`.\n */\nexport function classifyWakeRefusal(\n  body: unknown,\n): Exclude<DeepAgentWakeRefusal, null> {\n  if (typeof body === \"object\" && body !== null) {\n    const record = body as Record<string, unknown>;\n    if (\n      typeof record.error === \"string\" &&\n      PINBOARD_PLACEMENT_REFUSAL_ERRORS.has(record.error)\n    ) {\n      return \"placement\";\n    }\n    if (\n      typeof record.detail === \"string\" &&\n      PINNED_TRANSIENT_WORKER_REFUSALS.has(record.detail)\n    ) {\n      return \"worker\";\n    }\n  }\n  return \"unknown\";\n}\n\n/** Structural `fetch` for the wake call — this package compiles without the DOM lib. */\nexport type DeepAgentWakeFetch = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    keepalive?: boolean;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n}>;\n\nexport interface DeepAgentWakeOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  fetch?: DeepAgentWakeFetch | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  now?: () => number;\n  /** The surface pages cut lanes: declare what its attach declares (see `DeepAgentAttachTransportOptions`). */\n  laneHistory?: boolean | undefined;\n}\n\n/**\n * Wake a thread's server instance ahead of its attach. `POST …/prewarm` runs\n * the host's `authorize` and history load — the fence adopt, graph compile and\n * checkpoint read that make a cold attach's hello take ≈1 s — and answers with\n * no thread content, only whether the history was already resident. Fire it\n * on hover intent, before a pooled attach or the click's own dial, so the\n * activation overlaps the handshake and the attach that follows finds the\n * instance warm.\n *\n * Fire-and-forget by contract: every failure resolves `null`, and a host\n * without the route (404) is reported like any other non-OK answer. A 503/429\n * `Retry-After` is recorded as a dial floor for the thread, so the attach that\n * follows waits it out instead of bouncing — in full, except a 503 that names\n * one of pinned's instance-lifecycle refusals (one instance mid-teardown on\n * the worker the thread already has; see {@link DeepAgentWakeRefusal}), whose\n * floor is capped at {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n */\nexport async function wakeDeepAgentThread({\n  baseUrl,\n  threadId,\n  headers,\n  fetch: fetchOverride,\n  retryGate = attachRetryGate,\n  onAttachTiming,\n  now = () => Date.now(),\n  laneHistory = false,\n}: DeepAgentWakeOptions): Promise<DeepAgentWakeResult | null> {\n  const fetchImpl =\n    fetchOverride ?? (globalThis as { fetch?: DeepAgentWakeFetch }).fetch;\n  if (typeof fetchImpl !== \"function\") return null;\n  const threadUrl = deepAgentThreadUrl({ baseUrl, threadId });\n  const emit = (event: DeepAgentAttachTimingEvent): void => {\n    try {\n      onAttachTiming?.(event);\n    } catch {\n      // Observers are best-effort.\n    }\n  };\n  const startedAt = now();\n  try {\n    const resolved = withDeclaredProtocolVersion(\n      await headers({ staleAuth: false }),\n      { laneHistory },\n    );\n    const response = await fetchImpl(`${threadUrl}/prewarm`, {\n      method: \"POST\",\n      headers: resolved,\n      keepalive: true,\n    });\n    const durationMs = now() - startedAt;\n    let retryAfterMs: number | null = null;\n    let refusal: DeepAgentWakeRefusal = null;\n    if (response.status === 503 || response.status === 429) {\n      let body: unknown = null;\n      try {\n        body = await response.json();\n      } catch {\n        // A refusal without a readable body is classified by nothing.\n      }\n      refusal = classifyWakeRefusal(body);\n      const hinted = parseRetryAfterHeaderMs(\n        response.headers.get(\"retry-after\"),\n        now,\n      );\n      if (hinted !== null) {\n        retryAfterMs =\n          response.status === 503 && refusal === \"worker\"\n            ? Math.min(hinted, WAKE_WORKER_REFUSAL_FLOOR_MS)\n            : hinted;\n        if (retryAfterMs > 0) {\n          retryGate.noteRetryAfter(threadUrl, retryAfterMs);\n          emit({\n            type: \"retry-after\",\n            url: threadUrl,\n            delayMs: retryAfterMs,\n            source: \"http-header\",\n          });\n        }\n      }\n    }\n    let warm = false;\n    let history: DeepAgentWakeResult[\"history\"] = null;\n    if (response.ok) {\n      try {\n        const body = (await response.json()) as {\n          warm?: unknown;\n          history?: unknown;\n        } | null;\n        warm = body?.warm === true;\n        history =\n          body?.history === \"warm\" || body?.history === \"fresh_load\"\n            ? body.history\n            : null;\n      } catch {\n        // A 200 without a JSON body still means the instance is up.\n        warm = true;\n      }\n    }\n    emit({\n      type: \"wake\",\n      url: threadUrl,\n      status: response.status,\n      durationMs,\n      history,\n      refusal,\n    });\n    return {\n      status: response.status,\n      warm,\n      history,\n      retryAfterMs,\n      refusal,\n      durationMs,\n    };\n  } catch {\n    return null;\n  }\n}\n"],"names":[],"mappings":";;;;AA4BO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AACF,GAGW;AACT,SAAO,GAAG,QAAQ,QAAQ,QAAQ,EAAE,CAAC,IAAI,mBAAmB,QAAQ,CAAC;AACvE;AAmDO,SAAS,+BAAiD;AAAA,EAC/D;AAAA,EACA;AAAA,EACA;AAAA,EACA,MAAM;AAAA,EACN,QAAQ;AAAA,EACR;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA,cAAc;AAChB,GAEE;AACA,QAAM,MAAM,mBAAmB,EAAE,SAAS,UAAU;AAGpD,QAAM,SAAS,8BAA8B,EAAE,IAAA,CAAK,MAAM;AAC1D,QAAM,kBAAkB,4BAA4B;AAAA,IAClD;AAAA,IACA,KAAK;AAAA,IACL,SAAS;AAAA,IACT;AAAA,EAAA,CACD;AACD,QAAM,UAAqC;AAAA,IACzC;AAAA,IACA,GAAI,SAAS,EAAE,OAAO,KAAA;AAAA,IACtB,SAAS,OAAO,QAAgC;AAC9C,YAAM,UAAU,YAAY,GAAG;AAC/B,qDAAgB;AAChB,aAAO;AAAA,QACL,4BAA4B,MAAM,QAAQ,GAAG,GAAG,EAAE,aAAa;AAAA,QAC/D;AAAA,MAAA;AAAA,IAEJ;AAAA,IACA,GAAI,gBAAgB,EAAE,aAAA;AAAA;AAAA;AAAA,IAGtB,GAAI,gBAAgB,aAAa;AAAA,MAC/B,WACE,gBAAgB;AAAA,IAAA;AAAA,IAEpB,GAAI,gBAAgB,SAAS;AAAA,MAC3B,OACE,gBAAgB;AAAA,IAAA;AAAA,EACpB;AAEF,SAAO,mBAA2B,SAAS,EAAE,KAAK,QAAQ;AAC5D;"}

package/dist/agent-runtime/src/desktop-handoff.d.ts

@@ -0,0 +1,139 @@
+/** Authenticated desktop handoffs carry references, never document/chat contents or credentials. */
+import { z } from "zod";
+export declare const DESKTOP_HANDOFF_PROTOCOL_VERSION: 1;
+export declare const DESKTOP_HANDOFF_MAX_ASSETS = 50;
+export declare const desktopHandoffAssetSchema: z.ZodObject<{
+    asset_id: z.ZodString;
+    reference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type DesktopHandoffAsset = z.infer<typeof desktopHandoffAssetSchema>;
+export declare const desktopHandoffResultSchema: z.ZodObject<{
+    desktop_version: z.ZodString;
+    protocol_version: z.ZodLiteral<1>;
+    thread_opened: z.ZodBoolean;
+    assets: z.ZodArray<z.ZodObject<{
+        asset_id: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            opened: "opened";
+            web_fallback: "web_fallback";
+        }>;
+        reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DesktopHandoffResult = z.infer<typeof desktopHandoffResultSchema>;
+export declare const desktopHandoffViewSchema: z.ZodObject<{
+    handoff_id: z.ZodString;
+    thread_id: z.ZodNullable<z.ZodString>;
+    session_asset_id: z.ZodNullable<z.ZodString>;
+    source: z.ZodLiteral<"spaces">;
+    destination: z.ZodLiteral<"desktop">;
+    environment: z.ZodEnum<{
+        localhost: "localhost";
+        production: "production";
+        staging: "staging";
+    }>;
+    state: z.ZodEnum<{
+        acknowledged: "acknowledged";
+        claimed: "claimed";
+        failed: "failed";
+        issued: "issued";
+        launched: "launched";
+    }>;
+    issued_at: z.ZodISODateTime;
+    expires_at: z.ZodISODateTime;
+    claimed_at: z.ZodNullable<z.ZodISODateTime>;
+    acknowledged_at: z.ZodNullable<z.ZodISODateTime>;
+    failure_reason: z.ZodNullable<z.ZodString>;
+    assets: z.ZodArray<z.ZodObject<{
+        asset_id: z.ZodString;
+        reference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    active_asset_id: z.ZodNullable<z.ZodString>;
+    result: z.ZodNullable<z.ZodObject<{
+        desktop_version: z.ZodString;
+        protocol_version: z.ZodLiteral<1>;
+        thread_opened: z.ZodBoolean;
+        assets: z.ZodArray<z.ZodObject<{
+            asset_id: z.ZodString;
+            status: z.ZodEnum<{
+                failed: "failed";
+                opened: "opened";
+                web_fallback: "web_fallback";
+            }>;
+            reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DesktopHandoffView = z.infer<typeof desktopHandoffViewSchema>;
+export declare const desktopHandoffLaunchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"desktop">;
+    scheme_url: z.ZodString;
+    download_url: z.ZodURL;
+    deployment_url: z.ZodURL;
+    protocol_version: z.ZodLiteral<1>;
+}, z.core.$strip>;
+export type DesktopHandoffLaunch = z.infer<typeof desktopHandoffLaunchSchema>;
+export declare const createDesktopHandoffResponseSchema: z.ZodObject<{
+    handoff: z.ZodObject<{
+        handoff_id: z.ZodString;
+        thread_id: z.ZodNullable<z.ZodString>;
+        session_asset_id: z.ZodNullable<z.ZodString>;
+        source: z.ZodLiteral<"spaces">;
+        destination: z.ZodLiteral<"desktop">;
+        environment: z.ZodEnum<{
+            localhost: "localhost";
+            production: "production";
+            staging: "staging";
+        }>;
+        state: z.ZodEnum<{
+            acknowledged: "acknowledged";
+            claimed: "claimed";
+            failed: "failed";
+            issued: "issued";
+            launched: "launched";
+        }>;
+        issued_at: z.ZodISODateTime;
+        expires_at: z.ZodISODateTime;
+        claimed_at: z.ZodNullable<z.ZodISODateTime>;
+        acknowledged_at: z.ZodNullable<z.ZodISODateTime>;
+        failure_reason: z.ZodNullable<z.ZodString>;
+        assets: z.ZodArray<z.ZodObject<{
+            asset_id: z.ZodString;
+            reference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
+        active_asset_id: z.ZodNullable<z.ZodString>;
+        result: z.ZodNullable<z.ZodObject<{
+            desktop_version: z.ZodString;
+            protocol_version: z.ZodLiteral<1>;
+            thread_opened: z.ZodBoolean;
+            assets: z.ZodArray<z.ZodObject<{
+                asset_id: z.ZodString;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    opened: "opened";
+                    web_fallback: "web_fallback";
+                }>;
+                reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    launch: z.ZodObject<{
+        kind: z.ZodLiteral<"desktop">;
+        scheme_url: z.ZodString;
+        download_url: z.ZodURL;
+        deployment_url: z.ZodURL;
+        protocol_version: z.ZodLiteral<1>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CreateDesktopHandoffResponse = z.infer<typeof createDesktopHandoffResponseSchema>;
+export interface CreateDesktopHandoffInput {
+    thread_id?: string | null;
+    assets: DesktopHandoffAsset[];
+    active_asset_id?: string | null;
+    source: "spaces";
+}
+/** Only a destination acknowledgement proves a launch. Timeouts prove no installation state. */
+export declare function desktopHandoffSummary({ handoff, }: {
+    handoff: DesktopHandoffView;
+}): string;

package/dist/agent-runtime/src/durable-thread-snapshot-cache.cjs

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const threadSnapshotCache = require("./thread-snapshot-cache.cjs");
+const threadSnapshotMirror = require("./thread-snapshot-mirror.cjs");
+const DEFAULT_MAX_THREADS = 30;
+const OFFLINE_SNAPSHOT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
+function browserOffline() {
+  var _a;
+  const host = globalThis;
+  return ((_a = host.navigator) == null ? void 0 : _a.onLine) === false;
+}
+function createDurableThreadSnapshotCache({
+  mirror,
+  isOffline = browserOffline,
+  maxThreads = DEFAULT_MAX_THREADS,
+  maxAgeMs,
+  offlineMaxAgeMs = OFFLINE_SNAPSHOT_MAX_AGE_MS,
+  now = () => Date.now()
+}) {
+  let ownerId = null;
+  let epoch = 0;
+  let primed = null;
+  let hydration = Promise.resolve();
+  const offline = /* @__PURE__ */ new Map();
+  const offlineSeeds = /* @__PURE__ */ new Map();
+  const restored = /* @__PURE__ */ new Set();
+  const listeners = /* @__PURE__ */ new Set();
+  const notify = () => {
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  };
+  const clearOfflineSeed = (threadId) => {
+    if (offlineSeeds.delete(threadId)) notify();
+  };
+  const keepOffline = (threadId, entry) => {
+    offline.delete(threadId);
+    offline.set(threadId, entry);
+    while (offline.size > maxThreads) {
+      const oldest = offline.keys().next().value;
+      if (oldest === void 0) break;
+      offline.delete(oldest);
+    }
+  };
+  const memory = threadSnapshotCache.createDeepAgentThreadSnapshotCache({
+    maxThreads,
+    maxAgeMs,
+    now,
+    onChange: (change) => {
+      const owner = ownerId;
+      if (owner === null) return;
+      switch (change.type) {
+        case "remember":
+          mirror.write({ ownerId: owner, threadId: change.threadId, state: change.state, at: change.at });
+          return;
+        case "forget":
+          mirror.remove({ ownerId: owner, threadId: change.threadId });
+          return;
+        case "clear":
+          return;
+      }
+    }
+  });
+  const offlineEntry = (threadId) => {
+    const entry = offline.get(threadId);
+    return entry && now() - entry.at <= offlineMaxAgeMs ? entry : void 0;
+  };
+  const dropEverything = () => {
+    memory.clear();
+    offline.clear();
+    restored.clear();
+    if (offlineSeeds.size > 0) {
+      offlineSeeds.clear();
+      notify();
+    }
+  };
+  return {
+    remember(threadId, state) {
+      memory.remember(threadId, state);
+      restored.delete(threadId);
+      if (threadSnapshotMirror.isRestingThreadSnapshot(state)) keepOffline(threadId, { state, at: now() });
+      clearOfflineSeed(threadId);
+    },
+    take(threadId) {
+      if (!isOffline()) return memory.take(threadId);
+      const entry = offlineEntry(threadId);
+      if (!entry) return void 0;
+      if (offlineSeeds.get(threadId) !== entry.at) {
+        offlineSeeds.set(threadId, entry.at);
+        notify();
+      }
+      return entry.state;
+    },
+    peek(threadId) {
+      return isOffline() ? offlineEntry(threadId) !== void 0 : memory.peek(threadId);
+    },
+    forget(threadId) {
+      memory.forget(threadId);
+      offline.delete(threadId);
+      restored.delete(threadId);
+      clearOfflineSeed(threadId);
+    },
+    clear() {
+      dropEverything();
+    },
+    owner: () => ownerId,
+    setOwner(next) {
+      if (next === ownerId) return hydration;
+      const previous = ownerId;
+      ownerId = next;
+      epoch += 1;
+      dropEverything();
+      if (previous !== null) void mirror.clearOwner(previous);
+      if (next === null) {
+        hydration = Promise.resolve();
+        return hydration;
+      }
+      const readEpoch = epoch;
+      const read = (primed == null ? void 0 : primed.ownerId) === next ? primed.read : mirror.load(next);
+      primed = null;
+      hydration = read.then((entries) => {
+        if (readEpoch !== epoch || ownerId !== next) return;
+        for (const entry of entries) {
+          if (!offline.has(entry.threadId)) keepOffline(entry.threadId, { state: entry.state, at: entry.at });
+          if (memory.peek(entry.threadId)) continue;
+          memory.restore(entry.threadId, entry.state, entry.at);
+          if (memory.peek(entry.threadId)) restored.add(entry.threadId);
+        }
+      });
+      return hydration;
+    },
+    prime(next) {
+      if (next === ownerId || (primed == null ? void 0 : primed.ownerId) === next) return;
+      primed = { ownerId: next, read: mirror.load(next) };
+    },
+    offlineSeedAt: (threadId) => offlineSeeds.get(threadId) ?? null,
+    subscribeOfflineSeeds(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    isRestored: (threadId) => restored.has(threadId),
+    whenHydrated: () => hydration,
+    async wipe() {
+      epoch += 1;
+      primed = null;
+      dropEverything();
+      await mirror.clearAll();
+    }
+  };
+}
+exports.OFFLINE_SNAPSHOT_MAX_AGE_MS = OFFLINE_SNAPSHOT_MAX_AGE_MS;
+exports.createDurableThreadSnapshotCache = createDurableThreadSnapshotCache;
+//# sourceMappingURL=durable-thread-snapshot-cache.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"durable-thread-snapshot-cache.cjs","sources":["../../../../agent-runtime/src/durable-thread-snapshot-cache.ts"],"sourcesContent":["import {\n  createDeepAgentThreadSnapshotCache,\n  type DeepAgentThreadSnapshotCache,\n} from \"./thread-snapshot-cache\";\nimport { isRestingThreadSnapshot, type ThreadSnapshotMirror } from \"./thread-snapshot-mirror\";\nimport type { DeepAgentStreamValues } from \"./types\";\n\n/**\n * The thread snapshot cache with a durable, encrypted mirror behind it (`thread-snapshot-mirror.ts`):\n * a reload seeds a recently visited thread from what it last showed, and a thread can be read while\n * the transport cannot connect at all.\n *\n * - **Online, nothing changes.** `take` serves the in-memory entry within its age bound (one hour by\n *   default), exactly as the plain cache does, and the attach snapshot replaces the seed.\n * - **Offline** (`isOffline()`: the host's own word that Athena can't be reached), `take` serves the\n *   thread's last resting transcript this page holds (what it read, or what the mirror kept), up to\n *   `offlineMaxAgeMs` old and past the online bound, so a person can read their recent\n *   conversations on a plane. Never a mid-stream state: a run the connection dropped is a partial\n *   transcript, and the resting one before it is what shows. Every offline seed, however recent, is\n *   recorded with its capture time (`offlineSeedAt`) so the host can say the transcript is \"as of\"\n *   then; only the next state the wire delivers for the thread (its attach) clears it.\n * - **Owned.** Entries belong to one owner (`setOwner`): a change drops every entry, deletes the\n *   previous owner's mirrored records and reads the new owner's. A snapshot captured under one\n *   account never seeds a mount under another. `wipe` drops everything (a sign-out).\n */\nexport interface DurableThreadSnapshotCache extends DeepAgentThreadSnapshotCache {\n  peek(threadId: string): boolean;\n  /** Bind the cache to the acting owner (`null`: nobody signed in; nothing is mirrored). */\n  setOwner(ownerId: string | null): Promise<void>;\n  /**\n   * Start reading an owner's mirrored snapshots before the owner is known for sure (a host's\n   * last-owner hint at boot): `setOwner` adopts the read if that owner is the one bound, and it\n   * is discarded otherwise. Binds nothing and deletes nothing.\n   */\n  prime(ownerId: string): void;\n  /** The owner the cache is bound to. */\n  owner(): string | null;\n  /**\n   * When the seed `take` last served for `threadId` was captured, if it was served while Athena\n   * could not be reached; `null` otherwise, and again once the wire delivers the thread.\n   */\n  offlineSeedAt(threadId: string): number | null;\n  /** Calls `listener` whenever an offline seed is served or cleared; returns what stops it. */\n  subscribeOfflineSeeds(listener: () => void): () => void;\n  /** Whether the entry `take` would serve for `threadId` came back from the mirror. */\n  isRestored(threadId: string): boolean;\n  /** Resolves once the current owner's mirrored snapshots have been read (tests, telemetry). */\n  whenHydrated(): Promise<void>;\n  /** Drop every entry, in memory and in the mirror (a sign-out, a workspace switch). */\n  wipe(): Promise<void>;\n}\n\nexport interface DurableThreadSnapshotCacheOptions {\n  mirror: ThreadSnapshotMirror;\n  /** Whether Athena can't be reached right now (the host's reachability, or the browser's). */\n  isOffline?: () => boolean;\n  maxThreads?: number;\n  /** The online age bound (the plain cache's). */\n  maxAgeMs?: number;\n  /** How old a mirrored snapshot may be and still be read offline. */\n  offlineMaxAgeMs?: number;\n  now?: () => number;\n}\n\nconst DEFAULT_MAX_THREADS = 30;\n/** What a device keeps for reading offline: the offline plan's 30 days. */\nexport const OFFLINE_SNAPSHOT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;\n\nfunction browserOffline(): boolean {\n  const host = globalThis as { navigator?: { onLine?: boolean } };\n  return host.navigator?.onLine === false;\n}\n\nexport function createDurableThreadSnapshotCache({\n  mirror,\n  isOffline = browserOffline,\n  maxThreads = DEFAULT_MAX_THREADS,\n  maxAgeMs,\n  offlineMaxAgeMs = OFFLINE_SNAPSHOT_MAX_AGE_MS,\n  now = () => Date.now(),\n}: DurableThreadSnapshotCacheOptions): DurableThreadSnapshotCache {\n  let ownerId: string | null = null;\n  // Bumped on every owner change and wipe: a mirror read in flight then must not admit what it read.\n  let epoch = 0;\n  let primed: { ownerId: string; read: ReturnType<ThreadSnapshotMirror[\"load\"]> } | null = null;\n  let hydration: Promise<void> = Promise.resolve();\n  // Every resting snapshot readable offline (the mirror's, and this page's own), newest last.\n  const offline = new Map<string, { state: DeepAgentStreamValues; at: number }>();\n  const offlineSeeds = new Map<string, number>();\n  const restored = new Set<string>();\n  const listeners = new Set<() => void>();\n\n  const notify = (): void => {\n    for (const listener of listeners) {\n      try {\n        listener();\n      } catch {\n        // A host listener's fault never reaches the wire path.\n      }\n    }\n  };\n  const clearOfflineSeed = (threadId: string): void => {\n    if (offlineSeeds.delete(threadId)) notify();\n  };\n  const keepOffline = (threadId: string, entry: { state: DeepAgentStreamValues; at: number }): void => {\n    offline.delete(threadId);\n    offline.set(threadId, entry);\n    while (offline.size > maxThreads) {\n      const oldest = offline.keys().next().value;\n      if (oldest === undefined) break;\n      offline.delete(oldest);\n    }\n  };\n\n  const memory = createDeepAgentThreadSnapshotCache({\n    maxThreads,\n    maxAgeMs,\n    now,\n    onChange: (change) => {\n      const owner = ownerId;\n      if (owner === null) return;\n      switch (change.type) {\n        case \"remember\":\n          mirror.write({ ownerId: owner, threadId: change.threadId, state: change.state, at: change.at });\n          return;\n        case \"forget\":\n          mirror.remove({ ownerId: owner, threadId: change.threadId });\n          return;\n        case \"clear\":\n          return;\n      }\n    },\n  });\n\n  /** The thread's last resting transcript within the offline bound. */\n  const offlineEntry = (threadId: string): { state: DeepAgentStreamValues; at: number } | undefined => {\n    const entry = offline.get(threadId);\n    return entry && now() - entry.at <= offlineMaxAgeMs ? entry : undefined;\n  };\n\n  const dropEverything = (): void => {\n    memory.clear();\n    offline.clear();\n    restored.clear();\n    if (offlineSeeds.size > 0) {\n      offlineSeeds.clear();\n      notify();\n    }\n  };\n\n  return {\n    remember(threadId, state) {\n      memory.remember(threadId, state);\n      restored.delete(threadId);\n      // A mid-stream state keeps the resting transcript before it readable offline, as the mirror\n      // keeps that one's record. One too long to seal still reads from memory.\n      if (isRestingThreadSnapshot(state)) keepOffline(threadId, { state, at: now() });\n      // The wire delivered the thread: the transcript is current again.\n      clearOfflineSeed(threadId);\n    },\n    take(threadId) {\n      if (!isOffline()) return memory.take(threadId);\n      const entry = offlineEntry(threadId);\n      if (!entry) return undefined;\n      if (offlineSeeds.get(threadId) !== entry.at) {\n        offlineSeeds.set(threadId, entry.at);\n        notify();\n      }\n      return entry.state;\n    },\n    peek(threadId) {\n      return isOffline() ? offlineEntry(threadId) !== undefined : memory.peek(threadId);\n    },\n    forget(threadId) {\n      memory.forget(threadId);\n      offline.delete(threadId);\n      restored.delete(threadId);\n      clearOfflineSeed(threadId);\n    },\n    clear() {\n      dropEverything();\n    },\n    owner: () => ownerId,\n    setOwner(next) {\n      if (next === ownerId) return hydration;\n      const previous = ownerId;\n      ownerId = next;\n      epoch += 1;\n      dropEverything();\n      if (previous !== null) void mirror.clearOwner(previous);\n      if (next === null) {\n        hydration = Promise.resolve();\n        return hydration;\n      }\n      const readEpoch = epoch;\n      const read = primed?.ownerId === next ? primed.read : mirror.load(next);\n      primed = null;\n      hydration = read.then((entries) => {\n        // The owner moved on, or everything was wiped, while the read was in flight.\n        if (readEpoch !== epoch || ownerId !== next) return;\n        for (const entry of entries) {\n          if (!offline.has(entry.threadId)) keepOffline(entry.threadId, { state: entry.state, at: entry.at });\n          if (memory.peek(entry.threadId)) continue;\n          memory.restore(entry.threadId, entry.state, entry.at);\n          if (memory.peek(entry.threadId)) restored.add(entry.threadId);\n        }\n      });\n      return hydration;\n    },\n    prime(next) {\n      if (next === ownerId || primed?.ownerId === next) return;\n      primed = { ownerId: next, read: mirror.load(next) };\n    },\n    offlineSeedAt: (threadId) => offlineSeeds.get(threadId) ?? null,\n    subscribeOfflineSeeds(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    isRestored: (threadId) => restored.has(threadId),\n    whenHydrated: () => hydration,\n    async wipe() {\n      epoch += 1;\n      primed = null;\n      dropEverything();\n      await mirror.clearAll();\n    },\n  };\n}\n"],"names":["createDeepAgentThreadSnapshotCache","isRestingThreadSnapshot"],"mappings":"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"}

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

@@ -0,0 +1,60 @@
+import { type DeepAgentThreadSnapshotCache } from "./thread-snapshot-cache";
+import { type ThreadSnapshotMirror } from "./thread-snapshot-mirror";
+/**
+ * The thread snapshot cache with a durable, encrypted mirror behind it (`thread-snapshot-mirror.ts`):
+ * a reload seeds a recently visited thread from what it last showed, and a thread can be read while
+ * the transport cannot connect at all.
+ *
+ * - **Online, nothing changes.** `take` serves the in-memory entry within its age bound (one hour by
+ *   default), exactly as the plain cache does, and the attach snapshot replaces the seed.
+ * - **Offline** (`isOffline()`: the host's own word that Athena can't be reached), `take` serves the
+ *   thread's last resting transcript this page holds (what it read, or what the mirror kept), up to
+ *   `offlineMaxAgeMs` old and past the online bound, so a person can read their recent
+ *   conversations on a plane. Never a mid-stream state: a run the connection dropped is a partial
+ *   transcript, and the resting one before it is what shows. Every offline seed, however recent, is
+ *   recorded with its capture time (`offlineSeedAt`) so the host can say the transcript is "as of"
+ *   then; only the next state the wire delivers for the thread (its attach) clears it.
+ * - **Owned.** Entries belong to one owner (`setOwner`): a change drops every entry, deletes the
+ *   previous owner's mirrored records and reads the new owner's. A snapshot captured under one
+ *   account never seeds a mount under another. `wipe` drops everything (a sign-out).
+ */
+export interface DurableThreadSnapshotCache extends DeepAgentThreadSnapshotCache {
+    peek(threadId: string): boolean;
+    /** Bind the cache to the acting owner (`null`: nobody signed in; nothing is mirrored). */
+    setOwner(ownerId: string | null): Promise<void>;
+    /**
+     * Start reading an owner's mirrored snapshots before the owner is known for sure (a host's
+     * last-owner hint at boot): `setOwner` adopts the read if that owner is the one bound, and it
+     * is discarded otherwise. Binds nothing and deletes nothing.
+     */
+    prime(ownerId: string): void;
+    /** The owner the cache is bound to. */
+    owner(): string | null;
+    /**
+     * When the seed `take` last served for `threadId` was captured, if it was served while Athena
+     * could not be reached; `null` otherwise, and again once the wire delivers the thread.
+     */
+    offlineSeedAt(threadId: string): number | null;
+    /** Calls `listener` whenever an offline seed is served or cleared; returns what stops it. */
+    subscribeOfflineSeeds(listener: () => void): () => void;
+    /** Whether the entry `take` would serve for `threadId` came back from the mirror. */
+    isRestored(threadId: string): boolean;
+    /** Resolves once the current owner's mirrored snapshots have been read (tests, telemetry). */
+    whenHydrated(): Promise<void>;
+    /** Drop every entry, in memory and in the mirror (a sign-out, a workspace switch). */
+    wipe(): Promise<void>;
+}
+export interface DurableThreadSnapshotCacheOptions {
+    mirror: ThreadSnapshotMirror;
+    /** Whether Athena can't be reached right now (the host's reachability, or the browser's). */
+    isOffline?: () => boolean;
+    maxThreads?: number;
+    /** The online age bound (the plain cache's). */
+    maxAgeMs?: number;
+    /** How old a mirrored snapshot may be and still be read offline. */
+    offlineMaxAgeMs?: number;
+    now?: () => number;
+}
+/** What a device keeps for reading offline: the offline plan's 30 days. */
+export declare const OFFLINE_SNAPSHOT_MAX_AGE_MS: number;
+export declare function createDurableThreadSnapshotCache({ mirror, isOffline, maxThreads, maxAgeMs, offlineMaxAgeMs, now, }: DurableThreadSnapshotCacheOptions): DurableThreadSnapshotCache;

package/dist/agent-runtime/src/durable-thread-snapshot-cache.js

@@ -0,0 +1,158 @@
+import { createDeepAgentThreadSnapshotCache } from "./thread-snapshot-cache.js";
+import { isRestingThreadSnapshot } from "./thread-snapshot-mirror.js";
+const DEFAULT_MAX_THREADS = 30;
+const OFFLINE_SNAPSHOT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
+function browserOffline() {
+  var _a;
+  const host = globalThis;
+  return ((_a = host.navigator) == null ? void 0 : _a.onLine) === false;
+}
+function createDurableThreadSnapshotCache({
+  mirror,
+  isOffline = browserOffline,
+  maxThreads = DEFAULT_MAX_THREADS,
+  maxAgeMs,
+  offlineMaxAgeMs = OFFLINE_SNAPSHOT_MAX_AGE_MS,
+  now = () => Date.now()
+}) {
+  let ownerId = null;
+  let epoch = 0;
+  let primed = null;
+  let hydration = Promise.resolve();
+  const offline = /* @__PURE__ */ new Map();
+  const offlineSeeds = /* @__PURE__ */ new Map();
+  const restored = /* @__PURE__ */ new Set();
+  const listeners = /* @__PURE__ */ new Set();
+  const notify = () => {
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  };
+  const clearOfflineSeed = (threadId) => {
+    if (offlineSeeds.delete(threadId)) notify();
+  };
+  const keepOffline = (threadId, entry) => {
+    offline.delete(threadId);
+    offline.set(threadId, entry);
+    while (offline.size > maxThreads) {
+      const oldest = offline.keys().next().value;
+      if (oldest === void 0) break;
+      offline.delete(oldest);
+    }
+  };
+  const memory = createDeepAgentThreadSnapshotCache({
+    maxThreads,
+    maxAgeMs,
+    now,
+    onChange: (change) => {
+      const owner = ownerId;
+      if (owner === null) return;
+      switch (change.type) {
+        case "remember":
+          mirror.write({ ownerId: owner, threadId: change.threadId, state: change.state, at: change.at });
+          return;
+        case "forget":
+          mirror.remove({ ownerId: owner, threadId: change.threadId });
+          return;
+        case "clear":
+          return;
+      }
+    }
+  });
+  const offlineEntry = (threadId) => {
+    const entry = offline.get(threadId);
+    return entry && now() - entry.at <= offlineMaxAgeMs ? entry : void 0;
+  };
+  const dropEverything = () => {
+    memory.clear();
+    offline.clear();
+    restored.clear();
+    if (offlineSeeds.size > 0) {
+      offlineSeeds.clear();
+      notify();
+    }
+  };
+  return {
+    remember(threadId, state) {
+      memory.remember(threadId, state);
+      restored.delete(threadId);
+      if (isRestingThreadSnapshot(state)) keepOffline(threadId, { state, at: now() });
+      clearOfflineSeed(threadId);
+    },
+    take(threadId) {
+      if (!isOffline()) return memory.take(threadId);
+      const entry = offlineEntry(threadId);
+      if (!entry) return void 0;
+      if (offlineSeeds.get(threadId) !== entry.at) {
+        offlineSeeds.set(threadId, entry.at);
+        notify();
+      }
+      return entry.state;
+    },
+    peek(threadId) {
+      return isOffline() ? offlineEntry(threadId) !== void 0 : memory.peek(threadId);
+    },
+    forget(threadId) {
+      memory.forget(threadId);
+      offline.delete(threadId);
+      restored.delete(threadId);
+      clearOfflineSeed(threadId);
+    },
+    clear() {
+      dropEverything();
+    },
+    owner: () => ownerId,
+    setOwner(next) {
+      if (next === ownerId) return hydration;
+      const previous = ownerId;
+      ownerId = next;
+      epoch += 1;
+      dropEverything();
+      if (previous !== null) void mirror.clearOwner(previous);
+      if (next === null) {
+        hydration = Promise.resolve();
+        return hydration;
+      }
+      const readEpoch = epoch;
+      const read = (primed == null ? void 0 : primed.ownerId) === next ? primed.read : mirror.load(next);
+      primed = null;
+      hydration = read.then((entries) => {
+        if (readEpoch !== epoch || ownerId !== next) return;
+        for (const entry of entries) {
+          if (!offline.has(entry.threadId)) keepOffline(entry.threadId, { state: entry.state, at: entry.at });
+          if (memory.peek(entry.threadId)) continue;
+          memory.restore(entry.threadId, entry.state, entry.at);
+          if (memory.peek(entry.threadId)) restored.add(entry.threadId);
+        }
+      });
+      return hydration;
+    },
+    prime(next) {
+      if (next === ownerId || (primed == null ? void 0 : primed.ownerId) === next) return;
+      primed = { ownerId: next, read: mirror.load(next) };
+    },
+    offlineSeedAt: (threadId) => offlineSeeds.get(threadId) ?? null,
+    subscribeOfflineSeeds(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    isRestored: (threadId) => restored.has(threadId),
+    whenHydrated: () => hydration,
+    async wipe() {
+      epoch += 1;
+      primed = null;
+      dropEverything();
+      await mirror.clearAll();
+    }
+  };
+}
+export {
+  OFFLINE_SNAPSHOT_MAX_AGE_MS,
+  createDurableThreadSnapshotCache
+};
+//# sourceMappingURL=durable-thread-snapshot-cache.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"durable-thread-snapshot-cache.js","sources":["../../../../agent-runtime/src/durable-thread-snapshot-cache.ts"],"sourcesContent":["import {\n  createDeepAgentThreadSnapshotCache,\n  type DeepAgentThreadSnapshotCache,\n} from \"./thread-snapshot-cache\";\nimport { isRestingThreadSnapshot, type ThreadSnapshotMirror } from \"./thread-snapshot-mirror\";\nimport type { DeepAgentStreamValues } from \"./types\";\n\n/**\n * The thread snapshot cache with a durable, encrypted mirror behind it (`thread-snapshot-mirror.ts`):\n * a reload seeds a recently visited thread from what it last showed, and a thread can be read while\n * the transport cannot connect at all.\n *\n * - **Online, nothing changes.** `take` serves the in-memory entry within its age bound (one hour by\n *   default), exactly as the plain cache does, and the attach snapshot replaces the seed.\n * - **Offline** (`isOffline()`: the host's own word that Athena can't be reached), `take` serves the\n *   thread's last resting transcript this page holds (what it read, or what the mirror kept), up to\n *   `offlineMaxAgeMs` old and past the online bound, so a person can read their recent\n *   conversations on a plane. Never a mid-stream state: a run the connection dropped is a partial\n *   transcript, and the resting one before it is what shows. Every offline seed, however recent, is\n *   recorded with its capture time (`offlineSeedAt`) so the host can say the transcript is \"as of\"\n *   then; only the next state the wire delivers for the thread (its attach) clears it.\n * - **Owned.** Entries belong to one owner (`setOwner`): a change drops every entry, deletes the\n *   previous owner's mirrored records and reads the new owner's. A snapshot captured under one\n *   account never seeds a mount under another. `wipe` drops everything (a sign-out).\n */\nexport interface DurableThreadSnapshotCache extends DeepAgentThreadSnapshotCache {\n  peek(threadId: string): boolean;\n  /** Bind the cache to the acting owner (`null`: nobody signed in; nothing is mirrored). */\n  setOwner(ownerId: string | null): Promise<void>;\n  /**\n   * Start reading an owner's mirrored snapshots before the owner is known for sure (a host's\n   * last-owner hint at boot): `setOwner` adopts the read if that owner is the one bound, and it\n   * is discarded otherwise. Binds nothing and deletes nothing.\n   */\n  prime(ownerId: string): void;\n  /** The owner the cache is bound to. */\n  owner(): string | null;\n  /**\n   * When the seed `take` last served for `threadId` was captured, if it was served while Athena\n   * could not be reached; `null` otherwise, and again once the wire delivers the thread.\n   */\n  offlineSeedAt(threadId: string): number | null;\n  /** Calls `listener` whenever an offline seed is served or cleared; returns what stops it. */\n  subscribeOfflineSeeds(listener: () => void): () => void;\n  /** Whether the entry `take` would serve for `threadId` came back from the mirror. */\n  isRestored(threadId: string): boolean;\n  /** Resolves once the current owner's mirrored snapshots have been read (tests, telemetry). */\n  whenHydrated(): Promise<void>;\n  /** Drop every entry, in memory and in the mirror (a sign-out, a workspace switch). */\n  wipe(): Promise<void>;\n}\n\nexport interface DurableThreadSnapshotCacheOptions {\n  mirror: ThreadSnapshotMirror;\n  /** Whether Athena can't be reached right now (the host's reachability, or the browser's). */\n  isOffline?: () => boolean;\n  maxThreads?: number;\n  /** The online age bound (the plain cache's). */\n  maxAgeMs?: number;\n  /** How old a mirrored snapshot may be and still be read offline. */\n  offlineMaxAgeMs?: number;\n  now?: () => number;\n}\n\nconst DEFAULT_MAX_THREADS = 30;\n/** What a device keeps for reading offline: the offline plan's 30 days. */\nexport const OFFLINE_SNAPSHOT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;\n\nfunction browserOffline(): boolean {\n  const host = globalThis as { navigator?: { onLine?: boolean } };\n  return host.navigator?.onLine === false;\n}\n\nexport function createDurableThreadSnapshotCache({\n  mirror,\n  isOffline = browserOffline,\n  maxThreads = DEFAULT_MAX_THREADS,\n  maxAgeMs,\n  offlineMaxAgeMs = OFFLINE_SNAPSHOT_MAX_AGE_MS,\n  now = () => Date.now(),\n}: DurableThreadSnapshotCacheOptions): DurableThreadSnapshotCache {\n  let ownerId: string | null = null;\n  // Bumped on every owner change and wipe: a mirror read in flight then must not admit what it read.\n  let epoch = 0;\n  let primed: { ownerId: string; read: ReturnType<ThreadSnapshotMirror[\"load\"]> } | null = null;\n  let hydration: Promise<void> = Promise.resolve();\n  // Every resting snapshot readable offline (the mirror's, and this page's own), newest last.\n  const offline = new Map<string, { state: DeepAgentStreamValues; at: number }>();\n  const offlineSeeds = new Map<string, number>();\n  const restored = new Set<string>();\n  const listeners = new Set<() => void>();\n\n  const notify = (): void => {\n    for (const listener of listeners) {\n      try {\n        listener();\n      } catch {\n        // A host listener's fault never reaches the wire path.\n      }\n    }\n  };\n  const clearOfflineSeed = (threadId: string): void => {\n    if (offlineSeeds.delete(threadId)) notify();\n  };\n  const keepOffline = (threadId: string, entry: { state: DeepAgentStreamValues; at: number }): void => {\n    offline.delete(threadId);\n    offline.set(threadId, entry);\n    while (offline.size > maxThreads) {\n      const oldest = offline.keys().next().value;\n      if (oldest === undefined) break;\n      offline.delete(oldest);\n    }\n  };\n\n  const memory = createDeepAgentThreadSnapshotCache({\n    maxThreads,\n    maxAgeMs,\n    now,\n    onChange: (change) => {\n      const owner = ownerId;\n      if (owner === null) return;\n      switch (change.type) {\n        case \"remember\":\n          mirror.write({ ownerId: owner, threadId: change.threadId, state: change.state, at: change.at });\n          return;\n        case \"forget\":\n          mirror.remove({ ownerId: owner, threadId: change.threadId });\n          return;\n        case \"clear\":\n          return;\n      }\n    },\n  });\n\n  /** The thread's last resting transcript within the offline bound. */\n  const offlineEntry = (threadId: string): { state: DeepAgentStreamValues; at: number } | undefined => {\n    const entry = offline.get(threadId);\n    return entry && now() - entry.at <= offlineMaxAgeMs ? entry : undefined;\n  };\n\n  const dropEverything = (): void => {\n    memory.clear();\n    offline.clear();\n    restored.clear();\n    if (offlineSeeds.size > 0) {\n      offlineSeeds.clear();\n      notify();\n    }\n  };\n\n  return {\n    remember(threadId, state) {\n      memory.remember(threadId, state);\n      restored.delete(threadId);\n      // A mid-stream state keeps the resting transcript before it readable offline, as the mirror\n      // keeps that one's record. One too long to seal still reads from memory.\n      if (isRestingThreadSnapshot(state)) keepOffline(threadId, { state, at: now() });\n      // The wire delivered the thread: the transcript is current again.\n      clearOfflineSeed(threadId);\n    },\n    take(threadId) {\n      if (!isOffline()) return memory.take(threadId);\n      const entry = offlineEntry(threadId);\n      if (!entry) return undefined;\n      if (offlineSeeds.get(threadId) !== entry.at) {\n        offlineSeeds.set(threadId, entry.at);\n        notify();\n      }\n      return entry.state;\n    },\n    peek(threadId) {\n      return isOffline() ? offlineEntry(threadId) !== undefined : memory.peek(threadId);\n    },\n    forget(threadId) {\n      memory.forget(threadId);\n      offline.delete(threadId);\n      restored.delete(threadId);\n      clearOfflineSeed(threadId);\n    },\n    clear() {\n      dropEverything();\n    },\n    owner: () => ownerId,\n    setOwner(next) {\n      if (next === ownerId) return hydration;\n      const previous = ownerId;\n      ownerId = next;\n      epoch += 1;\n      dropEverything();\n      if (previous !== null) void mirror.clearOwner(previous);\n      if (next === null) {\n        hydration = Promise.resolve();\n        return hydration;\n      }\n      const readEpoch = epoch;\n      const read = primed?.ownerId === next ? primed.read : mirror.load(next);\n      primed = null;\n      hydration = read.then((entries) => {\n        // The owner moved on, or everything was wiped, while the read was in flight.\n        if (readEpoch !== epoch || ownerId !== next) return;\n        for (const entry of entries) {\n          if (!offline.has(entry.threadId)) keepOffline(entry.threadId, { state: entry.state, at: entry.at });\n          if (memory.peek(entry.threadId)) continue;\n          memory.restore(entry.threadId, entry.state, entry.at);\n          if (memory.peek(entry.threadId)) restored.add(entry.threadId);\n        }\n      });\n      return hydration;\n    },\n    prime(next) {\n      if (next === ownerId || primed?.ownerId === next) return;\n      primed = { ownerId: next, read: mirror.load(next) };\n    },\n    offlineSeedAt: (threadId) => offlineSeeds.get(threadId) ?? null,\n    subscribeOfflineSeeds(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    isRestored: (threadId) => restored.has(threadId),\n    whenHydrated: () => hydration,\n    async wipe() {\n      epoch += 1;\n      primed = null;\n      dropEverything();\n      await mirror.clearAll();\n    },\n  };\n}\n"],"names":[],"mappings":"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"}