@athenaintel/react 0.41.3 → 0.42.1

package/dist/agent-runtime/src/queue.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Derivations for the server-owned statewire queue and steer lanes, shared by
+ * every queued-messages tray (Olympus, the React SDK, the Chrome extension).
+ *
+ * The queue is SERVER-owned: statewire surfaces it on the runs projection.
+ * "Send now" moves an item into the steer lane (`run/steer` — the host stops
+ * the run and dispatches it once the run settles; on a stopped/errored thread
+ * the same move dispatches immediately as a stop-/error-continue run) and
+ * remove issues `run/dequeue`. While the thread rests stopped/errored,
+ * stranded steer-lane entries list ahead of the queue — they dispatch first,
+ * as one batch, so they carry Remove but no per-row Send now.
+ *
+ * Pure helpers only: the host component reads `useStatewireRuns()` and
+ * `useDeepAgentThreadStatus()` itself (both mockable per surface) and passes
+ * the values in.
+ */
+import type { StatewireThread } from '@assistant-ui/react-statewire';
+import type { DeepAgentThreadStatus } from './thread-status';
+/** The text content of a queued entry (non-text parts render as fallbacks). */
+export declare function queueEntryText(parts: readonly {
+    type: string;
+    text?: string;
+}[]): string;
+/**
+ * Whether a lane entry is still awaiting its send's settle: the host stamps
+ * `meta` on every entry it admits (`_op_meta` — submitter and contextSync
+ * snapshot), so a meta-less entry is this client's own optimistic fold. The
+ * send is still in flight and can still be refused (billing gate, auth,
+ * reconnect), which the tray must not render as an accepted queue position.
+ */
+export declare function isQueueEntryUnsettled(entry: StatewireThread.RunsQueueEntry): boolean;
+/**
+ * The ids of queued entries the user prioritized (⚡ — `run/prioritize`), as
+ * the host records them in its durable `prioritizedQueueIds` state. A
+ * prioritized entry heads the queue lane and the live run ends at its next
+ * model-call boundary to deliver it, so trays render these rows lit and offer
+ * "Remove priority" instead of "Prioritize". Tolerates the key being absent
+ * (a thread that never prioritized, a pre-feature host) and ignores anything
+ * that is not a string id.
+ */
+export declare function readPrioritizedQueueIds(raw: unknown): readonly string[];
+export interface QueueLaneFlags {
+    isRunning: boolean;
+    /** A stopped/errored thread can continue with its queued work. */
+    isContinuable: boolean;
+}
+/** The thread-status split every queue tray keys its affordances on. */
+export declare function queueLaneFlags(status: DeepAgentThreadStatus): QueueLaneFlags;
+export interface StatewireQueueRow {
+    item: StatewireThread.RunsQueueEntry;
+    lane: 'queue' | 'steer';
+}
+/**
+ * The rows a queue tray renders, in dispatch order: stranded steer-lane
+ * entries first (only while the thread rests continuable — during a run they
+ * already render in the message list), then the queue lane.
+ */
+export declare function buildStatewireQueueRows(options: {
+    queue: readonly StatewireThread.RunsQueueEntry[];
+    steerQueue: readonly StatewireThread.RunsQueueEntry[];
+    isContinuable: boolean;
+}): StatewireQueueRow[];
+/**
+ * Whether a row offers "Send now": queue-lane rows only (steer entries already
+ * dispatch first), every row while the thread rests continuable, and only the
+ * head row while a run is live (later rows would jump the queue order).
+ */
+export declare function showQueueRowSendNow(options: {
+    lane: 'queue' | 'steer';
+    index: number;
+    isRunning: boolean;
+    isContinuable: boolean;
+}): boolean;
+/**
+ * Whether a row offers "Steer" (`run/steer-live`): queue-lane rows while a run
+ * is live. Steer folds the entry into the RUNNING turn at its next model call
+ * — after the in-flight tool chain, never mid-tool — and the run goes on with
+ * it in context (ChatGPT's and Codex's Steer, versus Queue). Nothing is
+ * cancelled and no second run starts, so every queued row qualifies, not just
+ * the head. At rest there is no turn to steer: Send now already dispatches.
+ */
+export declare function showQueueRowSteer(options: {
+    lane: 'queue' | 'steer';
+    isRunning: boolean;
+}): boolean;
+export type QueueEditCommand = {
+    type: 'run/steer';
+    runId: string;
+    message: StatewireThread.UserMessage;
+} | {
+    type: 'run/enqueue';
+    runId: string;
+    message: StatewireThread.UserMessage;
+};
+/**
+ * Re-send a queued entry under its own id on its own lane with edited text:
+ * the host replaces the queued message's content in place, leaving its queue
+ * position and lane untouched (a same-id send never dispatches). The built-in
+ * queue client has no update command, so this goes straight to the runs
+ * protocol. Returns `null` when there is nothing to send — blank or unchanged
+ * text, or no live run entry to address.
+ */
+export declare function buildQueueEditCommand(options: {
+    item: StatewireThread.RunsQueueEntry;
+    lane: 'queue' | 'steer';
+    runId: string | null;
+    text: string;
+    /**
+     * The edited message's metadata, replacing the entry's (the host replaces
+     * the queued message whole). Omitted, the entry's metadata is kept, minus a
+     * composer markdown that described the old text.
+     */
+    metadata?: Readonly<Record<string, unknown>> | undefined;
+}): QueueEditCommand | null;
+/**
+ * Grace between observing a stranded settle and auto-promoting the queue
+ * head — long enough for the host's own settle bookkeeping (or a status flap
+ * during reconnect) to resolve first, short enough to read as "it just
+ * continued" rather than "it hung".
+ */
+export declare const QUEUE_AUTO_CONTINUE_DELAY_MS = 2000;
+/** Whether the last cancellation marker records a user or client stop. */
+export declare function userStopBlocksQueueAutoContinue(options: {
+    marker: string | undefined;
+    source: string | undefined;
+}): boolean;
+/** `fate (cause)[: message]` — the detail a failed-send row carries. */
+export declare function describeQueueSendFailure(failure: StatewireThread.RunsFailedEntry['sendFailure']): string;
+/**
+ * Whether a `retryFailed` / `discardFailed` throw is the covered drop race:
+ * statewire drops a failed entry on its own as soon as a canonical update
+ * shows the message landed, and acting on a just-dropped entry throws. Both
+ * the session record ("unknown failed command") and the adapter's projection
+ * ("unknown failed entry") use this prefix. Nothing is lost in that race — the
+ * message already made it and the row is about to disappear — so a tray
+ * swallows it (keeping telemetry) instead of crashing the click handler.
+ */
+export declare function isFailedSendEntryRace(error: unknown): boolean;

package/dist/agent-runtime/src/quota-safe-local-storage-session.d.ts

@@ -0,0 +1,154 @@
+import type { StatewireClient } from "statewire";
+import { KeyValueSessionStorage } from "statewire/storage";
+/** A persisted session record: per-lane failed entries (a pre-lane record carried them at the root). */
+type SessionRecordLike = {
+    failed?: unknown;
+    lanes?: Record<string, {
+        failed?: unknown;
+    } | null | undefined> | null;
+};
+export declare function readPersistedFailedSendStamps(sessionKey: string): ReadonlyMap<string, number> | null;
+/**
+ * Send stamps (message id → epoch ms of the original send) off an already
+ * loaded session record's failed lane — the storage-agnostic half of
+ * {@link readPersistedFailedSendStamps}, for hosts whose session store is not
+ * localStorage (the React Native AsyncStorage-backed store reads its record
+ * synchronously through `SessionStorage.load()`).
+ *
+ * Returns `null` for no record (every failed entry then counts as fresh) and
+ * an empty map for a record without failures.
+ */
+export declare function readFailedSendStampsFromRecord(record: SessionRecordLike | null | undefined): ReadonlyMap<string, number> | null;
+/** A storage operation the session survived by degrading instead of failing. */
+export type SessionStorageDegradation = {
+    operation: "getItem" | "setItem" | "removeItem" | "getAllKeys" | "withUnused"
+    /** The lock manager refused the transaction fence; it ran unfenced. */
+     | "lock"
+    /**
+     * The stored record is one this build cannot read (not JSON, or a newer
+     * storage version): served as absent, and the key is shielded from being
+     * overwritten so the record survives this tab.
+     */
+     | "record"
+    /** statewire's own storage failure (a structurally invalid stored record). */
+     | "session"
+    /**
+     * Queued commands persisted by an earlier statewire build no longer fit
+     * the current wire/protocol range: parked in the lane's failed list (the
+     * send-recovery sweep re-dispatches them) instead of blocking the mount.
+     */
+     | "migrate";
+    key: string;
+    error: unknown;
+};
+type ProducedRange = NonNullable<StatewireClient.SessionCommand["produced"]>;
+/**
+ * The oldest wire whose stored statements the current client still replays.
+ * Bundled clients before #45143 offered 2026-09-13 through 2026-09-30 and
+ * stamped every queued statement with 2026-09-13. The durable statement grammar
+ * (protocol, method, params, meta, seq) is the same on 2026-09-30; only
+ * frame-level context differs. So those statements ride the current wire
+ * unchanged, while the network offer stays native 2026-09-30 only.
+ */
+export declare const STORED_STATEMENT_WIRE_FLOOR = "2026-09-13";
+/**
+ * statewire's `migrate` for a record whose queued commands were produced by
+ * an earlier build. A command whose statement the current wire still replays
+ * ({@link STORED_STATEMENT_WIRE_FLOOR}: an approval's `run/input` saved by a
+ * previous bundled client, say) stays queued, re-stamped with the current
+ * range, so it is delivered with its original seq. Every other incompatible
+ * command leaves its lane's queue and is
+ * retained as a `lost`/`session-lost` failed send re-stamped with the current
+ * range. Client identity, lane clocks, compatible commands and existing failed
+ * history are untouched, so the mount proceeds and the send-recovery sweep
+ * (or the user, via the failed-send UI) re-dispatches the parked sends under
+ * the negotiated format instead of the runtime throwing before it dials.
+ *
+ * Returns the record itself when nothing needed migrating, and the count of
+ * parked commands otherwise.
+ */
+export declare function parkIncompatibleSessionCommands(record: StatewireClient.SessionRecord, current: ProducedRange, now?: number): {
+    record: StatewireClient.SessionRecord;
+    parked: number;
+    restamped: number;
+};
+/**
+ * Whether `error` is the browser refusing a write for lack of room, under
+ * every name the engines use — `QuotaExceededError` (Chromium, WebKit, current
+ * Firefox), `NS_ERROR_DOM_QUOTA_REACHED` (older Firefox), the legacy
+ * `DOMException` codes 22 (WebKit) and 1014 (Firefox) — or a plain error whose
+ * message carries one of those (storage proxies and WebViews rewrap the
+ * exception). Olympus's `isStorageQuotaError` recognises the same set; the two
+ * stay in step.
+ */
+export declare function isStorageQuotaError(error: unknown): boolean;
+type SyncBackend = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+    getAllKeys: () => readonly string[];
+    withUnused: (key: string, action: () => Promise<void>) => Promise<void>;
+};
+/**
+ * Wraps a synchronous key-value backend so a failing origin degrades the
+ * session to memory-only persistence instead of stopping the connection.
+ *
+ * statewire's session storage latches the first unrecognised write failure
+ * and from then on rejects every send (`stopped/storage-error`, "session
+ * storage failed" on the connection chip). It only recovers a
+ * `QuotaExceededError` by that exact name — sweeping old session records and
+ * retrying the write once — and latches again when the retry fails too. Here
+ * the first quota failure per key is surfaced under that name so the sweep
+ * runs; the retry that follows it and every other storage failure are absorbed
+ * and reported through `onDegraded`, so chat keeps working.
+ *
+ * An absorbed write is kept in an in-memory overlay that `getItem` serves
+ * first: statewire re-reads the record through `load()` on every shared-mode
+ * transaction, so a stale persisted copy would otherwise win back its old
+ * `nextSeq`, `clientId` and command journal. The overlay is per tab — another
+ * tab sharing the thread still reads the last persisted copy, which is the
+ * memory-only degradation this backend exists to allow. A later successful
+ * write clears the overlay entry.
+ *
+ * A key whose read threw, or whose stored value this build cannot read (see
+ * {@link unreadableRecord}), is served as absent and shielded: writes to it
+ * stay in the overlay for good, so a fresh lane minted over an unreadable
+ * record never overwrites what another tab or a newer build persisted.
+ */
+export declare function quotaTolerantBackend({ inner, onDegraded, }: {
+    inner: SyncBackend;
+    onDegraded: (degradation: SessionStorageDegradation) => void;
+}): SyncBackend & KeyValueSessionStorage.Backend;
+/**
+ * Removes session records last saved more than `maxAgeMs` ago, skipping the
+ * keys mounted in this tab and, through `withUnused`, those another tab holds.
+ *
+ * statewire's own retention sweep only retires records with nothing queued and
+ * nothing failed: a record still carrying an unconfirmed or failed send is
+ * exempt from both its age and count bounds, so every thread left with one
+ * kept its key forever. Past the TTL those sends are long out of send
+ * recovery's auto-retry window, so the record goes the same way an empty one
+ * does.
+ */
+export declare function retireExpiredSessionRecords({ backend, mounted, maxAgeMs, now, }: {
+    backend: Pick<SyncBackend, "getItem" | "removeItem" | "getAllKeys" | "withUnused">;
+    mounted: ReadonlyMap<string, number>;
+    maxAgeMs: number;
+    now?: number;
+}): Promise<void>;
+/** Athena's browser session keys and retention policy. */
+export declare const QuotaSafeLocalStorageSession: import("@assistant-ui/tap").Resource<StatewireClient.SessionStorage, [QuotaSafeLocalStorageSession.Options]>;
+export declare namespace QuotaSafeLocalStorageSession {
+    type Options = {
+        threadId: string;
+        key?: (threadId: string) => string;
+        ttl?: number;
+        max?: number;
+        /**
+         * Called when a storage operation failed and the session carried on in
+         * memory. Defaults to one `console.warn` per operation and key.
+         */
+        onStorageDegraded?: (degradation: SessionStorageDegradation) => void;
+    };
+}
+export {};

package/dist/agent-runtime/src/running-tool-placeholder.cjs

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const RUNNING_PLACEHOLDER_KWARG = "streaming";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function isRunningToolPlaceholderArtifact(artifact) {
+  if (!isRecord(artifact)) return false;
+  const metadata = artifact._tool_message_metadata;
+  return isRecord(metadata) && metadata[RUNNING_PLACEHOLDER_KWARG] === true;
+}
+exports.isRunningToolPlaceholderArtifact = isRunningToolPlaceholderArtifact;
+//# sourceMappingURL=running-tool-placeholder.cjs.map

package/dist/agent-runtime/src/running-tool-placeholder.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"running-tool-placeholder.cjs","sources":["../../../../agent-runtime/src/running-tool-placeholder.ts"],"sourcesContent":["/**\n * The backend's running-tool placeholder: the ToolMessage a long-running tool's\n * card shows until the tool returns — a `task` subagent's live transcript, a\n * tool's preliminary result (Studio and Python execution progress, deep\n * research, image descriptions, drive indexing, AOP progress), or a\n * programmatic-tool-calling execution's sub-call log. Agora's\n * `running_tool_placeholder` builds all three: id `tool-running-<tool_call_id>`\n * and `additional_kwargs.streaming`. The tool's real ToolMessage replaces it by\n * `tool_call_id`, with its own id and no such flag.\n *\n * A placeholder is a `tool` message, so its mere presence gives the call a\n * defined `result`: read the flag before counting a call as done.\n *\n * Self-contained on purpose: the message converter imports it, so whatever it\n * imports ships in every surface's startup bundle (the Office pane's startup\n * budget has no room for `tool-result.ts`, which only tool cards need).\n */\n\nconst RUNNING_PLACEHOLDER_KWARG = 'streaming';\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\n/** Whether a raw wire message is a running tool's placeholder rather than its result. */\nexport function isRunningToolPlaceholder(message: unknown): boolean {\n  if (!isRecord(message) || message.type !== 'tool') return false;\n  const kwargs = message.additional_kwargs;\n  return isRecord(kwargs) && kwargs[RUNNING_PLACEHOLDER_KWARG] === true;\n}\n\n/**\n * Whether a converted tool-call part's `artifact` comes from a running tool's\n * placeholder: the converter lifts a ToolMessage's `additional_kwargs` into\n * `artifact._tool_message_metadata`, the marker included.\n */\nexport function isRunningToolPlaceholderArtifact(artifact: unknown): boolean {\n  if (!isRecord(artifact)) return false;\n  const metadata = artifact._tool_message_metadata;\n  return isRecord(metadata) && metadata[RUNNING_PLACEHOLDER_KWARG] === true;\n}\n"],"names":[],"mappings":";;AAkBA,MAAM,4BAA4B;AAElC,MAAM,WAAW,CAAC,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAc9D,SAAS,iCAAiC,UAA4B;AAC3E,MAAI,CAAC,SAAS,QAAQ,EAAG,QAAO;AAChC,QAAM,WAAW,SAAS;AAC1B,SAAO,SAAS,QAAQ,KAAK,SAAS,yBAAyB,MAAM;AACvE;;"}

package/dist/agent-runtime/src/running-tool-placeholder.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The backend's running-tool placeholder: the ToolMessage a long-running tool's
+ * card shows until the tool returns — a `task` subagent's live transcript, a
+ * tool's preliminary result (Studio and Python execution progress, deep
+ * research, image descriptions, drive indexing, AOP progress), or a
+ * programmatic-tool-calling execution's sub-call log. Agora's
+ * `running_tool_placeholder` builds all three: id `tool-running-<tool_call_id>`
+ * and `additional_kwargs.streaming`. The tool's real ToolMessage replaces it by
+ * `tool_call_id`, with its own id and no such flag.
+ *
+ * A placeholder is a `tool` message, so its mere presence gives the call a
+ * defined `result`: read the flag before counting a call as done.
+ *
+ * Self-contained on purpose: the message converter imports it, so whatever it
+ * imports ships in every surface's startup bundle (the Office pane's startup
+ * budget has no room for `tool-result.ts`, which only tool cards need).
+ */
+/** Whether a raw wire message is a running tool's placeholder rather than its result. */
+export declare function isRunningToolPlaceholder(message: unknown): boolean;
+/**
+ * Whether a converted tool-call part's `artifact` comes from a running tool's
+ * placeholder: the converter lifts a ToolMessage's `additional_kwargs` into
+ * `artifact._tool_message_metadata`, the marker included.
+ */
+export declare function isRunningToolPlaceholderArtifact(artifact: unknown): boolean;

package/dist/agent-runtime/src/running-tool-placeholder.js

@@ -0,0 +1,11 @@
+const RUNNING_PLACEHOLDER_KWARG = "streaming";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function isRunningToolPlaceholderArtifact(artifact) {
+  if (!isRecord(artifact)) return false;
+  const metadata = artifact._tool_message_metadata;
+  return isRecord(metadata) && metadata[RUNNING_PLACEHOLDER_KWARG] === true;
+}
+export {
+  isRunningToolPlaceholderArtifact
+};
+//# sourceMappingURL=running-tool-placeholder.js.map

package/dist/agent-runtime/src/running-tool-placeholder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"running-tool-placeholder.js","sources":["../../../../agent-runtime/src/running-tool-placeholder.ts"],"sourcesContent":["/**\n * The backend's running-tool placeholder: the ToolMessage a long-running tool's\n * card shows until the tool returns — a `task` subagent's live transcript, a\n * tool's preliminary result (Studio and Python execution progress, deep\n * research, image descriptions, drive indexing, AOP progress), or a\n * programmatic-tool-calling execution's sub-call log. Agora's\n * `running_tool_placeholder` builds all three: id `tool-running-<tool_call_id>`\n * and `additional_kwargs.streaming`. The tool's real ToolMessage replaces it by\n * `tool_call_id`, with its own id and no such flag.\n *\n * A placeholder is a `tool` message, so its mere presence gives the call a\n * defined `result`: read the flag before counting a call as done.\n *\n * Self-contained on purpose: the message converter imports it, so whatever it\n * imports ships in every surface's startup bundle (the Office pane's startup\n * budget has no room for `tool-result.ts`, which only tool cards need).\n */\n\nconst RUNNING_PLACEHOLDER_KWARG = 'streaming';\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\n/** Whether a raw wire message is a running tool's placeholder rather than its result. */\nexport function isRunningToolPlaceholder(message: unknown): boolean {\n  if (!isRecord(message) || message.type !== 'tool') return false;\n  const kwargs = message.additional_kwargs;\n  return isRecord(kwargs) && kwargs[RUNNING_PLACEHOLDER_KWARG] === true;\n}\n\n/**\n * Whether a converted tool-call part's `artifact` comes from a running tool's\n * placeholder: the converter lifts a ToolMessage's `additional_kwargs` into\n * `artifact._tool_message_metadata`, the marker included.\n */\nexport function isRunningToolPlaceholderArtifact(artifact: unknown): boolean {\n  if (!isRecord(artifact)) return false;\n  const metadata = artifact._tool_message_metadata;\n  return isRecord(metadata) && metadata[RUNNING_PLACEHOLDER_KWARG] === true;\n}\n"],"names":[],"mappings":"AAkBA,MAAM,4BAA4B;AAElC,MAAM,WAAW,CAAC,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAc9D,SAAS,iCAAiC,UAA4B;AAC3E,MAAI,CAAC,SAAS,QAAQ,EAAG,QAAO;AAChC,QAAM,WAAW,SAAS;AAC1B,SAAO,SAAS,QAAQ,KAAK,SAAS,yBAAyB,MAAM;AACvE;"}

package/dist/agent-runtime/src/runtime-messages.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Typed runtime messages — the one description of "the runtime ended this run"
+ * that every chat surface renders from.
+ *
+ * The deep-agent backend records how a run ended in two shapes that ride
+ * ordinary `ai` messages (a new LangChain message type would crash the shipped
+ * converter, whose convertible set is closed):
+ *
+ * - a **run-lifecycle marker** (`athena_run_marker`: `cancelled` / `failed`,
+ *   plus `athena_run_marker_source`) — see {@link readRunMarkerFromSourceMessages};
+ * - a **handoff message** (`athena_handoff: true`) — the closing summary the
+ *   runtime asked the model to write when a guard or the step budget ended the
+ *   run, instead of fabricating an internal sentence.
+ *
+ * Both now carry the canonical `athena_termination_reason`
+ * (`agora/graphs/athena_deep_agent/termination.py`). This module reads all of
+ * that into one {@link AthenaRuntimeMessage} so Olympus, mobile, the Chrome
+ * extension, and the Office add-in agree on kind, severity, copy, and the
+ * sole-vs-grouped distinction — the last of which is load-bearing: a marker
+ * appended after the assistant's own work is chunked into that message, and
+ * replacing the whole row would hide completed prose and tool cards.
+ */
+import { getExternalStoreMessages } from '@assistant-ui/core';
+/** The backend's canonical reason vocabulary (`KNOWN_TERMINATION_REASONS`). */
+export declare const TERMINATION_REASONS: readonly ['completed', 'user_stop', 'send_now', 'voice_steer', 'transport_cancel', 'pod_drain', 'fence_lost', 'instance_closed', 'unattributed_stop', 'recursion_limit', 'step_budget', 'duplicate_call_guard', 'synthetic_stop', 'ended_after_tools', 'error', 'model_refusal', 'abandoned'];
+export type AthenaTerminationReason = (typeof TERMINATION_REASONS)[number];
+/**
+ * How a runtime ending renders:
+ * - `stopped` — a cancellation the user (or a client action) asked for;
+ * - `paused` — a pod-drain pause; the run resumes from its checkpoint;
+ * - `failed` — the graph raised, hit the recursion limit, or was abandoned;
+ * - `handoff` — the runtime ended the run and the model wrote a closing
+ *   summary (the message text), which renders as prose under a banner.
+ */
+export type AthenaRuntimeMessageKind = 'stopped' | 'paused' | 'failed' | 'handoff';
+export type AthenaRuntimeMessageSeverity = 'info' | 'warning' | 'error';
+export interface TerminationDescription {
+    /** Short label for the banner / status row. */
+    title: string;
+    /** One sentence of reason-specific explanation, when it adds information. */
+    detail: string | undefined;
+}
+export interface AthenaRuntimeMessage {
+    kind: AthenaRuntimeMessageKind;
+    /** Canonical reason (may be a value newer than this client knows). */
+    reason: string | undefined;
+    severity: AthenaRuntimeMessageSeverity;
+    title: string;
+    detail: string | undefined;
+    /** The message's own text: a marker's backend copy, or the handoff summary. */
+    text: string | undefined;
+    /**
+     * A `send_now` promotion cancels the live run as plumbing, not as a
+     * user-visible stop: keep it in the data, paint nothing.
+     */
+    silent: boolean;
+    /**
+     * True when the runtime message is the ONLY source message behind this
+     * thread message (it owns the whole row). False when the chunk also holds
+     * the assistant's own work, which must keep rendering.
+     */
+    isSoleSourceMessage: boolean;
+}
+/**
+ * Copy for a runtime ending. Reasons this client does not know fall back to
+ * the kind's generic title, so a newer backend never renders as an empty row.
+ */
+export declare function describeTerminationReason(kind: AthenaRuntimeMessageKind, reason: string | undefined): TerminationDescription;
+type Kwargs = Record<string, unknown> | undefined;
+/** The termination reason stamped on `additional_kwargs` (top-level or mirror). */
+export declare function readTerminationReason(kwargs: Kwargs): string | undefined;
+/**
+ * Read the runtime ending behind a thread message, from its bound source
+ * messages first (a marker or handoff chunked after the assistant's own turn
+ * is never the first source, so the joined `metadata.custom` would miss it —
+ * see {@link readRunMarkerFromSourceMessages}), then from joined metadata for
+ * surfaces without bound sources.
+ */
+export declare function readRuntimeMessageFromSourceMessages(message: Parameters<typeof getExternalStoreMessages>[0] & {
+    metadata?: {
+        custom?: Record<string, unknown> | undefined;
+    } | undefined;
+    content?: unknown;
+}): AthenaRuntimeMessage | undefined;
+/**
+ * The backend marker copy worth showing under a runtime card, or `undefined`.
+ *
+ * A failure marker's text carries the specific error ("The run failed:
+ * provider returned 502"), so it is shown when no reason-specific detail
+ * exists. Stop/pause copy only restates the title, and a handoff's text is the
+ * message body itself, so neither is repeated. Marker copy leads with an emoji
+ * for raw-transcript readers; the card's icon plays that role, so it is
+ * stripped. Shared by every presenter so mobile and DOM cannot drift.
+ */
+export declare function runtimeMessageMarkerText(message: AthenaRuntimeMessage): string | undefined;
+/**
+ * The runtime message's kind when it owns the whole row, else `undefined`.
+ *
+ * Returns a primitive so it is safe as a `useAuiState` selector (the reader
+ * above builds a fresh object per call; an object snapshot would loop the
+ * render under `Object.is` comparison).
+ */
+export declare function readSoleRuntimeMessageKind(message: Parameters<typeof readRuntimeMessageFromSourceMessages>[0]): AthenaRuntimeMessageKind | undefined;
+export {};

package/dist/agent-runtime/src/screen-point.d.ts

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