@calliopelabs/ui 0.13.0 → 0.16.0

package/dist/chat/MessageList.js

@@ -0,0 +1,71 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ArrowDownIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/Button.js";
+import { useUI } from "../provider/UIProvider.js";
+import { EmptyState } from "../states/EmptyState.js";
+import { LoadingState } from "../states/LoadingState.js";
+import { MessageBubble } from "./MessageBubble.js";
+import { ToolCallCard } from "./ToolCallCard.js";
+const MemoBubble = React.memo(MessageBubble);
+const MemoToolCall = React.memo(ToolCallCard);
+/** How close to the end, in pixels, still counts as reading the latest. */
+const PINNED = 48;
+/**
+ * The conversation in arrival order: message bubbles with tool call cards
+ * between them, a failed run's error at the end. It follows the stream while
+ * the person is at the bottom and stops following when they scroll up, with
+ * a button back to the latest. Each bubble re-renders only when its message
+ * changes, so a long conversation streams without virtualization; a host
+ * with thousands of turns pages its history.
+ */
+export function MessageList({ view, renderContent, renderToolCall, renderAfter, footer, toolTitle, onApprove, onDeny, onRetry, loading = false, empty, label, className, }) {
+    const { messages } = useUI();
+    const t = messages.chat;
+    const scroller = React.useRef(null);
+    const [pinned, setPinned] = React.useState(true);
+    const byId = React.useMemo(() => ({
+        messages: new Map(view.messages.map((m) => [m.id, m])),
+        calls: new Map(view.toolCalls.map((c) => [c.id, c])),
+    }), [view.messages, view.toolCalls]);
+    React.useLayoutEffect(() => {
+        const el = scroller.current;
+        if (pinned && el)
+            el.scrollTop = el.scrollHeight;
+    }, [pinned, byId, view.error]);
+    const jump = () => {
+        const el = scroller.current;
+        if (el)
+            el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
+        setPinned(true);
+    };
+    let body;
+    if (loading)
+        body = _jsx(LoadingState, { variant: "rows", rows: 3 });
+    else if (view.timeline.length === 0 && !view.error)
+        body = empty ?? _jsx(EmptyState, { title: t.empty, description: t.emptyDescription });
+    else
+        body = (_jsxs(_Fragment, { children: [view.timeline.map((item) => {
+                    const after = renderAfter?.(item);
+                    let node = null;
+                    if (item.kind === "message") {
+                        const message = byId.messages.get(item.id);
+                        node = message ? _jsx(MemoBubble, { message: message, renderContent: renderContent }) : null;
+                    }
+                    else {
+                        const call = byId.calls.get(item.id);
+                        const custom = call ? renderToolCall?.(call) : undefined;
+                        node = !call ? null : custom !== undefined ? (custom) : (_jsx(MemoToolCall, { call: call, title: toolTitle?.(call), onApprove: onApprove, onDeny: onDeny }));
+                    }
+                    return (_jsxs(React.Fragment, { children: [node, after] }, `${item.kind === "message" ? "m" : "t"}:${item.id}`));
+                }), footer, view.status === "error" && view.error && (_jsxs("div", { role: "alert", className: "flex min-w-0 flex-col gap-2 rounded-lg border border-danger-border bg-danger-bg px-3 py-2 text-sm text-danger-fg sm:flex-row sm:items-center", children: [_jsxs("p", { className: "min-w-0 flex-1 [overflow-wrap:anywhere]", children: [_jsx("span", { className: "font-medium", children: t.runFailed }), ": ", view.error.message] }), onRetry && (_jsx(Button, { variant: "outline", size: "sm", onClick: onRetry, children: t.retry }))] }))] }));
+    return (_jsxs("div", { "data-slot": "message-list", className: cn("relative flex min-h-0 flex-col", className), children: [_jsx("div", { ref: scroller, role: "log", "aria-label": label ?? t.conversation, "aria-busy": view.status === "running" || loading || undefined, 
+                // A scrolling region is reached by keyboard (WCAG 2.1.1).
+                // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
+                tabIndex: 0, onScroll: (event) => {
+                    const el = event.currentTarget;
+                    setPinned(el.scrollHeight - el.scrollTop - el.clientHeight < PINNED);
+                }, className: "flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto p-4 outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset", children: body }), !pinned && (_jsxs(Button, { variant: "outline", size: "sm", onClick: jump, className: "absolute bottom-3 left-1/2 -translate-x-1/2 shadow-md", children: [_jsx(ArrowDownIcon, { "aria-hidden": true }), t.jumpToLatest] }))] }));
+}

package/dist/chat/ModelPicker.d.ts

@@ -0,0 +1,17 @@
+import { type SelectOption } from "../primitives/Select.js";
+export interface ModelPickerProps {
+    /** The models this host offers, in its words. The package names none. */
+    options: readonly SelectOption[];
+    value: string;
+    onValueChange: (value: string) => void;
+    disabled?: boolean;
+    /** Names the picker. Defaults to "Model". */
+    label?: string;
+    className?: string;
+}
+/**
+ * The model for the next turn, from the options the host passes: which
+ * models exist, which the person may use and what each costs are the host's.
+ * Small enough for a composer's actions.
+ */
+export declare function ModelPicker({ options, value, onValueChange, disabled, label, className, }: ModelPickerProps): import("react").JSX.Element;

package/dist/chat/ModelPicker.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUI } from "../provider/UIProvider.js";
+import { Select } from "../primitives/Select.js";
+/**
+ * The model for the next turn, from the options the host passes: which
+ * models exist, which the person may use and what each costs are the host's.
+ * Small enough for a composer's actions.
+ */
+export function ModelPicker({ options, value, onValueChange, disabled, label, className, }) {
+    const { messages } = useUI();
+    return (_jsx(Select, { options: options, value: value, onValueChange: onValueChange, disabled: disabled, "aria-label": label ?? messages.chat.model, size: "sm", className: className }));
+}

package/dist/chat/ToolCallCard.d.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+import { type ChatToolCall } from "./model.js";
+export interface ToolCallCardProps {
+    call: ChatToolCall;
+    /** The tool's name for people ("Run SQL"). Defaults to the call's name. */
+    title?: string;
+    /** Draws the result: a table, a chart. Defaults to the result as text, pretty-printed when it is JSON. */
+    renderResult?: (call: ChatToolCall) => React.ReactNode;
+    /** Whether the details start open. A call waiting for approval always starts open. */
+    defaultOpen?: boolean;
+    /**
+     * Approves a call the run paused on, after the confirm step. Awaited; see
+     * ConfirmDialog. The host resumes the run (AG-UI `resume`); the card only
+     * reports the decision.
+     */
+    onApprove?: (call: ChatToolCall) => Promise<unknown> | unknown;
+    /** Denies it, after the confirm step, with the reason the person gave. */
+    onDeny?: (call: ChatToolCall, reason: string) => Promise<unknown> | unknown;
+    className?: string;
+}
+/**
+ * One tool call: its name and status, its arguments as they stream and its
+ * result or error behind a disclosure, and, when the run paused on it,
+ * approve and deny through the library's confirm flow (a denial always with
+ * a reason). Host-driven: it never runs or resumes anything.
+ */
+export declare function ToolCallCard({ call, title, renderResult, defaultOpen, onApprove, onDeny, className, }: ToolCallCardProps): React.JSX.Element;

package/dist/chat/ToolCallCard.js

@@ -0,0 +1,52 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronRightIcon, WrenchIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { ConfirmDialog } from "../overlays/ConfirmDialog.js";
+import { Button } from "../primitives/Button.js";
+import { useUI } from "../provider/UIProvider.js";
+import { StatusBadge } from "../status/StatusBadge.js";
+import { parseToolCallArgs } from "./model.js";
+const TONE = {
+    streaming: "info",
+    running: "info",
+    complete: "ok",
+    failed: "error",
+    cancelled: "muted",
+    approval: "warn",
+};
+/** JSON text shown indented when it parses, as it came otherwise. */
+const pretty = (text) => {
+    const value = parseToolCallArgs(text);
+    return value === undefined ? text : JSON.stringify(value, null, 2);
+};
+/**
+ * One tool call: its name and status, its arguments as they stream and its
+ * result or error behind a disclosure, and, when the run paused on it,
+ * approve and deny through the library's confirm flow (a denial always with
+ * a reason). Host-driven: it never runs or resumes anything.
+ */
+export function ToolCallCard({ call, title, renderResult, defaultOpen = false, onApprove, onDeny, className, }) {
+    const { messages } = useUI();
+    const t = messages.chat;
+    const id = React.useId();
+    const name = title ?? call.name;
+    const waiting = call.approval !== undefined;
+    const [open, setOpen] = React.useState(defaultOpen || waiting);
+    const [confirming, setConfirming] = React.useState(null);
+    // A call that comes to wait for approval opens, so the person sees what they approve.
+    const [wasWaiting, setWasWaiting] = React.useState(waiting);
+    if (waiting !== wasWaiting) {
+        setWasWaiting(waiting);
+        if (waiting)
+            setOpen(true);
+    }
+    const status = waiting ? "approval" : call.status;
+    const detailsId = `${id}-details`;
+    return (_jsxs("section", { "aria-label": t.toolCall(name), "data-slot": "tool-call-card", "data-status": status, className: cn("flex min-w-0 flex-col rounded-lg border bg-card text-sm", className), children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-2 px-3 py-2", children: [_jsx(WrenchIcon, { "aria-hidden": true, className: "size-4 shrink-0 text-muted-foreground" }), _jsxs("button", { type: "button", "aria-expanded": open, "aria-controls": detailsId, onClick: () => setOpen((o) => !o), className: "inline-flex min-w-0 items-center gap-1 rounded-sm text-left outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring", children: [_jsx(ChevronRightIcon, { "aria-hidden": true, className: cn("size-3.5 shrink-0 transition-transform", open && "rotate-90") }), _jsx("span", { className: "font-mono text-xs font-medium [overflow-wrap:anywhere]", children: name }), " ", _jsx("span", { className: "sr-only", children: t.details })] }), _jsx(StatusBadge, { tone: TONE[status], pulse: status === "streaming" || status === "running", className: "ml-auto", children: t.toolStatus(status) })] }), open && (_jsxs("div", { id: detailsId, className: "flex min-w-0 flex-col gap-2 border-t px-3 py-2", children: [_jsx(Block, { label: t.arguments, children: call.args ? pretty(call.args) : t.noArguments }), call.error !== undefined && (_jsx(Block, { label: t.toolError, tone: "error", children: call.error })), call.result !== undefined &&
+                        (renderResult ? (_jsx("div", { className: "min-w-0", children: renderResult(call) })) : (_jsx(Block, { label: t.result, children: pretty(call.result) })))] })), waiting && (onApprove || onDeny) && (_jsxs("div", { className: "flex min-w-0 flex-col gap-2 border-t px-3 py-2 sm:flex-row sm:items-center", children: [_jsx("p", { className: "min-w-0 flex-1 [overflow-wrap:anywhere]", children: call.approval?.message ?? t.approvalNeeded }), _jsxs("div", { className: "flex gap-2", children: [onDeny && (_jsx(Button, { variant: "outline", size: "sm", onClick: () => setConfirming("deny"), children: t.deny })), onApprove && (_jsx(Button, { size: "sm", onClick: () => setConfirming("approve"), children: t.approve }))] })] })), _jsx(ConfirmDialog, { open: confirming === "approve", onOpenChange: (next) => !next && setConfirming(null), title: t.approveTitle(name), description: call.approval?.message ?? t.approveDescription, confirmLabel: t.approve, onConfirm: () => onApprove?.(call) }), _jsx(ConfirmDialog, { open: confirming === "deny", onOpenChange: (next) => !next && setConfirming(null), title: t.denyTitle(name), description: t.denyDescription, confirmLabel: t.deny, destructive: true, reason: { label: t.denyReason }, onConfirm: (reason) => onDeny?.(call, reason) })] }));
+}
+function Block({ label, tone, children, }) {
+    return (_jsxs("div", { className: "flex min-w-0 flex-col gap-1", children: [_jsx("p", { className: "font-mono text-2xs font-medium tracking-wider text-muted-foreground uppercase", children: label }), _jsx("pre", { role: "region", "aria-label": label, tabIndex: 0, className: cn("max-h-64 min-w-0 overflow-auto rounded-md bg-muted p-2 font-mono text-xs [overflow-wrap:anywhere] whitespace-pre-wrap outline-none focus-visible:ring-2 focus-visible:ring-ring", tone === "error" && "bg-danger-bg text-danger-fg"), children: children })] }));
+}

package/dist/chat/model.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The conversation view an AG-UI event stream builds, and the reducer that
+ * folds one event into it. Engine-agnostic: any agent that speaks AG-UI
+ * (or an adapter that turns an engine's stream into AG-UI events) drives the
+ * chat components through this one shape. Pure and immutable: every event
+ * returns a new view that shares what did not change, so a message that did
+ * not change keeps its identity and a memoized bubble does not re-render.
+ * Tolerant: an event for a message or call it has not seen starts one, and a
+ * state delta that fails to apply is counted and dropped, never thrown.
+ */
+import { type ContentPart, type Event, type Interrupt } from "@ag-ui/core";
+/** Any AG-UI event, as `@ag-ui/core` types it. */
+export type AgUiEvent = Event;
+/** A run's pause for a person: AG-UI's `RUN_FINISHED` interrupt outcome. */
+export type AgUiInterrupt = Interrupt;
+export type ChatRole = "user" | "assistant" | "system" | "developer" | "tool";
+export interface ChatMessage {
+    id: string;
+    role: ChatRole;
+    /** The text so far; grows while `streaming`. */
+    content: string;
+    /** True while its deltas are still arriving. */
+    streaming: boolean;
+    /** The speaker's display name, when the event carried one. */
+    name?: string;
+}
+/**
+ * `streaming`: its arguments are arriving. `running`: the arguments are in and
+ * the result is not. `complete`: a result came, or the run finished without
+ * one. `failed`: the tool reported an error or the run errored first.
+ * `cancelled`: a person stopped the run first.
+ */
+export type ChatToolCallStatus = "streaming" | "running" | "complete" | "failed" | "cancelled";
+/** A tool call the run paused on, waiting for a person to approve or deny it. */
+export interface ChatApproval {
+    interruptId: string;
+    reason: string;
+    /** What to ask the person, in the agent's words. */
+    message?: string;
+}
+export interface ChatToolCall {
+    id: string;
+    name: string;
+    /** The arguments as JSON text, as streamed; see `parseToolCallArgs`. */
+    args: string;
+    status: ChatToolCallStatus;
+    /** The result as text. */
+    result?: string;
+    error?: string;
+    /** The assistant message that made the call, when the agent said. */
+    parentMessageId?: string;
+    /** Set while the run waits on a person for this call; cleared when the next run starts. */
+    approval?: ChatApproval;
+}
+/** The conversation in arrival order: messages and tool calls interleaved. */
+export type ChatTimelineItem = {
+    kind: "message";
+    id: string;
+} | {
+    kind: "tool-call";
+    id: string;
+};
+/**
+ * `finished`: the run ended successfully. `interrupted`: it ended waiting on
+ * a person (see `interrupts`). `cancelled`: a person stopped it.
+ */
+export type ChatRunStatus = "idle" | "running" | "finished" | "interrupted" | "cancelled" | "error";
+export type ChatStepStatus = "running" | "finished" | "failed" | "cancelled";
+export interface ChatStep {
+    name: string;
+    status: ChatStepStatus;
+}
+export interface ChatView {
+    threadId: string | null;
+    /** The latest run's id. */
+    runId: string | null;
+    status: ChatRunStatus;
+    error: {
+        message: string;
+        code?: string;
+    } | null;
+    /** What the latest run's `RUN_FINISHED` carried as `result`. */
+    result?: unknown;
+    messages: readonly ChatMessage[];
+    toolCalls: readonly ChatToolCall[];
+    timeline: readonly ChatTimelineItem[];
+    /** The latest run's steps, in the order they started. */
+    steps: readonly ChatStep[];
+    /** What the latest run is waiting on, when it ended `interrupted`. */
+    interrupts: readonly AgUiInterrupt[];
+    /** The shared state: the last `STATE_SNAPSHOT` with every `STATE_DELTA` since. */
+    state: unknown;
+    /** State deltas that did not apply; the next snapshot repairs them. */
+    rejectedDeltas: number;
+    /** Every `CUSTOM` event, in order, for the host to read. */
+    custom: readonly {
+        name: string;
+        value: unknown;
+    }[];
+    /** Every `RAW` event, in order, for the host to read. */
+    raw: readonly {
+        event: unknown;
+        source?: string;
+    }[];
+}
+export declare function createChatView(): ChatView;
+/** A tool call's arguments as JSON, or undefined while they do not parse (still streaming). */
+export declare function parseToolCallArgs(args: string): unknown;
+/** The text of an AG-UI content value: a string, or the text parts of a part list. */
+export declare function contentText(content: string | readonly ContentPart[] | undefined): string;
+/**
+ * Folds one AG-UI event into the view. Handles the run lifecycle
+ * (`RUN_STARTED`, `RUN_FINISHED` with its outcome, `RUN_ERROR`), steps, text
+ * messages and their chunks, tool calls and their chunks and results, shared
+ * state (`STATE_SNAPSHOT`, `STATE_DELTA` as JSON Patch), `MESSAGES_SNAPSHOT`,
+ * `CUSTOM` and `RAW`. Activity, reasoning and sub-agent events leave the view
+ * as it is.
+ */
+export declare function reduceChat(view: ChatView, event: AgUiEvent): ChatView;
+/** Folds a sequence of events, from a fresh view or from `view`. */
+export declare function foldChat(events: Iterable<AgUiEvent>, view?: ChatView): ChatView;
+/** True while the latest run is in flight: the composer offers stop, not send. */
+export declare function isChatRunning(view: ChatView): boolean;

package/dist/chat/model.js

@@ -0,0 +1,337 @@
+/**
+ * The conversation view an AG-UI event stream builds, and the reducer that
+ * folds one event into it. Engine-agnostic: any agent that speaks AG-UI
+ * (or an adapter that turns an engine's stream into AG-UI events) drives the
+ * chat components through this one shape. Pure and immutable: every event
+ * returns a new view that shares what did not change, so a message that did
+ * not change keeps its identity and a memoized bubble does not re-render.
+ * Tolerant: an event for a message or call it has not seen starts one, and a
+ * state delta that fails to apply is counted and dropped, never thrown.
+ */
+import { EventType, } from "@ag-ui/core";
+import { applyJsonPatch } from "./patch.js";
+export function createChatView() {
+    return {
+        threadId: null,
+        runId: null,
+        status: "idle",
+        error: null,
+        messages: [],
+        toolCalls: [],
+        timeline: [],
+        steps: [],
+        interrupts: [],
+        state: undefined,
+        rejectedDeltas: 0,
+        custom: [],
+        raw: [],
+    };
+}
+/** A tool call's arguments as JSON, or undefined while they do not parse (still streaming). */
+export function parseToolCallArgs(args) {
+    if (args.trim() === "")
+        return undefined;
+    try {
+        return JSON.parse(args);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The text of an AG-UI content value: a string, or the text parts of a part list. */
+export function contentText(content) {
+    if (content === undefined)
+        return "";
+    if (typeof content === "string")
+        return content;
+    return content.map((part) => (part.type === "text" ? part.text : "")).join("");
+}
+function lastIndex(items, id) {
+    for (let i = items.length - 1; i >= 0; i--)
+        if (items[i]?.id === id)
+            return i;
+    return -1;
+}
+function upsertMessage(view, id, update, start = { role: "assistant", streaming: true }) {
+    const i = lastIndex(view.messages, id);
+    const messages = view.messages.slice();
+    if (i < 0) {
+        messages.push(update({ id, content: "", ...start }));
+        return { ...view, messages, timeline: [...view.timeline, { kind: "message", id }] };
+    }
+    messages[i] = update(messages[i]);
+    return { ...view, messages };
+}
+function upsertCall(view, id, update, name = "") {
+    const i = lastIndex(view.toolCalls, id);
+    const toolCalls = view.toolCalls.slice();
+    if (i < 0) {
+        toolCalls.push(update({ id, name, args: "", status: "streaming" }));
+        return { ...view, toolCalls, timeline: [...view.timeline, { kind: "tool-call", id }] };
+    }
+    toolCalls[i] = update(toolCalls[i]);
+    return { ...view, toolCalls };
+}
+/** Maps only the items `pick` selects, keeping every other item's identity. */
+function mapWhere(items, pick, update) {
+    return items.some(pick) ? items.map((item) => (pick(item) ? update(item) : item)) : items;
+}
+const open = (call) => call.status === "streaming" || call.status === "running";
+/** Closes what a run's end leaves open: streaming messages, running steps, open calls. */
+function closeRun(view, step, call) {
+    return {
+        messages: mapWhere(view.messages, (m) => m.streaming, (m) => ({ ...m, streaming: false })),
+        steps: mapWhere(view.steps, (s) => s.status === "running", (s) => ({ ...s, status: step })),
+        toolCalls: mapWhere(view.toolCalls, open, call),
+    };
+}
+function finish(view, event) {
+    const outcome = event.outcome ?? { type: "success" };
+    const base = { ...view, error: null, result: event.result };
+    if (outcome.type === "cancelled") {
+        return {
+            ...base,
+            status: "cancelled",
+            interrupts: [],
+            ...closeRun(view, "cancelled", (c) => ({ ...c, status: "cancelled" })),
+        };
+    }
+    if (outcome.type === "interrupt") {
+        const byCall = new Map(outcome.interrupts.flatMap((i) => (i.toolCallId ? [[i.toolCallId, i]] : [])));
+        const closed = closeRun(view, "finished", (c) => c);
+        return {
+            ...base,
+            status: "interrupted",
+            interrupts: outcome.interrupts,
+            ...closed,
+            toolCalls: mapWhere(closed.toolCalls, (c) => byCall.has(c.id), (c) => {
+                const i = byCall.get(c.id);
+                return {
+                    ...c,
+                    approval: {
+                        interruptId: i.id,
+                        reason: i.reason,
+                        ...(i.message === undefined ? {} : { message: i.message }),
+                    },
+                };
+            }),
+        };
+    }
+    const pending = new Set(outcome.pendingToolCallIds ?? []);
+    return {
+        ...base,
+        status: "finished",
+        interrupts: [],
+        ...closeRun(view, "finished", (c) => pending.has(c.id) ? { ...c, status: "running" } : { ...c, status: "complete" }),
+    };
+}
+const ROLES = new Set(["user", "assistant", "system", "developer"]);
+/**
+ * A `MESSAGES_SNAPSHOT` replaces the conversation: messages, tool calls and
+ * their results, in the snapshot's order. A call keeps a pending approval
+ * across it. Activity and reasoning messages are not part of the view.
+ */
+function fromSnapshot(view, snapshot) {
+    const messages = [];
+    const toolCalls = [];
+    const timeline = [];
+    const before = new Map(view.toolCalls.map((c) => [c.id, c]));
+    for (const m of snapshot) {
+        if (m.role === "tool") {
+            const call = toolCalls.find((c) => c.id === m.toolCallId);
+            const text = contentText(m.content);
+            if (call) {
+                call.result = text;
+                call.status = m.error ? "failed" : "complete";
+                if (m.error)
+                    call.error = m.error;
+            }
+            else {
+                messages.push({ id: m.id, role: "tool", content: text, streaming: false });
+                timeline.push({ kind: "message", id: m.id });
+            }
+            continue;
+        }
+        if (!ROLES.has(m.role))
+            continue;
+        const message = m;
+        const text = contentText(message.content);
+        if (text || message.role !== "assistant" || !message.toolCalls?.length) {
+            messages.push({
+                id: message.id,
+                role: message.role,
+                content: text,
+                streaming: false,
+                ...(message.name ? { name: message.name } : {}),
+            });
+            timeline.push({ kind: "message", id: message.id });
+        }
+        if (message.role !== "assistant")
+            continue;
+        for (const t of message.toolCalls ?? []) {
+            const approval = before.get(t.id)?.approval;
+            toolCalls.push({
+                id: t.id,
+                name: t.function.name,
+                args: t.function.arguments,
+                status: "running",
+                parentMessageId: message.id,
+                ...(approval ? { approval } : {}),
+            });
+            timeline.push({ kind: "tool-call", id: t.id });
+        }
+    }
+    // A call with no result in a snapshot of a run that is over has finished.
+    const settled = view.status === "running"
+        ? toolCalls
+        : toolCalls.map((c) => c.status === "running" && !c.approval ? { ...c, status: "complete" } : c);
+    return { ...view, messages, toolCalls: settled, timeline };
+}
+/**
+ * Folds one AG-UI event into the view. Handles the run lifecycle
+ * (`RUN_STARTED`, `RUN_FINISHED` with its outcome, `RUN_ERROR`), steps, text
+ * messages and their chunks, tool calls and their chunks and results, shared
+ * state (`STATE_SNAPSHOT`, `STATE_DELTA` as JSON Patch), `MESSAGES_SNAPSHOT`,
+ * `CUSTOM` and `RAW`. Activity, reasoning and sub-agent events leave the view
+ * as it is.
+ */
+export function reduceChat(view, event) {
+    switch (event.type) {
+        case EventType.RUN_STARTED:
+            return {
+                ...view,
+                threadId: event.threadId,
+                runId: event.runId,
+                status: "running",
+                error: null,
+                result: undefined,
+                steps: [],
+                interrupts: [],
+                toolCalls: mapWhere(view.toolCalls, (c) => c.approval !== undefined, ({ approval: _, ...c }) => c),
+            };
+        case EventType.RUN_FINISHED:
+            return finish(view, event);
+        case EventType.RUN_ERROR:
+            return {
+                ...view,
+                status: "error",
+                error: { message: event.message, ...(event.code ? { code: event.code } : {}) },
+                ...closeRun(view, "failed", (c) => ({ ...c, status: "failed" })),
+            };
+        case EventType.STEP_STARTED:
+            return { ...view, steps: [...view.steps, { name: event.stepName, status: "running" }] };
+        case EventType.STEP_FINISHED: {
+            const steps = view.steps.slice();
+            let i = steps.length - 1;
+            while (i >= 0 && !(steps[i].name === event.stepName && steps[i].status === "running"))
+                i--;
+            if (i < 0)
+                steps.push({ name: event.stepName, status: "finished" });
+            else
+                steps[i] = { ...steps[i], status: "finished" };
+            return { ...view, steps };
+        }
+        case EventType.TEXT_MESSAGE_START:
+            return upsertMessage(view, event.messageId, (m) => ({ ...m, streaming: true, ...(event.name ? { name: event.name } : {}) }), { role: event.role ?? "assistant", streaming: true });
+        case EventType.TEXT_MESSAGE_CONTENT:
+            return upsertMessage(view, event.messageId, (m) => ({
+                ...m,
+                content: m.content + event.delta,
+                streaming: true,
+            }));
+        case EventType.TEXT_MESSAGE_END:
+            return upsertMessage(view, event.messageId, (m) => ({ ...m, streaming: false }));
+        case EventType.TEXT_MESSAGE_CHUNK: {
+            const last = view.messages.at(-1);
+            const id = event.messageId ?? (last?.streaming ? last.id : undefined);
+            if (!id)
+                return view;
+            // A chunk for a new message closes the one before it.
+            const closed = last?.streaming && last.id !== id
+                ? upsertMessage(view, last.id, (m) => ({ ...m, streaming: false }))
+                : view;
+            return upsertMessage(closed, id, (m) => ({ ...m, content: m.content + (event.delta ?? ""), streaming: true }), {
+                role: event.role ?? "assistant",
+                streaming: true,
+                ...(event.name ? { name: event.name } : {}),
+            });
+        }
+        case EventType.TOOL_CALL_START:
+            return upsertCall(view, event.toolCallId, (c) => ({
+                ...c,
+                name: event.toolCallName,
+                ...(event.parentMessageId ? { parentMessageId: event.parentMessageId } : {}),
+            }), event.toolCallName);
+        case EventType.TOOL_CALL_ARGS:
+            return upsertCall(view, event.toolCallId, (c) => ({ ...c, args: c.args + event.delta }));
+        case EventType.TOOL_CALL_END:
+            return upsertCall(view, event.toolCallId, (c) => c.status === "streaming" ? { ...c, status: "running" } : c);
+        case EventType.TOOL_CALL_CHUNK: {
+            const last = view.toolCalls.at(-1);
+            const id = event.toolCallId ?? (last?.status === "streaming" ? last.id : undefined);
+            if (!id)
+                return view;
+            return upsertCall(view, id, (c) => ({
+                ...c,
+                name: event.toolCallName ?? c.name,
+                args: c.args + (event.delta ?? ""),
+                ...(event.parentMessageId ? { parentMessageId: event.parentMessageId } : {}),
+            }), event.toolCallName);
+        }
+        case EventType.TOOL_CALL_RESULT:
+            return upsertCall(view, event.toolCallId, (c) => ({
+                ...c,
+                result: contentText(event.content),
+                status: "complete",
+            }));
+        case EventType.STATE_SNAPSHOT:
+            return { ...view, state: event.snapshot };
+        case EventType.STATE_DELTA:
+            try {
+                return { ...view, state: applyJsonPatch(view.state, event.delta) };
+            }
+            catch {
+                return { ...view, rejectedDeltas: view.rejectedDeltas + 1 };
+            }
+        case EventType.MESSAGES_SNAPSHOT:
+            return fromSnapshot(view, event.messages);
+        case EventType.CUSTOM:
+            return { ...view, custom: [...view.custom, { name: event.name, value: event.value }] };
+        case EventType.RAW:
+            return {
+                ...view,
+                raw: [
+                    ...view.raw,
+                    { event: event.event, ...(event.source ? { source: event.source } : {}) },
+                ],
+            };
+        case EventType.ACTIVITY_SNAPSHOT:
+        case EventType.ACTIVITY_DELTA:
+        case EventType.REASONING_START:
+        case EventType.REASONING_MESSAGE_START:
+        case EventType.REASONING_MESSAGE_CONTENT:
+        case EventType.REASONING_MESSAGE_END:
+        case EventType.REASONING_MESSAGE_CHUNK:
+        case EventType.REASONING_END:
+        case EventType.REASONING_ENCRYPTED_VALUE:
+        case EventType.SUBAGENT_STARTED:
+        case EventType.SUBAGENT_FINISHED:
+        case EventType.SUBAGENT_ERROR:
+            return view;
+        default:
+            // Exhaustive over the protocol this was built on; a newer event leaves the view alone.
+            event;
+            return view;
+    }
+}
+/** Folds a sequence of events, from a fresh view or from `view`. */
+export function foldChat(events, view = createChatView()) {
+    let current = view;
+    for (const event of events)
+        current = reduceChat(current, event);
+    return current;
+}
+/** True while the latest run is in flight: the composer offers stop, not send. */
+export function isChatRunning(view) {
+    return view.status === "running";
+}

package/dist/chat/patch.d.ts

@@ -0,0 +1,12 @@
+/**
+ * RFC 6902 JSON Patch over plain JSON, for AG-UI's `STATE_DELTA`. Pure:
+ * `applyJsonPatch` never mutates its input, it returns a new document that
+ * shares the untouched branches. A failing operation throws `JsonPatchError`
+ * and nothing of the patch applies.
+ */
+import type { JsonPatch } from "@ag-ui/core";
+export declare class JsonPatchError extends Error {
+    name: string;
+}
+/** Applies every operation in order, or throws `JsonPatchError` and applies none. */
+export declare function applyJsonPatch<T>(doc: T, patch: JsonPatch): T;