@athenaintel/react 0.41.3 → 0.42.1

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

@@ -0,0 +1,603 @@
+import { getExternalStoreMessages, type ThreadMessage, type ThreadStep } from '@assistant-ui/core';
+import { type useExternalMessageConverter } from '@assistant-ui/core/react';
+import { type LangChainMessage } from '@assistant-ui/react-langgraph';
+import { type DeepAgentMessageAuthor } from './message-author';
+import type { DeepAgentToolOutputStore } from './tool-outputs';
+import type { DeepAgentWithdrawnTurns } from './withdrawn-turns';
+import type { DeepAgentLaneProjection, DeepAgentStreamValues, LangGraphState } from './types';
+/**
+ * A model call's token use as assistant-ui's native step usage, read off the
+ * LangChain message's `usage_metadata` with the session ledger's rule (agora
+ * `normalize_usage_metadata`, as `lane_usage.usage_counts` reads it; both are
+ * held to the same shapes): `inputTokens` counts the whole input, the prompt
+ * cache's reads and writes included, added in when the adapter left them out
+ * (the legacy Bedrock adapter) or the totals prove it did. `undefined` for a
+ * message that reports no usage.
+ */
+export declare function nativeStepUsage(message: LangChainMessage): ThreadStep['usage'];
+/**
+ * The shipped `convertLangChainMessages` with assistant-ui's native step and
+ * timing metadata filled in for an AI message: `metadata.steps` holds its model
+ * call with its token use ({@link nativeStepUsage}), and a turn's final message
+ * carries the turn's `metadata.timing` ({@link nativeTurnTiming}). assistant-ui
+ * joins a turn's messages by concatenating their steps (`joinExternalMessages`),
+ * so a converted turn lists every model call it made. Any other message converts
+ * as the shipped converter has it.
+ */
+export declare const convertDeepAgentLangChainMessage: useExternalMessageConverter.Callback<LangChainMessage>;
+/**
+ * Native message converter for the deep-agent runtime.
+ *
+ * This is the entire "conversion" layer: assistant-ui's shipped
+ * `convertLangChainMessages` (from `@assistant-ui/react-langgraph`) wired
+ * through `createMessageConverter`, with the native step and timing metadata
+ * the shipped converter leaves out ({@link convertDeepAgentLangChainMessage}).
+ * No bespoke per-message mapping — the agora `athena_deep_agent` graph streams
+ * standard LangChain messages via `append_langgraph_event`, and the shipped
+ * converter renders them.
+ */
+export declare const messageConverter: {
+    useThreadMessages: ({ messages, isRunning, joinStrategy, metadata, }: {
+        messages: LangChainMessage[];
+        isRunning: boolean;
+        joinStrategy?: import("@assistant-ui/core/store").JoinStrategy | undefined;
+        metadata?: useExternalMessageConverter.Metadata;
+    }) => ThreadMessage[];
+    toThreadMessages: (messages: LangChainMessage[], isRunning?: boolean, metadata?: useExternalMessageConverter.Metadata) => ThreadMessage[];
+    toOriginalMessages: (input: import("@assistant-ui/core").ThreadRuntimeState | ThreadMessage | ThreadMessage["content"][number]) => unknown[];
+    toOriginalMessage: (input: import("@assistant-ui/core").ThreadRuntimeState | ThreadMessage | ThreadMessage["content"][number]) => {};
+    useOriginalMessage: () => {};
+    useOriginalMessages: () => unknown[];
+};
+/**
+ * `message` with every tool call whose result is still the backend's
+ * running-tool placeholder (see {@link isRunningToolPlaceholderArtifact})
+ * marked `isPreliminary`: the result is interim, and the call has not settled.
+ *
+ * The shipped converter joins a placeholder ToolMessage into its call like any
+ * result, which would read as a finished call on every surface: assistant-ui
+ * gives a part with a result the `complete` status (cards draw "done", and a
+ * tool's completion side effects fire with the interim payload), and a tool's
+ * `streamCall` reader resolves with it. A preliminary part instead takes its
+ * message's status (`running` while the run is) and the reader waits for the
+ * real result, while the card still reads the interim one (progress, a deep
+ * research id, a streaming description). The real ToolMessage carries no
+ * marker, so its part is plain again. Turns without a placeholder pass through
+ * by identity.
+ */
+export declare function markPreliminaryToolResults(message: ThreadMessage): ThreadMessage;
+/**
+ * What a thread's conversion memory does: one pass's messages in, the pass's
+ * rows out. {@link DeepAgentMessageConversionCache} is the shared one; a host
+ * can build on it (`createSubagentTranscriptConversionCache`).
+ */
+export interface DeepAgentConversionMemory {
+    convert(messages: LangChainMessage[], isRunning: boolean): ThreadMessage[];
+}
+/**
+ * One thread's conversion memory: converting through it maps every source
+ * message that is unchanged since the previous pass to the IDENTICAL
+ * `ThreadMessage`, so a streamed token rebuilds only the turn it lands in
+ * instead of every message in the transcript (and every per-message
+ * subscriber, memo and tool card below it).
+ *
+ * Create one per attached thread and drop it with the attach: entries are
+ * keyed by source message identity (WeakMaps, so they die with the wire state
+ * that holds them), and a fresh cache per attach keeps one thread's converted
+ * messages from ever being served for another.
+ */
+export declare class DeepAgentMessageConversionCache implements DeepAgentConversionMemory {
+    private readonly cache;
+    /**
+     * Every cached entry is rebuilt when the metadata object changes identity,
+     * so it is created once per cache and never per pass. The tool-args
+     * key-order memory keeps a finished tool call's `argsText` in the order its
+     * arguments streamed in (assistant-ui's own LangGraph runtime passes the
+     * same).
+     */
+    private readonly metadata;
+    private previous;
+    /** `convertExternalMessages`' own rows for the previous pass, before parts were kept. */
+    private previousConverted;
+    /**
+     * Convert one pass's LangChain messages. Returns the previous pass's array
+     * itself when every converted message is unchanged, so a packet that moved
+     * no message re-renders no message; a re-converted turn keeps the row key
+     * of the row it continues (see {@link deepAgentRowKey}) and the previous
+     * pass's part objects for the parts that did not change
+     * (see {@link keepUnchangedParts}).
+     */
+    convert(messages: LangChainMessage[], isRunning: boolean): ThreadMessage[];
+}
+/**
+ * The key a deep-agent thread message renders under in a message list: its
+ * id, except for a turn that grew at its head.
+ *
+ * assistant-ui joins an agent run's consecutive messages into one turn whose
+ * id is its first message's, so a page of older history that folds into the
+ * first loaded turn (a long run's earlier steps) gives that turn a new id on
+ * every page. The conversion cache keeps such a turn under the key of the row
+ * it continues, so a list keyed by it keeps the turn's row, and the row's own
+ * state, while the page lands. What is mounted inside the row stays mounted
+ * only if the parts render under keys that survive the fold too: assistant-ui
+ * keys a toolkit group by its first part, which the fold changes when its
+ * steps join that group (`GroupedMessageParts` in `@athenaintel/react` carries
+ * the keys over). `message.id` stays the message's id: metadata, links and
+ * anchors read it.
+ *
+ * Takes a converted message or the message state assistant-ui publishes for
+ * it, which copies the key. A message from another runtime, or one converted
+ * without a conversion cache, renders under its id.
+ */
+export declare function deepAgentRowKey(message: {
+    readonly id: string;
+}): string;
+/** A conversion cache for one attached thread (see {@link DeepAgentMessageConversionCache}). */
+export declare function createDeepAgentMessageConversionCache(): DeepAgentMessageConversionCache;
+/**
+ * `metadata.custom` flag marking a bubble that is a projection of a run-lane
+ * entry — a message the server holds and has NOT dispatched yet.
+ *
+ * The lane is server-owned and replicated to every client on the thread, so
+ * an item queued on one surface projects onto all of them. Surfaces without a
+ * queue panel must therefore be able to tell a queued projection apart from a
+ * submitted turn, or a message another device queued renders as if this device
+ * had already sent it.
+ *
+ * `convertLangChainMessages` exposes `additional_kwargs.metadata` (and nothing
+ * else) as the thread message's `metadata.custom`.
+ */
+export declare const ATHENA_QUEUED_LANE_KEY = "athena_queued_lane";
+/**
+ * Whether a thread message's `metadata.custom` marks it as an undispatched
+ * lane projection. Returns a primitive, so it is safe to use directly as a
+ * `useAuiState` selector.
+ */
+export declare function isQueuedLaneMessage(custom: Record<string, unknown> | undefined): boolean;
+export interface DeepAgentMaterializeOptions {
+    /** The viewer, stamped onto this client's own not-yet-acknowledged sends. */
+    selfAuthor?: DeepAgentMessageAuthor | null;
+}
+/**
+ * Materialize fold for the statewire path: makes the server's dispatch record
+ * concrete in the LangGraph state itself, so direct state reads see dispatched
+ * messages and the lib's post-converter dispatch merge stays off.
+ */
+export declare const createDeepAgentMaterialize: ({ selfAuthor }?: DeepAgentMaterializeOptions) => (draft: DeepAgentStreamValues) => void;
+/** The materialize fold without a viewer identity (surfaces that pass none). */
+export declare const deepAgentMaterialize: (draft: DeepAgentStreamValues) => void;
+/**
+ * Project run lanes into human messages for the converter tail, so a queued or
+ * steered item stays visible below the pending-assistant placeholder until its
+ * dispatch. Surfaces with a queue panel project only the steer lane
+ * (`'steer-only'`); surfaces without one project both lanes (`'both'`).
+ *
+ * Every projected entry carries {@link ATHENA_QUEUED_LANE_KEY} so a surface
+ * without a queue panel can render it as queued rather than as a submitted
+ * turn.
+ */
+export declare const laneTailMessages: (state: unknown, laneProjection?: DeepAgentLaneProjection, selfAuthor?: DeepAgentMessageAuthor | null) => LangChainMessage[];
+/** Stable id for the derived running-assistant placeholder. */
+export declare const PENDING_ASSISTANT_MESSAGE_ID = "__athena_deep_agent_pending_assistant__";
+/**
+ * Append an empty assistant turn while a run is in flight and the visible
+ * history does not already end in one, so the thread shows its "Thinking…"
+ * status line from the moment a message is submitted.
+ *
+ * Mirrors `hasUpcomingMessage` in assistant-ui's legacy external-store runtime,
+ * which synthesized this placeholder itself. `StatewireThread` renders the
+ * converter's message list verbatim, so the placeholder has to come from here —
+ * derived from the replicated run status on every render (never written into
+ * transport state) so it cannot outlive the run, and carrying a stable id so
+ * the streaming bubble's identity does not churn when the real assistant
+ * message arrives.
+ *
+ * `tool` messages convert into assistant turns too, so a mid-run tool result
+ * must not produce a second placeholder row.
+ */
+export declare function withPendingAssistantMessage(messages: LangChainMessage[], isRunning: boolean): LangChainMessage[];
+/**
+ * Surface a run failure the base-correct way: stamp `status: { type:'incomplete',
+ * reason:'error', error }` onto the assistant turn so `<Thread/>` renders it via
+ * `ErrorPrimitive`. This is the core runtime's model (see `useLanggraphRuntime`
+ * `onError`) — NOT a fabricated `⚠️ The run failed` assistant text message, and
+ * NOT a magic-string contract shared with the agora backend.
+ *
+ * Stamps a trailing assistant message; if the visible history does not already
+ * end with an assistant turn, appends a synthetic empty assistant turn with a
+ * STABLE id so it never churns across renders. A `null` error is a no-op. The
+ * shipped `convertLangChainMessages` converter passes `message.status` through.
+ */
+export declare function applyRunErrorStatus(messages: LangChainMessage[], errorMessage: string | null): LangChainMessage[];
+/**
+ * `additional_kwargs` flag the backend stamps on run-lifecycle marker messages
+ * (agora `athena_deep_agent/run_markers.py`) — e.g. the "⏹️ Run stopped by
+ * user." message persisted when a run is cancelled.
+ */
+export declare const ATHENA_RUN_MARKER_KEY = "athena_run_marker";
+/** The {@link ATHENA_RUN_MARKER_KEY} value for a user-cancelled run. */
+export declare const ATHENA_RUN_MARKER_CANCELLED = "cancelled";
+/**
+ * `additional_kwargs` key carrying the stop source behind a cancellation
+ * marker (agora `stop_signals.py`: `user_stop`, `send_now`, `transport_cancel`,
+ * `unattributed`).
+ */
+export declare const ATHENA_RUN_MARKER_SOURCE_KEY = "athena_run_marker_source";
+/** The stop source for a "Send now" promotion pre-empting the live run. */
+export declare const ATHENA_STOP_SOURCE_SEND_NOW = "send_now";
+/**
+ * The stop source for a spoken follow-up that redirected a voice-delegated
+ * run through the steer lane: the user spoke, they never pressed Stop, so it
+ * renders as a redirect rather than as "Conversation stopped".
+ */
+export declare const ATHENA_STOP_SOURCE_VOICE_STEER = "voice_steer";
+/** The stop source for a pod-drain pause (server update), not a user stop. */
+export declare const ATHENA_STOP_SOURCE_POD_DRAIN = "pod_drain";
+/**
+ * The {@link ATHENA_RUN_MARKER_SOURCE_KEY} value for a run whose hosting
+ * instance closed under it (a server update that reached its eviction
+ * deadline mid-step, or a placement lost to a lease lapse). Same family as a
+ * pod drain: nobody stopped the run, the backend resumes it automatically.
+ */
+export declare const ATHENA_STOP_SOURCE_INSTANCE_CLOSED = "instance_closed";
+/**
+ * Whether a cancellation marker's source names the infrastructure — a pod
+ * drain or a closed instance — rather than a person or a client action. These
+ * endings read as a pause while the server resumes the run.
+ */
+export declare function isServerUpdateStopSource(source: string | undefined): boolean;
+/**
+ * The {@link ATHENA_RUN_MARKER_KEY} value for a failed run (graph error,
+ * including the `GraphRecursionError` "tool call limit was reached" case).
+ * The marker message's text content carries the user-facing failure copy.
+ */
+export declare const ATHENA_RUN_MARKER_FAILED = "failed";
+/**
+ * `additional_kwargs` key carrying the canonical reason a run ended (agora
+ * `athena_deep_agent/termination.py`): `user_stop`, `recursion_limit`,
+ * `duplicate_call_guard`, `step_budget`, `ended_after_tools`, `model_refusal`,
+ * `completed`, …
+ * Stamped on run-lifecycle markers and on handoff messages.
+ */
+export declare const ATHENA_TERMINATION_REASON_KEY = "athena_termination_reason";
+/**
+ * `additional_kwargs` flag on the closing message the runtime's **handoff
+ * turn** wrote (one tools-disabled model call made when a guard or the step
+ * budget ends the run). The message text is the agent's closing summary; the
+ * flag lets clients frame it as a runtime ending rather than a normal reply.
+ */
+export declare const ATHENA_HANDOFF_KEY = "athena_handoff";
+/**
+ * Read a run-lifecycle marker out of a thread message's **bound source
+ * messages**, bypassing the converter's metadata join entirely.
+ *
+ * Why this exists: assistant-ui chunks consecutive assistant/tool messages
+ * into ONE `ThreadMessage`, and the upstream join copies `metadata.custom`
+ * only from the FIRST assistant message of the chunk
+ * (`external-message-converter.ts`: the merge sits inside
+ * `if (assistantMessage.content.length === 0)`). A failure marker appended
+ * after the assistant's own turn is therefore never the first message in its
+ * chunk, so `message.metadata.custom.athena_run_marker` is silently dropped
+ * and the whole-message gate can't fire.
+ *
+ * `getExternalStoreMessages` returns the raw LangChain messages bound to the
+ * joined thread message, so the marker is found wherever it sits in the chunk.
+ * Returns the marker value plus its text content (the user-facing copy).
+ */
+export interface RunMarkerInfo {
+    marker: string;
+    /** The stop source stamped by the backend, when the marker carries one. */
+    source: string | undefined;
+    /** The marker message's text — the user-facing copy. */
+    text: string | undefined;
+    /**
+     * True when the marker is the ONLY source message behind this thread message,
+     * i.e. it owns the whole row (a cancelled run drops its partial turn, so its
+     * marker stands alone).
+     *
+     * False when the chunk also holds the assistant's own work. Replacing the row
+     * in that case would hide completed prose and tool cards — the marker must be
+     * styled in place instead.
+     */
+    isSoleSourceMessage: boolean;
+}
+export declare function readRunMarkerFromSourceMessages(message: Parameters<typeof getExternalStoreMessages>[0] & {
+    metadata?: {
+        custom?: Record<string, unknown> | undefined;
+    } | undefined;
+    content?: unknown;
+}): RunMarkerInfo | undefined;
+/**
+ * The marker value when the marker is the SOLE source message behind a thread
+ * message (it owns the whole row), else `undefined`.
+ *
+ * Returns a primitive so it is safe to use directly as a `useAuiState`
+ * selector: `readRunMarkerFromSourceMessages` builds a fresh object on every
+ * call, and selector snapshots are compared with `Object.is` — returning that
+ * object from a selector makes `getSnapshot` unstable and loops the render.
+ */
+export declare function readSoleRunMarker(message: Parameters<typeof readRunMarkerFromSourceMessages>[0]): string | undefined;
+/**
+ * Whether a run marker renders nothing: a `send_now` promotion cancels the
+ * live run as plumbing, not as a user-visible stop, so its cancellation
+ * marker stays in the data for provenance but paints no divider.
+ */
+export declare function isSilentRunMarker(found: RunMarkerInfo): boolean;
+/**
+ * Whether a cancellation marker records a server-update pause — a cooperative
+ * pod drain, or the hosting instance closing under the run — rather than a
+ * stop the user asked for. Rendered with distinct "paused by a server update"
+ * copy instead of the "Conversation stopped" pill; the backend resumes the run.
+ */
+export declare function isDrainRunMarker(found: RunMarkerInfo): boolean;
+/**
+ * Surface the backend's top-level `additional_kwargs.athena_run_marker` flag
+ * where the shipped converter can see it.
+ *
+ * `convertLangChainMessages` exposes ONLY `additional_kwargs.metadata` as the
+ * thread message's `metadata.custom`; every other `additional_kwargs` key is
+ * dropped. Marker messages persisted before the backend mirrored the flag into
+ * `metadata` carry it top-level only, so this lift keeps those threads styling
+ * correctly. Non-marker messages pass through with their identity unchanged,
+ * and already-mirrored markers are left as-is (idempotent).
+ */
+export declare function liftRunMarkerIntoMetadata(message: LangChainMessage): LangChainMessage;
+/**
+ * Mirror the termination reason and handoff flag into the converter's metadata
+ * channel. The backend dual-writes both (top-level + `metadata`), so this lift
+ * is the back-compat path for messages persisted before the mirror existed and
+ * for any emitter that only stamps the top-level key. Idempotent; identity for
+ * messages without the keys.
+ */
+export declare function liftTerminationIntoMetadata(message: LangChainMessage): LangChainMessage;
+/**
+ * `additional_kwargs` key (and `metadata` mirror) carrying a failure marker's
+ * structured error records (agora `athena_deep_agent/run_markers.py`
+ * `failure_error_records`): `[{ error, provider?, message? }]`, where `error`
+ * is the client code a surface branches on — `context_length_exceeded`,
+ * `transient_api_error` (with `provider: 'azure_foundry' |
+ * 'external_model_provider'`), `content_filter`, `request_too_large`, … — the
+ * same shape the legacy agent node emitted.
+ */
+export declare const ATHENA_ERRORS_KEY = "errors";
+/**
+ * Mirror a failure marker's structured `errors` records into the converter's
+ * metadata channel. The backend dual-writes them (top-level + `metadata`), so
+ * this lift is the back-compat path for messages that carry only the top-level
+ * key (an emitter that never mirrored, or a record persisted before the mirror
+ * existed). Records already present in the metadata channel win; no-ops are
+ * identity.
+ */
+export declare function liftErrorsIntoMetadata(message: LangChainMessage): LangChainMessage;
+/**
+ * Read a failure's structured `errors` records out of a thread message's
+ * **bound source messages**, bypassing the converter's metadata join.
+ *
+ * Same reason as {@link readRunMarkerFromSourceMessages}: assistant-ui chunks
+ * consecutive assistant/tool messages into ONE `ThreadMessage` and copies
+ * `metadata.custom` only from the FIRST assistant message of the chunk. The
+ * failure marker that carries the records is appended after the assistant's
+ * own turn, so `message.metadata.custom.errors` is silently dropped whenever
+ * the run produced anything before failing. The bound sources are walked from
+ * the tail (the terminal failure wins); the joined metadata is the fallback
+ * for surfaces whose messages carry no bound sources. Returns the raw records
+ * (callers validate the shape) or `undefined`.
+ */
+export declare function readMessageErrorsFromSourceMessages(message: Parameters<typeof getExternalStoreMessages>[0] & {
+    metadata?: {
+        custom?: Record<string, unknown> | undefined;
+    } | undefined;
+}): unknown[] | undefined;
+/**
+ * Mirror the producing model into the converter's metadata channel. Wire AI
+ * messages are full LangChain dumps whose `response_metadata` reports the model
+ * that generated them (`model_name` / `model`), but the shipped converter maps
+ * only `additional_kwargs.metadata` into `metadata.custom` — so without this
+ * lift a surface can only show the CURRENT run config's model, mislabeling
+ * earlier messages after a mid-thread model switch. A model already present in
+ * the metadata channel (backend-stamped provenance) wins; no-ops are identity.
+ */
+export declare function liftModelIntoMetadata(message: LangChainMessage): LangChainMessage;
+/**
+ * Mirror a per-message conversation-stats snapshot into the converter's
+ * metadata channel. Backends stamp the snapshot at the legacy location —
+ * top-level `additional_kwargs.conversation_stats` (the deep-agent stats
+ * middleware and the legacy agent node both write it there) — but the shipped
+ * converter maps only `additional_kwargs.metadata` into `metadata.custom`, so
+ * without this lift the model badge can never show a message's OWN context and
+ * falls back to thread-level live numbers. A snapshot already present in the
+ * metadata channel wins; no-ops are identity.
+ */
+export declare function liftConversationStatsIntoMetadata(message: LangChainMessage): LangChainMessage;
+/**
+ * Mirror the compaction boundary flag into the converter's metadata channel.
+ * A manual `/compact` persists its summary as a human message tagged with
+ * top-level `additional_kwargs.compaction_start` (plus `_created_at` for the
+ * divider timestamp) — the same location the legacy runtime used — but the
+ * shipped converter maps only `additional_kwargs.metadata` into
+ * `metadata.custom`, so without this lift the transcript's
+ * "Previous conversation summarized" divider can never render. A flag already
+ * present in the metadata channel wins; no-ops are identity.
+ */
+export declare function liftCompactionBoundaryIntoMetadata(message: LangChainMessage): LangChainMessage;
+/**
+ * Mirror the handoff summary flag into the converter's metadata channel.
+ * Handoff summaries are persisted as human messages tagged with top-level
+ * `additional_kwargs.handoff_summary` (plus `_created_at`) — the same location
+ * the backend uses for message metadata — but the shipped converter maps only
+ * `additional_kwargs.metadata` into `metadata.custom`, so without this lift
+ * the summary would render as a normal user bubble. A flag already present in
+ * the metadata channel wins; no-ops are identity.
+ */
+export declare function liftHandoffSummaryIntoMetadata(message: LangChainMessage): LangChainMessage;
+/**
+ * Mirror an AOP run's provenance into the converter's metadata channel. The
+ * backend stamps the kicking-off user message with top-level
+ * `additional_kwargs.aop_source` (agora `events/helpers.py`
+ * `_build_aop_source_metadata`), which the legacy converter surfaced as
+ * `metadata.custom.aop_source` — where the "AOP · <title>" badge reads it. The
+ * shipped `convertLangChainMessages` maps only `additional_kwargs.metadata`
+ * into `metadata.custom`, so without this lift an AOP run's conversation never
+ * shows which AOP asset kicked it off. Provenance already present in the
+ * metadata channel wins; no-ops are identity.
+ */
+export declare function liftAopSourceIntoMetadata(message: LangChainMessage): LangChainMessage;
+export declare function liftBranchIntoMetadata(message: LangChainMessage): LangChainMessage;
+/**
+ * Mirror a ToolMessage's user-set `additional_kwargs` into
+ * `artifact._tool_message_metadata` — the location `useToolCallMetadata` reads
+ * persisted per-tool-call metadata from (`email_sent_at`, draft edits,
+ * `calendar_event_created_at`, …).
+ *
+ * The `setMessageMetadata` mutation persists those keys onto the ToolMessage's
+ * `additional_kwargs` in the checkpoint, and the legacy converter lifted them
+ * into the artifact. The shipped `convertLangChainMessages` forwards only
+ * `artifact` and drops `additional_kwargs` for tool messages, so without this
+ * lift the metadata survives in the checkpoint but never reaches a tool card
+ * after a reload. Kwargs values win over same-key artifact entries (the kwargs
+ * are the durable write target); messages with no user-set kwargs pass through
+ * by identity.
+ */
+export declare function liftToolMessageMetadataIntoArtifact(message: LangChainMessage): LangChainMessage;
+/**
+ * Lift a windowed wire's tool-output truncation marker into the tool-call
+ * part's `artifact` (`_athena_content_truncated: { chars, messageId }`).
+ *
+ * The host cuts long plain-text tool outputs on a windowed wire and stamps
+ * `athena_content_truncated` on the wire message; the shipped converter joins
+ * a ToolMessage into its assistant turn's tool-call part and keeps only
+ * `artifact` and the result, so without this lift no tool card could tell the
+ * output is cut nor which message to ask `history/tool_output` for. Messages
+ * without the marker pass through by identity.
+ */
+export declare function liftTruncatedToolOutputIntoArtifact(message: LangChainMessage): LangChainMessage;
+/**
+ * A content list's bare-string entries as typed text parts.
+ *
+ * LangChain content is `string | (string | ContentBlock)[]`, and a model with
+ * no tools bound streams exactly that mix: `langchain_anthropic` coerces text
+ * deltas to plain strings when no tools are bound, yet a thinking block still
+ * arrives as a list block, so the merged reply is `["", {thinking}, "text"]`
+ * (the side-question lane's bare model). The shipped converter maps only typed
+ * blocks and drops the strings, leaving the reasoning with no answer. Empty
+ * strings are dropped; messages with no string entries pass through by
+ * identity.
+ */
+export declare function normalizeStringContentParts(message: LangChainMessage): LangChainMessage;
+/**
+ * A cut tool message with its full output put back, when the store holds one
+ * fetched for this very output (`history/tool_output` answered for the same
+ * `chars` the wire's marker reports); the marker leaves with the cut.
+ * Messages that are whole, whose output has not been fetched, or whose fetched
+ * output belongs to a length the host has since replaced, pass through by
+ * identity — the loader sees the mismatch and fetches again.
+ */
+export declare function substituteToolOutput(message: LangChainMessage, toolOutputs: DeepAgentToolOutputStore): LangChainMessage;
+/**
+ * Internal orchestration messages are useful in a trace export but must never
+ * become conversation bubbles. Agora stores the flag in `additional_kwargs`;
+ * live converter state can expose the same value under `metadata.custom`.
+ */
+export declare function isMessageHiddenFromFrontend(message: unknown): boolean;
+/**
+ * Whether `convertLangChainMessages` can map this message at all.
+ *
+ * An unmappable entry converts to `undefined`, which assistant-ui's
+ * `convertExternalMessages` wraps as `outputs: [undefined]` and then reads
+ * `output.role` off — throwing `Cannot read property 'role' of undefined` and
+ * taking the entire thread down instead of dropping one message.
+ */
+export declare function isConvertibleChatMessage(message: unknown): boolean;
+/**
+ * The one message pipeline every deep-agent surface renders through:
+ *
+ * 1. drop messages the shipped converter cannot map (`RemoveMessage` etc. —
+ *    an unmappable entry would crash the whole thread) and internal
+ *    orchestration messages flagged hidden-from-frontend;
+ * 1a. turn bare-string entries of a content list into typed text parts (see
+ *    {@link normalizeStringContentParts}) so a tool-less model's answer next
+ *    to its thinking block is not dropped by the converter;
+ * 2. lift run-lifecycle markers into the converter's `metadata` channel
+ *    (see {@link liftRunMarkerIntoMetadata}) so the cancellation row styles as
+ *    a status divider instead of a plain assistant bubble, and the termination
+ *    reason + handoff flag alongside them (see
+ *    {@link liftTerminationIntoMetadata}) so every surface can render a
+ *    runtime ending (see `runtime-messages.ts`);
+ * 3. lift each AI message's producing model into the same channel
+ *    (see {@link liftModelIntoMetadata}) so model badges reflect the model that
+ *    actually generated the message, not the currently configured one;
+ * 4. lift each AI message's per-message conversation-stats snapshot into the
+ *    same channel (see {@link liftConversationStatsIntoMetadata}) so the model
+ *    badge's hover card shows that message's own context usage;
+ * 5. lift the compaction boundary flag on `/compact` summary messages into the
+ *    same channel (see {@link liftCompactionBoundaryIntoMetadata}) so the
+ *    transcript renders its "Previous conversation summarized" divider;
+ * 6. lift the handoff summary flag on carried-over context messages into the
+ *    same channel (see {@link liftHandoffSummaryIntoMetadata}) so the
+ *    transcript keeps the summary behind its context panel;
+ * 7. lift an AOP run's provenance on its kicking-off user message into the
+ *    same channel (see {@link liftAopSourceIntoMetadata}) so the message
+ *    renders its "AOP · <title>" origin badge;
+ * 8. lift each ToolMessage's user-set `additional_kwargs` into
+ *    `artifact._tool_message_metadata` (see
+ *    {@link liftToolMessageMetadataIntoArtifact}) so persisted per-tool-call
+ *    metadata reaches tool cards after a reload;
+ * 9. lift a windowed wire's tool-output truncation marker into the tool-call
+ *    part's `artifact` (see {@link liftTruncatedToolOutputIntoArtifact}) so a
+ *    tool card can fetch the whole output — after first putting back any
+ *    output already fetched (see {@link substituteToolOutput});
+ * 10. lift the host's per-message branch stamp into the same channel
+ *    (see {@link liftBranchIntoMetadata}) so the branch picker renders each
+ *    message's edit fan-out.
+ *
+ * Identity-stable per source: an unchanged source message maps to the
+ * IDENTICAL lifted object across passes (see {@link liftedMessageCache}).
+ */
+export declare function sanitizeLangChainMessages(messages: readonly LangChainMessage[], { toolOutputs }?: {
+    toolOutputs?: DeepAgentToolOutputStore;
+}): LangChainMessage[];
+/** Type guard for the runtime state — an object carrying a `messages` array. */
+export declare function isLangGraphState(value: unknown): value is LangGraphState;
+export interface ConvertDeepAgentStateOptions {
+    laneProjection?: DeepAgentLaneProjection;
+    /**
+     * The viewer, as the backend would stamp them: the author of this client's
+     * own not-yet-acknowledged lane entries (see {@link laneEntryAuthor}).
+     */
+    selfAuthor?: DeepAgentMessageAuthor | null;
+    /**
+     * Full tool outputs fetched back for a windowed wire's cut tool messages
+     * (see {@link substituteToolOutput}); omitted on surfaces that never
+     * declare a window.
+     */
+    toolOutputs?: DeepAgentToolOutputStore;
+    /**
+     * User turns this client took back ahead of the wire (see
+     * {@link DeepAgentWithdrawnTurns}): omitted from the transcript, together
+     * with the pending-assistant placeholder a withdrawn tail would earn.
+     */
+    withdrawnTurns?: DeepAgentWithdrawnTurns;
+    /**
+     * The attached thread's conversion memory (see
+     * {@link createDeepAgentMessageConversionCache}): unchanged messages keep
+     * their converted identity across passes. Without one every pass converts
+     * the whole transcript from scratch.
+     */
+    conversionCache?: DeepAgentConversionMemory;
+}
+/**
+ * Map server state → assistant-ui thread messages.
+ *
+ * `state.messages` is the authoritative LangChain history streamed by the
+ * backend. The replicated run status (`runs[0].status`) drives the
+ * pending-assistant placeholder and the running status. Lane entries render at
+ * the tail, after the placeholder, while the run is live (the run is still
+ * working the history above them); once the thread rests stopped/errored they
+ * are omitted (surfaces with a queue panel list them there instead).
+ * Consecutive spoken user turns collapse into one user message (see
+ * {@link groupSpokenUserTurns}) before conversion.
+ */
+export declare function convertDeepAgentState(state: unknown, { laneProjection, selfAuthor, toolOutputs, withdrawnTurns, conversionCache, }?: ConvertDeepAgentStateOptions): {
+    messages: ThreadMessage[];
+    isRunning: boolean;
+};