@athenaintel/react 0.57.2 → 0.59.0

package/dist/agent-runtime/src/deep-agent-transport-recipe.d.ts

@@ -2,6 +2,7 @@ import type { ResourceElement } from "@assistant-ui/tap";
 import type { Statewire, StatewireClient } from "statewire";
 import { type DeepAgentInterestDeclaration, type DeepAgentMessageWindowDeclaration } from "./message-window";
 import { type AttachRetryGate, type DeepAgentAttachTimingEvent, type DeepAgentWakeRefusal } from "./statewire-attach-observer";
+import { type StatewireTransportOptions } from "./statewire-transport";
 /** Auth-header resolver for the transport; `staleAuth` is true right after an
  * auth rejection, so resolvers that can force-renew should honor it. */
 export type DeepAgentHeadersResolver = (ctx: {
@@ -55,6 +56,12 @@ export interface DeepAgentAttachTransportOptions {
      * default version is declared.
      */
     laneHistory?: boolean | undefined;
+    /**
+     * Runs in the sharer about to stamp, before stamping (`StatewireClient.OnFlush`): the chat
+     * outbox's flush policy holds a hidden tab's reloaded message sends
+     * (`createChatOutboxFlushPolicy`).
+     */
+    onFlush?: StatewireTransportOptions["onFlush"] | undefined;
 }
 /**
  * The ONE recipe for a deep-agent thread transport — shared by the mounted
@@ -70,7 +77,7 @@ export interface DeepAgentAttachTransportOptions {
  * attach paths resolve headers before they dial, so this is the seam where a
  * hint can hold the next dial without touching the library's backoff.
  */
-export declare function createDeepAgentAttachTransport<TState = unknown>({ baseUrl, threadId, headers, sse, isNew, sessionStore, onAuthResolve, onAttachTiming, retryGate, messageWindow, declaredInterests, laneHistory, }: DeepAgentAttachTransportOptions): ResourceElement<Statewire<TState | undefined>>;
+export declare function createDeepAgentAttachTransport<TState = unknown>({ baseUrl, threadId, headers, sse, isNew, sessionStore, onAuthResolve, onAttachTiming, retryGate, messageWindow, declaredInterests, laneHistory, onFlush, }: DeepAgentAttachTransportOptions): ResourceElement<Statewire<TState | undefined>>;
 /** What `POST …/prewarm` answered. */
 export interface DeepAgentWakeResult {
     status: number;

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

@@ -21,7 +21,8 @@ function createDeepAgentAttachTransport({
   retryGate = attachRetryGate,
   messageWindow,
   declaredInterests,
-  laneHistory = false
+  laneHistory = false,
+  onFlush
 }) {
   const url = deepAgentThreadUrl({ baseUrl, threadId });
   const useSse = resolveStatewireTransportKind({ sse }) === "sse";
@@ -48,6 +49,7 @@ function createDeepAgentAttachTransport({
       );
     },
     ...sessionStore && { sessionStore },
+    ...onFlush && { onFlush },
     // Structural types: this package compiles without the DOM lib, while
     // statewire's option types name the browser `WebSocket`/`fetch`.
     ...instrumentation.webSocket && {

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 DeepAgentInterestDeclaration,\n  type DeepAgentMessageWindowDeclaration,\n  withDeclaredInterests,\n  withDeclaredMessageWindow,\n} from \"./message-window\";\nimport { withDeclaredPagedHistory } from \"./history-store\";\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 view this thread's attach holds, read at every attach's header\n   * resolve (`x-athena-deep-agent-interests`, see `message-window.ts`): a\n   * re-attach's hello then carries the pages it had loaded on whichever host\n   * instance it lands on. `null` (a first attach) declares nothing. Not part\n   * of a pooled dial, which never held a view.\n   */\n  declaredInterests?: (() => DeepAgentInterestDeclaration | null) | 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  declaredInterests,\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 withDeclaredInterests(\n        withDeclaredPagedHistory(\n          withDeclaredMessageWindow(\n            withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),\n            messageWindow,\n          ),\n        ),\n        declaredInterests?.() ?? null,\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":";;;;;AA+BO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AACF,GAGW;AACT,SAAO,GAAG,QAAQ,QAAQ,QAAQ,EAAE,CAAC,IAAI,mBAAmB,QAAQ,CAAC;AACvE;AA2DO,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;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;AAAA,UACE;AAAA,YACE,4BAA4B,MAAM,QAAQ,GAAG,GAAG,EAAE,aAAa;AAAA,YAC/D;AAAA,UAAA;AAAA,QACF;AAAA,SAEF,6DAAyB;AAAA,MAAA;AAAA,IAE7B;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 DeepAgentInterestDeclaration,\n  type DeepAgentMessageWindowDeclaration,\n  withDeclaredInterests,\n  withDeclaredMessageWindow,\n} from \"./message-window\";\nimport { withDeclaredPagedHistory } from \"./history-store\";\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 view this thread's attach holds, read at every attach's header\n   * resolve (`x-athena-deep-agent-interests`, see `message-window.ts`): a\n   * re-attach's hello then carries the pages it had loaded on whichever host\n   * instance it lands on. `null` (a first attach) declares nothing. Not part\n   * of a pooled dial, which never held a view.\n   */\n  declaredInterests?: (() => DeepAgentInterestDeclaration | null) | 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   * Runs in the sharer about to stamp, before stamping (`StatewireClient.OnFlush`): the chat\n   * outbox's flush policy holds a hidden tab's reloaded message sends\n   * (`createChatOutboxFlushPolicy`).\n   */\n  onFlush?: StatewireTransportOptions[\"onFlush\"] | 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  declaredInterests,\n  laneHistory = false,\n  onFlush,\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 withDeclaredInterests(\n        withDeclaredPagedHistory(\n          withDeclaredMessageWindow(\n            withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),\n            messageWindow,\n          ),\n        ),\n        declaredInterests?.() ?? null,\n      );\n    },\n    ...(sessionStore && { sessionStore }),\n    ...(onFlush && { onFlush }),\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":";;;;;AA+BO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AACF,GAGW;AACT,SAAO,GAAG,QAAQ,QAAQ,QAAQ,EAAE,CAAC,IAAI,mBAAmB,QAAQ,CAAC;AACvE;AAiEO,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;AAAA,EACA,cAAc;AAAA,EACd;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;AAAA,UACE;AAAA,YACE,4BAA4B,MAAM,QAAQ,GAAG,GAAG,EAAE,aAAa;AAAA,YAC/D;AAAA,UAAA;AAAA,QACF;AAAA,SAEF,6DAAyB;AAAA,MAAA;AAAA,IAE7B;AAAA,IACA,GAAI,gBAAgB,EAAE,aAAA;AAAA,IACtB,GAAI,WAAW,EAAE,QAAA;AAAA;AAAA;AAAA,IAGjB,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/dictation-preferences.d.ts

@@ -0,0 +1,356 @@
+import { z } from 'zod';
+import type { DictationListenOptions } from './dictation-session';
+/**
+ * A person's dictation preferences, one record per person in Athena's cloud (agora's
+ * `GET` / `PUT /api/dictation-preferences`, with a `revision`), shared by every Athena app that
+ * dictates: the desktop app's Settings ▸ Dictation and the web app's Settings ▸ Dictation edit the
+ * same settings, the same dictionary, the same replacements and the same snippets.
+ *
+ * This module is what those apps share: the record's schema, the settings by the name each has in
+ * the record, the defaults, the limits, the languages, the keyterm budget, the three-way merge
+ * that settles two apps saving at once, and the body of a whole-record `PUT` that keeps what the
+ * writing app does not know or cannot show (another app's settings and shortcuts, a replacement's
+ * and a snippet's id, and every list entry past what the app shows unless the app removed it): a
+ * whole-record write never deletes what the app never showed.
+ *
+ * Snippets never reach Deepgram: an app expands them on the final transcript itself
+ * (`dictation-snippets.ts`), and their triggers are not keyterms.
+ *
+ * The microphone and the sounds belong to a device and are never in the record. Nothing here waits
+ * on the network on a dictation's path: an app dictates with the copy it holds (or the defaults).
+ */
+/**
+ * The languages dictation offers, as Deepgram's Nova-3 tags (its models-and-languages list; agora
+ * checks each tag's shape): English first, then `multi`, Nova-3's own auto-detect, which follows the
+ * speaker across English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian and
+ * Dutch, even mid-sentence, and keeps the dictionary; then the rest by name.
+ */
+export declare const DICTATION_LANGUAGE_CODES: readonly ['en', 'multi', 'af', 'ar', 'hy', 'be', 'bn', 'bs', 'bg', 'ca', 'zh', 'zh-TW', 'zh-HK', 'hr', 'cs', 'da', 'nl', 'nl-BE', 'en-AU', 'en-CA', 'en-IN', 'en-NZ', 'en-GB', 'et', 'fi', 'fr', 'fr-CA', 'gl', 'ka', 'de', 'de-CH', 'el', 'gu', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'kn', 'kk', 'ko', 'lv', 'lt', 'mk', 'ms', 'mr', 'mn', 'ne', 'no', 'ps', 'fa', 'pl', 'pt', 'pt-BR', 'pt-PT', 'pa', 'ro', 'ru', 'sr', 'sk', 'sl', 'es', 'es-419', 'sv', 'tl', 'ta', 'te', 'th', 'tr', 'uk', 'ur', 'vi', 'xh', 'zu'];
+export type DictationLanguage = (typeof DICTATION_LANGUAGE_CODES)[number];
+/** Auto-detect: Nova-3's multilingual model, for whoever switches languages as they speak. */
+export declare const DICTATION_AUTO_DETECT_LANGUAGE = "multi";
+/** What Settings says under the language while Auto-detect is chosen. */
+export declare const DICTATION_AUTO_DETECT_NOTE = "Follows you across English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian and Dutch, even when you switch mid-sentence.";
+export declare const DICTATION_LANGUAGE_LABELS: Readonly<Record<DictationLanguage, string>>;
+export declare function isDictationLanguage(value: unknown): value is DictationLanguage;
+/**
+ * What an app lets a person keep and sends with each dictation: Deepgram's own limits, which agora's
+ * relay enforces (`dictation_stream.py`). The record can hold more (written by another app, or
+ * through the API); an app keeps that overflow on every write without showing it.
+ */
+export declare const MAX_DICTIONARY_TERMS = 100;
+export declare const MAX_REPLACEMENTS = 200;
+/** A term, a find and a replacement are each at most this long (agora counts code points). */
+export declare const MAX_TERM_CHARS = 100;
+/** agora's own bounds on the record (`DictationPreferencesWrite`). */
+export declare const CLOUD_MAX_DICTIONARY_TERMS = 2000;
+export declare const CLOUD_MAX_REPLACEMENTS = 1000;
+export declare const CLOUD_MAX_FIND_CHARS = 200;
+export declare const CLOUD_MAX_REPLACE_CHARS = 1000;
+export declare const CLOUD_MAX_SETTINGS_BYTES: number;
+export declare const CLOUD_MAX_SNIPPETS = 500;
+/**
+ * A snippet's trigger and text are each at most this long, agora's own bounds (`DictationSnippet`,
+ * which counts code points, as `codePointLength` does).
+ */
+export declare const MAX_SNIPPET_TRIGGER_CHARS = 200;
+export declare const MAX_SNIPPET_TEXT_CHARS = 10000;
+/**
+ * The snippets an app shows and expands: half of what agora keeps, so the record always has room
+ * for what another app adds while this one is full (`cloudBodyOf` keeps it there, never cutting
+ * another app's entry to make room for this one's).
+ */
+export declare const MAX_SNIPPETS = 250;
+/**
+ * Deepgram takes keyterms worth at most 500 tokens per stream (its keyterm limits; a longer list is
+ * refused, and the dictation with it). An app sends no more than this by its estimate, which can't
+ * come in under Deepgram's count.
+ */
+export declare const KEYTERM_TOKEN_BUDGET = 450;
+/**
+ * A term's Deepgram tokens, estimated so it can't come in under them: a byte-level tokenizer splits
+ * no finer than a byte, so every UTF-8 byte that is not an ASCII letter or digit (a space, a mark,
+ * every byte of an accented letter, a kana, a kanji, an emoji) counts as one; a run of ASCII
+ * letters or digits counts one per two characters; and the term itself one more.
+ */
+export declare function keytermTokens({ term }: {
+    term: string;
+}): number;
+/**
+ * The dictionary's terms that fit Deepgram's keyterm budget: the newest first (the dictionary
+ * appends, so a word just added always counts), sent in the dictionary's own order. Settings ▸
+ * Dictation shows the ones left out as "Not sent".
+ */
+export declare function keytermsWithinBudget({ terms }: {
+    terms: readonly string[];
+}): string[];
+/** The settings every Athena app shares, by the name each has in agora's record. */
+export declare const SHARED_SETTING_KEYS: {
+    readonly language: 'language';
+    readonly smartFormat: 'smart_format';
+    readonly punctuate: 'punctuate';
+    readonly fillerWords: 'filler_words';
+    readonly dictation: 'spoken_punctuation';
+    readonly voiceLock: 'voice_lock';
+    readonly numerals: 'numerals';
+    readonly profanityFilter: 'profanity_filter';
+};
+export type SharedSettingKey = keyof typeof SHARED_SETTING_KEYS;
+export interface SharedDictationSettings {
+    language: DictationLanguage;
+    smartFormat: boolean;
+    punctuate: boolean;
+    fillerWords: boolean;
+    /** Spoken punctuation: say "period" for a period (Deepgram's `dictation`). */
+    dictation: boolean;
+    /** Only the first speaker heard is kept (Deepgram's speaker labels, `diarize`). */
+    voiceLock: boolean;
+    numerals: boolean;
+    profanityFilter: boolean;
+}
+/** Hades' defaults, which the desktop app keeps too. */
+export declare const DEFAULT_SHARED_SETTINGS: Readonly<SharedDictationSettings>;
+export type DictationToggleKey = Exclude<SharedSettingKey, 'language'>;
+/** The recognition switches, as both Settings pages list them. */
+export declare const DICTATION_RECOGNITION_TOGGLES: ReadonlyArray<{
+    key: DictationToggleKey;
+    label: string;
+    description: string;
+}>;
+/** A dictionary term as an app keeps it: trimmed, never empty, within Deepgram's length. */
+export declare const DictationTermSchema: z.ZodString;
+/** A find-and-replace Deepgram applies to the transcript; an empty `replace` removes what it finds. */
+export declare const DictationReplacementSchema: z.ZodObject<{
+    find: z.ZodString;
+    replace: z.ZodString;
+}, z.core.$strip>;
+export type DictationReplacement = z.infer<typeof DictationReplacementSchema>;
+/** A string's length as agora counts it: in code points (an emoji is one, not two). */
+export declare function codePointLength(value: string): number;
+/**
+ * Saying `trigger` inserts `text` (Wispr Flow's snippets): the trigger trimmed, holding a letter or
+ * a digit (a trigger of punctuation alone would match none of what is said), the text as typed but
+ * never blank; each within agora's bounds, with no NUL character, which agora refuses.
+ */
+export declare const DictationSnippetSchema: z.ZodObject<{
+    trigger: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type DictationSnippet = z.infer<typeof DictationSnippetSchema>;
+/**
+ * The words a trigger is said as: split at spaces, each without the punctuation typed at its end
+ * ("my email?" is said as "my email"). Expansion matches these (`dictation-snippets.ts`).
+ */
+export declare function triggerWordsOf(trigger: string): string[];
+/**
+ * A snippet's identity in every list and merge: its trigger as it is said, in lower case. Two
+ * triggers said alike ("my email", "My  email?") are one snippet, as expansion could only ever
+ * pick one of them.
+ */
+export declare const snippetKey: (entry: {
+    trigger: string;
+}) => string;
+/** What syncs: the shared settings, the dictionary, the replacements and the snippets. */
+export interface SharedPreferences {
+    settings: SharedDictationSettings;
+    dictionary: string[];
+    replacements: DictationReplacement[];
+    snippets: DictationSnippet[];
+    /**
+     * The dictionary's words Athena learned from the person's own corrections after a paste (owner
+     * decision 2026-11-06, as Wispr Flow does), always some of `dictionary`, in the order learned:
+     * every app marks them as learned, never as typed. A word the person types in themselves is
+     * theirs, and loses the mark.
+     */
+    learned: string[];
+}
+export declare const DEFAULT_SHARED_PREFERENCES: Readonly<SharedPreferences>;
+/**
+ * agora's record as it answers it (`DictationPreferencesOut`). Every list and map is required: a
+ * whole-record write is built from it, so one that can't be read is never written back.
+ */
+export declare const CloudDictationPreferencesSchema: z.ZodObject<{
+    revision: z.ZodNumber;
+    settings: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    dictionary: z.ZodArray<z.ZodString>;
+    replacements: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    snippets: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    shortcuts: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    learned_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type CloudDictationPreferences = z.infer<typeof CloudDictationPreferencesSchema>;
+/** What agora answers for a person who never saved: revision 0, everything empty. */
+export declare const EMPTY_CLOUD_DICTATION_PREFERENCES: Readonly<CloudDictationPreferences>;
+/** The body of `PUT /api/dictation-preferences`: the whole new state on the revision read. */
+export interface DictationPreferencesWriteBody {
+    revision: number;
+    settings: Record<string, unknown>;
+    dictionary: string[];
+    replacements: Array<Record<string, unknown>>;
+    snippets: Array<Record<string, unknown>>;
+    shortcuts: Record<string, unknown>;
+    /** The learned words of `dictionary`; agora keeps only those the dictionary holds. */
+    learned_terms: string[];
+}
+/** `learned` as some of `dictionary`: each once, only words it holds, in the order learned. */
+export declare function learnedWithin({ learned, dictionary, }: {
+    learned: readonly unknown[];
+    dictionary: readonly string[];
+}): string[];
+/** The terms that are still terms, trimmed, each once, up to Deepgram's limit. */
+export declare function normalizeDictionary({ terms }: {
+    terms: readonly unknown[];
+}): string[];
+/** The replacements that are still replacements (a find trimmed), up to Deepgram's limit. */
+export declare function normalizeReplacements({ replacements, }: {
+    replacements: readonly unknown[];
+}): DictationReplacement[];
+/**
+ * The snippets that are still snippets (a trigger trimmed), each trigger once in any case (the
+ * first kept), up to what an app shows. Only the trigger and the text: an id stays in the record
+ * (`cloudBodyOf`).
+ */
+export declare function normalizeSnippets({ snippets, }: {
+    snippets: readonly unknown[];
+}): DictationSnippet[];
+/** The cloud's record as an app reads it: each setting it cannot read is `fallback`'s. */
+export declare function sharedFromCloud({ cloud, fallback, }: {
+    cloud: CloudDictationPreferences;
+    fallback?: Readonly<SharedPreferences>;
+}): SharedPreferences;
+/** What an app removed since `base`: never sent back, whatever the cloud still holds. */
+export interface RemovedHere {
+    terms: ReadonlySet<string>;
+    /** Replacements, by their find in lower case. */
+    keys: ReadonlySet<string>;
+    /** Snippets, by their trigger in lower case (`snippetKey`). */
+    snippets: ReadonlySet<string>;
+}
+/** Nothing removed. */
+export declare const NOTHING_REMOVED: RemovedHere;
+export declare function removedSince({ base, local, }: {
+    base: SharedPreferences;
+    local: SharedPreferences;
+}): RemovedHere;
+/**
+ * The body of a PUT: `shared` over what the cloud keeps that the app does not know or cannot show.
+ * Every entry of the cloud's lists the app cannot hold (past its 100 terms, 200 replacements and
+ * 250 snippets, or an entry longer than it takes) stays as it is, unless the app removed it: a
+ * whole-record write never deletes what the app never showed. Another app's settings and the
+ * shortcuts go back as they were, and a replacement and a snippet keep the id the cloud gave them.
+ */
+export declare function cloudBodyOf({ shared, cloud, removed, }: {
+    shared: SharedPreferences;
+    cloud: CloudDictationPreferences;
+    removed: RemovedHere;
+}): DictationPreferencesWriteBody;
+export declare function same(a: unknown, b: unknown): boolean;
+/**
+ * Both sides changed since `base`: each setting takes the side that changed it (`local`'s when
+ * both did), and each list is `remote`'s with `local`'s additions and removals applied (a
+ * replacement `local` changed takes `local`'s text). At a list's limit, `local`'s additions keep
+ * their place and `remote`'s last entries are the ones past it.
+ */
+export declare function mergeShared({ base, local, remote, }: {
+    base: SharedPreferences;
+    local: SharedPreferences;
+    remote: SharedPreferences;
+}): SharedPreferences;
+/** A dictionary with `term` added: trimmed, once, within Deepgram's limits; null when it cannot be. */
+export declare function withTerm({ dictionary, term, }: {
+    dictionary: readonly string[];
+    term: string;
+}): string[] | null;
+/**
+ * The dictionary once the person typed `term` in: a new word added (as `withTerm`), or one Athena
+ * had learned kept and made theirs (no longer marked learned); null when nothing changes.
+ */
+export declare function withTypedTerm({ dictionary, learned, term, }: {
+    dictionary: readonly string[];
+    learned: readonly string[];
+    term: string;
+}): {
+    dictionary: string[];
+    learned: string[];
+} | null;
+/**
+ * `shared` with the words a correction taught (`terms`, already checked by the learner) added and
+ * marked learned, at the end so Deepgram's budget keeps them first. At the dictionary's limit the
+ * oldest learned word makes room, never one the person typed; a word already there stays as it is.
+ */
+export declare function learnTerms({ shared, terms, }: {
+    shared: SharedPreferences;
+    terms: readonly string[];
+}): SharedPreferences;
+/** Replacements with one more (its find trimmed); null when it cannot be added. */
+export declare function withReplacement({ replacements, replacement, }: {
+    replacements: readonly DictationReplacement[];
+    replacement: DictationReplacement;
+}): DictationReplacement[] | null;
+/** Snippets with one more (its trigger trimmed), at the end; null when it cannot be added. */
+export declare function withSnippet({ snippets, snippet, }: {
+    snippets: readonly DictationSnippet[];
+    snippet: DictationSnippet;
+}): DictationSnippet[] | null;
+/**
+ * Snippets with the one whose trigger is `trigger` changed to `snippet`, in its place; null when
+ * that one is gone or the change cannot be kept (a trigger another snippet has, or one too long).
+ */
+export declare function withSnippetChanged({ snippets, trigger, snippet, }: {
+    snippets: readonly DictationSnippet[];
+    trigger: string;
+    snippet: DictationSnippet;
+}): DictationSnippet[] | null;
+/**
+ * The Deepgram listen parameters a person's settings ask for, one value each, every one inside
+ * agora's relay allowlist: the language, the switches as `true`/`false`, spoken punctuation as
+ * `dictation` and voice lock as `diarize` (its substrate: speaker labels).
+ */
+export declare function dictationListenParams({ settings, }: {
+    settings: SharedDictationSettings;
+}): Record<string, string>;
+/**
+ * What a dictation sends Deepgram of the person's lists: the dictionary as keyterms within
+ * Deepgram's budget (the newest kept) and the replacements, normalized again so a value the relay
+ * would refuse the stream for can never reach it, whatever wrote it.
+ */
+export declare function dictationVocabulary({ preferences }: {
+    preferences: SharedPreferences;
+}): {
+    keyterms: string[];
+    replacements: DictationReplacement[];
+};
+/**
+ * Everything a dictation's stream asks Deepgram for of the person's preferences, as the options of
+ * `DeepgramDictationSession` (`@athenaintel/agent-runtime/dictation`): the listen parameters, the
+ * keyterms, the replacements, and voice lock.
+ */
+export declare function dictationStreamOptions({ preferences, }: {
+    preferences: SharedPreferences;
+}): Required<DictationListenOptions>;
+/** A stale write (another app saved first) is read, merged and sent again at most this many times. */
+export declare const MAX_STALE_RETRIES = 3;
+/** One `PUT` of the record: what agora saved, or that another app saved first (409). */
+export type DictationPreferencesWriteAnswer = {
+    kind: 'saved';
+    cloud: CloudDictationPreferences;
+} | {
+    kind: 'stale';
+};
+/** Every attempt met a newer record: the save gives up, and the person's change is not saved. */
+export declare class DictationPreferencesConflictError extends Error {
+    constructor();
+}
+/**
+ * Saves `local`, the person's copy edited from `cloud` (the record as they read it), on `cloud`'s
+ * revision. When another app saved first (`stale`), the record is read again and the person's
+ * changes are merged three ways against the copy they started from, then sent again, at most
+ * `MAX_STALE_RETRIES` times. Nothing is written when the record already holds every change. Returns
+ * the record as agora now holds it; a network failure from `read` or `write` is thrown as is.
+ */
+export declare function saveSharedPreferences({ cloud, local, read, write, }: {
+    cloud: CloudDictationPreferences;
+    local: SharedPreferences;
+    read: () => Promise<CloudDictationPreferences>;
+    write: (body: DictationPreferencesWriteBody) => Promise<DictationPreferencesWriteAnswer>;
+}): Promise<CloudDictationPreferences>;