@athenaintel/react 0.19.0 → 0.21.0

package/dist/packages/agent-runtime/src/runtime-messages.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-messages.cjs","sources":["../../../../../agent-runtime/src/runtime-messages.ts"],"sourcesContent":["/**\n * Typed runtime messages — the one description of \"the runtime ended this run\"\n * that every chat surface renders from.\n *\n * The deep-agent backend records how a run ended in two shapes that ride\n * ordinary `ai` messages (a new LangChain message type would crash the shipped\n * converter, whose convertible set is closed):\n *\n * - a **run-lifecycle marker** (`athena_run_marker`: `cancelled` / `failed`,\n *   plus `athena_run_marker_source`) — see {@link readRunMarkerFromSourceMessages};\n * - a **handoff message** (`athena_handoff: true`) — the closing summary the\n *   runtime asked the model to write when a guard or the step budget ended the\n *   run, instead of fabricating an internal sentence.\n *\n * Both now carry the canonical `athena_termination_reason`\n * (`agora/graphs/athena_deep_agent/termination.py`). This module reads all of\n * that into one {@link AthenaRuntimeMessage} so Olympus, mobile, the Chrome\n * extension, and the Office add-in agree on kind, severity, copy, and the\n * sole-vs-grouped distinction — the last of which is load-bearing: a marker\n * appended after the assistant's own work is chunked into that message, and\n * replacing the whole row would hide completed prose and tool cards.\n */\n\nimport { getExternalStoreMessages } from '@assistant-ui/core';\nimport type { LangChainMessage } from '@assistant-ui/react-langgraph';\nimport {\n  ATHENA_HANDOFF_KEY,\n  ATHENA_RUN_MARKER_CANCELLED,\n  ATHENA_RUN_MARKER_FAILED,\n  ATHENA_RUN_MARKER_KEY,\n  ATHENA_RUN_MARKER_SOURCE_KEY,\n  ATHENA_STOP_SOURCE_SEND_NOW,\n  ATHENA_TERMINATION_REASON_KEY,\n  isServerUpdateStopSource,\n} from './messages';\n\n/** The backend's canonical reason vocabulary (`KNOWN_TERMINATION_REASONS`). */\nexport const TERMINATION_REASONS = [\n  'completed',\n  'user_stop',\n  'send_now',\n  'voice_steer',\n  'transport_cancel',\n  'pod_drain',\n  'fence_lost',\n  'instance_closed',\n  'unattributed_stop',\n  'recursion_limit',\n  'step_budget',\n  'duplicate_call_guard',\n  'synthetic_stop',\n  'ended_after_tools',\n  'error',\n  'model_refusal',\n  'abandoned',\n] as const;\n\nexport type AthenaTerminationReason = (typeof TERMINATION_REASONS)[number];\n\n/**\n * How a runtime ending renders:\n * - `stopped` — a cancellation the user (or a client action) asked for;\n * - `paused` — a pod-drain pause; the run resumes from its checkpoint;\n * - `failed` — the graph raised, hit the recursion limit, or was abandoned;\n * - `handoff` — the runtime ended the run and the model wrote a closing\n *   summary (the message text), which renders as prose under a banner.\n */\nexport type AthenaRuntimeMessageKind = 'stopped' | 'paused' | 'failed' | 'handoff';\n\nexport type AthenaRuntimeMessageSeverity = 'info' | 'warning' | 'error';\n\nexport interface TerminationDescription {\n  /** Short label for the banner / status row. */\n  title: string;\n  /** One sentence of reason-specific explanation, when it adds information. */\n  detail: string | undefined;\n}\n\nexport interface AthenaRuntimeMessage {\n  kind: AthenaRuntimeMessageKind;\n  /** Canonical reason (may be a value newer than this client knows). */\n  reason: string | undefined;\n  severity: AthenaRuntimeMessageSeverity;\n  title: string;\n  detail: string | undefined;\n  /** The message's own text: a marker's backend copy, or the handoff summary. */\n  text: string | undefined;\n  /**\n   * A `send_now` promotion cancels the live run as plumbing, not as a\n   * user-visible stop: keep it in the data, paint nothing.\n   */\n  silent: boolean;\n  /**\n   * True when the runtime message is the ONLY source message behind this\n   * thread message (it owns the whole row). False when the chunk also holds\n   * the assistant's own work, which must keep rendering.\n   */\n  isSoleSourceMessage: boolean;\n}\n\nconst MAX_STEPS_HINT = 'Raise “Max steps” in the agent settings for longer runs.';\n\n/**\n * Copy for a runtime ending. Reasons this client does not know fall back to\n * the kind's generic title, so a newer backend never renders as an empty row.\n */\nexport function describeTerminationReason(\n  kind: AthenaRuntimeMessageKind,\n  reason: string | undefined\n): TerminationDescription {\n  switch (kind) {\n    case 'paused':\n      return {\n        title: 'Paused by a server update',\n        detail: 'Progress up to this point is saved — send a message to continue.',\n      };\n    case 'stopped':\n      switch (reason) {\n        case 'voice_steer':\n          return {\n            title: 'Redirected by a spoken follow-up',\n            detail:\n              'The voice conversation changed the request; the work continues with the new instructions.',\n          };\n        case 'transport_cancel':\n          return {\n            title: 'Run cancelled',\n            detail:\n              'Cancelled by a page reload, navigation, or closed view — not an explicit Stop. Send a follow-up to continue.',\n          };\n        case 'fence_lost':\n          return {\n            title: 'Run superseded',\n            detail: 'Another activation took over this thread.',\n          };\n        case 'instance_closed':\n          return {\n            title: 'Run stopped',\n            detail: 'The client that started it went away.',\n          };\n        default:\n          return { title: 'Conversation stopped', detail: undefined };\n      }\n    case 'failed':\n      switch (reason) {\n        case 'recursion_limit':\n          return {\n            title: 'Step limit reached',\n            detail: `The run was stopped before finishing; the work so far is saved. ${MAX_STEPS_HINT}`,\n          };\n        case 'abandoned':\n          return {\n            title: 'Run stopped unexpectedly',\n            detail:\n              'The server handling it went away mid-run (a crash, restart, or deploy). The work so far is saved.',\n          };\n        default:\n          return { title: 'Run failed', detail: undefined };\n      }\n    case 'handoff':\n      switch (reason) {\n        case 'duplicate_call_guard':\n          return {\n            title: 'Run ended by the runtime',\n            detail:\n              'The same tool calls were repeating with identical arguments and no new progress, so the agent was asked to wrap up.',\n          };\n        case 'step_budget':\n          return {\n            title: 'Run ended by the runtime',\n            detail: `The step budget ran out, so the agent was asked to wrap up. ${MAX_STEPS_HINT}`,\n          };\n        default:\n          return {\n            title: 'Run ended by the runtime',\n            detail: 'The agent was asked to wrap up.',\n          };\n      }\n  }\n}\n\nconst SEVERITY: Record<AthenaRuntimeMessageKind, AthenaRuntimeMessageSeverity> = {\n  stopped: 'info',\n  paused: 'info',\n  failed: 'error',\n  handoff: 'warning',\n};\n\ntype Kwargs = Record<string, unknown> | undefined;\n\nfunction metadataOf(kwargs: Kwargs): Record<string, unknown> | undefined {\n  const metadata = kwargs?.metadata;\n  return typeof metadata === 'object' && metadata !== null\n    ? (metadata as Record<string, unknown>)\n    : undefined;\n}\n\n/** The termination reason stamped on `additional_kwargs` (top-level or mirror). */\nexport function readTerminationReason(kwargs: Kwargs): string | undefined {\n  const top = kwargs?.[ATHENA_TERMINATION_REASON_KEY];\n  if (typeof top === 'string') return top;\n  const mirrored = metadataOf(kwargs)?.[ATHENA_TERMINATION_REASON_KEY];\n  return typeof mirrored === 'string' ? mirrored : undefined;\n}\n\nfunction readHandoff(kwargs: Kwargs): boolean {\n  return kwargs?.[ATHENA_HANDOFF_KEY] === true || metadataOf(kwargs)?.[ATHENA_HANDOFF_KEY] === true;\n}\n\nfunction textOf(content: unknown): string | undefined {\n  if (typeof content === 'string') return content;\n  if (!Array.isArray(content)) return undefined;\n  const texts = content\n    .map((block) =>\n      typeof block === 'string'\n        ? block\n        : block && typeof block === 'object' && (block as { type?: unknown }).type === 'text'\n          ? (block as { text?: unknown }).text\n          : undefined\n    )\n    .filter((text): text is string => typeof text === 'string' && text.length > 0);\n  return texts.length > 0 ? texts.join('\\n') : undefined;\n}\n\nfunction fromMarker(\n  marker: string,\n  source: string | undefined,\n  reason: string | undefined\n): Pick<AthenaRuntimeMessage, 'kind' | 'reason' | 'silent'> | undefined {\n  if (marker === ATHENA_RUN_MARKER_CANCELLED) {\n    const kind: AthenaRuntimeMessageKind = isServerUpdateStopSource(source) ? 'paused' : 'stopped';\n    return {\n      kind,\n      reason: reason ?? (source === 'unattributed' ? 'unattributed_stop' : source),\n      silent: source === ATHENA_STOP_SOURCE_SEND_NOW,\n    };\n  }\n  if (marker === ATHENA_RUN_MARKER_FAILED) {\n    return { kind: 'failed', reason: reason ?? 'error', silent: false };\n  }\n  return undefined;\n}\n\nfunction build(\n  partial: Pick<AthenaRuntimeMessage, 'kind' | 'reason' | 'silent'>,\n  text: string | undefined,\n  isSoleSourceMessage: boolean\n): AthenaRuntimeMessage {\n  const description = describeTerminationReason(partial.kind, partial.reason);\n  return {\n    kind: partial.kind,\n    reason: partial.reason,\n    severity: SEVERITY[partial.kind],\n    title: description.title,\n    detail: description.detail,\n    text,\n    silent: partial.silent,\n    isSoleSourceMessage,\n  };\n}\n\n/**\n * Read the runtime ending behind a thread message, from its bound source\n * messages first (a marker or handoff chunked after the assistant's own turn\n * is never the first source, so the joined `metadata.custom` would miss it —\n * see {@link readRunMarkerFromSourceMessages}), then from joined metadata for\n * surfaces without bound sources.\n */\nexport function readRuntimeMessageFromSourceMessages(\n  message: Parameters<typeof getExternalStoreMessages>[0] & {\n    metadata?: { custom?: Record<string, unknown> | undefined } | undefined;\n    content?: unknown;\n  }\n): AthenaRuntimeMessage | undefined {\n  const sources = getExternalStoreMessages<LangChainMessage>(message);\n  for (const source of sources) {\n    if (source?.type !== 'ai') continue;\n    const kwargs = source.additional_kwargs as Kwargs;\n    const marker = kwargs?.[ATHENA_RUN_MARKER_KEY];\n    const reason = readTerminationReason(kwargs);\n    const text = textOf(source.content);\n    if (typeof marker === 'string') {\n      const markerSource = kwargs?.[ATHENA_RUN_MARKER_SOURCE_KEY];\n      const partial = fromMarker(\n        marker,\n        typeof markerSource === 'string' ? markerSource : undefined,\n        reason\n      );\n      if (partial) return build(partial, text, sources.length === 1);\n    }\n    if (readHandoff(kwargs)) {\n      return build({ kind: 'handoff', reason, silent: false }, text, sources.length === 1);\n    }\n  }\n  const custom = message.metadata?.custom;\n  if (!custom) return undefined;\n  const parts = message.content;\n  const sole = Array.isArray(parts) ? parts.length <= 1 : true;\n  const joinedMarker = custom[ATHENA_RUN_MARKER_KEY];\n  const joinedReason = readTerminationReason({ metadata: custom });\n  if (typeof joinedMarker === 'string') {\n    const joinedSource = custom[ATHENA_RUN_MARKER_SOURCE_KEY];\n    const partial = fromMarker(\n      joinedMarker,\n      typeof joinedSource === 'string' ? joinedSource : undefined,\n      joinedReason\n    );\n    if (partial) return build(partial, undefined, sole);\n  }\n  if (custom[ATHENA_HANDOFF_KEY] === true) {\n    return build({ kind: 'handoff', reason: joinedReason, silent: false }, undefined, sole);\n  }\n  return undefined;\n}\n\n/**\n * The backend marker copy worth showing under a runtime card, or `undefined`.\n *\n * A failure marker's text carries the specific error (\"The run failed:\n * provider returned 502\"), so it is shown when no reason-specific detail\n * exists. Stop/pause copy only restates the title, and a handoff's text is the\n * message body itself, so neither is repeated. Marker copy leads with an emoji\n * for raw-transcript readers; the card's icon plays that role, so it is\n * stripped. Shared by every presenter so mobile and DOM cannot drift.\n */\nexport function runtimeMessageMarkerText(message: AthenaRuntimeMessage): string | undefined {\n  if (message.kind !== 'failed' || message.detail) return undefined;\n  const text = message.text?.replace(/^(?:⏹️|⏸️|⚠️|\\s)+/u, '').trim();\n  if (!text || text === message.title) return undefined;\n  return text;\n}\n\n/**\n * The runtime message's kind when it owns the whole row, else `undefined`.\n *\n * Returns a primitive so it is safe as a `useAuiState` selector (the reader\n * above builds a fresh object per call; an object snapshot would loop the\n * render under `Object.is` comparison).\n */\nexport function readSoleRuntimeMessageKind(\n  message: Parameters<typeof readRuntimeMessageFromSourceMessages>[0]\n): AthenaRuntimeMessageKind | undefined {\n  const found = readRuntimeMessageFromSourceMessages(message);\n  return found?.isSoleSourceMessage ? found.kind : undefined;\n}\n"],"names":["ATHENA_TERMINATION_REASON_KEY","ATHENA_HANDOFF_KEY","ATHENA_RUN_MARKER_CANCELLED","isServerUpdateStopSource","ATHENA_STOP_SOURCE_SEND_NOW","ATHENA_RUN_MARKER_FAILED","getExternalStoreMessages","ATHENA_RUN_MARKER_KEY","ATHENA_RUN_MARKER_SOURCE_KEY"],"mappings":"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"}

package/dist/packages/agent-runtime/src/runtime-messages.js

@@ -0,0 +1,187 @@
+import { getExternalStoreMessages } from "@assistant-ui/core";
+import { ATHENA_RUN_MARKER_KEY, ATHENA_RUN_MARKER_SOURCE_KEY, ATHENA_HANDOFF_KEY, ATHENA_TERMINATION_REASON_KEY, ATHENA_RUN_MARKER_CANCELLED, ATHENA_STOP_SOURCE_SEND_NOW, ATHENA_RUN_MARKER_FAILED, isServerUpdateStopSource } from "./messages.js";
+const MAX_STEPS_HINT = "Raise “Max steps” in the agent settings for longer runs.";
+function describeTerminationReason(kind, reason) {
+  switch (kind) {
+    case "paused":
+      return {
+        title: "Paused by a server update",
+        detail: "Progress up to this point is saved — send a message to continue."
+      };
+    case "stopped":
+      switch (reason) {
+        case "voice_steer":
+          return {
+            title: "Redirected by a spoken follow-up",
+            detail: "The voice conversation changed the request; the work continues with the new instructions."
+          };
+        case "transport_cancel":
+          return {
+            title: "Run cancelled",
+            detail: "Cancelled by a page reload, navigation, or closed view — not an explicit Stop. Send a follow-up to continue."
+          };
+        case "fence_lost":
+          return {
+            title: "Run superseded",
+            detail: "Another activation took over this thread."
+          };
+        case "instance_closed":
+          return {
+            title: "Run stopped",
+            detail: "The client that started it went away."
+          };
+        default:
+          return { title: "Conversation stopped", detail: void 0 };
+      }
+    case "failed":
+      switch (reason) {
+        case "recursion_limit":
+          return {
+            title: "Step limit reached",
+            detail: `The run was stopped before finishing; the work so far is saved. ${MAX_STEPS_HINT}`
+          };
+        case "abandoned":
+          return {
+            title: "Run stopped unexpectedly",
+            detail: "The server handling it went away mid-run (a crash, restart, or deploy). The work so far is saved."
+          };
+        default:
+          return { title: "Run failed", detail: void 0 };
+      }
+    case "handoff":
+      switch (reason) {
+        case "duplicate_call_guard":
+          return {
+            title: "Run ended by the runtime",
+            detail: "The same tool calls were repeating with identical arguments and no new progress, so the agent was asked to wrap up."
+          };
+        case "step_budget":
+          return {
+            title: "Run ended by the runtime",
+            detail: `The step budget ran out, so the agent was asked to wrap up. ${MAX_STEPS_HINT}`
+          };
+        default:
+          return {
+            title: "Run ended by the runtime",
+            detail: "The agent was asked to wrap up."
+          };
+      }
+  }
+}
+const SEVERITY = {
+  stopped: "info",
+  paused: "info",
+  failed: "error",
+  handoff: "warning"
+};
+function metadataOf(kwargs) {
+  const metadata = kwargs == null ? void 0 : kwargs.metadata;
+  return typeof metadata === "object" && metadata !== null ? metadata : void 0;
+}
+function readTerminationReason(kwargs) {
+  var _a;
+  const top = kwargs == null ? void 0 : kwargs[ATHENA_TERMINATION_REASON_KEY];
+  if (typeof top === "string") return top;
+  const mirrored = (_a = metadataOf(kwargs)) == null ? void 0 : _a[ATHENA_TERMINATION_REASON_KEY];
+  return typeof mirrored === "string" ? mirrored : void 0;
+}
+function readHandoff(kwargs) {
+  var _a;
+  return (kwargs == null ? void 0 : kwargs[ATHENA_HANDOFF_KEY]) === true || ((_a = metadataOf(kwargs)) == null ? void 0 : _a[ATHENA_HANDOFF_KEY]) === true;
+}
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return void 0;
+  const texts = content.map(
+    (block) => typeof block === "string" ? block : block && typeof block === "object" && block.type === "text" ? block.text : void 0
+  ).filter((text) => typeof text === "string" && text.length > 0);
+  return texts.length > 0 ? texts.join("\n") : void 0;
+}
+function fromMarker(marker, source, reason) {
+  if (marker === ATHENA_RUN_MARKER_CANCELLED) {
+    const kind = isServerUpdateStopSource(source) ? "paused" : "stopped";
+    return {
+      kind,
+      reason: reason ?? (source === "unattributed" ? "unattributed_stop" : source),
+      silent: source === ATHENA_STOP_SOURCE_SEND_NOW
+    };
+  }
+  if (marker === ATHENA_RUN_MARKER_FAILED) {
+    return { kind: "failed", reason: reason ?? "error", silent: false };
+  }
+  return void 0;
+}
+function build(partial, text, isSoleSourceMessage) {
+  const description = describeTerminationReason(partial.kind, partial.reason);
+  return {
+    kind: partial.kind,
+    reason: partial.reason,
+    severity: SEVERITY[partial.kind],
+    title: description.title,
+    detail: description.detail,
+    text,
+    silent: partial.silent,
+    isSoleSourceMessage
+  };
+}
+function readRuntimeMessageFromSourceMessages(message) {
+  var _a;
+  const sources = getExternalStoreMessages(message);
+  for (const source of sources) {
+    if ((source == null ? void 0 : source.type) !== "ai") continue;
+    const kwargs = source.additional_kwargs;
+    const marker = kwargs == null ? void 0 : kwargs[ATHENA_RUN_MARKER_KEY];
+    const reason = readTerminationReason(kwargs);
+    const text = textOf(source.content);
+    if (typeof marker === "string") {
+      const markerSource = kwargs == null ? void 0 : kwargs[ATHENA_RUN_MARKER_SOURCE_KEY];
+      const partial = fromMarker(
+        marker,
+        typeof markerSource === "string" ? markerSource : void 0,
+        reason
+      );
+      if (partial) return build(partial, text, sources.length === 1);
+    }
+    if (readHandoff(kwargs)) {
+      return build({ kind: "handoff", reason, silent: false }, text, sources.length === 1);
+    }
+  }
+  const custom = (_a = message.metadata) == null ? void 0 : _a.custom;
+  if (!custom) return void 0;
+  const parts = message.content;
+  const sole = Array.isArray(parts) ? parts.length <= 1 : true;
+  const joinedMarker = custom[ATHENA_RUN_MARKER_KEY];
+  const joinedReason = readTerminationReason({ metadata: custom });
+  if (typeof joinedMarker === "string") {
+    const joinedSource = custom[ATHENA_RUN_MARKER_SOURCE_KEY];
+    const partial = fromMarker(
+      joinedMarker,
+      typeof joinedSource === "string" ? joinedSource : void 0,
+      joinedReason
+    );
+    if (partial) return build(partial, void 0, sole);
+  }
+  if (custom[ATHENA_HANDOFF_KEY] === true) {
+    return build({ kind: "handoff", reason: joinedReason, silent: false }, void 0, sole);
+  }
+  return void 0;
+}
+function runtimeMessageMarkerText(message) {
+  var _a;
+  if (message.kind !== "failed" || message.detail) return void 0;
+  const text = (_a = message.text) == null ? void 0 : _a.replace(/^(?:⏹️|⏸️|⚠️|\s)+/u, "").trim();
+  if (!text || text === message.title) return void 0;
+  return text;
+}
+function readSoleRuntimeMessageKind(message) {
+  const found = readRuntimeMessageFromSourceMessages(message);
+  return (found == null ? void 0 : found.isSoleSourceMessage) ? found.kind : void 0;
+}
+export {
+  describeTerminationReason,
+  readRuntimeMessageFromSourceMessages,
+  readSoleRuntimeMessageKind,
+  readTerminationReason,
+  runtimeMessageMarkerText
+};
+//# sourceMappingURL=runtime-messages.js.map

package/dist/packages/agent-runtime/src/runtime-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-messages.js","sources":["../../../../../agent-runtime/src/runtime-messages.ts"],"sourcesContent":["/**\n * Typed runtime messages — the one description of \"the runtime ended this run\"\n * that every chat surface renders from.\n *\n * The deep-agent backend records how a run ended in two shapes that ride\n * ordinary `ai` messages (a new LangChain message type would crash the shipped\n * converter, whose convertible set is closed):\n *\n * - a **run-lifecycle marker** (`athena_run_marker`: `cancelled` / `failed`,\n *   plus `athena_run_marker_source`) — see {@link readRunMarkerFromSourceMessages};\n * - a **handoff message** (`athena_handoff: true`) — the closing summary the\n *   runtime asked the model to write when a guard or the step budget ended the\n *   run, instead of fabricating an internal sentence.\n *\n * Both now carry the canonical `athena_termination_reason`\n * (`agora/graphs/athena_deep_agent/termination.py`). This module reads all of\n * that into one {@link AthenaRuntimeMessage} so Olympus, mobile, the Chrome\n * extension, and the Office add-in agree on kind, severity, copy, and the\n * sole-vs-grouped distinction — the last of which is load-bearing: a marker\n * appended after the assistant's own work is chunked into that message, and\n * replacing the whole row would hide completed prose and tool cards.\n */\n\nimport { getExternalStoreMessages } from '@assistant-ui/core';\nimport type { LangChainMessage } from '@assistant-ui/react-langgraph';\nimport {\n  ATHENA_HANDOFF_KEY,\n  ATHENA_RUN_MARKER_CANCELLED,\n  ATHENA_RUN_MARKER_FAILED,\n  ATHENA_RUN_MARKER_KEY,\n  ATHENA_RUN_MARKER_SOURCE_KEY,\n  ATHENA_STOP_SOURCE_SEND_NOW,\n  ATHENA_TERMINATION_REASON_KEY,\n  isServerUpdateStopSource,\n} from './messages';\n\n/** The backend's canonical reason vocabulary (`KNOWN_TERMINATION_REASONS`). */\nexport const TERMINATION_REASONS = [\n  'completed',\n  'user_stop',\n  'send_now',\n  'voice_steer',\n  'transport_cancel',\n  'pod_drain',\n  'fence_lost',\n  'instance_closed',\n  'unattributed_stop',\n  'recursion_limit',\n  'step_budget',\n  'duplicate_call_guard',\n  'synthetic_stop',\n  'ended_after_tools',\n  'error',\n  'model_refusal',\n  'abandoned',\n] as const;\n\nexport type AthenaTerminationReason = (typeof TERMINATION_REASONS)[number];\n\n/**\n * How a runtime ending renders:\n * - `stopped` — a cancellation the user (or a client action) asked for;\n * - `paused` — a pod-drain pause; the run resumes from its checkpoint;\n * - `failed` — the graph raised, hit the recursion limit, or was abandoned;\n * - `handoff` — the runtime ended the run and the model wrote a closing\n *   summary (the message text), which renders as prose under a banner.\n */\nexport type AthenaRuntimeMessageKind = 'stopped' | 'paused' | 'failed' | 'handoff';\n\nexport type AthenaRuntimeMessageSeverity = 'info' | 'warning' | 'error';\n\nexport interface TerminationDescription {\n  /** Short label for the banner / status row. */\n  title: string;\n  /** One sentence of reason-specific explanation, when it adds information. */\n  detail: string | undefined;\n}\n\nexport interface AthenaRuntimeMessage {\n  kind: AthenaRuntimeMessageKind;\n  /** Canonical reason (may be a value newer than this client knows). */\n  reason: string | undefined;\n  severity: AthenaRuntimeMessageSeverity;\n  title: string;\n  detail: string | undefined;\n  /** The message's own text: a marker's backend copy, or the handoff summary. */\n  text: string | undefined;\n  /**\n   * A `send_now` promotion cancels the live run as plumbing, not as a\n   * user-visible stop: keep it in the data, paint nothing.\n   */\n  silent: boolean;\n  /**\n   * True when the runtime message is the ONLY source message behind this\n   * thread message (it owns the whole row). False when the chunk also holds\n   * the assistant's own work, which must keep rendering.\n   */\n  isSoleSourceMessage: boolean;\n}\n\nconst MAX_STEPS_HINT = 'Raise “Max steps” in the agent settings for longer runs.';\n\n/**\n * Copy for a runtime ending. Reasons this client does not know fall back to\n * the kind's generic title, so a newer backend never renders as an empty row.\n */\nexport function describeTerminationReason(\n  kind: AthenaRuntimeMessageKind,\n  reason: string | undefined\n): TerminationDescription {\n  switch (kind) {\n    case 'paused':\n      return {\n        title: 'Paused by a server update',\n        detail: 'Progress up to this point is saved — send a message to continue.',\n      };\n    case 'stopped':\n      switch (reason) {\n        case 'voice_steer':\n          return {\n            title: 'Redirected by a spoken follow-up',\n            detail:\n              'The voice conversation changed the request; the work continues with the new instructions.',\n          };\n        case 'transport_cancel':\n          return {\n            title: 'Run cancelled',\n            detail:\n              'Cancelled by a page reload, navigation, or closed view — not an explicit Stop. Send a follow-up to continue.',\n          };\n        case 'fence_lost':\n          return {\n            title: 'Run superseded',\n            detail: 'Another activation took over this thread.',\n          };\n        case 'instance_closed':\n          return {\n            title: 'Run stopped',\n            detail: 'The client that started it went away.',\n          };\n        default:\n          return { title: 'Conversation stopped', detail: undefined };\n      }\n    case 'failed':\n      switch (reason) {\n        case 'recursion_limit':\n          return {\n            title: 'Step limit reached',\n            detail: `The run was stopped before finishing; the work so far is saved. ${MAX_STEPS_HINT}`,\n          };\n        case 'abandoned':\n          return {\n            title: 'Run stopped unexpectedly',\n            detail:\n              'The server handling it went away mid-run (a crash, restart, or deploy). The work so far is saved.',\n          };\n        default:\n          return { title: 'Run failed', detail: undefined };\n      }\n    case 'handoff':\n      switch (reason) {\n        case 'duplicate_call_guard':\n          return {\n            title: 'Run ended by the runtime',\n            detail:\n              'The same tool calls were repeating with identical arguments and no new progress, so the agent was asked to wrap up.',\n          };\n        case 'step_budget':\n          return {\n            title: 'Run ended by the runtime',\n            detail: `The step budget ran out, so the agent was asked to wrap up. ${MAX_STEPS_HINT}`,\n          };\n        default:\n          return {\n            title: 'Run ended by the runtime',\n            detail: 'The agent was asked to wrap up.',\n          };\n      }\n  }\n}\n\nconst SEVERITY: Record<AthenaRuntimeMessageKind, AthenaRuntimeMessageSeverity> = {\n  stopped: 'info',\n  paused: 'info',\n  failed: 'error',\n  handoff: 'warning',\n};\n\ntype Kwargs = Record<string, unknown> | undefined;\n\nfunction metadataOf(kwargs: Kwargs): Record<string, unknown> | undefined {\n  const metadata = kwargs?.metadata;\n  return typeof metadata === 'object' && metadata !== null\n    ? (metadata as Record<string, unknown>)\n    : undefined;\n}\n\n/** The termination reason stamped on `additional_kwargs` (top-level or mirror). */\nexport function readTerminationReason(kwargs: Kwargs): string | undefined {\n  const top = kwargs?.[ATHENA_TERMINATION_REASON_KEY];\n  if (typeof top === 'string') return top;\n  const mirrored = metadataOf(kwargs)?.[ATHENA_TERMINATION_REASON_KEY];\n  return typeof mirrored === 'string' ? mirrored : undefined;\n}\n\nfunction readHandoff(kwargs: Kwargs): boolean {\n  return kwargs?.[ATHENA_HANDOFF_KEY] === true || metadataOf(kwargs)?.[ATHENA_HANDOFF_KEY] === true;\n}\n\nfunction textOf(content: unknown): string | undefined {\n  if (typeof content === 'string') return content;\n  if (!Array.isArray(content)) return undefined;\n  const texts = content\n    .map((block) =>\n      typeof block === 'string'\n        ? block\n        : block && typeof block === 'object' && (block as { type?: unknown }).type === 'text'\n          ? (block as { text?: unknown }).text\n          : undefined\n    )\n    .filter((text): text is string => typeof text === 'string' && text.length > 0);\n  return texts.length > 0 ? texts.join('\\n') : undefined;\n}\n\nfunction fromMarker(\n  marker: string,\n  source: string | undefined,\n  reason: string | undefined\n): Pick<AthenaRuntimeMessage, 'kind' | 'reason' | 'silent'> | undefined {\n  if (marker === ATHENA_RUN_MARKER_CANCELLED) {\n    const kind: AthenaRuntimeMessageKind = isServerUpdateStopSource(source) ? 'paused' : 'stopped';\n    return {\n      kind,\n      reason: reason ?? (source === 'unattributed' ? 'unattributed_stop' : source),\n      silent: source === ATHENA_STOP_SOURCE_SEND_NOW,\n    };\n  }\n  if (marker === ATHENA_RUN_MARKER_FAILED) {\n    return { kind: 'failed', reason: reason ?? 'error', silent: false };\n  }\n  return undefined;\n}\n\nfunction build(\n  partial: Pick<AthenaRuntimeMessage, 'kind' | 'reason' | 'silent'>,\n  text: string | undefined,\n  isSoleSourceMessage: boolean\n): AthenaRuntimeMessage {\n  const description = describeTerminationReason(partial.kind, partial.reason);\n  return {\n    kind: partial.kind,\n    reason: partial.reason,\n    severity: SEVERITY[partial.kind],\n    title: description.title,\n    detail: description.detail,\n    text,\n    silent: partial.silent,\n    isSoleSourceMessage,\n  };\n}\n\n/**\n * Read the runtime ending behind a thread message, from its bound source\n * messages first (a marker or handoff chunked after the assistant's own turn\n * is never the first source, so the joined `metadata.custom` would miss it —\n * see {@link readRunMarkerFromSourceMessages}), then from joined metadata for\n * surfaces without bound sources.\n */\nexport function readRuntimeMessageFromSourceMessages(\n  message: Parameters<typeof getExternalStoreMessages>[0] & {\n    metadata?: { custom?: Record<string, unknown> | undefined } | undefined;\n    content?: unknown;\n  }\n): AthenaRuntimeMessage | undefined {\n  const sources = getExternalStoreMessages<LangChainMessage>(message);\n  for (const source of sources) {\n    if (source?.type !== 'ai') continue;\n    const kwargs = source.additional_kwargs as Kwargs;\n    const marker = kwargs?.[ATHENA_RUN_MARKER_KEY];\n    const reason = readTerminationReason(kwargs);\n    const text = textOf(source.content);\n    if (typeof marker === 'string') {\n      const markerSource = kwargs?.[ATHENA_RUN_MARKER_SOURCE_KEY];\n      const partial = fromMarker(\n        marker,\n        typeof markerSource === 'string' ? markerSource : undefined,\n        reason\n      );\n      if (partial) return build(partial, text, sources.length === 1);\n    }\n    if (readHandoff(kwargs)) {\n      return build({ kind: 'handoff', reason, silent: false }, text, sources.length === 1);\n    }\n  }\n  const custom = message.metadata?.custom;\n  if (!custom) return undefined;\n  const parts = message.content;\n  const sole = Array.isArray(parts) ? parts.length <= 1 : true;\n  const joinedMarker = custom[ATHENA_RUN_MARKER_KEY];\n  const joinedReason = readTerminationReason({ metadata: custom });\n  if (typeof joinedMarker === 'string') {\n    const joinedSource = custom[ATHENA_RUN_MARKER_SOURCE_KEY];\n    const partial = fromMarker(\n      joinedMarker,\n      typeof joinedSource === 'string' ? joinedSource : undefined,\n      joinedReason\n    );\n    if (partial) return build(partial, undefined, sole);\n  }\n  if (custom[ATHENA_HANDOFF_KEY] === true) {\n    return build({ kind: 'handoff', reason: joinedReason, silent: false }, undefined, sole);\n  }\n  return undefined;\n}\n\n/**\n * The backend marker copy worth showing under a runtime card, or `undefined`.\n *\n * A failure marker's text carries the specific error (\"The run failed:\n * provider returned 502\"), so it is shown when no reason-specific detail\n * exists. Stop/pause copy only restates the title, and a handoff's text is the\n * message body itself, so neither is repeated. Marker copy leads with an emoji\n * for raw-transcript readers; the card's icon plays that role, so it is\n * stripped. Shared by every presenter so mobile and DOM cannot drift.\n */\nexport function runtimeMessageMarkerText(message: AthenaRuntimeMessage): string | undefined {\n  if (message.kind !== 'failed' || message.detail) return undefined;\n  const text = message.text?.replace(/^(?:⏹️|⏸️|⚠️|\\s)+/u, '').trim();\n  if (!text || text === message.title) return undefined;\n  return text;\n}\n\n/**\n * The runtime message's kind when it owns the whole row, else `undefined`.\n *\n * Returns a primitive so it is safe as a `useAuiState` selector (the reader\n * above builds a fresh object per call; an object snapshot would loop the\n * render under `Object.is` comparison).\n */\nexport function readSoleRuntimeMessageKind(\n  message: Parameters<typeof readRuntimeMessageFromSourceMessages>[0]\n): AthenaRuntimeMessageKind | undefined {\n  const found = readRuntimeMessageFromSourceMessages(message);\n  return found?.isSoleSourceMessage ? found.kind : undefined;\n}\n"],"names":[],"mappings":"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"}

package/dist/packages/agent-runtime/src/screen-point.cjs

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const SCREEN_POINT_PROTOCOL = "athena-point:";
+const SCREEN_POINT_HREF_PREFIX = `${SCREEN_POINT_PROTOCOL}//`;
+const SCREEN_POINT_MAX_EXTENT = 32767;
+const NUMBER_PATTERN = /^~?\s*(-?\d+(?:\.\d+)?)$/;
+function parseCoordinateNumber(raw) {
+  if (raw === null || raw.trim() === "") return { ok: false, error: "missing" };
+  const match = NUMBER_PATTERN.exec(raw.trim());
+  if (!match) return { ok: false, error: "non-finite-number" };
+  const value = Number(match[1]);
+  if (!Number.isFinite(value)) return { ok: false, error: "non-finite-number" };
+  if (value < 0) return { ok: false, error: "negative-number" };
+  if (value > SCREEN_POINT_MAX_EXTENT) return { ok: false, error: "extent-too-large" };
+  return { ok: true, value: Math.round(value) };
+}
+function isScreenPointHref(href) {
+  return typeof href === "string" && href.startsWith(SCREEN_POINT_HREF_PREFIX);
+}
+function parseScreenPointHref(href) {
+  if (!isScreenPointHref(href)) return { ok: false, error: "not-screen-point" };
+  const queryStart = href.indexOf("?");
+  if (queryStart === -1) return { ok: false, error: "missing-coordinate" };
+  const params = new URLSearchParams(href.slice(queryStart + 1));
+  const x = parseCoordinateNumber(params.get("x"));
+  const y = parseCoordinateNumber(params.get("y"));
+  if (!x.ok) return { ok: false, error: x.error === "missing" ? "missing-coordinate" : x.error };
+  if (!y.ok) return { ok: false, error: y.error === "missing" ? "missing-coordinate" : y.error };
+  const widthRaw = params.get("w") ?? params.get("width") ?? params.get("basisWidth");
+  const heightRaw = params.get("h") ?? params.get("height") ?? params.get("basisHeight");
+  let basis = null;
+  if (widthRaw !== null || heightRaw !== null) {
+    const width = parseCoordinateNumber(widthRaw);
+    const height = parseCoordinateNumber(heightRaw);
+    if (!width.ok || !height.ok) {
+      const failed = !width.ok ? width : height;
+      if (failed.ok) return { ok: false, error: "degenerate-basis" };
+      return {
+        ok: false,
+        error: failed.error === "missing" ? "degenerate-basis" : failed.error
+      };
+    }
+    if (width.value <= 0 || height.value <= 0) return { ok: false, error: "degenerate-basis" };
+    basis = { width: width.value, height: height.value };
+    if (x.value > basis.width || y.value > basis.height) {
+      return { ok: false, error: "out-of-bounds" };
+    }
+  }
+  const tabRaw = params.get("tab") ?? params.get("tab_id") ?? params.get("tabId");
+  let tabId = null;
+  if (tabRaw !== null && tabRaw.trim() !== "") {
+    const tab = Number(tabRaw);
+    tabId = Number.isInteger(tab) && tab >= 0 ? tab : null;
+  }
+  return { ok: true, point: { x: x.value, y: y.value, basis, tabId } };
+}
+function formatScreenPoint(point) {
+  const pair = `(${point.x}, ${point.y})`;
+  if (!point.basis) return `${pair} — screenshot size not recorded`;
+  return `${pair} in a ${point.basis.width}×${point.basis.height} screenshot`;
+}
+exports.SCREEN_POINT_HREF_PREFIX = SCREEN_POINT_HREF_PREFIX;
+exports.SCREEN_POINT_MAX_EXTENT = SCREEN_POINT_MAX_EXTENT;
+exports.SCREEN_POINT_PROTOCOL = SCREEN_POINT_PROTOCOL;
+exports.formatScreenPoint = formatScreenPoint;
+exports.isScreenPointHref = isScreenPointHref;
+exports.parseScreenPointHref = parseScreenPointHref;
+//# sourceMappingURL=screen-point.cjs.map

package/dist/packages/agent-runtime/src/screen-point.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-point.cjs","sources":["../../../../../agent-runtime/src/screen-point.ts"],"sourcesContent":["/**\n * Screen points: the agent's on-screen coordinates as structured, renderable\n * data.\n *\n * Browser agents already speak in `[x, y]` pairs — the `coordinate` argument\n * of `chrome_computer` / `device_computer` / `computer` is a pixel in the\n * screenshot the model was shown. In prose those pairs arrive as free text\n * (\"Delete at ~(1038, 81)\"), which no surface can render as anything but\n * characters. A screen point is that same pair written as a markdown link\n * whose destination carries the pair *and the dimensions of the screenshot it\n * was read from*:\n *\n *   [Delete](athena-point://screenshot?x=1038&y=81&w=1280&h=720&tab=8811)\n *\n * The agent keeps its native vocabulary (the coordinate it already has, the\n * screenshot size it was told) and does no arithmetic; every chat surface\n * that understands the scheme renders the link as a chip and, because the\n * basis dimensions travel with the point, can place a marker at the right\n * relative spot on any later rendition of that screenshot however the\n * transcript is laid out or the user's window is resized. Surfaces that do\n * not understand the scheme show the label as plain text (a link with an\n * unknown protocol), which is exactly the prose we have today — the format\n * degrades to the status quo, never below it.\n *\n * Pure string and number work, UI-library-free, shared by every chat surface\n * (Olympus, the React SDK hosts, the Chrome extension side panel) so a point\n * that is valid on one surface is valid on all of them.\n */\n\n/** URL scheme of a screen-point link. */\nexport const SCREEN_POINT_PROTOCOL = \"athena-point:\";\n/** Host of a screen-point link: the coordinate space the pair lives in. */\nexport const SCREEN_POINT_HOST = \"screenshot\";\n/** `href.startsWith(SCREEN_POINT_HREF_PREFIX)` is the cheap pre-check every renderer runs. */\nexport const SCREEN_POINT_HREF_PREFIX = `${SCREEN_POINT_PROTOCOL}//`;\n/**\n * The largest coordinate or dimension a point may carry. No screenshot the\n * runtime delivers approaches this; anything larger is a typo or a unit mix-up.\n */\nexport const SCREEN_POINT_MAX_EXTENT = 32_767;\n/**\n * The model-facing CUA screenshot size the Chrome extension emits by default\n * (`athena-in-chrome/extension/src/background.ts`, `CHROME_DEFAULT_WIDTH` /\n * `CHROME_DEFAULT_HEIGHT` in `chrome_browser_tools.py`). Surfaces may offer\n * it as the fallback basis for a point that omits `w`/`h`, clearly labelled\n * as assumed.\n */\nexport const DEFAULT_CUA_SCREENSHOT_SIZE = { width: 1280, height: 720 } as const;\n\n/** Width and height of a coordinate space, in that space's pixels. */\nexport interface ScreenSize {\n  width: number;\n  height: number;\n}\n\n/**\n * A point in screenshot space. `basis` is the size of the screenshot the pair\n * was read from; `null` when the link omitted it, in which case the point can\n * be shown but not placed. `tabId` is the Chrome tab the screenshot came from\n * when the agent had one.\n */\nexport interface ScreenPoint {\n  x: number;\n  y: number;\n  basis: ScreenSize | null;\n  tabId: number | null;\n}\n\n/**\n * Why a link that starts with the scheme could not become a point. Rendered\n * surfaces show the label as text with the reason in a tooltip, so a broken\n * link never becomes an interactive marker that points nowhere.\n */\nexport type ScreenPointParseError =\n  | \"not-screen-point\"\n  | \"missing-coordinate\"\n  | \"non-finite-number\"\n  | \"negative-number\"\n  | \"degenerate-basis\"\n  | \"out-of-bounds\"\n  | \"extent-too-large\";\n\nexport type ScreenPointParseResult =\n  | { ok: true; point: ScreenPoint }\n  | { ok: false; error: ScreenPointParseError };\n\n/** A number the agent may have written with a decimal point or a `~`: keep the integer pixel. */\nconst NUMBER_PATTERN = /^~?\\s*(-?\\d+(?:\\.\\d+)?)$/;\n\ntype NumberParse =\n  | { ok: true; value: number }\n  | { ok: false; error: \"non-finite-number\" | \"negative-number\" | \"extent-too-large\" }\n  | { ok: false; error: \"missing\" };\n\nfunction parseCoordinateNumber(raw: string | null): NumberParse {\n  if (raw === null || raw.trim() === \"\") return { ok: false, error: \"missing\" };\n  const match = NUMBER_PATTERN.exec(raw.trim());\n  if (!match) return { ok: false, error: \"non-finite-number\" };\n  const value = Number(match[1]);\n  if (!Number.isFinite(value)) return { ok: false, error: \"non-finite-number\" };\n  if (value < 0) return { ok: false, error: \"negative-number\" };\n  if (value > SCREEN_POINT_MAX_EXTENT) return { ok: false, error: \"extent-too-large\" };\n  return { ok: true, value: Math.round(value) };\n}\n\n/** Whether `href` is a screen-point link at all (the cheap pre-check). */\nexport function isScreenPointHref(href: string | null | undefined): href is string {\n  return typeof href === \"string\" && href.startsWith(SCREEN_POINT_HREF_PREFIX);\n}\n\n/**\n * Parse a screen-point link. Accepts the canonical form\n * `athena-point://screenshot?x=…&y=…&w=…&h=…&tab=…` and tolerates what a\n * model plausibly writes instead: `width`/`height` for `w`/`h`, `tab_id` for\n * `tab`, decimals, a leading `~`, and an empty or different host. Rejects,\n * with a reason, anything that would place a marker in the wrong spot:\n * non-finite or negative numbers, a zero or negative basis, a point outside\n * its basis, and absurd extents.\n */\nexport function parseScreenPointHref(href: string | null | undefined): ScreenPointParseResult {\n  if (!isScreenPointHref(href)) return { ok: false, error: \"not-screen-point\" };\n\n  // `new URL` treats a non-special scheme with an empty host inconsistently\n  // across engines; the query is the only part we read, so slice it off.\n  const queryStart = href.indexOf(\"?\");\n  if (queryStart === -1) return { ok: false, error: \"missing-coordinate\" };\n  const params = new URLSearchParams(href.slice(queryStart + 1));\n\n  const x = parseCoordinateNumber(params.get(\"x\"));\n  const y = parseCoordinateNumber(params.get(\"y\"));\n  if (!x.ok) return { ok: false, error: x.error === \"missing\" ? \"missing-coordinate\" : x.error };\n  if (!y.ok) return { ok: false, error: y.error === \"missing\" ? \"missing-coordinate\" : y.error };\n\n  const widthRaw = params.get(\"w\") ?? params.get(\"width\") ?? params.get(\"basisWidth\");\n  const heightRaw = params.get(\"h\") ?? params.get(\"height\") ?? params.get(\"basisHeight\");\n  let basis: ScreenSize | null = null;\n  if (widthRaw !== null || heightRaw !== null) {\n    const width = parseCoordinateNumber(widthRaw);\n    const height = parseCoordinateNumber(heightRaw);\n    // One dimension without the other is not a basis.\n    if (!width.ok || !height.ok) {\n      const failed = !width.ok ? width : height;\n      if (failed.ok) return { ok: false, error: \"degenerate-basis\" };\n      return {\n        ok: false,\n        error: failed.error === \"missing\" ? \"degenerate-basis\" : failed.error,\n      };\n    }\n    if (width.value <= 0 || height.value <= 0) return { ok: false, error: \"degenerate-basis\" };\n    basis = { width: width.value, height: height.value };\n    if (x.value > basis.width || y.value > basis.height) {\n      return { ok: false, error: \"out-of-bounds\" };\n    }\n  }\n\n  const tabRaw = params.get(\"tab\") ?? params.get(\"tab_id\") ?? params.get(\"tabId\");\n  let tabId: number | null = null;\n  if (tabRaw !== null && tabRaw.trim() !== \"\") {\n    const tab = Number(tabRaw);\n    tabId = Number.isInteger(tab) && tab >= 0 ? tab : null;\n  }\n\n  return { ok: true, point: { x: x.value, y: y.value, basis, tabId } };\n}\n\n/** The canonical link for a point — what the prompt teaches the agent to write. */\nexport function serializeScreenPointHref(point: ScreenPoint): string {\n  const params = new URLSearchParams();\n  params.set(\"x\", String(point.x));\n  params.set(\"y\", String(point.y));\n  if (point.basis) {\n    params.set(\"w\", String(point.basis.width));\n    params.set(\"h\", String(point.basis.height));\n  }\n  if (point.tabId !== null) params.set(\"tab\", String(point.tabId));\n  return `${SCREEN_POINT_HREF_PREFIX}${SCREEN_POINT_HOST}?${params.toString()}`;\n}\n\n/**\n * Where the point sits as a fraction of its basis, `0..1` on each axis, or\n * `null` when the point has no basis to be relative to. This is the only\n * number a renderer needs: `left: ${fx * 100}%` places the marker on any\n * rendition of the screenshot, whatever size it is drawn at.\n */\nexport function screenPointFraction(point: ScreenPoint): { fx: number; fy: number } | null {\n  if (!point.basis) return null;\n  return { fx: point.x / point.basis.width, fy: point.y / point.basis.height };\n}\n\n/** Whether two sizes are the same to within the few-pixel jitter a resize or scrollbar introduces. */\nexport function sameScreenSize({\n  a,\n  b,\n  tolerancePx = 4,\n}: {\n  a: ScreenSize;\n  b: ScreenSize;\n  tolerancePx?: number;\n}): boolean {\n  return Math.abs(a.width - b.width) <= tolerancePx && Math.abs(a.height - b.height) <= tolerancePx;\n}\n\n/**\n * How a point's basis relates to the screenshot it is about to be drawn on.\n * Mirrors the runtime's dispatch contract (`browser_coordinate_contract.json`):\n * the same size or a few pixels of jitter is `identity`; a uniform ratio on\n * both axes (browser zoom, a resized window at the same aspect) is\n * `uniform-scale` and the fraction still lands on the same element; anything\n * else is a `mismatch` — a different aspect ratio means the screenshot shows a\n * different framing (chrome headroom, a rotated device, a different tab) and\n * a fraction placed on it would point at the wrong thing.\n */\nexport type ScreenBasisFit =\n  | { kind: \"identity\" }\n  | { kind: \"uniform-scale\"; scale: number }\n  | { kind: \"mismatch\"; aspectDelta: number };\n\nexport function fitScreenBasis({\n  basis,\n  target,\n  aspectTolerance = 0.02,\n}: {\n  basis: ScreenSize;\n  target: ScreenSize;\n  aspectTolerance?: number;\n}): ScreenBasisFit {\n  if (\n    basis.width <= 0 ||\n    basis.height <= 0 ||\n    target.width <= 0 ||\n    target.height <= 0 ||\n    ![basis.width, basis.height, target.width, target.height].every(Number.isFinite)\n  ) {\n    return { kind: \"mismatch\", aspectDelta: Number.POSITIVE_INFINITY };\n  }\n  if (sameScreenSize({ a: basis, b: target })) return { kind: \"identity\" };\n  const scaleX = target.width / basis.width;\n  const scaleY = target.height / basis.height;\n  const aspectDelta = Math.abs(scaleX - scaleY) / Math.max(scaleX, scaleY);\n  if (aspectDelta <= aspectTolerance) return { kind: \"uniform-scale\", scale: (scaleX + scaleY) / 2 };\n  return { kind: \"mismatch\", aspectDelta };\n}\n\n/** Human-readable point for tooltips and accessible names: `(1038, 81) in a 1280×720 screenshot`. */\nexport function formatScreenPoint(point: ScreenPoint): string {\n  const pair = `(${point.x}, ${point.y})`;\n  if (!point.basis) return `${pair} — screenshot size not recorded`;\n  return `${pair} in a ${point.basis.width}×${point.basis.height} screenshot`;\n}\n\n/** The sentence a surface shows for a link that failed to parse. */\nexport function describeScreenPointError(error: ScreenPointParseError): string {\n  switch (error) {\n    case \"not-screen-point\":\n      return \"Not a screen point\";\n    case \"missing-coordinate\":\n      return \"Screen point is missing x or y\";\n    case \"non-finite-number\":\n      return \"Screen point has a non-numeric value\";\n    case \"negative-number\":\n      return \"Screen point has a negative value\";\n    case \"degenerate-basis\":\n      return \"Screen point has an invalid screenshot size\";\n    case \"out-of-bounds\":\n      return \"Screen point lies outside its screenshot\";\n    case \"extent-too-large\":\n      return \"Screen point value is implausibly large\";\n  }\n}\n\n/**\n * Screen points written into a text block, in order. Used by surfaces that\n * work on the raw markdown (the static message body's node parser, the\n * extension's plain-text composer) and by tests. Only the link form is\n * recognised — a bare `(1038, 81)` in prose is text, never a point, so a\n * model that was not taught the scheme changes nothing.\n */\nexport function findScreenPointLinks(\n  text: string,\n): Array<{ start: number; end: number; label: string; href: string }> {\n  const results: Array<{ start: number; end: number; label: string; href: string }> = [];\n  const pattern = /\\[([^\\]\\n]*)\\]\\((athena-point:\\/\\/[^\\s)]*)\\)/g;\n  for (const match of text.matchAll(pattern)) {\n    if (match.index === undefined) continue;\n    results.push({\n      start: match.index,\n      end: match.index + match[0].length,\n      label: match[1],\n      href: match[2],\n    });\n  }\n  return results;\n}\n"],"names":[],"mappings":"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"}

package/dist/packages/agent-runtime/src/screen-point.js

@@ -0,0 +1,68 @@
+const SCREEN_POINT_PROTOCOL = "athena-point:";
+const SCREEN_POINT_HREF_PREFIX = `${SCREEN_POINT_PROTOCOL}//`;
+const SCREEN_POINT_MAX_EXTENT = 32767;
+const NUMBER_PATTERN = /^~?\s*(-?\d+(?:\.\d+)?)$/;
+function parseCoordinateNumber(raw) {
+  if (raw === null || raw.trim() === "") return { ok: false, error: "missing" };
+  const match = NUMBER_PATTERN.exec(raw.trim());
+  if (!match) return { ok: false, error: "non-finite-number" };
+  const value = Number(match[1]);
+  if (!Number.isFinite(value)) return { ok: false, error: "non-finite-number" };
+  if (value < 0) return { ok: false, error: "negative-number" };
+  if (value > SCREEN_POINT_MAX_EXTENT) return { ok: false, error: "extent-too-large" };
+  return { ok: true, value: Math.round(value) };
+}
+function isScreenPointHref(href) {
+  return typeof href === "string" && href.startsWith(SCREEN_POINT_HREF_PREFIX);
+}
+function parseScreenPointHref(href) {
+  if (!isScreenPointHref(href)) return { ok: false, error: "not-screen-point" };
+  const queryStart = href.indexOf("?");
+  if (queryStart === -1) return { ok: false, error: "missing-coordinate" };
+  const params = new URLSearchParams(href.slice(queryStart + 1));
+  const x = parseCoordinateNumber(params.get("x"));
+  const y = parseCoordinateNumber(params.get("y"));
+  if (!x.ok) return { ok: false, error: x.error === "missing" ? "missing-coordinate" : x.error };
+  if (!y.ok) return { ok: false, error: y.error === "missing" ? "missing-coordinate" : y.error };
+  const widthRaw = params.get("w") ?? params.get("width") ?? params.get("basisWidth");
+  const heightRaw = params.get("h") ?? params.get("height") ?? params.get("basisHeight");
+  let basis = null;
+  if (widthRaw !== null || heightRaw !== null) {
+    const width = parseCoordinateNumber(widthRaw);
+    const height = parseCoordinateNumber(heightRaw);
+    if (!width.ok || !height.ok) {
+      const failed = !width.ok ? width : height;
+      if (failed.ok) return { ok: false, error: "degenerate-basis" };
+      return {
+        ok: false,
+        error: failed.error === "missing" ? "degenerate-basis" : failed.error
+      };
+    }
+    if (width.value <= 0 || height.value <= 0) return { ok: false, error: "degenerate-basis" };
+    basis = { width: width.value, height: height.value };
+    if (x.value > basis.width || y.value > basis.height) {
+      return { ok: false, error: "out-of-bounds" };
+    }
+  }
+  const tabRaw = params.get("tab") ?? params.get("tab_id") ?? params.get("tabId");
+  let tabId = null;
+  if (tabRaw !== null && tabRaw.trim() !== "") {
+    const tab = Number(tabRaw);
+    tabId = Number.isInteger(tab) && tab >= 0 ? tab : null;
+  }
+  return { ok: true, point: { x: x.value, y: y.value, basis, tabId } };
+}
+function formatScreenPoint(point) {
+  const pair = `(${point.x}, ${point.y})`;
+  if (!point.basis) return `${pair} — screenshot size not recorded`;
+  return `${pair} in a ${point.basis.width}×${point.basis.height} screenshot`;
+}
+export {
+  SCREEN_POINT_HREF_PREFIX,
+  SCREEN_POINT_MAX_EXTENT,
+  SCREEN_POINT_PROTOCOL,
+  formatScreenPoint,
+  isScreenPointHref,
+  parseScreenPointHref
+};
+//# sourceMappingURL=screen-point.js.map

package/dist/packages/agent-runtime/src/screen-point.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-point.js","sources":["../../../../../agent-runtime/src/screen-point.ts"],"sourcesContent":["/**\n * Screen points: the agent's on-screen coordinates as structured, renderable\n * data.\n *\n * Browser agents already speak in `[x, y]` pairs — the `coordinate` argument\n * of `chrome_computer` / `device_computer` / `computer` is a pixel in the\n * screenshot the model was shown. In prose those pairs arrive as free text\n * (\"Delete at ~(1038, 81)\"), which no surface can render as anything but\n * characters. A screen point is that same pair written as a markdown link\n * whose destination carries the pair *and the dimensions of the screenshot it\n * was read from*:\n *\n *   [Delete](athena-point://screenshot?x=1038&y=81&w=1280&h=720&tab=8811)\n *\n * The agent keeps its native vocabulary (the coordinate it already has, the\n * screenshot size it was told) and does no arithmetic; every chat surface\n * that understands the scheme renders the link as a chip and, because the\n * basis dimensions travel with the point, can place a marker at the right\n * relative spot on any later rendition of that screenshot however the\n * transcript is laid out or the user's window is resized. Surfaces that do\n * not understand the scheme show the label as plain text (a link with an\n * unknown protocol), which is exactly the prose we have today — the format\n * degrades to the status quo, never below it.\n *\n * Pure string and number work, UI-library-free, shared by every chat surface\n * (Olympus, the React SDK hosts, the Chrome extension side panel) so a point\n * that is valid on one surface is valid on all of them.\n */\n\n/** URL scheme of a screen-point link. */\nexport const SCREEN_POINT_PROTOCOL = \"athena-point:\";\n/** Host of a screen-point link: the coordinate space the pair lives in. */\nexport const SCREEN_POINT_HOST = \"screenshot\";\n/** `href.startsWith(SCREEN_POINT_HREF_PREFIX)` is the cheap pre-check every renderer runs. */\nexport const SCREEN_POINT_HREF_PREFIX = `${SCREEN_POINT_PROTOCOL}//`;\n/**\n * The largest coordinate or dimension a point may carry. No screenshot the\n * runtime delivers approaches this; anything larger is a typo or a unit mix-up.\n */\nexport const SCREEN_POINT_MAX_EXTENT = 32_767;\n/**\n * The model-facing CUA screenshot size the Chrome extension emits by default\n * (`athena-in-chrome/extension/src/background.ts`, `CHROME_DEFAULT_WIDTH` /\n * `CHROME_DEFAULT_HEIGHT` in `chrome_browser_tools.py`). Surfaces may offer\n * it as the fallback basis for a point that omits `w`/`h`, clearly labelled\n * as assumed.\n */\nexport const DEFAULT_CUA_SCREENSHOT_SIZE = { width: 1280, height: 720 } as const;\n\n/** Width and height of a coordinate space, in that space's pixels. */\nexport interface ScreenSize {\n  width: number;\n  height: number;\n}\n\n/**\n * A point in screenshot space. `basis` is the size of the screenshot the pair\n * was read from; `null` when the link omitted it, in which case the point can\n * be shown but not placed. `tabId` is the Chrome tab the screenshot came from\n * when the agent had one.\n */\nexport interface ScreenPoint {\n  x: number;\n  y: number;\n  basis: ScreenSize | null;\n  tabId: number | null;\n}\n\n/**\n * Why a link that starts with the scheme could not become a point. Rendered\n * surfaces show the label as text with the reason in a tooltip, so a broken\n * link never becomes an interactive marker that points nowhere.\n */\nexport type ScreenPointParseError =\n  | \"not-screen-point\"\n  | \"missing-coordinate\"\n  | \"non-finite-number\"\n  | \"negative-number\"\n  | \"degenerate-basis\"\n  | \"out-of-bounds\"\n  | \"extent-too-large\";\n\nexport type ScreenPointParseResult =\n  | { ok: true; point: ScreenPoint }\n  | { ok: false; error: ScreenPointParseError };\n\n/** A number the agent may have written with a decimal point or a `~`: keep the integer pixel. */\nconst NUMBER_PATTERN = /^~?\\s*(-?\\d+(?:\\.\\d+)?)$/;\n\ntype NumberParse =\n  | { ok: true; value: number }\n  | { ok: false; error: \"non-finite-number\" | \"negative-number\" | \"extent-too-large\" }\n  | { ok: false; error: \"missing\" };\n\nfunction parseCoordinateNumber(raw: string | null): NumberParse {\n  if (raw === null || raw.trim() === \"\") return { ok: false, error: \"missing\" };\n  const match = NUMBER_PATTERN.exec(raw.trim());\n  if (!match) return { ok: false, error: \"non-finite-number\" };\n  const value = Number(match[1]);\n  if (!Number.isFinite(value)) return { ok: false, error: \"non-finite-number\" };\n  if (value < 0) return { ok: false, error: \"negative-number\" };\n  if (value > SCREEN_POINT_MAX_EXTENT) return { ok: false, error: \"extent-too-large\" };\n  return { ok: true, value: Math.round(value) };\n}\n\n/** Whether `href` is a screen-point link at all (the cheap pre-check). */\nexport function isScreenPointHref(href: string | null | undefined): href is string {\n  return typeof href === \"string\" && href.startsWith(SCREEN_POINT_HREF_PREFIX);\n}\n\n/**\n * Parse a screen-point link. Accepts the canonical form\n * `athena-point://screenshot?x=…&y=…&w=…&h=…&tab=…` and tolerates what a\n * model plausibly writes instead: `width`/`height` for `w`/`h`, `tab_id` for\n * `tab`, decimals, a leading `~`, and an empty or different host. Rejects,\n * with a reason, anything that would place a marker in the wrong spot:\n * non-finite or negative numbers, a zero or negative basis, a point outside\n * its basis, and absurd extents.\n */\nexport function parseScreenPointHref(href: string | null | undefined): ScreenPointParseResult {\n  if (!isScreenPointHref(href)) return { ok: false, error: \"not-screen-point\" };\n\n  // `new URL` treats a non-special scheme with an empty host inconsistently\n  // across engines; the query is the only part we read, so slice it off.\n  const queryStart = href.indexOf(\"?\");\n  if (queryStart === -1) return { ok: false, error: \"missing-coordinate\" };\n  const params = new URLSearchParams(href.slice(queryStart + 1));\n\n  const x = parseCoordinateNumber(params.get(\"x\"));\n  const y = parseCoordinateNumber(params.get(\"y\"));\n  if (!x.ok) return { ok: false, error: x.error === \"missing\" ? \"missing-coordinate\" : x.error };\n  if (!y.ok) return { ok: false, error: y.error === \"missing\" ? \"missing-coordinate\" : y.error };\n\n  const widthRaw = params.get(\"w\") ?? params.get(\"width\") ?? params.get(\"basisWidth\");\n  const heightRaw = params.get(\"h\") ?? params.get(\"height\") ?? params.get(\"basisHeight\");\n  let basis: ScreenSize | null = null;\n  if (widthRaw !== null || heightRaw !== null) {\n    const width = parseCoordinateNumber(widthRaw);\n    const height = parseCoordinateNumber(heightRaw);\n    // One dimension without the other is not a basis.\n    if (!width.ok || !height.ok) {\n      const failed = !width.ok ? width : height;\n      if (failed.ok) return { ok: false, error: \"degenerate-basis\" };\n      return {\n        ok: false,\n        error: failed.error === \"missing\" ? \"degenerate-basis\" : failed.error,\n      };\n    }\n    if (width.value <= 0 || height.value <= 0) return { ok: false, error: \"degenerate-basis\" };\n    basis = { width: width.value, height: height.value };\n    if (x.value > basis.width || y.value > basis.height) {\n      return { ok: false, error: \"out-of-bounds\" };\n    }\n  }\n\n  const tabRaw = params.get(\"tab\") ?? params.get(\"tab_id\") ?? params.get(\"tabId\");\n  let tabId: number | null = null;\n  if (tabRaw !== null && tabRaw.trim() !== \"\") {\n    const tab = Number(tabRaw);\n    tabId = Number.isInteger(tab) && tab >= 0 ? tab : null;\n  }\n\n  return { ok: true, point: { x: x.value, y: y.value, basis, tabId } };\n}\n\n/** The canonical link for a point — what the prompt teaches the agent to write. */\nexport function serializeScreenPointHref(point: ScreenPoint): string {\n  const params = new URLSearchParams();\n  params.set(\"x\", String(point.x));\n  params.set(\"y\", String(point.y));\n  if (point.basis) {\n    params.set(\"w\", String(point.basis.width));\n    params.set(\"h\", String(point.basis.height));\n  }\n  if (point.tabId !== null) params.set(\"tab\", String(point.tabId));\n  return `${SCREEN_POINT_HREF_PREFIX}${SCREEN_POINT_HOST}?${params.toString()}`;\n}\n\n/**\n * Where the point sits as a fraction of its basis, `0..1` on each axis, or\n * `null` when the point has no basis to be relative to. This is the only\n * number a renderer needs: `left: ${fx * 100}%` places the marker on any\n * rendition of the screenshot, whatever size it is drawn at.\n */\nexport function screenPointFraction(point: ScreenPoint): { fx: number; fy: number } | null {\n  if (!point.basis) return null;\n  return { fx: point.x / point.basis.width, fy: point.y / point.basis.height };\n}\n\n/** Whether two sizes are the same to within the few-pixel jitter a resize or scrollbar introduces. */\nexport function sameScreenSize({\n  a,\n  b,\n  tolerancePx = 4,\n}: {\n  a: ScreenSize;\n  b: ScreenSize;\n  tolerancePx?: number;\n}): boolean {\n  return Math.abs(a.width - b.width) <= tolerancePx && Math.abs(a.height - b.height) <= tolerancePx;\n}\n\n/**\n * How a point's basis relates to the screenshot it is about to be drawn on.\n * Mirrors the runtime's dispatch contract (`browser_coordinate_contract.json`):\n * the same size or a few pixels of jitter is `identity`; a uniform ratio on\n * both axes (browser zoom, a resized window at the same aspect) is\n * `uniform-scale` and the fraction still lands on the same element; anything\n * else is a `mismatch` — a different aspect ratio means the screenshot shows a\n * different framing (chrome headroom, a rotated device, a different tab) and\n * a fraction placed on it would point at the wrong thing.\n */\nexport type ScreenBasisFit =\n  | { kind: \"identity\" }\n  | { kind: \"uniform-scale\"; scale: number }\n  | { kind: \"mismatch\"; aspectDelta: number };\n\nexport function fitScreenBasis({\n  basis,\n  target,\n  aspectTolerance = 0.02,\n}: {\n  basis: ScreenSize;\n  target: ScreenSize;\n  aspectTolerance?: number;\n}): ScreenBasisFit {\n  if (\n    basis.width <= 0 ||\n    basis.height <= 0 ||\n    target.width <= 0 ||\n    target.height <= 0 ||\n    ![basis.width, basis.height, target.width, target.height].every(Number.isFinite)\n  ) {\n    return { kind: \"mismatch\", aspectDelta: Number.POSITIVE_INFINITY };\n  }\n  if (sameScreenSize({ a: basis, b: target })) return { kind: \"identity\" };\n  const scaleX = target.width / basis.width;\n  const scaleY = target.height / basis.height;\n  const aspectDelta = Math.abs(scaleX - scaleY) / Math.max(scaleX, scaleY);\n  if (aspectDelta <= aspectTolerance) return { kind: \"uniform-scale\", scale: (scaleX + scaleY) / 2 };\n  return { kind: \"mismatch\", aspectDelta };\n}\n\n/** Human-readable point for tooltips and accessible names: `(1038, 81) in a 1280×720 screenshot`. */\nexport function formatScreenPoint(point: ScreenPoint): string {\n  const pair = `(${point.x}, ${point.y})`;\n  if (!point.basis) return `${pair} — screenshot size not recorded`;\n  return `${pair} in a ${point.basis.width}×${point.basis.height} screenshot`;\n}\n\n/** The sentence a surface shows for a link that failed to parse. */\nexport function describeScreenPointError(error: ScreenPointParseError): string {\n  switch (error) {\n    case \"not-screen-point\":\n      return \"Not a screen point\";\n    case \"missing-coordinate\":\n      return \"Screen point is missing x or y\";\n    case \"non-finite-number\":\n      return \"Screen point has a non-numeric value\";\n    case \"negative-number\":\n      return \"Screen point has a negative value\";\n    case \"degenerate-basis\":\n      return \"Screen point has an invalid screenshot size\";\n    case \"out-of-bounds\":\n      return \"Screen point lies outside its screenshot\";\n    case \"extent-too-large\":\n      return \"Screen point value is implausibly large\";\n  }\n}\n\n/**\n * Screen points written into a text block, in order. Used by surfaces that\n * work on the raw markdown (the static message body's node parser, the\n * extension's plain-text composer) and by tests. Only the link form is\n * recognised — a bare `(1038, 81)` in prose is text, never a point, so a\n * model that was not taught the scheme changes nothing.\n */\nexport function findScreenPointLinks(\n  text: string,\n): Array<{ start: number; end: number; label: string; href: string }> {\n  const results: Array<{ start: number; end: number; label: string; href: string }> = [];\n  const pattern = /\\[([^\\]\\n]*)\\]\\((athena-point:\\/\\/[^\\s)]*)\\)/g;\n  for (const match of text.matchAll(pattern)) {\n    if (match.index === undefined) continue;\n    results.push({\n      start: match.index,\n      end: match.index + match[0].length,\n      label: match[1],\n      href: match[2],\n    });\n  }\n  return results;\n}\n"],"names":[],"mappings":"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"}

package/dist/packages/agent-runtime/src/send-recovery.cjs

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const statewireState = require("./statewire-state.cjs");
+const AUTO_RETRY_FATES = /* @__PURE__ */ new Set(["lost", "aborted"]);
+const MAX_AUTO_RETRIES_PER_MESSAGE = 3;
+const MAX_AUTO_RETRY_AGE_MS = 24 * 60 * 60 * 1e3;
+function shouldAutoRetryFailedSend(failure) {
+  return failure !== void 0 && AUTO_RETRY_FATES.has(failure.fate);
+}
+function awaitsLostPredecessor(entry) {
+  return entry.sendFailure.fate === "aborted" && entry.sendFailure.predecessorLost === true;
+}
+function commandMessageId(update) {
+  var _a, _b;
+  const first = (_a = update.params) == null ? void 0 : _a[0];
+  const id = (_b = first == null ? void 0 : first.message) == null ? void 0 : _b.id;
+  return typeof id === "string" ? id : null;
+}
+function createDeepAgentSendRecovery(options) {
+  const now = options.now ?? Date.now;
+  const schedule = options.schedule ?? ((task) => queueMicrotask(task));
+  let disposed = false;
+  let hydrated = false;
+  let armed = false;
+  let sweepScheduled = false;
+  const attempts = /* @__PURE__ */ new Map();
+  const surfacedSkips = /* @__PURE__ */ new Set();
+  const surfacedDeferrals = /* @__PURE__ */ new Set();
+  const inFlight = /* @__PURE__ */ new Set();
+  const deferred = /* @__PURE__ */ new Set();
+  const record = (event, data) => {
+    var _a, _b;
+    (_b = (_a = options.diagnostics) == null ? void 0 : _a.call(options)) == null ? void 0 : _b.record(event, data);
+  };
+  const sweep = () => {
+    var _a;
+    sweepScheduled = false;
+    if (disposed || !hydrated || !armed) return;
+    const lane = options.lane();
+    if (lane === null) return;
+    armed = false;
+    deferred.clear();
+    const stamps = ((_a = options.failureStamps) == null ? void 0 : _a.call(options)) ?? null;
+    let lostPredecessorPending = false;
+    for (const entry of lane.failed) {
+      if (!shouldAutoRetryFailedSend(entry.sendFailure)) continue;
+      if (inFlight.has(entry.id)) {
+        if (entry.sendFailure.fate === "lost") lostPredecessorPending = true;
+        continue;
+      }
+      if (awaitsLostPredecessor(entry) && (lostPredecessorPending || inFlight.size > 0)) {
+        deferred.add(entry.id);
+        if (!surfacedDeferrals.has(entry.id)) {
+          surfacedDeferrals.add(entry.id);
+          record("send-recovery/deferred", { messageId: entry.id });
+        }
+        continue;
+      }
+      const isLost = entry.sendFailure.fate === "lost";
+      const stamp = stamps == null ? void 0 : stamps.get(entry.id);
+      if (stamp !== void 0 && now() - stamp > MAX_AUTO_RETRY_AGE_MS) {
+        if (!surfacedSkips.has(entry.id)) {
+          surfacedSkips.add(entry.id);
+          record("send-recovery/stale", { messageId: entry.id, ageMs: Math.round(now() - stamp) });
+        }
+        if (isLost) lostPredecessorPending = true;
+        continue;
+      }
+      const attempt = (attempts.get(entry.id) ?? 0) + 1;
+      if (attempt > MAX_AUTO_RETRIES_PER_MESSAGE) {
+        if (!surfacedSkips.has(entry.id)) {
+          surfacedSkips.add(entry.id);
+          record("send-recovery/exhausted", { messageId: entry.id });
+        }
+        if (isLost) lostPredecessorPending = true;
+        continue;
+      }
+      try {
+        lane.retryFailed(entry.id);
+        attempts.set(entry.id, attempt);
+        inFlight.add(entry.id);
+        if (isLost) lostPredecessorPending = true;
+        record("send-recovery/retry", {
+          messageId: entry.id,
+          fate: entry.sendFailure.fate,
+          attempt
+        });
+      } catch {
+        record("send-recovery/raced", { messageId: entry.id });
+      }
+    }
+    if (deferred.size > 0) armed = true;
+  };
+  const scheduleSweep = () => {
+    if (disposed || sweepScheduled || !hydrated || !armed) return;
+    sweepScheduled = true;
+    schedule(sweep);
+  };
+  return {
+    observeStateChange(state) {
+      if (disposed) return;
+      if (!hydrated && statewireState.isDeepAgentStateHydrated(state)) {
+        hydrated = true;
+        armed = true;
+      }
+      scheduleSweep();
+    },
+    observeCommand(update) {
+      if (disposed || update.status !== "settled") return;
+      const messageId = commandMessageId(update);
+      if (messageId !== null) inFlight.delete(messageId);
+      if (!shouldAutoRetryFailedSend(update.failure) && deferred.size === 0) return;
+      armed = true;
+      scheduleSweep();
+    },
+    observeFailedLaneChange() {
+      if (disposed) return;
+      armed = true;
+      scheduleSweep();
+    },
+    dispose() {
+      disposed = true;
+    }
+  };
+}
+exports.createDeepAgentSendRecovery = createDeepAgentSendRecovery;
+exports.shouldAutoRetryFailedSend = shouldAutoRetryFailedSend;
+//# sourceMappingURL=send-recovery.cjs.map