@datalayer/agent-runtimes 1.5.26 → 1.5.28

package/lib/chat/base/conversationItems.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What the web chat draws of its conversation (MOBILE M-030): the rows of
+ * `reduceConversation`'s state as the `DisplayItem`s `ChatMessageList`
+ * renders, with what only the web holds beside them — what a message showed
+ * and who said it (Reactor UI ops, REACTOR_UI RU-W), the steps of an
+ * application's code (LOOP P-16), and what a message carried that the
+ * conversation does not keep (when it was said, a voice's metadata).
+ *
+ * The conversation is the reducer's; this only draws it. A turn that ended
+ * without words and a step of the AG-UI run are not drawn here, as they were
+ * not before; a failure is said as the assistant's words.
+ *
+ * @module chat/base/conversationItems
+ */
+import type { Display } from '@datalayer/reactor/ui';
+import type { ConversationItem, ConversationState } from '../../portable/conversation';
+import type { DisplayItem, DisplayToolCallStatus, ToolCallMessage } from '../../types/chat';
+import type { ChatMessage, MessageSpeaker } from '../../types/messages';
+type ToolItem = Extract<ConversationItem, {
+    kind: 'tool';
+}>;
+/** What a message carried that the conversation does not keep. */
+export type MessageExtras = Omit<ChatMessage, 'id' | 'role' | 'content'>;
+/** A step of an application's code, drawn after the row that was last when it began. */
+export type StepRow = {
+    item: ToolCallMessage;
+    after: string | null;
+};
+/** What only the web holds beside the conversation's rows. */
+export type ChatLayer = {
+    /** By message id: when it was said, and what else it carried. */
+    extras: ReadonlyMap<string, MessageExtras>;
+    /** By message id: what it showed (`show`, `ask`, `patch`, `append`). */
+    displays: ReadonlyMap<string, Display[]>;
+    /** By message id: who said it (`meta`). */
+    speakers: ReadonlyMap<string, MessageSpeaker>;
+    /** The steps of an application's code, in the order they began. */
+    steps: readonly StepRow[];
+};
+export declare const emptyChatLayer: () => ChatLayer;
+/** The id a tool call's card has: its call's, prefixed. */
+export declare const toolCardId: (toolCallId: string) => string;
+/** The conversation row a drawn item is: a card's call, else itself. */
+export declare const rowIdOf: (item: DisplayItem) => string;
+/** A tool call's status, as its card says it. */
+export declare function cardStatusOf(item: ToolItem): DisplayToolCallStatus;
+/** A tool call as its card draws it. */
+export declare function toolCallOf(item: ToolItem): ToolCallMessage;
+/**
+ * A drawer of a conversation: each row drawn once, and drawn again only when
+ * it, or what the web holds beside it, changed — so a message streaming
+ * leaves the others as they were, for React.
+ */
+export declare function conversationDrawer(errorWords: (text: string) => string): (state: ConversationState, layer: ChatLayer) => DisplayItem[];
+export {};

package/lib/chat/base/conversationItems.js

@@ -0,0 +1,126 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export const emptyChatLayer = () => ({
+    extras: new Map(),
+    displays: new Map(),
+    speakers: new Map(),
+    steps: [],
+});
+/** The id a tool call's card has: its call's, prefixed. */
+export const toolCardId = (toolCallId) => `tool-${toolCallId}`;
+/** The conversation row a drawn item is: a card's call, else itself. */
+export const rowIdOf = (item) => 'toolCallId' in item && item.id === toolCardId(item.toolCallId)
+    ? item.toolCallId
+    : item.id;
+/** A tool call's status, as its card says it. */
+export function cardStatusOf(item) {
+    if (item.status !== 'running') {
+        return item.status;
+    }
+    return item.awaiting === 'approval' ? 'inProgress' : 'executing';
+}
+/** A tool call as its card draws it. */
+export function toolCallOf(item) {
+    return {
+        id: toolCardId(item.id),
+        type: 'tool-call',
+        toolCallId: item.id,
+        toolName: item.name,
+        args: item.input ?? {},
+        // Its value; its words when the value was too long to keep.
+        ...(item.value !== undefined
+            ? { result: item.value }
+            : item.result
+                ? { result: item.result }
+                : {}),
+        status: cardStatusOf(item),
+        ...(item.error ? { error: item.error } : {}),
+        ...(item.executionError ? { executionError: item.executionError } : {}),
+        ...(item.codeError
+            ? {
+                codeError: {
+                    name: item.codeError.name,
+                    value: item.codeError.value,
+                    ...(item.codeError.traceback
+                        ? { traceback: item.codeError.traceback }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(item.exitCode !== null ? { exitCode: item.exitCode } : {}),
+    };
+}
+/**
+ * A drawer of a conversation: each row drawn once, and drawn again only when
+ * it, or what the web holds beside it, changed — so a message streaming
+ * leaves the others as they were, for React.
+ */
+export function conversationDrawer(errorWords) {
+    const drawn = new Map();
+    const message = (row, layer) => {
+        const extras = layer.extras.get(row.id);
+        const displays = layer.displays.get(row.id);
+        const speaker = layer.speakers.get(row.id);
+        const kept = drawn.get(row.id);
+        if (kept &&
+            kept.row === row &&
+            kept.extras === extras &&
+            kept.displays === displays &&
+            kept.speaker === speaker) {
+            return kept.item;
+        }
+        const item = {
+            ...extras,
+            createdAt: extras?.createdAt ?? new Date(),
+            id: row.id,
+            role: row.kind === 'message' ? row.role : 'assistant',
+            content: row.kind === 'message' ? row.text : errorWords(row.text),
+            ...(displays ? { displays } : {}),
+            ...(speaker ? { speaker } : {}),
+        };
+        drawn.set(row.id, { row, extras, displays, speaker, item });
+        return item;
+    };
+    const tool = (row) => {
+        const kept = drawn.get(row.id);
+        if (kept && kept.row === row) {
+            return kept.item;
+        }
+        const item = toolCallOf(row);
+        drawn.set(row.id, { row, item });
+        return item;
+    };
+    return (state, layer) => {
+        const items = [];
+        const after = new Map();
+        for (const step of layer.steps) {
+            after.set(step.after, [...(after.get(step.after) ?? []), step.item]);
+        }
+        items.push(...(after.get(null) ?? []));
+        const seen = new Set();
+        for (const row of state.items) {
+            seen.add(row.id);
+            if (row.kind === 'message' || row.kind === 'error') {
+                items.push(message(row, layer));
+            }
+            else if (row.kind === 'tool') {
+                items.push(tool(row));
+            }
+            items.push(...(after.get(row.id) ?? []));
+        }
+        // A step after a row since taken away: at the end.
+        for (const [anchor, steps] of after) {
+            if (anchor !== null && !seen.has(anchor)) {
+                items.push(...steps);
+            }
+        }
+        for (const id of drawn.keys()) {
+            if (!seen.has(id)) {
+                drawn.delete(id);
+            }
+        }
+        return items;
+    };
+}

package/lib/portable/adapterEvents.d.ts

@@ -0,0 +1,107 @@
+/**
+ * What every protocol adapter says, as the conversation reducer reads it
+ * (MOBILE M-030): the web chat's message state is `reduceConversation`'s,
+ * whatever protocol its agent speaks.
+ *
+ * ## What the adapters say (the inventory)
+ *
+ * Every adapter under `src/protocols` turns its wire into the same
+ * `ProtocolEvent`s, and `ChatBase` read only those:
+ *
+ * | Adapter | Messages | Tool calls | Results | Ends |
+ * |---|---|---|---|---|
+ * | AG-UI (`AGUIAdapter`) | `message`, its words so far, at each `TEXT_MESSAGE_CONTENT` and at `TEXT_MESSAGE_END`; a fresh id per `TEXT_MESSAGE_START` | `tool-call` at `TOOL_CALL_START` (`{}`, `argsComplete: false`), again at `TOOL_CALL_END` with the parsed arguments | `tool-result` from `TOOL_CALL_RESULT` through `toolResultOf` | `done` at `RUN_FINISHED` with no frontend call pending; `error` at `RUN_ERROR`; `CUSTOM` as `activity`, `STATE_*` as `state-update` |
+ * | Vercel AI (`VercelAIAdapter`) | `message`, its words so far, per `text-delta`, again at `finish-step`/`finish`/`[DONE]` | `tool-call` at `tool-input-available` (whole, `argsComplete: true`) or `tool-call` | `tool-result` at `tool-output-available`/`tool-output-error`; a `pending_approval` result for a server call left waiting at `finish` | `done` at `finish`/`[DONE]`; `error` |
+ * | A2A (`A2AAdapter`) | `message`, a whole part's text, a fresh id each | — | — | `state-update` with the task's final state; `activity` for data parts (A2UI) |
+ * | ACP (`ACPAdapter`) | `message`, its words so far | `tool-call` | `tool-result` | `activity`; `error` |
+ * | In-page agent (`BrowserAgentAdapter`) | `message`, its words so far | `tool-call` | `tool-result` | `done`; `error` |
+ *
+ * Every adapter that runs a frontend tool emits its result too when the page
+ * sends it (`sendToolResult`). ChatBase kept, per adapter alike: the messages
+ * by id, written over with each message's words so far (sanitised of a
+ * model's leaked call markup); the tool calls by id, their arguments merged,
+ * their status from the result (failed for an error, a sandbox's execution
+ * error, a code error, a non-zero exit code or `execution_ok: false`; still
+ * running while `pending_approval` or while the person confirms its steps); a
+ * `state-update` completing the newest running call with the state as its
+ * result; stop marking running calls interrupted; history restored from the
+ * runtime's messages (tool calls and their results merged into cards).
+ *
+ * ## The normalisation
+ *
+ * `conversationEventsOf` says each `ProtocolEvent` as the reducer's input: a
+ * message as `MESSAGE_SAID`, a call as `TOOL_CALL_SAID`, a result as
+ * `TOOL_CALL_DONE`, `done` as `RUN_FINISHED`, `error` as `RUN_ERROR`, an
+ * activity as `CUSTOM` (so `loop.session` is the session's here too).
+ * `snapshotOfMessages` says a conversation read again as one AG-UI
+ * `MESSAGES_SNAPSHOT`, its tool calls and their results with it. Both refuse
+ * what is malformed, in a sentence.
+ *
+ * @module portable/adapterEvents
+ */
+import type { AgUiEvent } from './agui';
+import type { ConversationState } from './conversation';
+/** One event of a protocol adapter (`ProtocolEvent`), as far as the conversation reads it. */
+export type AdapterEvent = {
+    type: string;
+    data?: unknown;
+    message?: {
+        id?: unknown;
+        role?: unknown;
+        content?: unknown;
+    };
+    toolCall?: {
+        toolCallId?: unknown;
+        toolName?: unknown;
+        args?: unknown;
+        argsComplete?: boolean;
+    };
+    toolResult?: {
+        toolCallId?: unknown;
+        success?: unknown;
+        result?: unknown;
+        error?: unknown;
+    };
+    activity?: {
+        type: string;
+        data: unknown;
+    };
+    error?: {
+        message?: string;
+    };
+};
+/** One message of a conversation read again (`ChatMessage`), as far as the conversation reads it. */
+export type SaidMessage = {
+    id: string;
+    role: string;
+    content: unknown;
+    toolCalls?: {
+        toolCallId: string;
+        toolName: string;
+        args?: Record<string, unknown>;
+        status?: string;
+        result?: unknown;
+    }[];
+    metadata?: Record<string, unknown>;
+};
+/**
+ * An answer without the call markup a model sometimes writes into its words
+ * (`<calls>`, `<invoke>`, `<parameter>` and their fragments).
+ */
+export declare function sanitizeAssistantContent(content: string): string;
+/**
+ * One adapter event as the reducer's input, given the conversation it comes
+ * to (a `state-update` answers its newest running call). Nothing for what is
+ * not the conversation's: a connection's coming and going, a usage count.
+ * Throws, in a sentence, for an event that does not say what its type needs.
+ */
+export declare function conversationEventsOf(event: AdapterEvent, state: ConversationState): AgUiEvent[];
+/**
+ * A conversation read again (the runtime's messages, a thread given, the
+ * messages a store kept) as one AG-UI `MESSAGES_SNAPSHOT`: its words, its
+ * tool calls and their results, which `role: 'tool'` messages carry (their
+ * call's id in `metadata.toolCallId`) or a call carries itself. An answer's
+ * words are sanitised as they were when it streamed. Throws for a message by
+ * anyone else, and for a call still under way: the past has none.
+ */
+export declare function snapshotOfMessages(messages: readonly SaidMessage[]): AgUiEvent;

package/lib/portable/adapterEvents.js

@@ -0,0 +1,239 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * An answer without the call markup a model sometimes writes into its words
+ * (`<calls>`, `<invoke>`, `<parameter>` and their fragments).
+ */
+export function sanitizeAssistantContent(content) {
+    if (!content || !content.includes('<')) {
+        return content;
+    }
+    let sanitized = content;
+    // Remove complete blocks first.
+    sanitized = sanitized
+        .replace(/<\s*calls\b[\s\S]*?<\s*\/\s*calls\s*>/gi, '')
+        .replace(/<\s*(?:an:)?tml:invoke\b[\s\S]*?<\s*\/\s*(?:an:)?tml:invoke\s*>/gi, '')
+        .replace(/<\s*(?:an:)?tml:parameter\b[\s\S]*?<\s*\/\s*(?:an:)?tml:parameter\s*>/gi, '');
+    // Remove standalone/open/close tags and malformed tag fragments.
+    sanitized = sanitized
+        .replace(/<\s*\/?\s*(?:an:[a-z_]+|tml:[a-z_]+|calls)\b[^>]*>?/gi, '')
+        .replace(/<\s*\/\s*>/g, '')
+        .replace(/^[ \t]+$/gm, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return sanitized;
+}
+const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/**
+ * The call a `state-update` answers: the newest still running that waits on
+ * neither an approval nor the person's steps — a tool that answers by setting
+ * the shared state (AG-UI `STATE_SNAPSHOT`).
+ */
+function stateAnswers(state) {
+    for (let index = state.items.length - 1; index >= 0; index -= 1) {
+        const item = state.items[index];
+        if (item.kind === 'tool' &&
+            item.status === 'running' &&
+            item.awaiting !== 'approval') {
+            // A call the person confirms (its steps) waits on them.
+            return item.input && Array.isArray(item.input.steps) ? null : item.id;
+        }
+    }
+    return null;
+}
+/**
+ * One adapter event as the reducer's input, given the conversation it comes
+ * to (a `state-update` answers its newest running call). Nothing for what is
+ * not the conversation's: a connection's coming and going, a usage count.
+ * Throws, in a sentence, for an event that does not say what its type needs.
+ */
+export function conversationEventsOf(event, state) {
+    switch (event.type) {
+        case 'connected':
+        case 'disconnected':
+            return [];
+        case 'message': {
+            const message = event.message;
+            if (message === undefined) {
+                // Only its usage: the turn's count, not its words.
+                return [];
+            }
+            if (typeof message.id !== 'string' || !message.id) {
+                throw new Error('A message came without its id.');
+            }
+            if (message.role !== 'user' && message.role !== 'assistant') {
+                throw new Error(`Message ${message.id} is said by ${String(message.role)}: only the person or the assistant speaks here.`);
+            }
+            if (typeof message.content !== 'string') {
+                throw new Error(`Message ${message.id} says no words.`);
+            }
+            return [
+                {
+                    type: 'MESSAGE_SAID',
+                    messageId: message.id,
+                    role: message.role,
+                    text: message.role === 'assistant'
+                        ? sanitizeAssistantContent(message.content)
+                        : message.content,
+                },
+            ];
+        }
+        case 'tool-call': {
+            const call = event.toolCall;
+            if (!call ||
+                typeof call.toolCallId !== 'string' ||
+                !call.toolCallId ||
+                typeof call.toolName !== 'string' ||
+                !call.toolName) {
+                throw new Error('A tool call came without its id and its name.');
+            }
+            if (!isRecord(call.args)) {
+                throw new Error(`Tool call ${call.toolCallId}'s arguments are not an object.`);
+            }
+            return [
+                {
+                    type: 'TOOL_CALL_SAID',
+                    toolCallId: call.toolCallId,
+                    toolCallName: call.toolName,
+                    args: call.args,
+                },
+            ];
+        }
+        case 'tool-result': {
+            const result = event.toolResult;
+            if (!result ||
+                typeof result.toolCallId !== 'string' ||
+                !result.toolCallId) {
+                throw new Error('A tool result came without the id of its call.');
+            }
+            if (typeof result.success !== 'boolean') {
+                throw new Error(`Tool result of ${result.toolCallId} does not say whether it succeeded.`);
+            }
+            if (result.error !== undefined && typeof result.error !== 'string') {
+                throw new Error(`Tool result of ${result.toolCallId} says its error in no words.`);
+            }
+            return [
+                {
+                    type: 'TOOL_CALL_DONE',
+                    toolCallId: result.toolCallId,
+                    success: result.success,
+                    result: result.result,
+                    ...(result.error !== undefined ? { error: result.error } : {}),
+                },
+            ];
+        }
+        case 'state-update': {
+            const data = event.data;
+            const answers = data ? stateAnswers(state) : null;
+            if (!answers) {
+                return [];
+            }
+            const shared = isRecord(data) ? data : {};
+            return [
+                {
+                    type: 'TOOL_CALL_DONE',
+                    toolCallId: answers,
+                    success: true,
+                    result: shared.weather ?? shared.result ?? shared.toolResult ?? data,
+                },
+            ];
+        }
+        case 'activity': {
+            if (!event.activity || typeof event.activity.type !== 'string') {
+                throw new Error('An activity came without its type.');
+            }
+            return [
+                {
+                    type: 'CUSTOM',
+                    name: event.activity.type,
+                    value: event.activity.data,
+                },
+            ];
+        }
+        case 'done':
+            return [{ type: 'RUN_FINISHED' }];
+        case 'error':
+            return [
+                { type: 'RUN_ERROR', message: event.error?.message || 'Run failed' },
+            ];
+        default:
+            throw new Error(`An adapter said ${event.type}, which no client reads.`);
+    }
+}
+/** A tool call read again, as an AG-UI assistant message says it. */
+function callOf(call, messageId) {
+    if (typeof call.toolCallId !== 'string' || !call.toolCallId) {
+        throw new Error(`Message ${messageId} holds a tool call without its id.`);
+    }
+    return {
+        id: call.toolCallId,
+        type: 'function',
+        function: {
+            name: call.toolName,
+            arguments: JSON.stringify(call.args ?? {}),
+        },
+    };
+}
+/**
+ * A conversation read again (the runtime's messages, a thread given, the
+ * messages a store kept) as one AG-UI `MESSAGES_SNAPSHOT`: its words, its
+ * tool calls and their results, which `role: 'tool'` messages carry (their
+ * call's id in `metadata.toolCallId`) or a call carries itself. An answer's
+ * words are sanitised as they were when it streamed. Throws for a message by
+ * anyone else, and for a call still under way: the past has none.
+ */
+export function snapshotOfMessages(messages) {
+    const said = [];
+    for (const message of messages) {
+        if (message.role === 'tool') {
+            const toolCallId = message.metadata?.toolCallId;
+            if (typeof toolCallId !== 'string' || !toolCallId) {
+                throw new Error(`Tool result ${message.id} does not say which call it answers.`);
+            }
+            said.push({
+                id: message.id,
+                role: 'tool',
+                toolCallId,
+                content: message.content,
+            });
+            continue;
+        }
+        if (message.role !== 'user' && message.role !== 'assistant') {
+            throw new Error(`Message ${message.id} is said by ${message.role}: only the person, the assistant and its tools speak here.`);
+        }
+        const words = typeof message.content === 'string'
+            ? message.role === 'assistant'
+                ? sanitizeAssistantContent(message.content)
+                : message.content
+            : '';
+        const calls = message.role === 'assistant' ? (message.toolCalls ?? []) : [];
+        said.push({
+            id: message.id,
+            role: message.role,
+            content: words,
+            ...(calls.length
+                ? { toolCalls: calls.map(call => callOf(call, message.id)) }
+                : {}),
+        });
+        for (const call of calls) {
+            if (call.status !== undefined &&
+                call.status !== 'completed' &&
+                call.status !== 'failed') {
+                throw new Error(`Tool call ${call.toolCallId} is read again ${call.status}: a conversation's past holds no call under way.`);
+            }
+            if (call.result !== undefined || call.status === 'failed') {
+                said.push({
+                    id: `${call.toolCallId}-result`,
+                    role: 'tool',
+                    toolCallId: call.toolCallId,
+                    content: call.status === 'failed'
+                        ? { success: false, error: 'failed', result: call.result ?? null }
+                        : call.result,
+                });
+            }
+        }
+    }
+    return { type: 'MESSAGES_SNAPSHOT', messages: said };
+}

package/lib/portable/approvalCard.d.ts

@@ -0,0 +1,56 @@
+/**
+ * An approval as every card says it (MOBILE M-016): the shared controller
+ * and prop contract under the web's *Waiting for you* and Datalayer Mobile's
+ * Inbox and detail. A message to send is shown whole — its recipients,
+ * subject and body — and anything else is every argument the tool gave,
+ * complete (the raw fallback), its private `_` markers said apart as *why it
+ * asked*. A renderer owns its markup and its buttons, never these words.
+ *
+ * @module portable/approvalCard
+ */
+import { type ApprovalArgs, type MessageAsked } from './approvals';
+/** What every approval card says. */
+export declare const APPROVAL_CARD_WORDS: {
+    readonly to: "To";
+    readonly cc: "Cc";
+    readonly bcc: "Bcc";
+    readonly subject: "Subject";
+    readonly forwards: "It forwards a message you received.";
+    readonly replies: "A reply, in its conversation.";
+    readonly arguments: "What it would do";
+    readonly why: "Why it asked";
+    readonly noArguments: "It gave no arguments.";
+};
+/** An approval's tool and arguments, under either naming. */
+export type ApprovalCardSource = ApprovalArgs & {
+    tool_name?: string;
+    toolName?: string;
+};
+/** What a card shows of one approval. */
+export type ApprovalCard = {
+    /** The tool as an action, in words: `send_email` → `Send email`. */
+    action: string;
+    /** Why it asked (its Rule or check), or `''`. */
+    why: string;
+    /** A message to send, shown whole; `null` for anything else. */
+    message: MessageAsked | null;
+    /** Every non-private argument, complete, when it is not a message. */
+    raw: string;
+    /** One line for a list row: a message's recipients and subject (never its body), else why. */
+    summary: string;
+};
+/** The props of an approval card, on every platform. */
+export type ApprovalCardProps = {
+    card: ApprovalCard;
+    status: string;
+    /** A decision being sent: both buttons wait. */
+    busy?: boolean;
+    onApprove?: () => void;
+    onReject?: () => void;
+};
+/** `send_email` → `Send email`. */
+export declare const actionOf: (toolName: string) => string;
+/** Every argument, complete, as the raw fallback; private `_` markers are said apart as *why*. */
+export declare function argumentsShown(approval: ApprovalCardSource): string;
+/** What a card shows of an approval. */
+export declare function approvalCardOf(approval: ApprovalCardSource): ApprovalCard;

package/lib/portable/approvalCard.js

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * An approval as every card says it (MOBILE M-016): the shared controller
+ * and prop contract under the web's *Waiting for you* and Datalayer Mobile's
+ * Inbox and detail. A message to send is shown whole — its recipients,
+ * subject and body — and anything else is every argument the tool gave,
+ * complete (the raw fallback), its private `_` markers said apart as *why it
+ * asked*. A renderer owns its markup and its buttons, never these words.
+ *
+ * @module portable/approvalCard
+ */
+import { messageOfApproval, whyAsked, } from './approvals';
+/** What every approval card says. */
+export const APPROVAL_CARD_WORDS = {
+    to: 'To',
+    cc: 'Cc',
+    bcc: 'Bcc',
+    subject: 'Subject',
+    forwards: 'It forwards a message you received.',
+    replies: 'A reply, in its conversation.',
+    arguments: 'What it would do',
+    why: 'Why it asked',
+    noArguments: 'It gave no arguments.',
+};
+const argsOf = (approval) => (approval.tool_args ?? approval.toolArgs ?? {});
+/** `send_email` → `Send email`. */
+export const actionOf = (toolName) => {
+    const words = toolName.replace(/[_-]+/g, ' ').trim();
+    return words ? words[0].toUpperCase() + words.slice(1) : 'An action';
+};
+/** Every argument, complete, as the raw fallback; private `_` markers are said apart as *why*. */
+export function argumentsShown(approval) {
+    const visible = Object.fromEntries(Object.entries(argsOf(approval)).filter(([key]) => !key.startsWith('_')));
+    return Object.keys(visible).length === 0
+        ? APPROVAL_CARD_WORDS.noArguments
+        : JSON.stringify(visible, null, 2);
+}
+/** What a card shows of an approval. */
+export function approvalCardOf(approval) {
+    const message = messageOfApproval(approval);
+    const why = whyAsked(approval);
+    return {
+        action: actionOf(String(approval.tool_name ?? approval.toolName ?? '')),
+        why,
+        message,
+        raw: message ? '' : argumentsShown(approval),
+        summary: message
+            ? message.subject
+                ? `${message.to} · ${message.subject}`
+                : message.to
+            : why,
+    };
+}