@athenaintel/react 0.20.0 → 0.21.0

package/dist/packages/agent-runtime/src/statewire-transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"statewire-transport.js","sources":["../../../../../agent-runtime/src/statewire-transport.ts"],"sourcesContent":["import { type Statewire, type StatewireClient, StatewireHttp, StatewireWebsocket } from 'statewire';\nimport type { DeepAgentStreamValues } from './types';\n\nexport type StatewireTransportOptions = StatewireClient.HttpOptions &\n  StatewireClient.WebsocketOptions;\n\n/**\n * Build the deep-agent statewire transport: WebSocket by default, SSE when the\n * host app's toggle asks for it. The toggle source is host-specific (env var,\n * extension flag, config store), so the caller resolves it to a boolean.\n *\n * `TState` defaults to the deep-agent wire shape: the thread mounts that make\n * up nearly every caller get a typed state without naming it, and the other\n * mounts (the conversation index) name theirs.\n */\nexport const statewireTransport = <\n  TState = DeepAgentStreamValues,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n>(\n  options: StatewireTransportOptions,\n  { sse = false }: { sse?: boolean } = {}\n) =>\n  sse\n    ? StatewireHttp<TState, TCommands>({ protocol: 'athena', ...options })\n    : StatewireWebsocket<TState, TCommands>({ protocol: 'athena', ...options });\n"],"names":[],"mappings":";AAeO,MAAM,qBAAqB,CAIhC,SACA,EAAE,MAAM,UAA6B,CAAA,MAErC,MACI,cAAiC,EAAE,UAAU,UAAU,GAAG,QAAA,CAAS,IACnE,mBAAsC,EAAE,UAAU,UAAU,GAAG,QAAA,CAAS;"}
+{"version":3,"file":"statewire-transport.js","sources":["../../../../../agent-runtime/src/statewire-transport.ts"],"sourcesContent":["import { type Statewire, type StatewireClient, StatewireHttp, StatewireWebsocket } from 'statewire';\nimport type { DeepAgentStreamValues } from './types';\n\nexport type StatewireTransportOptions = StatewireClient.HttpOptions &\n  StatewireClient.WebsocketOptions;\n\n/**\n * The application protocol the deep-agent transport stamps on every command.\n * The thread client must declare the same protocol: statewire's core applies\n * its optimistic folds only to commands of its own protocol, so a mismatch\n * leaves a send invisible until the server's frame lands.\n */\nexport const DEEP_AGENT_STATEWIRE_PROTOCOL = 'athena';\n\n/**\n * Build the deep-agent statewire transport: WebSocket by default, SSE when the\n * host app's toggle asks for it. The toggle source is host-specific (env var,\n * extension flag, config store), so the caller resolves it to a boolean.\n *\n * `TState` defaults to the deep-agent wire shape: the thread mounts that make\n * up nearly every caller get a typed state without naming it, and the other\n * mounts (the conversation index) name theirs.\n */\nexport const statewireTransport = <\n  TState = DeepAgentStreamValues,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n>(\n  options: StatewireTransportOptions,\n  { sse = false }: { sse?: boolean } = {}\n) =>\n  sse\n    ? StatewireHttp<TState, TCommands>({ protocol: DEEP_AGENT_STATEWIRE_PROTOCOL, ...options })\n    : StatewireWebsocket<TState, TCommands>({\n        protocol: DEEP_AGENT_STATEWIRE_PROTOCOL,\n        ...options,\n      });\n"],"names":[],"mappings":";AAYO,MAAM,gCAAgC;AAWtC,MAAM,qBAAqB,CAIhC,SACA,EAAE,MAAM,MAAA,IAA6B,CAAA,MAErC,MACI,cAAiC,EAAE,UAAU,+BAA+B,GAAG,QAAA,CAAS,IACxF,mBAAsC;AAAA,EACpC,UAAU;AAAA,EACV,GAAG;AACL,CAAC;"}

package/dist/packages/agent-runtime/src/thread-handoff.cjs

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../node_modules/qrcode-generator/dist/qrcode.cjs");
+const schemas = require("../../../node_modules/zod/v4/classic/schemas.cjs");
+const HANDOFF_DESTINATIONS = ["chrome", "mobile", "word", "powerpoint", "excel"];
+const OFFICE_HANDOFF_DESTINATIONS = ["word", "powerpoint", "excel"];
+["mobile", ...OFFICE_HANDOFF_DESTINATIONS];
+const handoffEnvironmentSchema = schemas.enum(["production", "staging", "localhost"]);
+const handoffStateSchema = schemas.enum(["issued", "launched", "claimed", "acknowledged", "failed"]);
+const handoffReadinessStateSchema = schemas.enum([
+  "unsupported",
+  "unknown",
+  "not_registered",
+  "registered",
+  "stale"
+]);
+const handoffDestinationSchema = schemas.enum(HANDOFF_DESTINATIONS);
+const destinationReadinessSchema = schemas.object({
+  destination: handoffDestinationSchema,
+  state: handoffReadinessStateSchema,
+  last_seen_at: schemas.string().nullable().optional(),
+  label: schemas.string().nullable().optional(),
+  marketplace_url: schemas.string().nullable().optional()
+});
+schemas.object({
+  environment: handoffEnvironmentSchema,
+  destinations: schemas.array(destinationReadinessSchema)
+});
+const threadHandoffViewSchema = schemas.object({
+  handoff_id: schemas.string(),
+  thread_id: schemas.string(),
+  session_asset_id: schemas.string().nullable(),
+  source: schemas.string(),
+  destination: handoffDestinationSchema,
+  environment: handoffEnvironmentSchema,
+  state: handoffStateSchema,
+  issued_at: schemas.string(),
+  expires_at: schemas.string(),
+  claimed_at: schemas.string().nullable(),
+  acknowledged_at: schemas.string().nullable(),
+  failure_reason: schemas.string().nullable(),
+  push_delivered: schemas.boolean().nullable()
+});
+const mobileHandoffLaunchSchema = schemas.object({
+  kind: schemas.literal("mobile"),
+  push_attempted: schemas.boolean(),
+  push_delivered: schemas.boolean(),
+  device_count: schemas.number(),
+  /** Universal/App Link (or browser URL) carrying only the opaque handoff id. */
+  link_url: schemas.string(),
+  /** Custom-scheme fallback for browsers that do not honour app links. */
+  scheme_url: schemas.string()
+});
+const officeHandoffLaunchSchema = schemas.object({
+  kind: schemas.literal("office"),
+  host: schemas.enum(OFFICE_HANDOFF_DESTINATIONS),
+  /** `ms-word:nft|u|<template>` — opens a blank document from the template. */
+  desktop_url: schemas.string(),
+  template_url: schemas.string(),
+  /** Office on the web: blank document, Athena opened from the ribbon. */
+  web_url: schemas.string(),
+  marketplace_url: schemas.string().nullable()
+});
+const chromeHandoffLaunchSchema = schemas.object({ kind: schemas.literal("chrome") });
+const handoffLaunchSchema = schemas.discriminatedUnion("kind", [
+  mobileHandoffLaunchSchema,
+  officeHandoffLaunchSchema,
+  chromeHandoffLaunchSchema
+]);
+schemas.object({
+  handoff: threadHandoffViewSchema,
+  launch: handoffLaunchSchema
+});
+exports.HANDOFF_DESTINATIONS = HANDOFF_DESTINATIONS;
+exports.OFFICE_HANDOFF_DESTINATIONS = OFFICE_HANDOFF_DESTINATIONS;
+exports.chromeHandoffLaunchSchema = chromeHandoffLaunchSchema;
+exports.destinationReadinessSchema = destinationReadinessSchema;
+exports.handoffEnvironmentSchema = handoffEnvironmentSchema;
+exports.handoffLaunchSchema = handoffLaunchSchema;
+exports.handoffReadinessStateSchema = handoffReadinessStateSchema;
+exports.handoffStateSchema = handoffStateSchema;
+exports.mobileHandoffLaunchSchema = mobileHandoffLaunchSchema;
+exports.officeHandoffLaunchSchema = officeHandoffLaunchSchema;
+exports.threadHandoffViewSchema = threadHandoffViewSchema;
+//# sourceMappingURL=thread-handoff.cjs.map

package/dist/packages/agent-runtime/src/thread-handoff.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-handoff.cjs","sources":["../../../../../agent-runtime/src/thread-handoff.ts"],"sourcesContent":["/**\n * Cross-surface \"Continue in…\" thread handoff — the client half of agora's\n * `/api/handoffs` protocol shared by Olympus (Spaces) and Athena in Chrome.\n *\n * A handoff never carries conversation content. The server binds an opaque\n * `handoff_id` to the durable thread, and the destination surface (mobile app,\n * Office add-in) claims that id and acknowledges once it owns the thread. The\n * source surface closes its own copilot only after that acknowledgement.\n */\nimport qrcode from 'qrcode-generator';\nimport { z } from 'zod';\n\nexport const HANDOFF_DESTINATIONS = ['chrome', 'mobile', 'word', 'powerpoint', 'excel'] as const;\nexport type HandoffDestination = (typeof HANDOFF_DESTINATIONS)[number];\n\nexport const OFFICE_HANDOFF_DESTINATIONS = ['word', 'powerpoint', 'excel'] as const;\nexport type OfficeHandoffDestination = (typeof OFFICE_HANDOFF_DESTINATIONS)[number];\n\n/** Destinations agora brokers; Chrome is launched page-side by the extension. */\nexport const SERVER_HANDOFF_DESTINATIONS = ['mobile', ...OFFICE_HANDOFF_DESTINATIONS] as const;\nexport type ServerHandoffDestination = (typeof SERVER_HANDOFF_DESTINATIONS)[number];\n\nexport type HandoffSource = 'spaces' | 'chrome' | 'mobile' | 'word' | 'powerpoint' | 'excel';\n\nexport const handoffEnvironmentSchema = z.enum(['production', 'staging', 'localhost']);\nexport type HandoffEnvironment = z.infer<typeof handoffEnvironmentSchema>;\n\nexport const handoffStateSchema = z.enum(['issued', 'launched', 'claimed', 'acknowledged', 'failed']);\nexport type HandoffState = z.infer<typeof handoffStateSchema>;\n\nexport const handoffReadinessStateSchema = z.enum([\n  'unsupported',\n  'unknown',\n  'not_registered',\n  'registered',\n  'stale',\n]);\nexport type HandoffReadinessState = z.infer<typeof handoffReadinessStateSchema>;\n\nconst handoffDestinationSchema = z.enum(HANDOFF_DESTINATIONS);\n\nexport const destinationReadinessSchema = z.object({\n  destination: handoffDestinationSchema,\n  state: handoffReadinessStateSchema,\n  last_seen_at: z.string().nullable().optional(),\n  label: z.string().nullable().optional(),\n  marketplace_url: z.string().nullable().optional(),\n});\nexport type DestinationReadiness = z.infer<typeof destinationReadinessSchema>;\n\nexport const handoffReadinessResponseSchema = z.object({\n  environment: handoffEnvironmentSchema,\n  destinations: z.array(destinationReadinessSchema),\n});\nexport type HandoffReadinessResponse = z.infer<typeof handoffReadinessResponseSchema>;\n\nexport const threadHandoffViewSchema = z.object({\n  handoff_id: z.string(),\n  thread_id: z.string(),\n  session_asset_id: z.string().nullable(),\n  source: z.string(),\n  destination: handoffDestinationSchema,\n  environment: handoffEnvironmentSchema,\n  state: handoffStateSchema,\n  issued_at: z.string(),\n  expires_at: z.string(),\n  claimed_at: z.string().nullable(),\n  acknowledged_at: z.string().nullable(),\n  failure_reason: z.string().nullable(),\n  push_delivered: z.boolean().nullable(),\n});\nexport type ThreadHandoffView = z.infer<typeof threadHandoffViewSchema>;\n\nexport const mobileHandoffLaunchSchema = z.object({\n  kind: z.literal('mobile'),\n  push_attempted: z.boolean(),\n  push_delivered: z.boolean(),\n  device_count: z.number(),\n  /** Universal/App Link (or browser URL) carrying only the opaque handoff id. */\n  link_url: z.string(),\n  /** Custom-scheme fallback for browsers that do not honour app links. */\n  scheme_url: z.string(),\n});\nexport type MobileHandoffLaunch = z.infer<typeof mobileHandoffLaunchSchema>;\n\nexport const officeHandoffLaunchSchema = z.object({\n  kind: z.literal('office'),\n  host: z.enum(OFFICE_HANDOFF_DESTINATIONS),\n  /** `ms-word:nft|u|<template>` — opens a blank document from the template. */\n  desktop_url: z.string(),\n  template_url: z.string(),\n  /** Office on the web: blank document, Athena opened from the ribbon. */\n  web_url: z.string(),\n  marketplace_url: z.string().nullable(),\n});\nexport type OfficeHandoffLaunch = z.infer<typeof officeHandoffLaunchSchema>;\n\nexport const chromeHandoffLaunchSchema = z.object({ kind: z.literal('chrome') });\n\nexport const handoffLaunchSchema = z.discriminatedUnion('kind', [\n  mobileHandoffLaunchSchema,\n  officeHandoffLaunchSchema,\n  chromeHandoffLaunchSchema,\n]);\nexport type HandoffLaunch = z.infer<typeof handoffLaunchSchema>;\n\nexport const createThreadHandoffResponseSchema = z.object({\n  handoff: threadHandoffViewSchema,\n  launch: handoffLaunchSchema,\n});\nexport type CreateThreadHandoffResponse = z.infer<typeof createThreadHandoffResponseSchema>;\n\nexport interface CreateThreadHandoffInput {\n  threadId: string;\n  destination: ServerHandoffDestination;\n  source: HandoffSource;\n}\n\n/**\n * Surface-specific HTTP adapter. Olympus binds it to `apiClient`; the\n * extension binds it to its authenticated fetch. Both must resolve (not\n * reject) with parsed responses so the flow can attribute failures.\n */\nexport interface ThreadHandoffTransport {\n  getReadiness: (options: { signal?: AbortSignal }) => Promise<HandoffReadinessResponse>;\n  createHandoff: (input: CreateThreadHandoffInput) => Promise<CreateThreadHandoffResponse>;\n  getHandoff: (options: { handoffId: string; signal?: AbortSignal }) => Promise<ThreadHandoffView>;\n}\n\nexport const HANDOFF_DESTINATION_LABELS: Record<HandoffDestination, string> = {\n  chrome: 'Google Chrome',\n  mobile: 'Athena Mobile',\n  word: 'Microsoft Word',\n  powerpoint: 'Microsoft PowerPoint',\n  excel: 'Microsoft Excel',\n};\n\nexport const isOfficeHandoffDestination = (\n  destination: HandoffDestination\n): destination is OfficeHandoffDestination =>\n  (OFFICE_HANDOFF_DESTINATIONS as readonly string[]).includes(destination);\n\nexport const isServerHandoffDestination = (\n  destination: HandoffDestination\n): destination is ServerHandoffDestination => destination !== 'chrome';\n\n/** Index a readiness response by destination; missing rows read as `unknown`. */\nexport const readinessByDestination = (\n  response: HandoffReadinessResponse | null | undefined\n): Record<HandoffDestination, DestinationReadiness> => {\n  const result = {} as Record<HandoffDestination, DestinationReadiness>;\n  for (const destination of HANDOFF_DESTINATIONS) {\n    result[destination] = { destination, state: 'unknown' };\n  }\n  for (const row of response?.destinations ?? []) {\n    result[row.destination] = row;\n  }\n  return result;\n};\n\n/**\n * How a mobile handoff should be presented before the phone answers.\n *\n * - `app`: a fresh push token exists — the phone gets a notification and the\n *   QR is only offered as a secondary path.\n * - `qr`: no usable device is known — lead with the QR / link.\n */\nexport type MobileLaunchMode = 'app' | 'qr';\n\nexport const selectMobileLaunchMode = (readiness: DestinationReadiness | null | undefined): MobileLaunchMode =>\n  readiness?.state === 'registered' ? 'app' : 'qr';\n\n/**\n * What a \"Continue in…\" row should say for a destination given its readiness.\n * Shared so Spaces and the extension render identical copy.\n */\nexport interface HandoffDestinationPresentation {\n  destination: HandoffDestination;\n  label: string;\n  /** Secondary line under the label; `null` when the row needs no caveat. */\n  detail: string | null;\n  /**\n   * `install` rows do not create a handoff — they point at install help;\n   * `unavailable` rows are disabled.\n   */\n  action: 'handoff' | 'install' | 'unavailable';\n}\n\nexport const presentHandoffDestination = ({\n  destination,\n  readiness,\n}: {\n  destination: HandoffDestination;\n  readiness: DestinationReadiness | null | undefined;\n}): HandoffDestinationPresentation => {\n  const label = HANDOFF_DESTINATION_LABELS[destination];\n  const state = readiness?.state ?? 'unknown';\n  if (destination === 'chrome') {\n    return { destination, label, detail: null, action: 'handoff' };\n  }\n  if (state === 'unsupported') {\n    return { destination, label, detail: 'Not available in this environment', action: 'unavailable' };\n  }\n  if (destination === 'mobile') {\n    switch (state) {\n      case 'registered':\n        return {\n          destination,\n          label,\n          detail: readiness?.label ? `Notify ${readiness.label}` : 'Notify your phone',\n          action: 'handoff',\n        };\n      case 'stale':\n        return {\n          destination,\n          label,\n          detail: readiness?.label\n            ? `${readiness.label} hasn't checked in recently — scan a QR code`\n            : 'Scan a QR code',\n          action: 'handoff',\n        };\n      default:\n        return { destination, label, detail: 'Scan a QR code', action: 'handoff' };\n    }\n  }\n  switch (state) {\n    case 'registered':\n      return { destination, label, detail: 'Opens a blank document', action: 'handoff' };\n    case 'stale':\n      return {\n        destination,\n        label,\n        detail: 'Opens a blank document — add-in last seen a while ago',\n        action: 'handoff',\n      };\n    case 'not_registered':\n      // Presence is only recorded once the pane has run, so \"not detected\" can\n      // be a false negative; keep the handoff available unless a store exists.\n      return {\n        destination,\n        label,\n        detail: 'Athena add-in not detected',\n        action: readiness?.marketplace_url ? 'install' : 'handoff',\n      };\n    default:\n      return { destination, label, detail: 'Opens a blank document', action: 'handoff' };\n  }\n};\n\n/**\n * QR symbol for a handoff link as a single SVG path in module units, so any\n * surface can render `<svg viewBox=\"0 0 {size} {size}\"><path d={path} /></svg>`\n * without a canvas or an image request.\n */\nexport const buildHandoffQrSvg = ({ text }: { text: string }): { size: number; path: string } => {\n  const symbol = qrcode(0, 'M');\n  symbol.addData(text);\n  symbol.make();\n  const size: number = symbol.getModuleCount();\n  const segments: string[] = [];\n  for (let row = 0; row < size; row += 1) {\n    let runStart = -1;\n    for (let col = 0; col <= size; col += 1) {\n      const dark: boolean = col < size && symbol.isDark(row, col);\n      if (dark && runStart === -1) {\n        runStart = col;\n      } else if (!dark && runStart !== -1) {\n        segments.push(`M${runStart} ${row}h${col - runStart}v1h-${col - runStart}z`);\n        runStart = -1;\n      }\n    }\n  }\n  return { size, path: segments.join('') };\n};\n\nexport type HandoffOutcome =\n  | { status: 'acknowledged'; handoff: ThreadHandoffView }\n  | { status: 'failed'; handoff: ThreadHandoffView | null; reason: string }\n  | { status: 'timeout'; handoff: ThreadHandoffView | null }\n  | { status: 'cancelled'; handoff: ThreadHandoffView | null };\n\nexport const isTerminalHandoffState = (state: HandoffState): boolean =>\n  state === 'acknowledged' || state === 'failed';\n\nexport interface WaitForHandoffOutcomeOptions {\n  transport: Pick<ThreadHandoffTransport, 'getHandoff'>;\n  handoffId: string;\n  /** Wall-clock budget; mobile pushes typically land in seconds, Office launches in tens of seconds. */\n  timeoutMs: number;\n  pollIntervalMs?: number;\n  signal?: AbortSignal;\n  onUpdate?: (handoff: ThreadHandoffView) => void;\n  /** Injected for tests. */\n  now?: () => number;\n  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;\n}\n\nconst defaultSleep = (ms: number, signal?: AbortSignal): Promise<void> =>\n  new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve();\n      return;\n    }\n    const timer = setTimeout(() => {\n      signal?.removeEventListener('abort', onAbort);\n      resolve();\n    }, ms);\n    function onAbort() {\n      clearTimeout(timer);\n      resolve();\n    }\n    signal?.addEventListener('abort', onAbort, { once: true });\n  });\n\n/**\n * Poll one handoff until the destination acknowledges, the server marks it\n * failed, the budget elapses, or the caller aborts. Each request is bound to\n * the remaining budget so a stalled response cannot outlive the deadline.\n * Retryable transport errors are retried within the budget; permanent ones\n * (auth, wrong deployment, malformed payload) fail immediately with their\n * actionable message. The last known view is reported.\n */\nexport async function waitForHandoffOutcome({\n  transport,\n  handoffId,\n  timeoutMs,\n  pollIntervalMs = 1500,\n  signal,\n  onUpdate,\n  now = () => Date.now(),\n  sleep = defaultSleep,\n}: WaitForHandoffOutcomeOptions): Promise<HandoffOutcome> {\n  const deadline = now() + timeoutMs;\n  let lastKnown: ThreadHandoffView | null = null;\n  while (true) {\n    if (signal?.aborted) {\n      return { status: 'cancelled', handoff: lastKnown };\n    }\n    const budgetMs: number = deadline - now();\n    if (budgetMs <= 0) {\n      return { status: 'timeout', handoff: lastKnown };\n    }\n    const poll = new AbortController();\n    const abortPoll = () => poll.abort();\n    const pollDeadline = setTimeout(abortPoll, budgetMs);\n    signal?.addEventListener('abort', abortPoll, { once: true });\n    try {\n      const view = await transport.getHandoff({ handoffId, signal: poll.signal });\n      lastKnown = view;\n      onUpdate?.(view);\n      if (view.state === 'acknowledged') {\n        return { status: 'acknowledged', handoff: view };\n      }\n      if (view.state === 'failed') {\n        return {\n          status: 'failed',\n          handoff: view,\n          reason: view.failure_reason ?? 'The destination could not open this conversation.',\n        };\n      }\n      if (now() >= Date.parse(view.expires_at)) {\n        return { status: 'timeout', handoff: view };\n      }\n    } catch (error) {\n      if (signal?.aborted) {\n        return { status: 'cancelled', handoff: lastKnown };\n      }\n      if (poll.signal.aborted) {\n        return { status: 'timeout', handoff: lastKnown };\n      }\n      switch (classifyHandoffTransportError(error)) {\n        case 'gone':\n          return {\n            status: 'failed',\n            handoff: lastKnown,\n            reason: 'This handoff expired before the destination opened it.',\n          };\n        case 'permanent':\n          return { status: 'failed', handoff: lastKnown, reason: describeHandoffTransportError(error) };\n        case 'retryable':\n          break;\n      }\n    } finally {\n      clearTimeout(pollDeadline);\n      signal?.removeEventListener('abort', abortPoll);\n    }\n    const remainingMs: number = deadline - now();\n    if (remainingMs <= 0) {\n      return { status: 'timeout', handoff: lastKnown };\n    }\n    await sleep(Math.min(pollIntervalMs, remainingMs), signal);\n    if (now() >= deadline) {\n      return { status: 'timeout', handoff: lastKnown };\n    }\n  }\n}\n\n/** Error raised by a transport when the server no longer knows the handoff (404). */\nexport class HandoffGoneError extends Error {\n  constructor(handoffId: string) {\n    super(`Handoff ${handoffId} is no longer available`);\n    this.name = 'HandoffGoneError';\n  }\n}\n\nexport const isHandoffGoneError = (error: unknown): error is HandoffGoneError =>\n  error instanceof HandoffGoneError ||\n  (error instanceof Error && error.name === 'HandoffGoneError');\n\n/**\n * Transport failure that polling the same handoff can never recover from:\n * the session is signed out, the token belongs to another deployment, the\n * server rejected the request, or the payload did not match the schema.\n */\nexport class HandoffPermanentError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = 'HandoffPermanentError';\n  }\n}\n\nexport const isHandoffPermanentError = (error: unknown): error is HandoffPermanentError =>\n  error instanceof HandoffPermanentError ||\n  (error instanceof Error && error.name === 'HandoffPermanentError');\n\nexport type HandoffTransportErrorKind = 'gone' | 'permanent' | 'retryable';\n\n/**\n * Shared classification for both transports: only network failures and\n * retryable server statuses keep the poll alive. Schema mismatches surface as\n * `ZodError` from either adapter and are permanent.\n */\nexport const classifyHandoffTransportError = (error: unknown): HandoffTransportErrorKind => {\n  if (isHandoffGoneError(error)) return 'gone';\n  if (isHandoffPermanentError(error) || error instanceof z.ZodError) return 'permanent';\n  return 'retryable';\n};\n\n/** 5xx, timeouts and rate limits may clear on the next poll; any other 4xx will not. */\nexport const isRetryableHandoffHttpStatus = (status: number): boolean =>\n  status >= 500 || status === 408 || status === 429;\n\n/**\n * Map a non-2xx status to the transport error the poll loop understands.\n * `detail` is the server's actionable message when it sent one.\n */\nexport const handoffHttpError = ({\n  handoffId,\n  status,\n  detail,\n}: {\n  handoffId: string;\n  status: number;\n  detail: string | null;\n}): Error => {\n  if (status === 404) return new HandoffGoneError(handoffId);\n  const message: string = detail ?? `The handoff request failed (${status}).`;\n  return isRetryableHandoffHttpStatus(status) ? new Error(message) : new HandoffPermanentError(message);\n};\n\nexport const describeHandoffTransportError = (error: unknown): string => {\n  if (error instanceof z.ZodError) {\n    return 'The server sent an unexpected response. Refresh and try again.';\n  }\n  if (error instanceof Error && error.message) return error.message;\n  return 'Lost track of the handoff. Try again.';\n};\n\n/** `?handoff=<id>` — the query parameter mobile-web and QR links carry. */\nexport const HANDOFF_URL_PARAM = 'handoff';\n\n/**\n * Read a handoff id from a URL. Ids are server-issued, URL-safe tokens; anything\n * else is rejected so a tampered link never reaches the claim path.\n */\nexport const parseHandoffIdParam = (value: string | null | undefined): string | null => {\n  if (!value) {\n    return null;\n  }\n  return /^[A-Za-z0-9_-]{8,128}$/.test(value) ? value : null;\n};\n\n/** Athena Mobile's custom URL scheme (`mobile-app-react-native/app.json` → `scheme`). */\nexport const MOBILE_APP_SCHEME = 'athenavisionapplication';\n\n/**\n * Custom-scheme launch for a handoff — what a phone's browser opens when the\n * Universal/App Link landed on mobile web instead of in the app. Mirrors\n * agora's `_mobile_scheme_url`; carries only the opaque handoff id.\n */\nexport const buildMobileHandoffSchemeUrl = ({ handoffId }: { handoffId: string }): string =>\n  `${MOBILE_APP_SCHEME}://chat?${HANDOFF_URL_PARAM}=${encodeURIComponent(handoffId)}`;\n"],"names":["z.enum","z.object","z.string","z.array","z.boolean","z.literal","z.number","z.discriminatedUnion"],"mappings":";;;;AAYO,MAAM,uBAAuB,CAAC,UAAU,UAAU,QAAQ,cAAc,OAAO;AAG/E,MAAM,8BAA8B,CAAC,QAAQ,cAAc,OAAO;AAI9B,CAAC,UAAU,GAAG,2BAA2B;AAK7E,MAAM,2BAA2BA,QAAAA,KAAO,CAAC,cAAc,WAAW,WAAW,CAAC;AAG9E,MAAM,qBAAqBA,QAAAA,KAAO,CAAC,UAAU,YAAY,WAAW,gBAAgB,QAAQ,CAAC;AAG7F,MAAM,8BAA8BA,QAAAA,KAAO;AAAA,EAChD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAGD,MAAM,2BAA2BA,QAAAA,KAAO,oBAAoB;AAErD,MAAM,6BAA6BC,QAAAA,OAAS;AAAA,EACjD,aAAa;AAAA,EACb,OAAO;AAAA,EACP,cAAcC,QAAAA,OAAE,EAAS,SAAA,EAAW,SAAA;AAAA,EACpC,OAAOA,QAAAA,OAAE,EAAS,SAAA,EAAW,SAAA;AAAA,EAC7B,iBAAiBA,QAAAA,OAAE,EAAS,SAAA,EAAW,SAAA;AACzC,CAAC;AAG6CD,QAAAA,OAAS;AAAA,EACrD,aAAa;AAAA,EACb,cAAcE,QAAAA,MAAQ,0BAA0B;AAClD,CAAC;AAGM,MAAM,0BAA0BF,QAAAA,OAAS;AAAA,EAC9C,YAAYC,QAAAA,OAAE;AAAA,EACd,WAAWA,QAAAA,OAAE;AAAA,EACb,kBAAkBA,QAAAA,OAAE,EAAS,SAAA;AAAA,EAC7B,QAAQA,QAAAA,OAAE;AAAA,EACV,aAAa;AAAA,EACb,aAAa;AAAA,EACb,OAAO;AAAA,EACP,WAAWA,QAAAA,OAAE;AAAA,EACb,YAAYA,QAAAA,OAAE;AAAA,EACd,YAAYA,QAAAA,OAAE,EAAS,SAAA;AAAA,EACvB,iBAAiBA,QAAAA,OAAE,EAAS,SAAA;AAAA,EAC5B,gBAAgBA,QAAAA,OAAE,EAAS,SAAA;AAAA,EAC3B,gBAAgBE,QAAAA,QAAE,EAAU,SAAA;AAC9B,CAAC;AAGM,MAAM,4BAA4BH,QAAAA,OAAS;AAAA,EAChD,MAAMI,QAAAA,QAAU,QAAQ;AAAA,EACxB,gBAAgBD,QAAAA,QAAE;AAAA,EAClB,gBAAgBA,QAAAA,QAAE;AAAA,EAClB,cAAcE,QAAAA,OAAE;AAAA;AAAA,EAEhB,UAAUJ,QAAAA,OAAE;AAAA;AAAA,EAEZ,YAAYA,QAAAA,OAAE;AAChB,CAAC;AAGM,MAAM,4BAA4BD,QAAAA,OAAS;AAAA,EAChD,MAAMI,QAAAA,QAAU,QAAQ;AAAA,EACxB,MAAML,QAAAA,KAAO,2BAA2B;AAAA;AAAA,EAExC,aAAaE,QAAAA,OAAE;AAAA,EACf,cAAcA,QAAAA,OAAE;AAAA;AAAA,EAEhB,SAASA,QAAAA,OAAE;AAAA,EACX,iBAAiBA,QAAAA,OAAE,EAAS,SAAA;AAC9B,CAAC;AAGM,MAAM,4BAA4BD,QAAAA,OAAS,EAAE,MAAMI,QAAAA,QAAU,QAAQ,EAAA,CAAG;AAExE,MAAM,sBAAsBE,QAAAA,mBAAqB,QAAQ;AAAA,EAC9D;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAGgDN,QAAAA,OAAS;AAAA,EACxD,SAAS;AAAA,EACT,QAAQ;AACV,CAAC;;;;;;;;;;;;"}

package/dist/packages/agent-runtime/src/thread-handoff.js

@@ -0,0 +1,85 @@
+import "../../../node_modules/qrcode-generator/dist/qrcode.js";
+import { enum as _enum, object, string, boolean, literal, discriminatedUnion, array, number } from "../../../node_modules/zod/v4/classic/schemas.js";
+const HANDOFF_DESTINATIONS = ["chrome", "mobile", "word", "powerpoint", "excel"];
+const OFFICE_HANDOFF_DESTINATIONS = ["word", "powerpoint", "excel"];
+["mobile", ...OFFICE_HANDOFF_DESTINATIONS];
+const handoffEnvironmentSchema = _enum(["production", "staging", "localhost"]);
+const handoffStateSchema = _enum(["issued", "launched", "claimed", "acknowledged", "failed"]);
+const handoffReadinessStateSchema = _enum([
+  "unsupported",
+  "unknown",
+  "not_registered",
+  "registered",
+  "stale"
+]);
+const handoffDestinationSchema = _enum(HANDOFF_DESTINATIONS);
+const destinationReadinessSchema = object({
+  destination: handoffDestinationSchema,
+  state: handoffReadinessStateSchema,
+  last_seen_at: string().nullable().optional(),
+  label: string().nullable().optional(),
+  marketplace_url: string().nullable().optional()
+});
+object({
+  environment: handoffEnvironmentSchema,
+  destinations: array(destinationReadinessSchema)
+});
+const threadHandoffViewSchema = object({
+  handoff_id: string(),
+  thread_id: string(),
+  session_asset_id: string().nullable(),
+  source: string(),
+  destination: handoffDestinationSchema,
+  environment: handoffEnvironmentSchema,
+  state: handoffStateSchema,
+  issued_at: string(),
+  expires_at: string(),
+  claimed_at: string().nullable(),
+  acknowledged_at: string().nullable(),
+  failure_reason: string().nullable(),
+  push_delivered: boolean().nullable()
+});
+const mobileHandoffLaunchSchema = object({
+  kind: literal("mobile"),
+  push_attempted: boolean(),
+  push_delivered: boolean(),
+  device_count: number(),
+  /** Universal/App Link (or browser URL) carrying only the opaque handoff id. */
+  link_url: string(),
+  /** Custom-scheme fallback for browsers that do not honour app links. */
+  scheme_url: string()
+});
+const officeHandoffLaunchSchema = object({
+  kind: literal("office"),
+  host: _enum(OFFICE_HANDOFF_DESTINATIONS),
+  /** `ms-word:nft|u|<template>` — opens a blank document from the template. */
+  desktop_url: string(),
+  template_url: string(),
+  /** Office on the web: blank document, Athena opened from the ribbon. */
+  web_url: string(),
+  marketplace_url: string().nullable()
+});
+const chromeHandoffLaunchSchema = object({ kind: literal("chrome") });
+const handoffLaunchSchema = discriminatedUnion("kind", [
+  mobileHandoffLaunchSchema,
+  officeHandoffLaunchSchema,
+  chromeHandoffLaunchSchema
+]);
+object({
+  handoff: threadHandoffViewSchema,
+  launch: handoffLaunchSchema
+});
+export {
+  HANDOFF_DESTINATIONS,
+  OFFICE_HANDOFF_DESTINATIONS,
+  chromeHandoffLaunchSchema,
+  destinationReadinessSchema,
+  handoffEnvironmentSchema,
+  handoffLaunchSchema,
+  handoffReadinessStateSchema,
+  handoffStateSchema,
+  mobileHandoffLaunchSchema,
+  officeHandoffLaunchSchema,
+  threadHandoffViewSchema
+};
+//# sourceMappingURL=thread-handoff.js.map

package/dist/packages/agent-runtime/src/thread-handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-handoff.js","sources":["../../../../../agent-runtime/src/thread-handoff.ts"],"sourcesContent":["/**\n * Cross-surface \"Continue in…\" thread handoff — the client half of agora's\n * `/api/handoffs` protocol shared by Olympus (Spaces) and Athena in Chrome.\n *\n * A handoff never carries conversation content. The server binds an opaque\n * `handoff_id` to the durable thread, and the destination surface (mobile app,\n * Office add-in) claims that id and acknowledges once it owns the thread. The\n * source surface closes its own copilot only after that acknowledgement.\n */\nimport qrcode from 'qrcode-generator';\nimport { z } from 'zod';\n\nexport const HANDOFF_DESTINATIONS = ['chrome', 'mobile', 'word', 'powerpoint', 'excel'] as const;\nexport type HandoffDestination = (typeof HANDOFF_DESTINATIONS)[number];\n\nexport const OFFICE_HANDOFF_DESTINATIONS = ['word', 'powerpoint', 'excel'] as const;\nexport type OfficeHandoffDestination = (typeof OFFICE_HANDOFF_DESTINATIONS)[number];\n\n/** Destinations agora brokers; Chrome is launched page-side by the extension. */\nexport const SERVER_HANDOFF_DESTINATIONS = ['mobile', ...OFFICE_HANDOFF_DESTINATIONS] as const;\nexport type ServerHandoffDestination = (typeof SERVER_HANDOFF_DESTINATIONS)[number];\n\nexport type HandoffSource = 'spaces' | 'chrome' | 'mobile' | 'word' | 'powerpoint' | 'excel';\n\nexport const handoffEnvironmentSchema = z.enum(['production', 'staging', 'localhost']);\nexport type HandoffEnvironment = z.infer<typeof handoffEnvironmentSchema>;\n\nexport const handoffStateSchema = z.enum(['issued', 'launched', 'claimed', 'acknowledged', 'failed']);\nexport type HandoffState = z.infer<typeof handoffStateSchema>;\n\nexport const handoffReadinessStateSchema = z.enum([\n  'unsupported',\n  'unknown',\n  'not_registered',\n  'registered',\n  'stale',\n]);\nexport type HandoffReadinessState = z.infer<typeof handoffReadinessStateSchema>;\n\nconst handoffDestinationSchema = z.enum(HANDOFF_DESTINATIONS);\n\nexport const destinationReadinessSchema = z.object({\n  destination: handoffDestinationSchema,\n  state: handoffReadinessStateSchema,\n  last_seen_at: z.string().nullable().optional(),\n  label: z.string().nullable().optional(),\n  marketplace_url: z.string().nullable().optional(),\n});\nexport type DestinationReadiness = z.infer<typeof destinationReadinessSchema>;\n\nexport const handoffReadinessResponseSchema = z.object({\n  environment: handoffEnvironmentSchema,\n  destinations: z.array(destinationReadinessSchema),\n});\nexport type HandoffReadinessResponse = z.infer<typeof handoffReadinessResponseSchema>;\n\nexport const threadHandoffViewSchema = z.object({\n  handoff_id: z.string(),\n  thread_id: z.string(),\n  session_asset_id: z.string().nullable(),\n  source: z.string(),\n  destination: handoffDestinationSchema,\n  environment: handoffEnvironmentSchema,\n  state: handoffStateSchema,\n  issued_at: z.string(),\n  expires_at: z.string(),\n  claimed_at: z.string().nullable(),\n  acknowledged_at: z.string().nullable(),\n  failure_reason: z.string().nullable(),\n  push_delivered: z.boolean().nullable(),\n});\nexport type ThreadHandoffView = z.infer<typeof threadHandoffViewSchema>;\n\nexport const mobileHandoffLaunchSchema = z.object({\n  kind: z.literal('mobile'),\n  push_attempted: z.boolean(),\n  push_delivered: z.boolean(),\n  device_count: z.number(),\n  /** Universal/App Link (or browser URL) carrying only the opaque handoff id. */\n  link_url: z.string(),\n  /** Custom-scheme fallback for browsers that do not honour app links. */\n  scheme_url: z.string(),\n});\nexport type MobileHandoffLaunch = z.infer<typeof mobileHandoffLaunchSchema>;\n\nexport const officeHandoffLaunchSchema = z.object({\n  kind: z.literal('office'),\n  host: z.enum(OFFICE_HANDOFF_DESTINATIONS),\n  /** `ms-word:nft|u|<template>` — opens a blank document from the template. */\n  desktop_url: z.string(),\n  template_url: z.string(),\n  /** Office on the web: blank document, Athena opened from the ribbon. */\n  web_url: z.string(),\n  marketplace_url: z.string().nullable(),\n});\nexport type OfficeHandoffLaunch = z.infer<typeof officeHandoffLaunchSchema>;\n\nexport const chromeHandoffLaunchSchema = z.object({ kind: z.literal('chrome') });\n\nexport const handoffLaunchSchema = z.discriminatedUnion('kind', [\n  mobileHandoffLaunchSchema,\n  officeHandoffLaunchSchema,\n  chromeHandoffLaunchSchema,\n]);\nexport type HandoffLaunch = z.infer<typeof handoffLaunchSchema>;\n\nexport const createThreadHandoffResponseSchema = z.object({\n  handoff: threadHandoffViewSchema,\n  launch: handoffLaunchSchema,\n});\nexport type CreateThreadHandoffResponse = z.infer<typeof createThreadHandoffResponseSchema>;\n\nexport interface CreateThreadHandoffInput {\n  threadId: string;\n  destination: ServerHandoffDestination;\n  source: HandoffSource;\n}\n\n/**\n * Surface-specific HTTP adapter. Olympus binds it to `apiClient`; the\n * extension binds it to its authenticated fetch. Both must resolve (not\n * reject) with parsed responses so the flow can attribute failures.\n */\nexport interface ThreadHandoffTransport {\n  getReadiness: (options: { signal?: AbortSignal }) => Promise<HandoffReadinessResponse>;\n  createHandoff: (input: CreateThreadHandoffInput) => Promise<CreateThreadHandoffResponse>;\n  getHandoff: (options: { handoffId: string; signal?: AbortSignal }) => Promise<ThreadHandoffView>;\n}\n\nexport const HANDOFF_DESTINATION_LABELS: Record<HandoffDestination, string> = {\n  chrome: 'Google Chrome',\n  mobile: 'Athena Mobile',\n  word: 'Microsoft Word',\n  powerpoint: 'Microsoft PowerPoint',\n  excel: 'Microsoft Excel',\n};\n\nexport const isOfficeHandoffDestination = (\n  destination: HandoffDestination\n): destination is OfficeHandoffDestination =>\n  (OFFICE_HANDOFF_DESTINATIONS as readonly string[]).includes(destination);\n\nexport const isServerHandoffDestination = (\n  destination: HandoffDestination\n): destination is ServerHandoffDestination => destination !== 'chrome';\n\n/** Index a readiness response by destination; missing rows read as `unknown`. */\nexport const readinessByDestination = (\n  response: HandoffReadinessResponse | null | undefined\n): Record<HandoffDestination, DestinationReadiness> => {\n  const result = {} as Record<HandoffDestination, DestinationReadiness>;\n  for (const destination of HANDOFF_DESTINATIONS) {\n    result[destination] = { destination, state: 'unknown' };\n  }\n  for (const row of response?.destinations ?? []) {\n    result[row.destination] = row;\n  }\n  return result;\n};\n\n/**\n * How a mobile handoff should be presented before the phone answers.\n *\n * - `app`: a fresh push token exists — the phone gets a notification and the\n *   QR is only offered as a secondary path.\n * - `qr`: no usable device is known — lead with the QR / link.\n */\nexport type MobileLaunchMode = 'app' | 'qr';\n\nexport const selectMobileLaunchMode = (readiness: DestinationReadiness | null | undefined): MobileLaunchMode =>\n  readiness?.state === 'registered' ? 'app' : 'qr';\n\n/**\n * What a \"Continue in…\" row should say for a destination given its readiness.\n * Shared so Spaces and the extension render identical copy.\n */\nexport interface HandoffDestinationPresentation {\n  destination: HandoffDestination;\n  label: string;\n  /** Secondary line under the label; `null` when the row needs no caveat. */\n  detail: string | null;\n  /**\n   * `install` rows do not create a handoff — they point at install help;\n   * `unavailable` rows are disabled.\n   */\n  action: 'handoff' | 'install' | 'unavailable';\n}\n\nexport const presentHandoffDestination = ({\n  destination,\n  readiness,\n}: {\n  destination: HandoffDestination;\n  readiness: DestinationReadiness | null | undefined;\n}): HandoffDestinationPresentation => {\n  const label = HANDOFF_DESTINATION_LABELS[destination];\n  const state = readiness?.state ?? 'unknown';\n  if (destination === 'chrome') {\n    return { destination, label, detail: null, action: 'handoff' };\n  }\n  if (state === 'unsupported') {\n    return { destination, label, detail: 'Not available in this environment', action: 'unavailable' };\n  }\n  if (destination === 'mobile') {\n    switch (state) {\n      case 'registered':\n        return {\n          destination,\n          label,\n          detail: readiness?.label ? `Notify ${readiness.label}` : 'Notify your phone',\n          action: 'handoff',\n        };\n      case 'stale':\n        return {\n          destination,\n          label,\n          detail: readiness?.label\n            ? `${readiness.label} hasn't checked in recently — scan a QR code`\n            : 'Scan a QR code',\n          action: 'handoff',\n        };\n      default:\n        return { destination, label, detail: 'Scan a QR code', action: 'handoff' };\n    }\n  }\n  switch (state) {\n    case 'registered':\n      return { destination, label, detail: 'Opens a blank document', action: 'handoff' };\n    case 'stale':\n      return {\n        destination,\n        label,\n        detail: 'Opens a blank document — add-in last seen a while ago',\n        action: 'handoff',\n      };\n    case 'not_registered':\n      // Presence is only recorded once the pane has run, so \"not detected\" can\n      // be a false negative; keep the handoff available unless a store exists.\n      return {\n        destination,\n        label,\n        detail: 'Athena add-in not detected',\n        action: readiness?.marketplace_url ? 'install' : 'handoff',\n      };\n    default:\n      return { destination, label, detail: 'Opens a blank document', action: 'handoff' };\n  }\n};\n\n/**\n * QR symbol for a handoff link as a single SVG path in module units, so any\n * surface can render `<svg viewBox=\"0 0 {size} {size}\"><path d={path} /></svg>`\n * without a canvas or an image request.\n */\nexport const buildHandoffQrSvg = ({ text }: { text: string }): { size: number; path: string } => {\n  const symbol = qrcode(0, 'M');\n  symbol.addData(text);\n  symbol.make();\n  const size: number = symbol.getModuleCount();\n  const segments: string[] = [];\n  for (let row = 0; row < size; row += 1) {\n    let runStart = -1;\n    for (let col = 0; col <= size; col += 1) {\n      const dark: boolean = col < size && symbol.isDark(row, col);\n      if (dark && runStart === -1) {\n        runStart = col;\n      } else if (!dark && runStart !== -1) {\n        segments.push(`M${runStart} ${row}h${col - runStart}v1h-${col - runStart}z`);\n        runStart = -1;\n      }\n    }\n  }\n  return { size, path: segments.join('') };\n};\n\nexport type HandoffOutcome =\n  | { status: 'acknowledged'; handoff: ThreadHandoffView }\n  | { status: 'failed'; handoff: ThreadHandoffView | null; reason: string }\n  | { status: 'timeout'; handoff: ThreadHandoffView | null }\n  | { status: 'cancelled'; handoff: ThreadHandoffView | null };\n\nexport const isTerminalHandoffState = (state: HandoffState): boolean =>\n  state === 'acknowledged' || state === 'failed';\n\nexport interface WaitForHandoffOutcomeOptions {\n  transport: Pick<ThreadHandoffTransport, 'getHandoff'>;\n  handoffId: string;\n  /** Wall-clock budget; mobile pushes typically land in seconds, Office launches in tens of seconds. */\n  timeoutMs: number;\n  pollIntervalMs?: number;\n  signal?: AbortSignal;\n  onUpdate?: (handoff: ThreadHandoffView) => void;\n  /** Injected for tests. */\n  now?: () => number;\n  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;\n}\n\nconst defaultSleep = (ms: number, signal?: AbortSignal): Promise<void> =>\n  new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve();\n      return;\n    }\n    const timer = setTimeout(() => {\n      signal?.removeEventListener('abort', onAbort);\n      resolve();\n    }, ms);\n    function onAbort() {\n      clearTimeout(timer);\n      resolve();\n    }\n    signal?.addEventListener('abort', onAbort, { once: true });\n  });\n\n/**\n * Poll one handoff until the destination acknowledges, the server marks it\n * failed, the budget elapses, or the caller aborts. Each request is bound to\n * the remaining budget so a stalled response cannot outlive the deadline.\n * Retryable transport errors are retried within the budget; permanent ones\n * (auth, wrong deployment, malformed payload) fail immediately with their\n * actionable message. The last known view is reported.\n */\nexport async function waitForHandoffOutcome({\n  transport,\n  handoffId,\n  timeoutMs,\n  pollIntervalMs = 1500,\n  signal,\n  onUpdate,\n  now = () => Date.now(),\n  sleep = defaultSleep,\n}: WaitForHandoffOutcomeOptions): Promise<HandoffOutcome> {\n  const deadline = now() + timeoutMs;\n  let lastKnown: ThreadHandoffView | null = null;\n  while (true) {\n    if (signal?.aborted) {\n      return { status: 'cancelled', handoff: lastKnown };\n    }\n    const budgetMs: number = deadline - now();\n    if (budgetMs <= 0) {\n      return { status: 'timeout', handoff: lastKnown };\n    }\n    const poll = new AbortController();\n    const abortPoll = () => poll.abort();\n    const pollDeadline = setTimeout(abortPoll, budgetMs);\n    signal?.addEventListener('abort', abortPoll, { once: true });\n    try {\n      const view = await transport.getHandoff({ handoffId, signal: poll.signal });\n      lastKnown = view;\n      onUpdate?.(view);\n      if (view.state === 'acknowledged') {\n        return { status: 'acknowledged', handoff: view };\n      }\n      if (view.state === 'failed') {\n        return {\n          status: 'failed',\n          handoff: view,\n          reason: view.failure_reason ?? 'The destination could not open this conversation.',\n        };\n      }\n      if (now() >= Date.parse(view.expires_at)) {\n        return { status: 'timeout', handoff: view };\n      }\n    } catch (error) {\n      if (signal?.aborted) {\n        return { status: 'cancelled', handoff: lastKnown };\n      }\n      if (poll.signal.aborted) {\n        return { status: 'timeout', handoff: lastKnown };\n      }\n      switch (classifyHandoffTransportError(error)) {\n        case 'gone':\n          return {\n            status: 'failed',\n            handoff: lastKnown,\n            reason: 'This handoff expired before the destination opened it.',\n          };\n        case 'permanent':\n          return { status: 'failed', handoff: lastKnown, reason: describeHandoffTransportError(error) };\n        case 'retryable':\n          break;\n      }\n    } finally {\n      clearTimeout(pollDeadline);\n      signal?.removeEventListener('abort', abortPoll);\n    }\n    const remainingMs: number = deadline - now();\n    if (remainingMs <= 0) {\n      return { status: 'timeout', handoff: lastKnown };\n    }\n    await sleep(Math.min(pollIntervalMs, remainingMs), signal);\n    if (now() >= deadline) {\n      return { status: 'timeout', handoff: lastKnown };\n    }\n  }\n}\n\n/** Error raised by a transport when the server no longer knows the handoff (404). */\nexport class HandoffGoneError extends Error {\n  constructor(handoffId: string) {\n    super(`Handoff ${handoffId} is no longer available`);\n    this.name = 'HandoffGoneError';\n  }\n}\n\nexport const isHandoffGoneError = (error: unknown): error is HandoffGoneError =>\n  error instanceof HandoffGoneError ||\n  (error instanceof Error && error.name === 'HandoffGoneError');\n\n/**\n * Transport failure that polling the same handoff can never recover from:\n * the session is signed out, the token belongs to another deployment, the\n * server rejected the request, or the payload did not match the schema.\n */\nexport class HandoffPermanentError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = 'HandoffPermanentError';\n  }\n}\n\nexport const isHandoffPermanentError = (error: unknown): error is HandoffPermanentError =>\n  error instanceof HandoffPermanentError ||\n  (error instanceof Error && error.name === 'HandoffPermanentError');\n\nexport type HandoffTransportErrorKind = 'gone' | 'permanent' | 'retryable';\n\n/**\n * Shared classification for both transports: only network failures and\n * retryable server statuses keep the poll alive. Schema mismatches surface as\n * `ZodError` from either adapter and are permanent.\n */\nexport const classifyHandoffTransportError = (error: unknown): HandoffTransportErrorKind => {\n  if (isHandoffGoneError(error)) return 'gone';\n  if (isHandoffPermanentError(error) || error instanceof z.ZodError) return 'permanent';\n  return 'retryable';\n};\n\n/** 5xx, timeouts and rate limits may clear on the next poll; any other 4xx will not. */\nexport const isRetryableHandoffHttpStatus = (status: number): boolean =>\n  status >= 500 || status === 408 || status === 429;\n\n/**\n * Map a non-2xx status to the transport error the poll loop understands.\n * `detail` is the server's actionable message when it sent one.\n */\nexport const handoffHttpError = ({\n  handoffId,\n  status,\n  detail,\n}: {\n  handoffId: string;\n  status: number;\n  detail: string | null;\n}): Error => {\n  if (status === 404) return new HandoffGoneError(handoffId);\n  const message: string = detail ?? `The handoff request failed (${status}).`;\n  return isRetryableHandoffHttpStatus(status) ? new Error(message) : new HandoffPermanentError(message);\n};\n\nexport const describeHandoffTransportError = (error: unknown): string => {\n  if (error instanceof z.ZodError) {\n    return 'The server sent an unexpected response. Refresh and try again.';\n  }\n  if (error instanceof Error && error.message) return error.message;\n  return 'Lost track of the handoff. Try again.';\n};\n\n/** `?handoff=<id>` — the query parameter mobile-web and QR links carry. */\nexport const HANDOFF_URL_PARAM = 'handoff';\n\n/**\n * Read a handoff id from a URL. Ids are server-issued, URL-safe tokens; anything\n * else is rejected so a tampered link never reaches the claim path.\n */\nexport const parseHandoffIdParam = (value: string | null | undefined): string | null => {\n  if (!value) {\n    return null;\n  }\n  return /^[A-Za-z0-9_-]{8,128}$/.test(value) ? value : null;\n};\n\n/** Athena Mobile's custom URL scheme (`mobile-app-react-native/app.json` → `scheme`). */\nexport const MOBILE_APP_SCHEME = 'athenavisionapplication';\n\n/**\n * Custom-scheme launch for a handoff — what a phone's browser opens when the\n * Universal/App Link landed on mobile web instead of in the app. Mirrors\n * agora's `_mobile_scheme_url`; carries only the opaque handoff id.\n */\nexport const buildMobileHandoffSchemeUrl = ({ handoffId }: { handoffId: string }): string =>\n  `${MOBILE_APP_SCHEME}://chat?${HANDOFF_URL_PARAM}=${encodeURIComponent(handoffId)}`;\n"],"names":["z.enum","z.object","z.string","z.array","z.boolean","z.literal","z.number","z.discriminatedUnion"],"mappings":";;AAYO,MAAM,uBAAuB,CAAC,UAAU,UAAU,QAAQ,cAAc,OAAO;AAG/E,MAAM,8BAA8B,CAAC,QAAQ,cAAc,OAAO;AAI9B,CAAC,UAAU,GAAG,2BAA2B;AAK7E,MAAM,2BAA2BA,MAAO,CAAC,cAAc,WAAW,WAAW,CAAC;AAG9E,MAAM,qBAAqBA,MAAO,CAAC,UAAU,YAAY,WAAW,gBAAgB,QAAQ,CAAC;AAG7F,MAAM,8BAA8BA,MAAO;AAAA,EAChD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAGD,MAAM,2BAA2BA,MAAO,oBAAoB;AAErD,MAAM,6BAA6BC,OAAS;AAAA,EACjD,aAAa;AAAA,EACb,OAAO;AAAA,EACP,cAAcC,OAAE,EAAS,SAAA,EAAW,SAAA;AAAA,EACpC,OAAOA,OAAE,EAAS,SAAA,EAAW,SAAA;AAAA,EAC7B,iBAAiBA,OAAE,EAAS,SAAA,EAAW,SAAA;AACzC,CAAC;AAG6CD,OAAS;AAAA,EACrD,aAAa;AAAA,EACb,cAAcE,MAAQ,0BAA0B;AAClD,CAAC;AAGM,MAAM,0BAA0BF,OAAS;AAAA,EAC9C,YAAYC,OAAE;AAAA,EACd,WAAWA,OAAE;AAAA,EACb,kBAAkBA,OAAE,EAAS,SAAA;AAAA,EAC7B,QAAQA,OAAE;AAAA,EACV,aAAa;AAAA,EACb,aAAa;AAAA,EACb,OAAO;AAAA,EACP,WAAWA,OAAE;AAAA,EACb,YAAYA,OAAE;AAAA,EACd,YAAYA,OAAE,EAAS,SAAA;AAAA,EACvB,iBAAiBA,OAAE,EAAS,SAAA;AAAA,EAC5B,gBAAgBA,OAAE,EAAS,SAAA;AAAA,EAC3B,gBAAgBE,QAAE,EAAU,SAAA;AAC9B,CAAC;AAGM,MAAM,4BAA4BH,OAAS;AAAA,EAChD,MAAMI,QAAU,QAAQ;AAAA,EACxB,gBAAgBD,QAAE;AAAA,EAClB,gBAAgBA,QAAE;AAAA,EAClB,cAAcE,OAAE;AAAA;AAAA,EAEhB,UAAUJ,OAAE;AAAA;AAAA,EAEZ,YAAYA,OAAE;AAChB,CAAC;AAGM,MAAM,4BAA4BD,OAAS;AAAA,EAChD,MAAMI,QAAU,QAAQ;AAAA,EACxB,MAAML,MAAO,2BAA2B;AAAA;AAAA,EAExC,aAAaE,OAAE;AAAA,EACf,cAAcA,OAAE;AAAA;AAAA,EAEhB,SAASA,OAAE;AAAA,EACX,iBAAiBA,OAAE,EAAS,SAAA;AAC9B,CAAC;AAGM,MAAM,4BAA4BD,OAAS,EAAE,MAAMI,QAAU,QAAQ,EAAA,CAAG;AAExE,MAAM,sBAAsBE,mBAAqB,QAAQ;AAAA,EAC9D;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAGgDN,OAAS;AAAA,EACxD,SAAS;AAAA,EACT,QAAQ;AACV,CAAC;"}

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

@@ -67,7 +67,7 @@ function toThreadSnapshotSeed(state) {
   const {
     __interrupt__: _interrupt,
     ptc_subagents: _ptcSubagents,
-    legacyRunActive: _legacyRunActive,
+    outOfBandRunActive: _outOfBandRunActive,
     ...rest
   } = state;
   return { ...rest, runs: seedRunsLane(state.runs) };

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

@@ -1 +1 @@
-{"version":3,"file":"thread-snapshot-cache.cjs","sources":["../../../../../agent-runtime/src/thread-snapshot-cache.ts"],"sourcesContent":["import type { DeepAgentStreamValues } from './types';\n\n/**\n * Per-tab LRU of the last wire state seen per thread, so a switch back to a\n * recently-visited thread can mount with that snapshot instead of an empty\n * \"loading\" state (see `UseDeepAgentThreadOptions.snapshotCache`). Entries are\n * references into states the wire already produced — remembering is O(1) and\n * copies nothing; the bound is `maxThreads` retained states.\n */\nexport interface DeepAgentThreadSnapshotCache {\n  /** Record the latest hydrated wire state for a thread. */\n  remember(threadId: string, state: DeepAgentStreamValues): void;\n  /** The freshest remembered state for a thread, or `undefined` when none is\n   * held or the entry aged out. */\n  take(threadId: string): DeepAgentStreamValues | undefined;\n  /**\n   * Drop a single thread's entry. Called when the server refuses\n   * authorization for the thread — a refused thread must not warm-paint on\n   * its next mount.\n   */\n  forget(threadId: string): void;\n  /**\n   * Drop every entry. Called when the acting identity changes — a snapshot\n   * captured under one account must never seed a mount under another.\n   */\n  clear(): void;\n  /**\n   * Whether a fresh entry is held for the thread, without consuming or\n   * touching it. Hosts read it at selection time to decide whether the switch\n   * can paint from a seed (no loading treatment) or must cover the attach\n   * wait. Optional so hand-rolled caches keep type-checking; the built-in\n   * cache implements it.\n   */\n  peek?(threadId: string): boolean;\n}\n\n/** A write observed on the cache — the durable-mirror seam (see `onChange`). */\nexport type DeepAgentThreadSnapshotCacheChange =\n  | { type: 'remember'; threadId: string; state: DeepAgentStreamValues; at: number }\n  | { type: 'forget'; threadId: string }\n  | { type: 'clear' };\n\nexport interface DeepAgentThreadSnapshotCacheOptions {\n  /** Threads retained; the least-recently written entry evicts beyond this. */\n  maxThreads?: number;\n  /**\n   * Entries older than this are dropped at read time. The seed's value is\n   * \"the thread you just left\" — a snapshot from long ago is more likely to\n   * flash content the server has since rewritten than to save a paint.\n   */\n  maxAgeMs?: number;\n  /**\n   * Observer of every write (`remember`, `forget`, `clear`). Hosts mirror\n   * entries into durable storage from here so a reload can seed too; the\n   * observer is never invoked for `restore`, which re-admits mirrored entries.\n   * Exceptions are swallowed — a mirror fault must not break the wire path.\n   */\n  onChange?: (change: DeepAgentThreadSnapshotCacheChange) => void;\n  /** Injectable clock (tests). */\n  now?: () => number;\n}\n\n/** The built-in cache: the host contract plus the durable-mirror re-admission. */\nexport interface CreatedDeepAgentThreadSnapshotCache extends DeepAgentThreadSnapshotCache {\n  peek(threadId: string): boolean;\n  /**\n   * Re-admit an entry captured earlier — a mirrored snapshot after a reload —\n   * under its ORIGINAL capture time, so the age bound still applies. Never\n   * displaces a fresher in-memory entry and never notifies `onChange`.\n   */\n  restore(threadId: string, state: DeepAgentStreamValues, at: number): void;\n}\n\nconst DEFAULT_MAX_THREADS = 30;\nconst DEFAULT_MAX_AGE_MS = 60 * 60 * 1000;\n\nexport function createDeepAgentThreadSnapshotCache(\n  options: DeepAgentThreadSnapshotCacheOptions = {}\n): CreatedDeepAgentThreadSnapshotCache {\n  const maxThreads = options.maxThreads ?? DEFAULT_MAX_THREADS;\n  const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;\n  const now = options.now ?? (() => Date.now());\n  const notify = (change: DeepAgentThreadSnapshotCacheChange): void => {\n    try {\n      options.onChange?.(change);\n    } catch {\n      // The mirror is best-effort; the in-memory cache stays authoritative.\n    }\n  };\n  // Map iteration order is insertion order; delete-then-set on every write\n  // keeps the first key the least-recently written.\n  const entries = new Map<string, { state: DeepAgentStreamValues; at: number }>();\n  const evict = (): void => {\n    while (entries.size > maxThreads) {\n      const oldest = entries.keys().next().value;\n      if (oldest === undefined) break;\n      entries.delete(oldest);\n    }\n  };\n  const fresh = (threadId: string): { state: DeepAgentStreamValues; at: number } | undefined => {\n    const entry = entries.get(threadId);\n    if (!entry) return undefined;\n    if (now() - entry.at > maxAgeMs) {\n      entries.delete(threadId);\n      return undefined;\n    }\n    return entry;\n  };\n  return {\n    remember(threadId, state) {\n      const at = now();\n      entries.delete(threadId);\n      entries.set(threadId, { state, at });\n      evict();\n      notify({ type: 'remember', threadId, state, at });\n    },\n    take(threadId) {\n      return fresh(threadId)?.state;\n    },\n    peek(threadId) {\n      return fresh(threadId) !== undefined;\n    },\n    restore(threadId, state, at) {\n      if (now() - at > maxAgeMs) return;\n      const existing = entries.get(threadId);\n      if (existing && existing.at >= at) return;\n      entries.delete(threadId);\n      entries.set(threadId, { state, at });\n      evict();\n    },\n    forget(threadId) {\n      entries.delete(threadId);\n      notify({ type: 'forget', threadId });\n    },\n    clear() {\n      entries.clear();\n      notify({ type: 'clear' });\n    },\n  };\n}\n\n/**\n * Shape a remembered wire state for use as a mount's `initialState`.\n *\n * Messages/todos and the other app-owned keys seed as captured. The run lane\n * seeds by what the user left: a thread whose run was `running` when the\n * snapshot was taken seeds a running entry (see {@link seedRunsLane}) so the\n * switch back reads Running with a Stop control on its first frame — the same\n * frame `runs: []` would render as \"ready\" with a Send button over a thread the\n * server is still mid-run on. Every other live-lifecycle lane normalizes to\n * resting: a seeded input request could collect a decision the server may have\n * already resolved, so an `input-required` entry seeds as no run at all.\n * `__interrupt__` is dropped for the same reason, and so are `ptc_subagents`\n * (the live in-eval dispatch lane — a seeded \"running\" dispatch card under a\n * resting thread would render active with no eval behind it) and\n * `legacyRunActive` (the host's out-of-band-run-in-progress flag — seeding a\n * finished run's `true` would hide the composer until the attach corrected\n * it). Durable thread properties (`runConfig`, `sessionPersisted`, …) seed as\n * captured; the attach snapshot then replaces the whole seed.\n */\nexport function toThreadSnapshotSeed(state: DeepAgentStreamValues): DeepAgentStreamValues {\n  const {\n    __interrupt__: _interrupt,\n    ptc_subagents: _ptcSubagents,\n    legacyRunActive: _legacyRunActive,\n    ...rest\n  } = state;\n  return { ...rest, runs: seedRunsLane(state.runs) };\n}\n\n/**\n * The run entries a seed carries.\n *\n * Only a `running` entry survives, and only its replicated identity and its\n * durable lanes: `runId` (the target of a Stop sent during the attach\n * round-trip — the live run's id if it is still running, and a refused stop\n * if it finished meanwhile), `epoch` (rides that Stop so a replayed stop cannot\n * end a later leg) and the `queue`/`steerQueue` entries (server lanes the tray\n * renders). The in-flight records rest until the snapshot: `dispatching` and\n * `nextDispatch` are batches the materializer would re-apply onto messages\n * that already contain them, `stopping` is a rewind the host may have\n * finished, `inputRequests` is a parked decision, and `error` is a failure the\n * next user run clears. An entry in any other status — `stopped`, `error`,\n * `input-required` — seeds as no run.\n */\nfunction seedRunsLane(\n  runs: DeepAgentStreamValues['runs']\n): NonNullable<DeepAgentStreamValues['runs']> {\n  const live = runs?.[0];\n  if (live === undefined || live.status !== 'running') return [];\n  return [\n    {\n      runId: live.runId,\n      status: 'running',\n      queue: live.queue,\n      steerQueue: live.steerQueue,\n      ...(live.epoch !== undefined && { epoch: live.epoch }),\n    },\n  ];\n}\n"],"names":[],"mappings":";;AAyEA,MAAM,sBAAsB;AAC5B,MAAM,qBAAqB,KAAK,KAAK;AAE9B,SAAS,mCACd,UAA+C,IACV;AACrC,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,MAAM,QAAQ,QAAQ,MAAM,KAAK,IAAA;AACvC,QAAM,SAAS,CAAC,WAAqD;;AACnE,QAAI;AACF,oBAAQ,aAAR,iCAAmB;AAAA,IACrB,QAAQ;AAAA,IAER;AAAA,EACF;AAGA,QAAM,8BAAc,IAAA;AACpB,QAAM,QAAQ,MAAY;AACxB,WAAO,QAAQ,OAAO,YAAY;AAChC,YAAM,SAAS,QAAQ,KAAA,EAAO,OAAO;AACrC,UAAI,WAAW,OAAW;AAC1B,cAAQ,OAAO,MAAM;AAAA,IACvB;AAAA,EACF;AACA,QAAM,QAAQ,CAAC,aAA+E;AAC5F,UAAM,QAAQ,QAAQ,IAAI,QAAQ;AAClC,QAAI,CAAC,MAAO,QAAO;AACnB,QAAI,IAAA,IAAQ,MAAM,KAAK,UAAU;AAC/B,cAAQ,OAAO,QAAQ;AACvB,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT;AACA,SAAO;AAAA,IACL,SAAS,UAAU,OAAO;AACxB,YAAM,KAAK,IAAA;AACX,cAAQ,OAAO,QAAQ;AACvB,cAAQ,IAAI,UAAU,EAAE,OAAO,IAAI;AACnC,YAAA;AACA,aAAO,EAAE,MAAM,YAAY,UAAU,OAAO,IAAI;AAAA,IAClD;AAAA,IACA,KAAK,UAAU;;AACb,cAAO,WAAM,QAAQ,MAAd,mBAAiB;AAAA,IAC1B;AAAA,IACA,KAAK,UAAU;AACb,aAAO,MAAM,QAAQ,MAAM;AAAA,IAC7B;AAAA,IACA,QAAQ,UAAU,OAAO,IAAI;AAC3B,UAAI,IAAA,IAAQ,KAAK,SAAU;AAC3B,YAAM,WAAW,QAAQ,IAAI,QAAQ;AACrC,UAAI,YAAY,SAAS,MAAM,GAAI;AACnC,cAAQ,OAAO,QAAQ;AACvB,cAAQ,IAAI,UAAU,EAAE,OAAO,IAAI;AACnC,YAAA;AAAA,IACF;AAAA,IACA,OAAO,UAAU;AACf,cAAQ,OAAO,QAAQ;AACvB,aAAO,EAAE,MAAM,UAAU,SAAA,CAAU;AAAA,IACrC;AAAA,IACA,QAAQ;AACN,cAAQ,MAAA;AACR,aAAO,EAAE,MAAM,SAAS;AAAA,IAC1B;AAAA,EAAA;AAEJ;AAqBO,SAAS,qBAAqB,OAAqD;AACxF,QAAM;AAAA,IACJ,eAAe;AAAA,IACf,eAAe;AAAA,IACf,iBAAiB;AAAA,IACjB,GAAG;AAAA,EAAA,IACD;AACJ,SAAO,EAAE,GAAG,MAAM,MAAM,aAAa,MAAM,IAAI,EAAA;AACjD;AAiBA,SAAS,aACP,MAC4C;AAC5C,QAAM,OAAO,6BAAO;AACpB,MAAI,SAAS,UAAa,KAAK,WAAW,kBAAkB,CAAA;AAC5D,SAAO;AAAA,IACL;AAAA,MACE,OAAO,KAAK;AAAA,MACZ,QAAQ;AAAA,MACR,OAAO,KAAK;AAAA,MACZ,YAAY,KAAK;AAAA,MACjB,GAAI,KAAK,UAAU,UAAa,EAAE,OAAO,KAAK,MAAA;AAAA,IAAM;AAAA,EACtD;AAEJ;;;"}
+{"version":3,"file":"thread-snapshot-cache.cjs","sources":["../../../../../agent-runtime/src/thread-snapshot-cache.ts"],"sourcesContent":["import type { DeepAgentStreamValues } from './types';\n\n/**\n * Per-tab LRU of the last wire state seen per thread, so a switch back to a\n * recently-visited thread can mount with that snapshot instead of an empty\n * \"loading\" state (see `UseDeepAgentThreadOptions.snapshotCache`). Entries are\n * references into states the wire already produced — remembering is O(1) and\n * copies nothing; the bound is `maxThreads` retained states.\n */\nexport interface DeepAgentThreadSnapshotCache {\n  /** Record the latest hydrated wire state for a thread. */\n  remember(threadId: string, state: DeepAgentStreamValues): void;\n  /** The freshest remembered state for a thread, or `undefined` when none is\n   * held or the entry aged out. */\n  take(threadId: string): DeepAgentStreamValues | undefined;\n  /**\n   * Drop a single thread's entry. Called when the server refuses\n   * authorization for the thread — a refused thread must not warm-paint on\n   * its next mount.\n   */\n  forget(threadId: string): void;\n  /**\n   * Drop every entry. Called when the acting identity changes — a snapshot\n   * captured under one account must never seed a mount under another.\n   */\n  clear(): void;\n  /**\n   * Whether a fresh entry is held for the thread, without consuming or\n   * touching it. Hosts read it at selection time to decide whether the switch\n   * can paint from a seed (no loading treatment) or must cover the attach\n   * wait. Optional so hand-rolled caches keep type-checking; the built-in\n   * cache implements it.\n   */\n  peek?(threadId: string): boolean;\n}\n\n/** A write observed on the cache — the durable-mirror seam (see `onChange`). */\nexport type DeepAgentThreadSnapshotCacheChange =\n  | { type: 'remember'; threadId: string; state: DeepAgentStreamValues; at: number }\n  | { type: 'forget'; threadId: string }\n  | { type: 'clear' };\n\nexport interface DeepAgentThreadSnapshotCacheOptions {\n  /** Threads retained; the least-recently written entry evicts beyond this. */\n  maxThreads?: number;\n  /**\n   * Entries older than this are dropped at read time. The seed's value is\n   * \"the thread you just left\" — a snapshot from long ago is more likely to\n   * flash content the server has since rewritten than to save a paint.\n   */\n  maxAgeMs?: number;\n  /**\n   * Observer of every write (`remember`, `forget`, `clear`). Hosts mirror\n   * entries into durable storage from here so a reload can seed too; the\n   * observer is never invoked for `restore`, which re-admits mirrored entries.\n   * Exceptions are swallowed — a mirror fault must not break the wire path.\n   */\n  onChange?: (change: DeepAgentThreadSnapshotCacheChange) => void;\n  /** Injectable clock (tests). */\n  now?: () => number;\n}\n\n/** The built-in cache: the host contract plus the durable-mirror re-admission. */\nexport interface CreatedDeepAgentThreadSnapshotCache extends DeepAgentThreadSnapshotCache {\n  peek(threadId: string): boolean;\n  /**\n   * Re-admit an entry captured earlier — a mirrored snapshot after a reload —\n   * under its ORIGINAL capture time, so the age bound still applies. Never\n   * displaces a fresher in-memory entry and never notifies `onChange`.\n   */\n  restore(threadId: string, state: DeepAgentStreamValues, at: number): void;\n}\n\nconst DEFAULT_MAX_THREADS = 30;\nconst DEFAULT_MAX_AGE_MS = 60 * 60 * 1000;\n\nexport function createDeepAgentThreadSnapshotCache(\n  options: DeepAgentThreadSnapshotCacheOptions = {}\n): CreatedDeepAgentThreadSnapshotCache {\n  const maxThreads = options.maxThreads ?? DEFAULT_MAX_THREADS;\n  const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;\n  const now = options.now ?? (() => Date.now());\n  const notify = (change: DeepAgentThreadSnapshotCacheChange): void => {\n    try {\n      options.onChange?.(change);\n    } catch {\n      // The mirror is best-effort; the in-memory cache stays authoritative.\n    }\n  };\n  // Map iteration order is insertion order; delete-then-set on every write\n  // keeps the first key the least-recently written.\n  const entries = new Map<string, { state: DeepAgentStreamValues; at: number }>();\n  const evict = (): void => {\n    while (entries.size > maxThreads) {\n      const oldest = entries.keys().next().value;\n      if (oldest === undefined) break;\n      entries.delete(oldest);\n    }\n  };\n  const fresh = (threadId: string): { state: DeepAgentStreamValues; at: number } | undefined => {\n    const entry = entries.get(threadId);\n    if (!entry) return undefined;\n    if (now() - entry.at > maxAgeMs) {\n      entries.delete(threadId);\n      return undefined;\n    }\n    return entry;\n  };\n  return {\n    remember(threadId, state) {\n      const at = now();\n      entries.delete(threadId);\n      entries.set(threadId, { state, at });\n      evict();\n      notify({ type: 'remember', threadId, state, at });\n    },\n    take(threadId) {\n      return fresh(threadId)?.state;\n    },\n    peek(threadId) {\n      return fresh(threadId) !== undefined;\n    },\n    restore(threadId, state, at) {\n      if (now() - at > maxAgeMs) return;\n      const existing = entries.get(threadId);\n      if (existing && existing.at >= at) return;\n      entries.delete(threadId);\n      entries.set(threadId, { state, at });\n      evict();\n    },\n    forget(threadId) {\n      entries.delete(threadId);\n      notify({ type: 'forget', threadId });\n    },\n    clear() {\n      entries.clear();\n      notify({ type: 'clear' });\n    },\n  };\n}\n\n/**\n * Shape a remembered wire state for use as a mount's `initialState`.\n *\n * Messages/todos and the other app-owned keys seed as captured. The run lane\n * seeds by what the user left: a thread whose run was `running` when the\n * snapshot was taken seeds a running entry (see {@link seedRunsLane}) so the\n * switch back reads Running with a Stop control on its first frame — the same\n * frame `runs: []` would render as \"ready\" with a Send button over a thread the\n * server is still mid-run on. Every other live-lifecycle lane normalizes to\n * resting: a seeded input request could collect a decision the server may have\n * already resolved, so an `input-required` entry seeds as no run at all.\n * `__interrupt__` is dropped for the same reason, and so are `ptc_subagents`\n * (the live in-eval dispatch lane — a seeded \"running\" dispatch card under a\n * resting thread would render active with no eval behind it) and\n * `outOfBandRunActive` (the host's out-of-band-run-in-progress flag — seeding a\n * finished run's `true` would hide the composer until the attach corrected\n * it). Durable thread properties (`runConfig`, `sessionPersisted`, …) seed as\n * captured; the attach snapshot then replaces the whole seed.\n */\nexport function toThreadSnapshotSeed(state: DeepAgentStreamValues): DeepAgentStreamValues {\n  const {\n    __interrupt__: _interrupt,\n    ptc_subagents: _ptcSubagents,\n    outOfBandRunActive: _outOfBandRunActive,\n    ...rest\n  } = state;\n  return { ...rest, runs: seedRunsLane(state.runs) };\n}\n\n/**\n * The run entries a seed carries.\n *\n * Only a `running` entry survives, and only its replicated identity and its\n * durable lanes: `runId` (the target of a Stop sent during the attach\n * round-trip — the live run's id if it is still running, and a refused stop\n * if it finished meanwhile), `epoch` (rides that Stop so a replayed stop cannot\n * end a later leg) and the `queue`/`steerQueue` entries (server lanes the tray\n * renders). The in-flight records rest until the snapshot: `dispatching` and\n * `nextDispatch` are batches the materializer would re-apply onto messages\n * that already contain them, `stopping` is a rewind the host may have\n * finished, `inputRequests` is a parked decision, and `error` is a failure the\n * next user run clears. An entry in any other status — `stopped`, `error`,\n * `input-required` — seeds as no run.\n */\nfunction seedRunsLane(\n  runs: DeepAgentStreamValues['runs']\n): NonNullable<DeepAgentStreamValues['runs']> {\n  const live = runs?.[0];\n  if (live === undefined || live.status !== 'running') return [];\n  return [\n    {\n      runId: live.runId,\n      status: 'running',\n      queue: live.queue,\n      steerQueue: live.steerQueue,\n      ...(live.epoch !== undefined && { epoch: live.epoch }),\n    },\n  ];\n}\n"],"names":[],"mappings":";;AAyEA,MAAM,sBAAsB;AAC5B,MAAM,qBAAqB,KAAK,KAAK;AAE9B,SAAS,mCACd,UAA+C,IACV;AACrC,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,MAAM,QAAQ,QAAQ,MAAM,KAAK,IAAA;AACvC,QAAM,SAAS,CAAC,WAAqD;;AACnE,QAAI;AACF,oBAAQ,aAAR,iCAAmB;AAAA,IACrB,QAAQ;AAAA,IAER;AAAA,EACF;AAGA,QAAM,8BAAc,IAAA;AACpB,QAAM,QAAQ,MAAY;AACxB,WAAO,QAAQ,OAAO,YAAY;AAChC,YAAM,SAAS,QAAQ,KAAA,EAAO,OAAO;AACrC,UAAI,WAAW,OAAW;AAC1B,cAAQ,OAAO,MAAM;AAAA,IACvB;AAAA,EACF;AACA,QAAM,QAAQ,CAAC,aAA+E;AAC5F,UAAM,QAAQ,QAAQ,IAAI,QAAQ;AAClC,QAAI,CAAC,MAAO,QAAO;AACnB,QAAI,IAAA,IAAQ,MAAM,KAAK,UAAU;AAC/B,cAAQ,OAAO,QAAQ;AACvB,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT;AACA,SAAO;AAAA,IACL,SAAS,UAAU,OAAO;AACxB,YAAM,KAAK,IAAA;AACX,cAAQ,OAAO,QAAQ;AACvB,cAAQ,IAAI,UAAU,EAAE,OAAO,IAAI;AACnC,YAAA;AACA,aAAO,EAAE,MAAM,YAAY,UAAU,OAAO,IAAI;AAAA,IAClD;AAAA,IACA,KAAK,UAAU;;AACb,cAAO,WAAM,QAAQ,MAAd,mBAAiB;AAAA,IAC1B;AAAA,IACA,KAAK,UAAU;AACb,aAAO,MAAM,QAAQ,MAAM;AAAA,IAC7B;AAAA,IACA,QAAQ,UAAU,OAAO,IAAI;AAC3B,UAAI,IAAA,IAAQ,KAAK,SAAU;AAC3B,YAAM,WAAW,QAAQ,IAAI,QAAQ;AACrC,UAAI,YAAY,SAAS,MAAM,GAAI;AACnC,cAAQ,OAAO,QAAQ;AACvB,cAAQ,IAAI,UAAU,EAAE,OAAO,IAAI;AACnC,YAAA;AAAA,IACF;AAAA,IACA,OAAO,UAAU;AACf,cAAQ,OAAO,QAAQ;AACvB,aAAO,EAAE,MAAM,UAAU,SAAA,CAAU;AAAA,IACrC;AAAA,IACA,QAAQ;AACN,cAAQ,MAAA;AACR,aAAO,EAAE,MAAM,SAAS;AAAA,IAC1B;AAAA,EAAA;AAEJ;AAqBO,SAAS,qBAAqB,OAAqD;AACxF,QAAM;AAAA,IACJ,eAAe;AAAA,IACf,eAAe;AAAA,IACf,oBAAoB;AAAA,IACpB,GAAG;AAAA,EAAA,IACD;AACJ,SAAO,EAAE,GAAG,MAAM,MAAM,aAAa,MAAM,IAAI,EAAA;AACjD;AAiBA,SAAS,aACP,MAC4C;AAC5C,QAAM,OAAO,6BAAO;AACpB,MAAI,SAAS,UAAa,KAAK,WAAW,kBAAkB,CAAA;AAC5D,SAAO;AAAA,IACL;AAAA,MACE,OAAO,KAAK;AAAA,MACZ,QAAQ;AAAA,MACR,OAAO,KAAK;AAAA,MACZ,YAAY,KAAK;AAAA,MACjB,GAAI,KAAK,UAAU,UAAa,EAAE,OAAO,KAAK,MAAA;AAAA,IAAM;AAAA,EACtD;AAEJ;;;"}

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

@@ -65,7 +65,7 @@ function toThreadSnapshotSeed(state) {
   const {
     __interrupt__: _interrupt,
     ptc_subagents: _ptcSubagents,
-    legacyRunActive: _legacyRunActive,
+    outOfBandRunActive: _outOfBandRunActive,
     ...rest
   } = state;
   return { ...rest, runs: seedRunsLane(state.runs) };

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

@@ -1 +1 @@
-{"version":3,"file":"thread-snapshot-cache.js","sources":["../../../../../agent-runtime/src/thread-snapshot-cache.ts"],"sourcesContent":["import type { DeepAgentStreamValues } from './types';\n\n/**\n * Per-tab LRU of the last wire state seen per thread, so a switch back to a\n * recently-visited thread can mount with that snapshot instead of an empty\n * \"loading\" state (see `UseDeepAgentThreadOptions.snapshotCache`). Entries are\n * references into states the wire already produced — remembering is O(1) and\n * copies nothing; the bound is `maxThreads` retained states.\n */\nexport interface DeepAgentThreadSnapshotCache {\n  /** Record the latest hydrated wire state for a thread. */\n  remember(threadId: string, state: DeepAgentStreamValues): void;\n  /** The freshest remembered state for a thread, or `undefined` when none is\n   * held or the entry aged out. */\n  take(threadId: string): DeepAgentStreamValues | undefined;\n  /**\n   * Drop a single thread's entry. Called when the server refuses\n   * authorization for the thread — a refused thread must not warm-paint on\n   * its next mount.\n   */\n  forget(threadId: string): void;\n  /**\n   * Drop every entry. Called when the acting identity changes — a snapshot\n   * captured under one account must never seed a mount under another.\n   */\n  clear(): void;\n  /**\n   * Whether a fresh entry is held for the thread, without consuming or\n   * touching it. Hosts read it at selection time to decide whether the switch\n   * can paint from a seed (no loading treatment) or must cover the attach\n   * wait. Optional so hand-rolled caches keep type-checking; the built-in\n   * cache implements it.\n   */\n  peek?(threadId: string): boolean;\n}\n\n/** A write observed on the cache — the durable-mirror seam (see `onChange`). */\nexport type DeepAgentThreadSnapshotCacheChange =\n  | { type: 'remember'; threadId: string; state: DeepAgentStreamValues; at: number }\n  | { type: 'forget'; threadId: string }\n  | { type: 'clear' };\n\nexport interface DeepAgentThreadSnapshotCacheOptions {\n  /** Threads retained; the least-recently written entry evicts beyond this. */\n  maxThreads?: number;\n  /**\n   * Entries older than this are dropped at read time. The seed's value is\n   * \"the thread you just left\" — a snapshot from long ago is more likely to\n   * flash content the server has since rewritten than to save a paint.\n   */\n  maxAgeMs?: number;\n  /**\n   * Observer of every write (`remember`, `forget`, `clear`). Hosts mirror\n   * entries into durable storage from here so a reload can seed too; the\n   * observer is never invoked for `restore`, which re-admits mirrored entries.\n   * Exceptions are swallowed — a mirror fault must not break the wire path.\n   */\n  onChange?: (change: DeepAgentThreadSnapshotCacheChange) => void;\n  /** Injectable clock (tests). */\n  now?: () => number;\n}\n\n/** The built-in cache: the host contract plus the durable-mirror re-admission. */\nexport interface CreatedDeepAgentThreadSnapshotCache extends DeepAgentThreadSnapshotCache {\n  peek(threadId: string): boolean;\n  /**\n   * Re-admit an entry captured earlier — a mirrored snapshot after a reload —\n   * under its ORIGINAL capture time, so the age bound still applies. Never\n   * displaces a fresher in-memory entry and never notifies `onChange`.\n   */\n  restore(threadId: string, state: DeepAgentStreamValues, at: number): void;\n}\n\nconst DEFAULT_MAX_THREADS = 30;\nconst DEFAULT_MAX_AGE_MS = 60 * 60 * 1000;\n\nexport function createDeepAgentThreadSnapshotCache(\n  options: DeepAgentThreadSnapshotCacheOptions = {}\n): CreatedDeepAgentThreadSnapshotCache {\n  const maxThreads = options.maxThreads ?? DEFAULT_MAX_THREADS;\n  const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;\n  const now = options.now ?? (() => Date.now());\n  const notify = (change: DeepAgentThreadSnapshotCacheChange): void => {\n    try {\n      options.onChange?.(change);\n    } catch {\n      // The mirror is best-effort; the in-memory cache stays authoritative.\n    }\n  };\n  // Map iteration order is insertion order; delete-then-set on every write\n  // keeps the first key the least-recently written.\n  const entries = new Map<string, { state: DeepAgentStreamValues; at: number }>();\n  const evict = (): void => {\n    while (entries.size > maxThreads) {\n      const oldest = entries.keys().next().value;\n      if (oldest === undefined) break;\n      entries.delete(oldest);\n    }\n  };\n  const fresh = (threadId: string): { state: DeepAgentStreamValues; at: number } | undefined => {\n    const entry = entries.get(threadId);\n    if (!entry) return undefined;\n    if (now() - entry.at > maxAgeMs) {\n      entries.delete(threadId);\n      return undefined;\n    }\n    return entry;\n  };\n  return {\n    remember(threadId, state) {\n      const at = now();\n      entries.delete(threadId);\n      entries.set(threadId, { state, at });\n      evict();\n      notify({ type: 'remember', threadId, state, at });\n    },\n    take(threadId) {\n      return fresh(threadId)?.state;\n    },\n    peek(threadId) {\n      return fresh(threadId) !== undefined;\n    },\n    restore(threadId, state, at) {\n      if (now() - at > maxAgeMs) return;\n      const existing = entries.get(threadId);\n      if (existing && existing.at >= at) return;\n      entries.delete(threadId);\n      entries.set(threadId, { state, at });\n      evict();\n    },\n    forget(threadId) {\n      entries.delete(threadId);\n      notify({ type: 'forget', threadId });\n    },\n    clear() {\n      entries.clear();\n      notify({ type: 'clear' });\n    },\n  };\n}\n\n/**\n * Shape a remembered wire state for use as a mount's `initialState`.\n *\n * Messages/todos and the other app-owned keys seed as captured. The run lane\n * seeds by what the user left: a thread whose run was `running` when the\n * snapshot was taken seeds a running entry (see {@link seedRunsLane}) so the\n * switch back reads Running with a Stop control on its first frame — the same\n * frame `runs: []` would render as \"ready\" with a Send button over a thread the\n * server is still mid-run on. Every other live-lifecycle lane normalizes to\n * resting: a seeded input request could collect a decision the server may have\n * already resolved, so an `input-required` entry seeds as no run at all.\n * `__interrupt__` is dropped for the same reason, and so are `ptc_subagents`\n * (the live in-eval dispatch lane — a seeded \"running\" dispatch card under a\n * resting thread would render active with no eval behind it) and\n * `legacyRunActive` (the host's out-of-band-run-in-progress flag — seeding a\n * finished run's `true` would hide the composer until the attach corrected\n * it). Durable thread properties (`runConfig`, `sessionPersisted`, …) seed as\n * captured; the attach snapshot then replaces the whole seed.\n */\nexport function toThreadSnapshotSeed(state: DeepAgentStreamValues): DeepAgentStreamValues {\n  const {\n    __interrupt__: _interrupt,\n    ptc_subagents: _ptcSubagents,\n    legacyRunActive: _legacyRunActive,\n    ...rest\n  } = state;\n  return { ...rest, runs: seedRunsLane(state.runs) };\n}\n\n/**\n * The run entries a seed carries.\n *\n * Only a `running` entry survives, and only its replicated identity and its\n * durable lanes: `runId` (the target of a Stop sent during the attach\n * round-trip — the live run's id if it is still running, and a refused stop\n * if it finished meanwhile), `epoch` (rides that Stop so a replayed stop cannot\n * end a later leg) and the `queue`/`steerQueue` entries (server lanes the tray\n * renders). The in-flight records rest until the snapshot: `dispatching` and\n * `nextDispatch` are batches the materializer would re-apply onto messages\n * that already contain them, `stopping` is a rewind the host may have\n * finished, `inputRequests` is a parked decision, and `error` is a failure the\n * next user run clears. An entry in any other status — `stopped`, `error`,\n * `input-required` — seeds as no run.\n */\nfunction seedRunsLane(\n  runs: DeepAgentStreamValues['runs']\n): NonNullable<DeepAgentStreamValues['runs']> {\n  const live = runs?.[0];\n  if (live === undefined || live.status !== 'running') return [];\n  return [\n    {\n      runId: live.runId,\n      status: 'running',\n      queue: live.queue,\n      steerQueue: live.steerQueue,\n      ...(live.epoch !== undefined && { epoch: live.epoch }),\n    },\n  ];\n}\n"],"names":[],"mappings":"AAyEA,MAAM,sBAAsB;AAC5B,MAAM,qBAAqB,KAAK,KAAK;AAE9B,SAAS,mCACd,UAA+C,IACV;AACrC,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,MAAM,QAAQ,QAAQ,MAAM,KAAK,IAAA;AACvC,QAAM,SAAS,CAAC,WAAqD;AATvE;AAUI,QAAI;AACF,oBAAQ,aAAR,iCAAmB;AAAA,IACrB,QAAQ;AAAA,IAER;AAAA,EACF;AAGA,QAAM,8BAAc,IAAA;AACpB,QAAM,QAAQ,MAAY;AACxB,WAAO,QAAQ,OAAO,YAAY;AAChC,YAAM,SAAS,QAAQ,KAAA,EAAO,OAAO;AACrC,UAAI,WAAW,OAAW;AAC1B,cAAQ,OAAO,MAAM;AAAA,IACvB;AAAA,EACF;AACA,QAAM,QAAQ,CAAC,aAA+E;AAC5F,UAAM,QAAQ,QAAQ,IAAI,QAAQ;AAClC,QAAI,CAAC,MAAO,QAAO;AACnB,QAAI,IAAA,IAAQ,MAAM,KAAK,UAAU;AAC/B,cAAQ,OAAO,QAAQ;AACvB,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT;AACA,SAAO;AAAA,IACL,SAAS,UAAU,OAAO;AACxB,YAAM,KAAK,IAAA;AACX,cAAQ,OAAO,QAAQ;AACvB,cAAQ,IAAI,UAAU,EAAE,OAAO,IAAI;AACnC,YAAA;AACA,aAAO,EAAE,MAAM,YAAY,UAAU,OAAO,IAAI;AAAA,IAClD;AAAA,IACA,KAAK,UAAU;AA3CnB;AA4CM,cAAO,WAAM,QAAQ,MAAd,mBAAiB;AAAA,IAC1B;AAAA,IACA,KAAK,UAAU;AACb,aAAO,MAAM,QAAQ,MAAM;AAAA,IAC7B;AAAA,IACA,QAAQ,UAAU,OAAO,IAAI;AAC3B,UAAI,IAAA,IAAQ,KAAK,SAAU;AAC3B,YAAM,WAAW,QAAQ,IAAI,QAAQ;AACrC,UAAI,YAAY,SAAS,MAAM,GAAI;AACnC,cAAQ,OAAO,QAAQ;AACvB,cAAQ,IAAI,UAAU,EAAE,OAAO,IAAI;AACnC,YAAA;AAAA,IACF;AAAA,IACA,OAAO,UAAU;AACf,cAAQ,OAAO,QAAQ;AACvB,aAAO,EAAE,MAAM,UAAU,SAAA,CAAU;AAAA,IACrC;AAAA,IACA,QAAQ;AACN,cAAQ,MAAA;AACR,aAAO,EAAE,MAAM,SAAS;AAAA,IAC1B;AAAA,EAAA;AAEJ;AAqBO,SAAS,qBAAqB,OAAqD;AACxF,QAAM;AAAA,IACJ,eAAe;AAAA,IACf,eAAe;AAAA,IACf,iBAAiB;AAAA,IACjB,GAAG;AAAA,EAAA,IACD;AACJ,SAAO,EAAE,GAAG,MAAM,MAAM,aAAa,MAAM,IAAI,EAAA;AACjD;AAiBA,SAAS,aACP,MAC4C;AAC5C,QAAM,OAAO,6BAAO;AACpB,MAAI,SAAS,UAAa,KAAK,WAAW,kBAAkB,CAAA;AAC5D,SAAO;AAAA,IACL;AAAA,MACE,OAAO,KAAK;AAAA,MACZ,QAAQ;AAAA,MACR,OAAO,KAAK;AAAA,MACZ,YAAY,KAAK;AAAA,MACjB,GAAI,KAAK,UAAU,UAAa,EAAE,OAAO,KAAK,MAAA;AAAA,IAAM;AAAA,EACtD;AAEJ;"}
+{"version":3,"file":"thread-snapshot-cache.js","sources":["../../../../../agent-runtime/src/thread-snapshot-cache.ts"],"sourcesContent":["import type { DeepAgentStreamValues } from './types';\n\n/**\n * Per-tab LRU of the last wire state seen per thread, so a switch back to a\n * recently-visited thread can mount with that snapshot instead of an empty\n * \"loading\" state (see `UseDeepAgentThreadOptions.snapshotCache`). Entries are\n * references into states the wire already produced — remembering is O(1) and\n * copies nothing; the bound is `maxThreads` retained states.\n */\nexport interface DeepAgentThreadSnapshotCache {\n  /** Record the latest hydrated wire state for a thread. */\n  remember(threadId: string, state: DeepAgentStreamValues): void;\n  /** The freshest remembered state for a thread, or `undefined` when none is\n   * held or the entry aged out. */\n  take(threadId: string): DeepAgentStreamValues | undefined;\n  /**\n   * Drop a single thread's entry. Called when the server refuses\n   * authorization for the thread — a refused thread must not warm-paint on\n   * its next mount.\n   */\n  forget(threadId: string): void;\n  /**\n   * Drop every entry. Called when the acting identity changes — a snapshot\n   * captured under one account must never seed a mount under another.\n   */\n  clear(): void;\n  /**\n   * Whether a fresh entry is held for the thread, without consuming or\n   * touching it. Hosts read it at selection time to decide whether the switch\n   * can paint from a seed (no loading treatment) or must cover the attach\n   * wait. Optional so hand-rolled caches keep type-checking; the built-in\n   * cache implements it.\n   */\n  peek?(threadId: string): boolean;\n}\n\n/** A write observed on the cache — the durable-mirror seam (see `onChange`). */\nexport type DeepAgentThreadSnapshotCacheChange =\n  | { type: 'remember'; threadId: string; state: DeepAgentStreamValues; at: number }\n  | { type: 'forget'; threadId: string }\n  | { type: 'clear' };\n\nexport interface DeepAgentThreadSnapshotCacheOptions {\n  /** Threads retained; the least-recently written entry evicts beyond this. */\n  maxThreads?: number;\n  /**\n   * Entries older than this are dropped at read time. The seed's value is\n   * \"the thread you just left\" — a snapshot from long ago is more likely to\n   * flash content the server has since rewritten than to save a paint.\n   */\n  maxAgeMs?: number;\n  /**\n   * Observer of every write (`remember`, `forget`, `clear`). Hosts mirror\n   * entries into durable storage from here so a reload can seed too; the\n   * observer is never invoked for `restore`, which re-admits mirrored entries.\n   * Exceptions are swallowed — a mirror fault must not break the wire path.\n   */\n  onChange?: (change: DeepAgentThreadSnapshotCacheChange) => void;\n  /** Injectable clock (tests). */\n  now?: () => number;\n}\n\n/** The built-in cache: the host contract plus the durable-mirror re-admission. */\nexport interface CreatedDeepAgentThreadSnapshotCache extends DeepAgentThreadSnapshotCache {\n  peek(threadId: string): boolean;\n  /**\n   * Re-admit an entry captured earlier — a mirrored snapshot after a reload —\n   * under its ORIGINAL capture time, so the age bound still applies. Never\n   * displaces a fresher in-memory entry and never notifies `onChange`.\n   */\n  restore(threadId: string, state: DeepAgentStreamValues, at: number): void;\n}\n\nconst DEFAULT_MAX_THREADS = 30;\nconst DEFAULT_MAX_AGE_MS = 60 * 60 * 1000;\n\nexport function createDeepAgentThreadSnapshotCache(\n  options: DeepAgentThreadSnapshotCacheOptions = {}\n): CreatedDeepAgentThreadSnapshotCache {\n  const maxThreads = options.maxThreads ?? DEFAULT_MAX_THREADS;\n  const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;\n  const now = options.now ?? (() => Date.now());\n  const notify = (change: DeepAgentThreadSnapshotCacheChange): void => {\n    try {\n      options.onChange?.(change);\n    } catch {\n      // The mirror is best-effort; the in-memory cache stays authoritative.\n    }\n  };\n  // Map iteration order is insertion order; delete-then-set on every write\n  // keeps the first key the least-recently written.\n  const entries = new Map<string, { state: DeepAgentStreamValues; at: number }>();\n  const evict = (): void => {\n    while (entries.size > maxThreads) {\n      const oldest = entries.keys().next().value;\n      if (oldest === undefined) break;\n      entries.delete(oldest);\n    }\n  };\n  const fresh = (threadId: string): { state: DeepAgentStreamValues; at: number } | undefined => {\n    const entry = entries.get(threadId);\n    if (!entry) return undefined;\n    if (now() - entry.at > maxAgeMs) {\n      entries.delete(threadId);\n      return undefined;\n    }\n    return entry;\n  };\n  return {\n    remember(threadId, state) {\n      const at = now();\n      entries.delete(threadId);\n      entries.set(threadId, { state, at });\n      evict();\n      notify({ type: 'remember', threadId, state, at });\n    },\n    take(threadId) {\n      return fresh(threadId)?.state;\n    },\n    peek(threadId) {\n      return fresh(threadId) !== undefined;\n    },\n    restore(threadId, state, at) {\n      if (now() - at > maxAgeMs) return;\n      const existing = entries.get(threadId);\n      if (existing && existing.at >= at) return;\n      entries.delete(threadId);\n      entries.set(threadId, { state, at });\n      evict();\n    },\n    forget(threadId) {\n      entries.delete(threadId);\n      notify({ type: 'forget', threadId });\n    },\n    clear() {\n      entries.clear();\n      notify({ type: 'clear' });\n    },\n  };\n}\n\n/**\n * Shape a remembered wire state for use as a mount's `initialState`.\n *\n * Messages/todos and the other app-owned keys seed as captured. The run lane\n * seeds by what the user left: a thread whose run was `running` when the\n * snapshot was taken seeds a running entry (see {@link seedRunsLane}) so the\n * switch back reads Running with a Stop control on its first frame — the same\n * frame `runs: []` would render as \"ready\" with a Send button over a thread the\n * server is still mid-run on. Every other live-lifecycle lane normalizes to\n * resting: a seeded input request could collect a decision the server may have\n * already resolved, so an `input-required` entry seeds as no run at all.\n * `__interrupt__` is dropped for the same reason, and so are `ptc_subagents`\n * (the live in-eval dispatch lane — a seeded \"running\" dispatch card under a\n * resting thread would render active with no eval behind it) and\n * `outOfBandRunActive` (the host's out-of-band-run-in-progress flag — seeding a\n * finished run's `true` would hide the composer until the attach corrected\n * it). Durable thread properties (`runConfig`, `sessionPersisted`, …) seed as\n * captured; the attach snapshot then replaces the whole seed.\n */\nexport function toThreadSnapshotSeed(state: DeepAgentStreamValues): DeepAgentStreamValues {\n  const {\n    __interrupt__: _interrupt,\n    ptc_subagents: _ptcSubagents,\n    outOfBandRunActive: _outOfBandRunActive,\n    ...rest\n  } = state;\n  return { ...rest, runs: seedRunsLane(state.runs) };\n}\n\n/**\n * The run entries a seed carries.\n *\n * Only a `running` entry survives, and only its replicated identity and its\n * durable lanes: `runId` (the target of a Stop sent during the attach\n * round-trip — the live run's id if it is still running, and a refused stop\n * if it finished meanwhile), `epoch` (rides that Stop so a replayed stop cannot\n * end a later leg) and the `queue`/`steerQueue` entries (server lanes the tray\n * renders). The in-flight records rest until the snapshot: `dispatching` and\n * `nextDispatch` are batches the materializer would re-apply onto messages\n * that already contain them, `stopping` is a rewind the host may have\n * finished, `inputRequests` is a parked decision, and `error` is a failure the\n * next user run clears. An entry in any other status — `stopped`, `error`,\n * `input-required` — seeds as no run.\n */\nfunction seedRunsLane(\n  runs: DeepAgentStreamValues['runs']\n): NonNullable<DeepAgentStreamValues['runs']> {\n  const live = runs?.[0];\n  if (live === undefined || live.status !== 'running') return [];\n  return [\n    {\n      runId: live.runId,\n      status: 'running',\n      queue: live.queue,\n      steerQueue: live.steerQueue,\n      ...(live.epoch !== undefined && { epoch: live.epoch }),\n    },\n  ];\n}\n"],"names":[],"mappings":"AAyEA,MAAM,sBAAsB;AAC5B,MAAM,qBAAqB,KAAK,KAAK;AAE9B,SAAS,mCACd,UAA+C,IACV;AACrC,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,MAAM,QAAQ,QAAQ,MAAM,KAAK,IAAA;AACvC,QAAM,SAAS,CAAC,WAAqD;AATvE;AAUI,QAAI;AACF,oBAAQ,aAAR,iCAAmB;AAAA,IACrB,QAAQ;AAAA,IAER;AAAA,EACF;AAGA,QAAM,8BAAc,IAAA;AACpB,QAAM,QAAQ,MAAY;AACxB,WAAO,QAAQ,OAAO,YAAY;AAChC,YAAM,SAAS,QAAQ,KAAA,EAAO,OAAO;AACrC,UAAI,WAAW,OAAW;AAC1B,cAAQ,OAAO,MAAM;AAAA,IACvB;AAAA,EACF;AACA,QAAM,QAAQ,CAAC,aAA+E;AAC5F,UAAM,QAAQ,QAAQ,IAAI,QAAQ;AAClC,QAAI,CAAC,MAAO,QAAO;AACnB,QAAI,IAAA,IAAQ,MAAM,KAAK,UAAU;AAC/B,cAAQ,OAAO,QAAQ;AACvB,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT;AACA,SAAO;AAAA,IACL,SAAS,UAAU,OAAO;AACxB,YAAM,KAAK,IAAA;AACX,cAAQ,OAAO,QAAQ;AACvB,cAAQ,IAAI,UAAU,EAAE,OAAO,IAAI;AACnC,YAAA;AACA,aAAO,EAAE,MAAM,YAAY,UAAU,OAAO,IAAI;AAAA,IAClD;AAAA,IACA,KAAK,UAAU;AA3CnB;AA4CM,cAAO,WAAM,QAAQ,MAAd,mBAAiB;AAAA,IAC1B;AAAA,IACA,KAAK,UAAU;AACb,aAAO,MAAM,QAAQ,MAAM;AAAA,IAC7B;AAAA,IACA,QAAQ,UAAU,OAAO,IAAI;AAC3B,UAAI,IAAA,IAAQ,KAAK,SAAU;AAC3B,YAAM,WAAW,QAAQ,IAAI,QAAQ;AACrC,UAAI,YAAY,SAAS,MAAM,GAAI;AACnC,cAAQ,OAAO,QAAQ;AACvB,cAAQ,IAAI,UAAU,EAAE,OAAO,IAAI;AACnC,YAAA;AAAA,IACF;AAAA,IACA,OAAO,UAAU;AACf,cAAQ,OAAO,QAAQ;AACvB,aAAO,EAAE,MAAM,UAAU,SAAA,CAAU;AAAA,IACrC;AAAA,IACA,QAAQ;AACN,cAAQ,MAAA;AACR,aAAO,EAAE,MAAM,SAAS;AAAA,IAC1B;AAAA,EAAA;AAEJ;AAqBO,SAAS,qBAAqB,OAAqD;AACxF,QAAM;AAAA,IACJ,eAAe;AAAA,IACf,eAAe;AAAA,IACf,oBAAoB;AAAA,IACpB,GAAG;AAAA,EAAA,IACD;AACJ,SAAO,EAAE,GAAG,MAAM,MAAM,aAAa,MAAM,IAAI,EAAA;AACjD;AAiBA,SAAS,aACP,MAC4C;AAC5C,QAAM,OAAO,6BAAO;AACpB,MAAI,SAAS,UAAa,KAAK,WAAW,kBAAkB,CAAA;AAC5D,SAAO;AAAA,IACL;AAAA,MACE,OAAO,KAAK;AAAA,MACZ,QAAQ;AAAA,MACR,OAAO,KAAK;AAAA,MACZ,YAAY,KAAK;AAAA,MACjB,GAAI,KAAK,UAAU,UAAa,EAAE,OAAO,KAAK,MAAA;AAAA,IAAM;AAAA,EACtD;AAEJ;"}

package/dist/packages/agent-runtime/src/tool-metadata.cjs

@@ -105,14 +105,6 @@ const TOOL_DISPLAY_META = {
     emoji: "🔍",
     describe: describeQuery
   },
-  semantic_search: {
-    displayName: "Semantic Search",
-    activeLabel: "Searching your sources",
-    category: "Web",
-    icon: "search",
-    emoji: "🔍",
-    describe: describeQuery
-  },
   deep_research: {
     displayName: "Deep Research",
     activeLabel: "Researching",