@calliopelabs/ui 0.13.0 → 0.14.0

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;

package/dist/chat/patch.js

@@ -0,0 +1,149 @@
+export class JsonPatchError extends Error {
+    name = "JsonPatchError";
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const has = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+function parse(path) {
+    if (path === "")
+        return [];
+    if (!path.startsWith("/"))
+        throw new JsonPatchError(`bad pointer ${path}`);
+    return path
+        .slice(1)
+        .split("/")
+        .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+function index(array, key, forAdd) {
+    if (forAdd && key === "-")
+        return array.length;
+    if (!/^(0|[1-9]\d*)$/.test(key))
+        throw new JsonPatchError(`bad array index ${key}`);
+    const i = Number(key);
+    if (i > array.length || (!forAdd && i === array.length)) {
+        throw new JsonPatchError(`index ${key} out of range`);
+    }
+    return i;
+}
+function get(doc, segments) {
+    let current = doc;
+    for (const segment of segments) {
+        if (Array.isArray(current))
+            current = current[index(current, segment, false)];
+        else if (isObject(current) && has(current, segment))
+            current = current[segment];
+        else
+            throw new JsonPatchError(`no value at /${segments.join("/")}`);
+    }
+    return current;
+}
+/** Rebuilds the path to `segments`, with `leaf` deciding the last step. */
+function edit(doc, segments, leaf) {
+    const [head, ...rest] = segments;
+    if (head === undefined)
+        throw new JsonPatchError("the root is replaced, not edited");
+    if (rest.length === 0)
+        return leaf(doc, head);
+    if (Array.isArray(doc)) {
+        const i = index(doc, head, false);
+        const copy = doc.slice();
+        copy[i] = edit(doc[i], rest, leaf);
+        return copy;
+    }
+    if (isObject(doc) && has(doc, head))
+        return { ...doc, [head]: edit(doc[head], rest, leaf) };
+    throw new JsonPatchError(`no value at /${segments.join("/")}`);
+}
+function add(doc, path, value) {
+    const segments = parse(path);
+    if (segments.length === 0)
+        return value;
+    return edit(doc, segments, (parent, key) => {
+        if (Array.isArray(parent)) {
+            const copy = parent.slice();
+            copy.splice(index(parent, key, true), 0, value);
+            return copy;
+        }
+        if (isObject(parent))
+            return { ...parent, [key]: value };
+        throw new JsonPatchError(`cannot add under a scalar at ${path}`);
+    });
+}
+function remove(doc, path) {
+    return edit(doc, parse(path), (parent, key) => {
+        if (Array.isArray(parent)) {
+            const copy = parent.slice();
+            copy.splice(index(parent, key, false), 1);
+            return copy;
+        }
+        if (isObject(parent) && has(parent, key)) {
+            const copy = { ...parent };
+            delete copy[key];
+            return copy;
+        }
+        throw new JsonPatchError(`no value at ${path}`);
+    });
+}
+function replace(doc, path, value) {
+    const segments = parse(path);
+    if (segments.length === 0)
+        return value;
+    get(doc, segments);
+    return edit(doc, segments, (parent, key) => {
+        if (Array.isArray(parent)) {
+            const copy = parent.slice();
+            copy[index(parent, key, false)] = value;
+            return copy;
+        }
+        return { ...parent, [key]: value };
+    });
+}
+/** Values from the patch are copied in, so a later edit of the event never reaches the state. */
+const clone = (value) => value === undefined ? value : JSON.parse(JSON.stringify(value));
+function equal(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((value, i) => equal(value, b[i]));
+    }
+    if (isObject(a) && isObject(b)) {
+        const keys = Object.keys(a);
+        return (keys.length === Object.keys(b).length &&
+            keys.every((key) => has(b, key) && equal(a[key], b[key])));
+    }
+    return false;
+}
+function applyOne(doc, operation) {
+    switch (operation.op) {
+        case "add":
+            return add(doc, operation.path, clone(operation.value));
+        case "remove":
+            return remove(doc, operation.path);
+        case "replace":
+            return replace(doc, operation.path, clone(operation.value));
+        case "move": {
+            if (operation.path === operation.from)
+                return doc;
+            if (operation.path.startsWith(`${operation.from}/`)) {
+                throw new JsonPatchError("cannot move a value into its own child");
+            }
+            const value = get(doc, parse(operation.from));
+            return add(remove(doc, operation.from), operation.path, value);
+        }
+        case "copy":
+            return add(doc, operation.path, clone(get(doc, parse(operation.from))));
+        case "test":
+            if (!equal(get(doc, parse(operation.path)), operation.value)) {
+                throw new JsonPatchError(`test failed at ${operation.path}`);
+            }
+            return doc;
+        default:
+            throw new JsonPatchError(`unknown op ${operation.op}`);
+    }
+}
+/** Applies every operation in order, or throws `JsonPatchError` and applies none. */
+export function applyJsonPatch(doc, patch) {
+    let current = doc;
+    for (const operation of patch)
+        current = applyOne(current, operation);
+    return current;
+}

package/dist/chat/useAgUiRun.d.ts

@@ -0,0 +1,52 @@
+import { type AgUiEvent, type ChatView } from "./model.js";
+/**
+ * Pushes events as they arrive and says when the run's stream ends; returns
+ * the unsubscribe. The shape of an observable or an event emitter.
+ */
+export type AgUiSubscribe = (emit: (event: AgUiEvent) => void, done: (error?: unknown) => void) => () => void;
+/**
+ * Where a run's events come from: an async iterable (an `@ag-ui/client`
+ * agent's stream, an SSE reader, a recorded run) or a subscribe function.
+ * The host owns the connection; the hook only reads.
+ */
+export type AgUiEventSource = AsyncIterable<AgUiEvent> | AgUiSubscribe;
+export interface UseAgUiRunOptions {
+    /** The conversation so far, from history. Read once, on mount. */
+    initialView?: ChatView;
+    /** A stream that failed: the hook also folds it into the view as a run error. */
+    onError?: (error: unknown) => void;
+}
+export interface AgUiRun {
+    view: ChatView;
+    /** True from `run` until its stream ends or `stop`. */
+    running: boolean;
+    /**
+     * Reads one run's events into the view until the stream ends. Starting a
+     * run stops reading the one before. Resolves when the stream ends, is
+     * stopped or fails; a failure lands in the view, never as a rejection.
+     */
+    run: (source: AgUiEventSource) => Promise<void>;
+    /**
+     * Stops reading the current run and closes the view as cancelled. Telling
+     * the agent to stop is the host's (its own request); this only lets go.
+     */
+    stop: () => void;
+    /** Folds events the host makes itself: the person's own message before the run starts. */
+    dispatch: (events: AgUiEvent | readonly AgUiEvent[]) => void;
+    /** Starts over, from nothing or from `view`. Stops reading first. */
+    reset: (view?: ChatView) => void;
+}
+/** The person's own message as the events that fold it into the view. */
+export declare function userMessageEvents(id: string, text: string): AgUiEvent[];
+/**
+ * Holds a `ChatView` and folds a host-provided AG-UI event source into it,
+ * one run at a time. No network code: the host connects, authenticates and
+ * sends input, and hands the hook what comes back.
+ *
+ *   const chat = useAgUiRun();
+ *   onSubmit={(text) => {
+ *     chat.dispatch(userMessageEvents(id(), text));
+ *     void chat.run(agent.stream({ threadId, text }));
+ *   }}
+ */
+export declare function useAgUiRun({ initialView, onError }?: UseAgUiRunOptions): AgUiRun;