@artooi/agents-web-components 0.0.0-stage → 0.1.0

package/dist/core/ag_ui_chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ag_ui_chat.d.ts","sourceRoot":"","sources":["../../src/core/ag_ui_chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAW,IAAI,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAuBL,KAAK,oBAAoB,EAE1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAGhD,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEzF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAEnE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAwB,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE1E,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAetD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAG5E,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAG1E,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,sBAAsB,CAAC;AASlD,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAenG,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAKvE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAI1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,YAAY,EAAmB,MAAM,wBAAwB,CAAC;AAU5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQrD,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAkH5D;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,SAAQ,WAAW;;IACvC,wEAAwE;IACxE,YAAY,EAAE,YAAY,CAAmB;IAE7C;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM;IAErC;;;;;;;;OAQG;IACH,UAAU,EAAE,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAQ;IAEzD;;;;;;;;;;;;;;OAcG;IACH,cAAc,EAAE,SAAS,MAAM,EAAE,CAAM;IAEvC;;;;;OAKG;IACH,WAAW,UAAS;IAEpB;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,EAAE,qBAAqB,GAAG,IAAI,CAAQ;IAExD,yEAAyE;IACzE,WAAW,UAAS;IAEpB;;;;;OAKG;IACH,OAAO,UAAS;IAEhB;;;;;;OAMG;IACH,eAAe,EAAE,gBAAgB,GAAG,IAAI,CAAQ;IAEhD;;;;;;OAMG;IACH,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAQ;IAEjD;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,UAAS;IAEzB;;;;;;OAMG;IACH,gBAAgB,EACZ,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GACjF,IAAI,CAAQ;IAEhB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAoC;IAE1D;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,OAAO,EAAE,CAEzB;IAEF;;;;;OAKG;IACH,QAAQ,EAAE,QAAQ,CAAM;IAExB;;;;OAIG;IACH,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAEjD,iEAAiE;IACjE,UAAU,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,IAAI,CAAQ;IAE1C,iEAAiE;IACjE,iBAAiB,UAAQ;IAEzB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,EAAE,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,IAAI,CAAQ;IAE7C;;;;OAIG;IACH,iBAAiB,EAAE,uBAAuB,CAA6B;IAEvE;;;;;;OAMG;IACH,aAAa,EAAE,aAAa,GAAG,IAAI,CAAQ;IAE3C;;;;;OAKG;IACH,iBAAiB,EAAE,iBAAiB,GAAG,IAAI,CAAQ;IAEnD;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,UAAU,EAAE,oBAAoB,KAAK,OAAO,CAG5D;IAEH;;;;OAIG;IACH,YAAY,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAc;IAEzD;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM;IAE3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,EAAE,oBAAoB,GAAG,IAAI,CAAQ;IAEtD;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAM;IAEjC;;;;;OAKG;IACH,iBAAiB,EAAE,iBAAiB,CAA2D;IAyY/F,cAsPC;IAED,oEAAoE;IACpE,MAAM,KAAK,kBAAkB,IAAI,MAAM,EAAE,CAmBxC;IAED,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CA0H1F;IAED;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAEnC;IAED;;;;;;;;OAQG;IACH,IAAI,WAAW,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEnD;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAOvD;IAgBD,6EAA6E;IAC7E,iBAAiB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAE1C;IAED,kEAAkE;IAClE,IAAI,QAAQ,IAAI,MAAM,CAErB;IAKD,IAAI,QAAQ,CAAC,KAAK,EAAE,MAAM,EAEzB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,EAExB;IAED;;;;;;;;OAQG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,MAAM,EAEzB;IASD;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,WAAW,IAAI,kBAAkB,GAAG,IAAI,CAG3C;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,EAe/C;IAoDD;;;;;;;;;;;;OAYG;IACH,IAAI,WAAW,IAAI,eAAe,CAWjC;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,eAAe,EAErC;IAED;;;;;;;;;OASG;IACH,IAAI,gBAAgB,IAAI,oBAAoB,CAU3C;IAED,IAAI,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,EAE/C;IAED;;;;;;;;;;;OAWG;IACH,IAAI,WAAW,IAAI,SAAS,aAAa,EAAE,CAE1C;IAED,IAAI,WAAW,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,EAK/C;IAED,iBAAiB,IAAI,IAAI,CAmJxB;IAiCD;;;;;;;;;;;;OAYG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAS5B;IAED;;;;;OAKG;IACH,oBAAoB,IAAI,IAAI,CAc3B;IAYD;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAExB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAAgB,CAAC,MAAM,GAAE,WAA2B,GAAG,MAAM,IAAI,CAEhE;IA2CD;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI,CAExC;IAED,gFAAgF;IAChF,IAAI,SAAS,IAAI,OAAO,CAEvB;IAID,IAAI,SAAS,CAAC,KAAK,EAAE,OAAO,EAE3B;IAED;;;;;OAKG;IACH,YAAY,IAAI,IAAI,CASnB;IAcD;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,GAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI,CA2CpF;IAED;;;;;;OAMG;IACH,IAAI,MAAM,IAAI,MAAM,CAMnB;IAED;;;;;;OAMG;IACH,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAG5B;IAED;;;;;;;;;OASG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;;OAKG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;OAKG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;;;OAQG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;OAMG;IACH,IAAI,MAAM,IAAI,OAAO,GAAG,IAAI,CAE3B;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,EAI/B;IA2HD;;;;;;;;;;OAUG;IACH,eAAe,IAAI,iBAAiB,CAEnC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAEjF;IAED;;;;;;;OAOG;IACH,SAAS,IAAI,IAAI,CAGhB;IAED;;;OAGG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,SAAS,CAAC,KAAK,EAAE,OAAO,EAE3B;IAED;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAMrC;IAED,sEAAsE;IACtE,eAAe,IAAI,IAAI,CAEtB;IAkFD,qEAAqE;IACrE,eAAe,IAAI,IAAI,CAEtB;IAED;;;;;;;OAOG;IACH,WAAW,IAAI,IAAI,CASlB;IA+HD;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAO,GAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI,CA4B7D;IAmDD;;;;;;OAMG;IACH,eAAe,IAAI,IAAI,CAEtB;IAED,kDAAkD;IAClD,YAAY,IAAI,IAAI,CAEnB;IAED,kDAAkD;IAClD,gBAAgB,IAAI,IAAI,CAEvB;IAED;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5C;IAED;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKnC;IAED;;;;;OAKG;IACH,iBAAiB,IAAI,IAAI,CAMxB;IAED;;;;;;;;;;;OAWG;IACH,OAAO,IAAI,IAAI,CAsBd;IAiED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAyCtC;IAED;;;;;;;;;OASG;IACH,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAEhE;IA+sBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,GAAE,SAAS,aAAa,EAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CA+D/F;IAoBD;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE9B;IAgID;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,MAAM,GAAE,SAAS,CAAC,MAAM,GAAG,UAAU,CAAC,EAAyB,GAAG,IAAI,CAuBlF;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,wBAAwB,CAAC,YAAY,EAAE,oBAAoB,GAAG,IAAI,CAEjE;IAED;;;;;;;;OAQG;IACH,IAAI,sBAAsB,IAAI,SAAS,MAAM,EAAE,CAE9C;CACF"}

package/dist/core/agui_client.d.ts

@@ -0,0 +1,370 @@
+import { type AbstractAgent } from "@ag-ui/client";
+import { type Context, type Interrupt, type Message, type Tool } from "@ag-ui/core";
+import type { AttachmentRef } from "./attachment.js";
+import type { ToolOutcome } from "./tool_outcome.js";
+/** A tool call surfaced to the host by {@link AgUiClient}. */
+export interface AgUiToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly args: Record<string, unknown>;
+}
+/**
+ * Which message an answer surfaced by {@link AgUiClient} is, as the stream
+ * named it.
+ */
+export interface AgUiMessageIds {
+    /** The id the message streamed under, on its `TEXT_MESSAGE_START`/`END`. */
+    readonly messageId: string;
+    /**
+     * The run that streamed it, as that run's `RUN_STARTED` declared it.
+     *
+     * Absent when no `RUN_STARTED` was seen. `@ag-ui/client` 1.0 rejects a
+     * stream whose first event is anything else, so over a real agent this is
+     * always present; nothing else names the run the server recorded, so
+     * nothing is substituted when it is not.
+     *
+     * Text a sub-agent streams through the parent run carries the parent's run
+     * id: that is the stream it arrived on, and the delegation's
+     * `subagentRunId` names the child's work rather than a run the answer is
+     * recorded under.
+     */
+    readonly runId?: string;
+}
+/** The result of executing a frontend tool, destined for a tool-result message. */
+export interface ToolExecution {
+    /** String content for the AG-UI tool-result message. */
+    content: string;
+    /** Present when the handler failed; surfaced for logging. */
+    error?: string;
+    /**
+     * How the call ended, in the same vocabulary a server states on
+     * `TOOL_CALL_RESULT`. Omit for a success -- absent *is* success, here for the
+     * same reason it is on the wire.
+     *
+     * Distinct from {@link error}, which is a *message* and only exists for the
+     * one failure shape that produces one. A refusal has no error and is still
+     * not a success, and that is the case this field exists for.
+     */
+    outcome?: ToolOutcome;
+    /**
+     * When `true`, a navigating tool triggered a page reload. The loop stops
+     * without appending a result — the result is supplied after the next mount
+     * (see the resume path). Mutually exclusive with a usable `content`.
+     */
+    halt?: boolean;
+}
+/**
+ * Executes a frontend tool call.
+ *
+ * Returns the {@link ToolExecution} to post back to the agent, or `null` when
+ * there is nothing to post: the call is not a frontend tool the host owns (a
+ * server-side tool the server already executed, which the client must not
+ * re-run), or its run was stopped or handed over while the call waited. A
+ * stopped call is left unanswered here, like the calls after it in the round,
+ * and the next request answers it as not finished.
+ */
+export type ExecuteTool = (call: AgUiToolCall) => Promise<ToolExecution | null>;
+/**
+ * One user decision for a server-side-tool approval interrupt. Structurally
+ * matches `@ag-ui/client`'s (non-exported) `ResumeResponse`, the payload
+ * {@link buildResumeArray} turns into a `ResumeEntry`: `resolved` approves (with
+ * an optional `payload`, e.g. `{ approved: true }`), `cancelled` denies.
+ */
+export type InterruptResponse = {
+    status: "resolved";
+    payload?: unknown;
+} | {
+    status: "cancelled";
+};
+/**
+ * Resolves the approval interrupts a run finished on, keyed by interrupt id.
+ *
+ * A gated server-side tool defers instead of executing, so the run finishes on
+ * an interrupt outcome; the host collects one decision per interrupt and the
+ * loop resumes with the answers. Omit for agents that never gate server-side
+ * tools — an unresolved interrupt then ends the loop.
+ */
+export type ResolveInterrupts = (interrupts: readonly Interrupt[]) => Promise<Record<string, InterruptResponse>>;
+/**
+ * Callbacks the {@link AgUiClient} invokes as a run progresses. The host
+ * (the `<ag-ui-chat>` element) implements these to render streaming text and
+ * tool activity into the chat.
+ */
+export interface AgUiClientHandlers {
+    onRunStart(): void;
+    /** Fired on every streamed token; `buffer` is the full text so far. */
+    onTextDelta(buffer: string): void;
+    /**
+     * Fired when the assistant message completes; `buffer` is the final text,
+     * and `message` names it as the stream did.
+     */
+    onTextEnd(buffer: string, message: AgUiMessageIds): void;
+    /** Fired when the agent finishes calling a tool (server- or frontend-side). */
+    onToolCall(call: AgUiToolCall): void;
+    /**
+     * Fired when a server-side tool's result streams back (AG-UI's
+     * `TOOL_CALL_RESULT`). Frontend tools don't emit this — the client supplies
+     * their result itself — so this is the channel for server-executed output.
+     *
+     * `outcome` is the `outcome` key of the event's `metadata`, forwarded raw.
+     * It is `unknown` rather than {@link ToolOutcome} because metadata is open by
+     * key: the protocol declares the object and validates nothing inside it, so
+     * neither can this signature honestly claim to. Read it with
+     * `toolStatusFromOutcome`, which treats `undefined` and anything unrecognised
+     * as a success.
+     *
+     * Only the metadata is read. A server written against `@ag-ui/client` 0.x
+     * states the outcome at the top level of the event, and 1.0 strips that key
+     * before any subscriber runs, so from such a server this is `undefined` and
+     * the card settles as done.
+     */
+    onToolResult(toolCallId: string, content: string, outcome?: unknown): void;
+    /**
+     * Fired for AG-UI activity events — ambient notices about what the *run* did,
+     * as opposed to work the agent asked for. `django-ag-ui` emits one with
+     * `activityType: "compaction"` when it condensed the history.
+     */
+    onActivity(activityType: string, content: unknown, messageId: string): void;
+    /**
+     * An activity's content changed in place — a snapshot re-sent under the same
+     * `messageId` with `replace`, or an `ACTIVITY_DELTA` whose JSON patch
+     * `@ag-ui/client` has already applied.
+     *
+     * Reported after the client has updated its own message, so `content` is the
+     * result rather than the instruction. That is the whole reason this is a
+     * separate callback: the raw delta event fires *before* the patch lands, and
+     * a subscriber acting on it would redraw from stale content.
+     */
+    onActivityChanged(messageId: string, activityType: string, content: unknown): void;
+    /** Fired when a reasoning model starts emitting its chain-of-thought. */
+    onReasoningStart(): void;
+    /**
+     * Fired on every reasoning token, and once more when the block ends.
+     *
+     * ``buffer`` is the text accumulated *before* the token that triggered the
+     * call, which is what the protocol client passes -- so the stream trails by
+     * one delta and the final call, at the end of the block, is what completes
+     * it. Render the buffer wholesale rather than appending it.
+     */
+    onReasoningDelta(buffer: string): void;
+    /** Fired when the reasoning block ends (before the answer text streams). */
+    onReasoningEnd(): void;
+    onRunEnd(): void;
+    /**
+     * The server replaced the whole conversation with `MESSAGES_SNAPSHOT`.
+     *
+     * `@ag-ui/client` applies the event before any subscriber sees it, so by the
+     * time this fires `agent.messages` **is** the server's list -- and the run
+     * loop persists `agent.messages`. The replacement therefore reaches the
+     * conversation store whatever the host does; this hook exists so the host can
+     * stop that being invisible.
+     */
+    onMessagesSnapshot(messages: readonly Message[]): void;
+    /**
+     * The agent sent a `CUSTOM` event.
+     *
+     * Forwarded whole and uninterpreted: `name` is an open string the protocol
+     * does not enumerate, so a client that decided which names were legal would
+     * be the thing the open field exists to avoid.
+     */
+    onCustomEvent(name: string, value: unknown): void;
+    /**
+     * A delegated sub-agent started, inside the run.
+     *
+     * The protocol's own event, unlike the steps that follow it on
+     * {@link SUBAGENT_CUSTOM_NAME}. `parentToolCallId` links the delegation to the
+     * `delegate_task` call that spawned it -- the field AG-UI provides for the
+     * "agents as tools" shape -- and is `null` when the server did not send one,
+     * which a host reads as a delegation it has nothing to attach to.
+     *
+     * `subagentRunId` names the child run and is the only id the two closing
+     * events carry, so a host that wants to close what it opened has to remember
+     * the pairing.
+     */
+    onSubAgentStarted(subagentRunId: string, name: string, parentToolCallId: string | null): void;
+    /** The delegation named by `subagentRunId` completed. */
+    onSubAgentFinished(subagentRunId: string): void;
+    /**
+     * The delegation named by `subagentRunId` failed.
+     *
+     * `message` is server text and required by the protocol, but it is not an
+     * exception's words: `django-ag-ui` sends only which sub-agent failed, on the
+     * same reasoning that redacts a `RUN_ERROR`. Render it as text, never as
+     * markup.
+     */
+    onSubAgentError(subagentRunId: string, message: string): void;
+    onError(message: string): void;
+    /**
+     * Fired when the user cancelled the run ({@link AgUiClient.cancel}) — the
+     * deliberate-stop sibling of `onError`. Partial assistant text already
+     * streamed stays valid, so the host keeps the bubble and shows a stopped
+     * affordance rather than an error. `onSettled` still follows.
+     */
+    onCancelled(): void;
+    /**
+     * Fired exactly once when the interaction settles, however the run loop ended
+     * — server-only round, rounds exhausted, cancellation, or error. The terminal
+     * guarantee that the UI returns to rest.
+     */
+    onSettled(): void;
+}
+/**
+ * Provider of the per-run frontend tool catalog and context. Both are read
+ * fresh on every {@link AgUiClient.send} so the catalog reflects the current
+ * page state.
+ */
+export interface AgUiRunInputs {
+    getTools?: () => Tool[];
+    getContext?: () => Context[];
+}
+export interface AgUiClientConfig extends AgUiRunInputs {
+    /** The AG-UI agent to drive. Injected so it can be faked in tests. */
+    agent: AbstractAgent;
+    handlers: AgUiClientHandlers;
+    /** Executes frontend tool calls. Omit for server-only tool sets. */
+    executeTool?: ExecuteTool;
+    /**
+     * Resolves server-side-tool approval interrupts. Omit when no server-side
+     * tool is gated for approval — an interrupt then ends the loop unanswered.
+     */
+    resolveInterrupts?: ResolveInterrupts;
+    /**
+     * Invoked with the latest history whenever it changes, so the host can
+     * persist it for durability across page reloads. Omit to keep the
+     * conversation in-memory only.
+     */
+    onPersist?: (messages: readonly Message[]) => void;
+    /**
+     * Called whenever AG-UI shared state changes — a streamed `STATE_SNAPSHOT` /
+     * `STATE_DELTA`, or {@link AgUiClient.setState}. `@ag-ui/client` owns applying
+     * those events; this only forwards the result.
+     */
+    onStateChanged?: (state: Readonly<Record<string, unknown>>) => void;
+    /**
+     * Error text for {@link AgUiClientHandlers.onError} when a run's stream closes
+     * without a terminal AG-UI event. Defaults to `"Connection lost"`; the host
+     * passes its localized string.
+     */
+    connectionLostMessage?: string;
+    /**
+     * Result content for a tool call the conversation moved past without one: a
+     * Stop while the stream was arriving, a round that ended on `RUN_ERROR`, a
+     * call no {@link executeTool} answered, or history restored with a call still
+     * open. Sent to the agent, so it says only that the call did not finish --
+     * nobody refused it. Defaults to an English sentence; the host passes its
+     * localized string.
+     */
+    unfinishedMessage?: string;
+    /**
+     * Result content for a server-side approval that Stop closed while it was
+     * open, which the host's {@link resolveInterrupts} answers as declined.
+     * Defaults to `"User declined the action."`; the host passes its localized
+     * string.
+     */
+    declinedMessage?: string;
+    /**
+     * Upper bound on frontend tool-call to re-run rounds within one
+     * {@link AgUiClient.send}. Defaults to {@link MAX_TOOL_ROUNDS}.
+     *
+     * The default suits a chat whose tools answer questions. A page-driving
+     * deployment reaches it legitimately -- filling a form field by field is one
+     * round each -- and the symptom is not an error but an answer that stops
+     * mid-task, which reads as the model giving up. Raise it where a turn is
+     * expected to take many small steps.
+     *
+     * Read once, when the client is built. The bound is a property of the
+     * deployment rather than of a run, so re-reading it per round would only make
+     * a mid-run change possible, and a mid-run change to how long the run may
+     * last is not a thing a host has any way to reason about.
+     */
+    maxToolRounds?: number;
+}
+/**
+ * Raised when a run's stream closes cleanly at the transport level but never
+ * emits a terminal AG-UI event, so the run neither finished nor errored. Routed
+ * to {@link AgUiClientHandlers.onError} (it is not an abort), turning a silent
+ * "stuck pending" into a visible "connection lost".
+ */
+export declare class ConnectionLostError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thin orchestration layer over an AG-UI {@link AbstractAgent}.
+ *
+ * Translates AG-UI's subscriber callbacks into the host's
+ * {@link AgUiClientHandlers}, and appends the user message + current frontend
+ * tool catalog + context to each run.
+ */
+export declare class AgUiClient {
+    #private;
+    constructor(config: AgUiClientConfig);
+    /** The current AG-UI shared state, as the agent last applied it. */
+    get state(): Readonly<Record<string, unknown>>;
+    /** Replace the shared state; the next run sends it as `RunAgentInput.state`. */
+    setState(state: Readonly<Record<string, unknown>>): void;
+    /** Whether a run is currently in flight. */
+    get running(): boolean;
+    /** The current conversation history (for persistence / rehydration). */
+    get messages(): readonly Message[];
+    /**
+     * Append a user message and run the agent to completion.
+     *
+     * When the agent calls frontend tools, this executes them and re-runs the
+     * agent with the results, looping until the agent stops calling frontend
+     * tools (bounded by {@link AgUiClientConfig.maxToolRounds}, which defaults to
+     * {@link MAX_TOOL_ROUNDS}).
+     *
+     * `attachments` ride in the user message's `metadata`, under
+     * `attachments`, which is how the server learns which files the agent can
+     * read and how the default store round-trips them for history replay; see
+     * {@link messageAttachments}.
+     */
+    send(content: string, attachments?: readonly AttachmentRef[]): Promise<void>;
+    /**
+     * Drop everything after the most recent user message, so the same question
+     * can be asked again.
+     *
+     * Returns the retained history, or `null` when there is nothing to retry (no
+     * user message has been sent yet). The shortened history is saved before it
+     * replaces the current one, so a save that throws changes nothing and the
+     * throw propagates.
+     *
+     * **Truncates only** -- the caller re-renders from the returned list and then
+     * calls {@link resume}, because the transcript belongs to the element and a
+     * client that reached into it would own two things. Running here instead
+     * would stream the new answer in underneath the old one.
+     *
+     * Re-running answers the question the agent was last asked, rather than
+     * telling it its answer was wrong, which is what makes the result a
+     * *different* answer instead of a conversation about the previous one.
+     *
+     * **A retried turn re-runs its tools.** For a page-driving agent that is not
+     * neutral: the previous attempt already clicked what it clicked, and this
+     * does not undo it.
+     */
+    truncateToLastUser(): readonly Message[] | null;
+    /**
+     * Resume the run loop after a navigating tool's result was supplied
+     * post-reload (via {@link addToolResult}). Unlike {@link send}, adds no user
+     * message; it continues the conversation already in history.
+     */
+    resume(): Promise<void>;
+    /** Append a frontend tool result to history (used by the resume path). */
+    addToolResult(toolCallId: string, content: string): void;
+    /**
+     * Cancel the in-flight run (AG-UI has no server cancel route — aborting the
+     * streaming request is the protocol's cancel; the server observes the
+     * disconnect). Safe to call with no run in flight. Partial text already
+     * streamed stays in history; {@link AgUiClientHandlers.onCancelled} fires
+     * instead of `onError`, and `onSettled` still follows.
+     *
+     * Also stops a {@link send} or {@link resume} whose request has not been made
+     * yet, when host code it runs on the way calls this: the save of the turn,
+     * the tool and context providers, the save answering a call left open. No
+     * request is made then, and `onCancelled` and `onSettled` fire as for any
+     * other Stop. A cancel with nothing in flight is forgotten when the next
+     * send or resume begins.
+     */
+    cancel(): void;
+}
+//# sourceMappingURL=agui_client.d.ts.map

package/dist/core/agui_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agui_client.d.ts","sourceRoot":"","sources":["../../src/core/agui_client.ts"],"names":[],"mappings":"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"}

package/dist/core/attachment.d.ts

@@ -0,0 +1,42 @@
+import type { Message } from "@ag-ui/core";
+/**
+ * A durable, lightweight reference to one uploaded file — what an upload
+ * returns and what rides on a sent message, never the bytes.
+ *
+ * Mirrors django-ag-ui's `AttachmentRef`: the file uploads out-of-band to the
+ * attachments endpoint, the server hands back this ref, and the agent reads the
+ * content server-side via the `read_attachment` tool.
+ */
+export interface AttachmentRef {
+    /** Opaque, owner-scoped handle the server resolves back to bytes. */
+    readonly id: string;
+    /** Original filename, for display on the chip. */
+    readonly name: string;
+    /** Declared content type (a hint — the server is authoritative). */
+    readonly mime: string;
+    /** Size in bytes. */
+    readonly size: number;
+    /** Optional direct fetch URL (the owner-checked download endpoint). */
+    readonly url?: string;
+}
+/**
+ * The attachment refs a user message carries.
+ *
+ * `AgUiClient.send` writes them into the message's `metadata`, under
+ * `attachments`. That is the one place they survive the trip: `@ag-ui/client`
+ * 1.0 strips every key its schemas do not declare from the outgoing input, so
+ * refs written at the top level of the message never reach the server, while
+ * `metadata` is declared open by key and sent as it is. The server reads them
+ * from there to tell the agent which files it can read, and the default store
+ * round-trips them, so a restored conversation re-renders its chips.
+ *
+ * A conversation stored by an earlier release has them at the top level, so
+ * that is read when the metadata has none. An older server reads only the top
+ * level, so against one the agent is never told about a file at all.
+ *
+ * Storage is untrusted — hand-edited, truncated, or corrupted — so malformed
+ * entries are dropped here; a shapeless one would throw in `iconFor` and abort
+ * the whole history replay.
+ */
+export declare function messageAttachments(message: Message): readonly AttachmentRef[];
+//# sourceMappingURL=attachment.d.ts.map

package/dist/core/attachment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.d.ts","sourceRoot":"","sources":["../../src/core/attachment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,aAAa,EAAE,CAG7E"}

package/dist/core/chat_registry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One chat's place in the document's list of connected chats.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, which joins on connect and leaves on
+ * disconnect, so the list holds exactly the elements that are in a document
+ * now. Typed as `HTMLElement` rather than the element's class, because the DOM
+ * driver reads it and must not import the element.
+ */
+export declare class ChatRegistration {
+    #private;
+    constructor(chat: HTMLElement);
+    /**
+     * Join, as the most recently connected chat. An element moved in the DOM
+     * left on disconnect before it reconnected, so it rejoins at the end and no
+     * entry needs removing first.
+     */
+    join(): void;
+    /** Leave. The previous chat, if one is still connected, becomes the latest. */
+    leave(): void;
+    /** The most recently connected chat still in the document, or `null`. */
+    static latest(): HTMLElement | null;
+}
+//# sourceMappingURL=chat_registry.d.ts.map

package/dist/core/chat_registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat_registry.d.ts","sourceRoot":"","sources":["../../src/core/chat_registry.ts"],"names":[],"mappings":"AAeA;;;;;;;GAOG;AACH,qBAAa,gBAAgB;;IAG3B,YAAY,IAAI,EAAE,WAAW,EAE5B;IAED;;;;OAIG;IACH,IAAI,IAAI,IAAI,CAEX;IAED,+EAA+E;IAC/E,KAAK,IAAI,IAAI,CAEZ;IAED,yEAAyE;IACzE,MAAM,CAAC,MAAM,IAAI,WAAW,GAAG,IAAI,CAMlC;CACF"}

package/dist/core/client_seed.d.ts

@@ -0,0 +1,27 @@
+import type { Message } from "@ag-ui/core";
+/**
+ * What differs between the clients one conversation builds -- its own, and one
+ * per checkpoint continuation. Everything else about a client comes from the
+ * element's single construction, so an option added for one reaches the other.
+ */
+export interface ClientSeed {
+    /** Where the client's runs are sent. */
+    readonly endpoint: string;
+    /** The history the agent starts from, and sends with its first run. */
+    readonly initialMessages: readonly Message[];
+    /**
+     * The conversation this client's own history continues, which every save
+     * writes ahead of it.
+     *
+     * Empty for the conversation's own client, whose history is the whole
+     * conversation. A continuation's history is only the turn it adds and its
+     * answer -- the endpoint supplies the rest from its snapshot -- and a store
+     * keeps one list per thread, so a save of that history alone would replace
+     * the conversation with its last exchange, and not saving it lost the
+     * exchange on the next reload.
+     */
+    readonly follows: readonly Message[];
+    /** Handed the whole conversation each time the client saves it, as written. */
+    readonly onSaved?: (conversation: readonly Message[]) => void;
+}
+//# sourceMappingURL=client_seed.d.ts.map

package/dist/core/client_seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client_seed.d.ts","sourceRoot":"","sources":["../../src/core/client_seed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,eAAe,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,CAAC;CAC/D"}