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

package/dist/core/ag_ui_chat.d.ts

@@ -0,0 +1,836 @@
+import type { Context, Tool } from "@ag-ui/core";
+import { type ToolGroupDisplayMode } from "../constants.js";
+import type { Skill } from "../skills/skill.js";
+import { type ChatCorner, type ChatSurfaceReport } from "../tools/chat_surface_tools.js";
+import { type ClientTool } from "../tools/client_tool_registry.js";
+import { type ResolvePageTarget } from "../tools/page_action_tools.js";
+import { type PageMap } from "../tools/page_map.js";
+import { type PageState } from "../tools/page_state.js";
+import { type RouteMap } from "../tools/route_map.js";
+import type { RelativeTimeFormatter } from "../ui/history/relative_time.js";
+import { type ApprovalRenderer } from "../ui/interrupts/approval_card.js";
+import { type QuestionRenderer } from "../ui/interrupts/question_card.js";
+import { type Place } from "../ui/place/place.js";
+import { type ToolDisplayMode, type ToolPayloadFormatter } from "../ui/progress/tool_call_card.js";
+import { type UiStrings } from "../ui/ui_strings.js";
+import type { ActivityRegistration } from "./activity_registration.js";
+import { type AttachmentRef } from "./attachment.js";
+import { type ClientConversationStore, type NavigationCheckpoint } from "./conversation_store.js";
+import { type AgentFactory } from "./create_http_agent.js";
+import type { MessageRole } from "./message_role.js";
+import { type TranscribeHandler } from "./transcribe_audio.js";
+import { type UploadHandler } from "./upload_attachment.js";
+/**
+ * `<ag-ui-chat>` — a framework-free chat sidebar Web Component over AG-UI.
+ *
+ * Owns the Shadow DOM shell (header, scrolling message list, input row),
+ * builds an {@link AgUiClient} on first send via the overridable
+ * {@link agentFactory}, and renders streaming assistant text plus tool-call
+ * activity. Emits a {@link SUBMIT_EVENT} for host visibility.
+ *
+ * The per-run frontend tool catalog and context come from {@link getTools} and
+ * {@link getContext}.
+ */
+export declare class AgUiChat extends HTMLElement {
+    #private;
+    /** Agent factory; override to inject a custom or fake agent (tests). */
+    agentFactory: AgentFactory;
+    /**
+     * Static extra HTTP headers, sent with every request this element makes: the
+     * agent run, the thread index and its messages, the tool and skill catalogs,
+     * the run index, uploads and transcription.
+     *
+     * For values fixed for the element's lifetime. A rotating credential belongs
+     * in {@link getHeaders} instead — only a re-assignment updates this, so a
+     * token captured here is pinned until the host assigns again.
+     */
+    headers: Record<string, string>;
+    /**
+     * Live header source, called afresh immediately before every request — the
+     * way to supply rotating credentials, with nothing to re-assign or keep in
+     * sync.
+     *
+     * Composes with {@link headers} rather than replacing it: merged per key with
+     * `getHeaders()` winning, so a static `X-Client` and a rotating
+     * `Authorization` are configured independently and neither drops the other.
+     */
+    getHeaders: (() => Record<string, string>) | null;
+    /**
+     * Origins, besides the page's own, that this element may send {@link headers}
+     * and {@link getHeaders} credentials to without saying so on the console.
+     *
+     * Seven attributes name a URL, and every one of them carries these headers.
+     * They are plain HTML, so a page that builds one from a query parameter or
+     * from tenant-authored configuration has handed an attacker the destination,
+     * and the token leaves on the element's first request. Naming the origins you
+     * expect turns that from silent into either confirmed or reported.
+     *
+     * A notice rather than a refusal: a cross-origin agent is a documented
+     * deployment, so refusing would break working installations to defend against
+     * a page that is already interpolating untrusted data into its own markup.
+     * Leaving this empty costs nothing but one console line per foreign origin.
+     */
+    trustedOrigins: readonly string[];
+    /**
+     * Permit `<img>` in rendered assistant markdown. **Off by default**: a
+     * model-controlled image URL is fetched with no user interaction, which
+     * makes it a zero-click exfiltration channel for prompt-injected page
+     * data. Enable only when the content source is trusted.
+     */
+    allowImages: boolean;
+    /**
+     * Replace the relative timestamps in the thread drawer and the checkpoint
+     * panel -- `"5m ago"`, `"2d ago"` -- with the host's own formatting.
+     *
+     * The built-in is locale-neutral on purpose: there is no `Intl` anywhere in
+     * this component, so it never disagrees with the page it is embedded in by
+     * guessing a locale. That is a good default and a bad requirement, which is
+     * what this is for.
+     *
+     * ```js
+     * const rtf = new Intl.RelativeTimeFormat("de", { numeric: "auto" });
+     * chat.formatRelativeTime = (ts) =>
+     *   rtf.format(Math.round((ts - Date.now()) / 60000), "minute");
+     * ```
+     */
+    formatRelativeTime: RelativeTimeFormatter | null;
+    /** When true, destructive tools execute without a confirmation modal. */
+    autoConfirm: boolean;
+    /**
+     * When true, the built-in `ask_user` frontend tool is offered to the agent:
+     * calling it renders an inline question card and returns the user's answer.
+     * Off by default, like the other built-in tool groups, so the advertised
+     * catalog does not change until a host asks for it.
+     */
+    askUser: boolean;
+    /**
+     * Optional full replacement for the `ask_user` question UI, resolving with
+     * the answer; the same seam as {@link approvalRenderer}, styled via `strings`
+     * and the `question*` `::part()`s when left unset. Requires {@link askUser}.
+     * A renderer that throws or rejects hands the question to the built-in card,
+     * as a failing {@link approvalRenderer} does, unless Stop already fired.
+     */
+    askUserRenderer: QuestionRenderer | null;
+    /**
+     * Optional full replacement for the server-side-tool approval UI: an approval
+     * interrupt invokes this instead of the built-in {@link requestApproval}
+     * card, resolving `true` to approve or `false` to deny. Style the built-in
+     * card via `strings` and the `approval*` `::part()`s instead. The gate itself
+     * is enabled server-side; this only changes how the decision is collected.
+     */
+    approvalRenderer: ApprovalRenderer | null;
+    /**
+     * Let the user edit a gated call's arguments before approving it.
+     *
+     * Off by default and **an assertion about your server**, not a negotiation:
+     * AG-UI carries `editedArgs` in the resume payload and gates it on the
+     * agent's own `approveWithEdits` capability, which this component never sees
+     * -- capabilities are not on the wire it reads. So the host says whether its
+     * agent honours them. Turned on against a server that does not, the user
+     * would edit arguments it silently discards, which is worse than not
+     * offering.
+     *
+     * Only affects calls whose arguments are known here: an interrupt names a
+     * `toolCallId`, and the tool card for that call is where the arguments still
+     * are. An interrupt naming no card gets the plain approve/deny.
+     */
+    approveWithEdits: boolean;
+    /**
+     * Optional per-call confirmation predicate. When set it is authoritative,
+     * deciding from the tool name and args whether this particular call needs
+     * confirmation — so one tool can be instant for some args and confirmed for
+     * others, which a static `x-destructive` flag cannot express. When unset the
+     * `x-destructive` flag decides. `autoConfirm` short-circuits both.
+     */
+    confirmPredicate: ((toolName: string, args: Record<string, unknown>) => boolean | Promise<boolean>) | null;
+    /**
+     * Per-run frontend tool catalog provider. Defaults to the built-in
+     * `route.*` tools (when a {@link routeMap} is set) plus the tools registered
+     * via {@link registerTool} / {@link registerPageState}; override to supply a
+     * fully custom catalog.
+     */
+    getTools: () => Tool[];
+    /**
+     * Per-run context provider. Defaults to the compact page map, when a
+     * {@link getPageMap} provider is set and {@link autoInjectPageMap} is on.
+     *
+     * Attachments are deliberately not restated here: the server derives its own
+     * manifest from the refs riding the messages.
+     */
+    getContext: () => Context[];
+    /**
+     * Navigable routes the agent can jump to via the built-in `route.*` tools.
+     * While {@link getPlace} is unset, the route matching the current path also
+     * stands in as the place: the chip names it and the place entry carries it.
+     * No summary of the map itself is sent.
+     */
+    routeMap: RouteMap;
+    /**
+     * Optional client-side router. When set (an SPA), `navigate_to_route` routes
+     * in-page and the run loop continues; when unset (an MPA like the admin), it
+     * falls back to `window.location` and the resumable-loop machinery applies.
+     */
+    navigate: ((path: string) => void) | null;
+    /** Provider for the per-run page map; see {@link getContext}. */
+    getPageMap: (() => PageMap) | null;
+    /** Whether to auto-inject the page map into context each run. */
+    autoInjectPageMap: boolean;
+    /**
+     * Where in the app the user is. The chip in the composer's tool row draws it,
+     * and every tool round sends it as one `place` context entry from the same
+     * read, after whatever {@link getContext} returns, so a host that replaces
+     * that keeps it. Read before every round, on connect, on expand, when the
+     * composer gains focus, on `popstate` and `hashchange`, when the conversation
+     * changes, and on {@link refreshPlace}.
+     *
+     * When unset, the {@link routeMap} route matching `location.pathname` stands
+     * in: its title (else its id) as the label, its group as the detail, the
+     * path as the href. With neither, no chip is drawn and nothing is sent; a
+     * host with a route map that wants no chip sets `() => null`.
+     *
+     * The chip's eye toggle withholds the place, and with it the page: a round
+     * whose place is withheld sends no `page_map` entry, whatever
+     * {@link getContext} returns, and offers no `read_page`. It holds for the
+     * same place, lapses when a different place is read, and is not persisted.
+     */
+    getPlace: (() => Place | null) | null;
+    /**
+     * Persistence for the conversation + navigation checkpoint. Defaults to
+     * per-tab `sessionStorage` so the chat survives full page reloads; inject a
+     * server-backed store for cross-tab/device durability.
+     */
+    conversationStore: ClientConversationStore;
+    /**
+     * How attached files are uploaded. `null` (default) uses the built-in
+     * multipart `POST` to `data-attachments-url`; a custom {@link UploadHandler}
+     * swaps the transport without changing the tray, the chips, or the AG-UI
+     * wire. When set, the 📎 affordance appears even with no
+     * `data-attachments-url`, and the handler owns its own endpoint and headers.
+     */
+    uploadHandler: UploadHandler | null;
+    /**
+     * How recorded voice clips are transcribed. `null` (default) POSTs the clip
+     * to `data-transcribe-url`; a custom {@link TranscribeHandler} swaps the
+     * transport without touching the mic button. When set, the 🎤 affordance
+     * appears even with no `data-transcribe-url`.
+     */
+    transcribeHandler: TranscribeHandler | null;
+    /**
+     * Builds the tool result a navigating tool resumes with after the page
+     * reloads. Defaults to the landed URL; a host (e.g. the admin package) can
+     * override to include a page snapshot or post-reload validation errors.
+     */
+    navigationResult: (checkpoint: NavigationCheckpoint) => unknown;
+    /**
+     * Named values used to fill a skill prompt's `{placeholder}`s before send
+     * (e.g. `{ model: "Order", selected_ids: "1,2" }`). A host (the admin) sets
+     * this from the current page; a missing placeholder blocks the send.
+     */
+    skillContext: () => Record<string, unknown>;
+    /**
+     * Friendly display labels for tool-call cards, keyed by tool name. The
+     * fallback when a tool has no `x-summary` in its own schema, which chiefly
+     * means server-side tools: AG-UI streams only the tool-call name, so their
+     * schema never reaches the browser. Client tools should prefer `x-summary`.
+     */
+    toolSummaries: Record<string, string>;
+    /**
+     * Optional presentation hook for the two payload regions of a tool-call card
+     * -- the arguments and the result. Unset (the default) leaves both
+     * pretty-printed as JSON.
+     *
+     * The seam exists because a wide result has no good rendering as JSON: a
+     * thirty-field row is a wall of text where the host wanted a table, or a
+     * sentence. `ClientTool.render` cannot answer it -- it is handed the
+     * *arguments* only, and a server-side tool has no `ClientTool` at all, so the
+     * result region was the one part of the transcript a host could not reach.
+     *
+     * **Presentation, not translation.** The card and the model already read
+     * separate copies of a tool result: the model's is maintained by
+     * `@ag-ui/client` from the same event and persisted with the history, and the
+     * card has always shown that string reformatted. So a formatter changes what
+     * the person reads and nothing the agent reads -- which makes restyling safe
+     * and *rewording* a way to make the card disagree with the prose beside it.
+     * Rename a value on the server, where it reaches both.
+     *
+     * Read at render time rather than captured, so a host that sets it from a
+     * framework effect after the first card still formats the results that settle
+     * afterwards. See {@link ToolPayloadFormatter}.
+     */
+    formatToolPayload: ToolPayloadFormatter | null;
+    /**
+     * Localizable UI strings — a partial override merged over the English
+     * {@link DEFAULT_UI_STRINGS}. Resolved once on connect (so set it before the
+     * element is appended); the `data-strings` JSON attribute is the markup
+     * equivalent, and this property wins key-by-key over it.
+     */
+    strings: Partial<UiStrings>;
+    /**
+     * Resolve a `scroll_to` / `drag_and_drop` target string to a host-page
+     * element (or `null`). Defaults to a CSS-selector lookup; override to map
+     * page-map element ids. The page-action tools are opt-in via the
+     * `data-page-actions` attribute (`"scroll"` / `"drag"` / `"chat"`).
+     */
+    resolvePageTarget: ResolvePageTarget;
+    constructor();
+    /** Attributes the element reacts to after it has been connected. */
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, previous: string | null, value: string | null): void;
+    /**
+     * Declare a frontend tool the agent may call.
+     *
+     * **A handler's thrown message leaves the browser.** When a handler rejects,
+     * its `Error.message` is posted back as that call's tool result — into the
+     * conversation, on to the AG-UI endpoint, persisted server-side, and
+     * forwarded to the model provider on every later round. That is deliberate,
+     * since it is what lets the agent recover from a failure it caused; but it
+     * means an internal hostname, a signed URL or a stack-derived path in a
+     * rethrown error is disclosed to parties the host never chose. Throw the
+     * message you would be content for the model to read, and log the detail.
+     */
+    registerTool(tool: ClientTool): void;
+    /**
+     * AG-UI **shared state** for this conversation — the protocol's own state
+     * channel, sent as `RunAgentInput.state` on every run and replaced in place
+     * when the server streams `STATE_SNAPSHOT` / `STATE_DELTA`. Assigning seeds
+     * the next run; reading returns whatever the agent last applied.
+     *
+     * Listen for {@link STATE_EVENT} to react to server-driven changes. Distinct
+     * from {@link registerPageState}, which exposes host state as ordinary tools.
+     */
+    get sharedState(): Readonly<Record<string, unknown>>;
+    set sharedState(state: Readonly<Record<string, unknown>>);
+    /** Bind a piece of host page state to `read_<name>` / `set_<name>` tools. */
+    registerPageState(binding: PageState): void;
+    /** The AG-UI endpoint URL, read from the `endpoint` attribute. */
+    get endpoint(): string;
+    set endpoint(value: string);
+    /**
+     * Who the stored conversation belongs to, from the `user-key` attribute.
+     *
+     * Set it to whatever identifies the signed-in principal — a user id, an
+     * account id, a hash of one. The value joins the storage namespace, so two
+     * principals in the same tab cannot read each other's transcript, and
+     * **changing it purges what the previous one left behind**.
+     *
+     * That purge is the reason this is a live attribute rather than a
+     * connect-time one. `sessionStorage` survives same-tab navigation, so it
+     * survives a logout; and a single-page app signs out through its own router
+     * without remounting anything, so there is no other moment at which the
+     * element could find out. The host naming the new principal — or dropping the
+     * attribute — is the signal.
+     *
+     * Absent means exactly today's behaviour, which is why nothing breaks by
+     * leaving it off: the conversation is scoped to the element and to nobody in
+     * particular, and on a shared workstation it carries into whoever signs in
+     * next in the same tab.
+     *
+     * The first value to arrive is treated as a host naming the user who was
+     * already there, not as a handover: the conversation in progress moves into
+     * the principal's namespace rather than being destroyed, so an element
+     * configured by an async auth handshake keeps what is on screen.
+     */
+    get userKey(): string;
+    set userKey(value: string);
+    /**
+     * The signed-in user's display name, from the `user-name` attribute, for the
+     * greeting an empty conversation shows under `placement="page"`.
+     *
+     * Presentation only. Unlike {@link userKey} it scopes nothing and is never
+     * sent to the server. Absent or blank means the nameless greeting. Live: a
+     * name that arrives after the element connected replaces the greeting on
+     * screen.
+     */
+    get userName(): string;
+    set userName(value: string);
+    /**
+     * Cookie policy for **every** request this element makes, as `fetch`'s own
+     * `credentials` mode (`"omit"` / `"same-origin"` / `"include"`). Mirrored to
+     * the `credentials` attribute, so markup embeds can set it without script.
+     *
+     * `null` (the default) leaves the browser's `same-origin` default in place,
+     * which sends no cookies at all to an endpoint on a different origin — and
+     * the request goes out anonymously rather than failing, so the symptom is a
+     * 401 from a server that looks correctly configured. A cookie-authenticated
+     * cross-origin deployment wants `"include"`, plus
+     * `Access-Control-Allow-Credentials: true` and a concrete, non-wildcard
+     * `Access-Control-Allow-Origin` on the server.
+     *
+     * Read per request, so a late assignment applies to everything after it.
+     * `"omit"` cannot be honoured by the built-in upload transport, an
+     * `XMLHttpRequest` with only a two-state cookie switch; every other endpoint
+     * honours all three modes.
+     */
+    get credentials(): RequestCredentials | null;
+    set credentials(value: RequestCredentials | null);
+    /**
+     * How much detail tool-call cards show, from the `data-tool-display`
+     * attribute (`grouped` / `minimal` / `inline` / `compact` / `full`).
+     * Defaults to `grouped`, for an absent attribute and for a value the
+     * element does not know; `full` is the per-call card default before
+     * `grouped` existed.
+     *
+     * The four card modes are applied by the shadow CSS from the attribute
+     * itself, so changing between them restyles every card already in the
+     * transcript. Whether calls fold into a step group is decided as each card
+     * is built: switching to `grouped` folds only the calls drawn afterwards,
+     * and switching away flattens the existing groups, again by CSS.
+     */
+    get toolDisplay(): ToolDisplayMode;
+    set toolDisplay(value: ToolDisplayMode);
+    /**
+     * How an opened step group draws its calls, from the
+     * `data-tool-group-display` attribute (`full` / `compact` / `minimal` /
+     * `inline`). Defaults to `full`, for an absent attribute and for a value the
+     * element does not know, which is what a group drew before the attribute.
+     *
+     * Read only while `toolDisplay` is `grouped`: under a card mode the groups
+     * are flattened into that mode's cards. Applied by the shadow CSS from the
+     * attribute itself, so changing it restyles groups already on screen.
+     */
+    get toolGroupDisplay(): ToolGroupDisplayMode;
+    set toolGroupDisplay(value: ToolGroupDisplayMode);
+    /**
+     * The host's own constructed stylesheets, adopted after the built-in one.
+     *
+     * The escape hatch for structure that neither the tokens nor the parts
+     * reach. Per element, like the built-in sheet: two elements on one page can
+     * carry different sheets. Constructed sheets are not subject to a
+     * `style-src` policy, so this works under the same strict CSP the
+     * built-in sheet does. Setting it re-adopts at once; the array is copied, so
+     * mutating the one passed in changes nothing until it is set again.
+     *
+     * Unstable: reaches shadow class names, which may change in any minor.
+     */
+    get extraStyles(): readonly CSSStyleSheet[];
+    set extraStyles(sheets: readonly CSSStyleSheet[]);
+    connectedCallback(): void;
+    /**
+     * Re-run everything the element loads on startup — the tool-label catalog,
+     * the backend skill catalog and the thread's history — with the transport
+     * configuration as it stands now.
+     *
+     * For a host that can only configure the element after the fact (a token
+     * fetched in a passive effect, an async auth handshake), this re-issues the
+     * startup requests authenticated, without removing and re-inserting the node.
+     *
+     * A reload, not a merge: the in-flight run is cancelled and the transcript is
+     * rebuilt from persisted history, so anything streamed since is dropped. Call
+     * it once, when configuration lands, not between turns.
+     */
+    reload(): Promise<void>;
+    /**
+     * Tear down live resources when the element leaves the DOM: cancel the
+     * in-flight run so its stream closes, abort in-flight uploads so they do not
+     * orphan server-side files, and release the mic so the browser's recording
+     * indicator clears. Without this a removed element leaks all three.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Put `text` into the composer as a markdown quotation, and focus it.
+     *
+     * Deliberately **not** a send. Quoting is how a question narrows to one part
+     * of an answer, so the quotation is the preamble and the question is what
+     * comes next -- the caret is left after it, on its own line.
+     *
+     * This is also the seam for the half of this feature the component cannot
+     * build: selection in the **host page**. A widget mounted beside a table can
+     * be asked about a row, and nothing in a chat's own transcript can offer
+     * that. A host reads its own selection, however it likes, and calls this.
+     *
+     * No-ops on text that is empty or only whitespace.
+     */
+    quote(text: string): void;
+    /**
+     * Offer to quote what the user selects in the **host page**, not just in the
+     * transcript. Returns a function that stops offering.
+     *
+     * The same select-then-offer gesture, over a table, a diff, a report -- the
+     * surface the user actually works in, which is the half of quoting no hosted
+     * chat can reach. Opt-in, because it listens on the host's document and that
+     * is theirs to grant.
+     *
+     * Deliberately **not** a four-line recipe, which is how this shipped first
+     * and was wrong: a page listener that quotes every settled selection appends
+     * to the composer on every drag made to read, to copy or to fix a typo -- and
+     * it cannot tell a selection in the page's prose from one inside the user's
+     * own half-typed `<input>`, because Chrome reports a field's internal
+     * selection as an ordinary range over the field's *wrapper*. See
+     * {@link attachQuoteOffer} for the guards.
+     *
+     * Detached automatically when the element leaves the document; a host that
+     * re-mounts it calls this again.
+     */
+    offerQuoteInPage(within?: HTMLElement): () => void;
+    /**
+     * Replace the host-supplied (client) skill catalog. Merged after the embedded
+     * and fetched skills (so a client skill overrides a same-named server one).
+     */
+    setSkills(skills: readonly Skill[]): void;
+    /** Whether the widget is collapsed (reflected as the `collapsed` attribute). */
+    get collapsed(): boolean;
+    set collapsed(value: boolean);
+    /**
+     * Read {@link getPlace} (or the route map standing in) again and redraw the
+     * chip. A single-page app calls this after its router moves, since a
+     * `pushState` fires no event; history traversal and hash changes are caught
+     * without it. Does nothing before the element connects.
+     */
+    refreshPlace(): void;
+    /**
+     * Set the collapsed state: reflect the `collapsed` attribute, persist it
+     * per-tab, and emit a {@link TOGGLE_EVENT} so a host can mirror the state in
+     * its own chrome.
+     */
+    setCollapsed(collapsed: boolean, options?: {
+        readonly announce?: boolean;
+    }): void;
+    /**
+     * Answers the user has not seen, totalled across threads: each finished while
+     * the panel was collapsed, and is read once its thread is on screen with the
+     * panel expanded. The launcher's badge renders this; {@link UNREAD_EVENT}
+     * announces every change and the threads it touched, so a host chrome can
+     * render its own instead.
+     */
+    get unread(): number;
+    /**
+     * The thread on screen; `null` before the element first connects.
+     *
+     * Only reads. `conversationStore.threadId()` mints and stores a thread when
+     * the store points at none, so a host asking which conversation is showing
+     * could start one; this never does. {@link THREAD_EVENT} says when it changes.
+     */
+    get threadId(): string | null;
+    /**
+     * The title of the thread on screen; `""` while nothing has been sent in it,
+     * and before the element connects.
+     *
+     * A title renamed here, or one the conversation list shows that the thread's
+     * messages do not derive (a server's own), wins. Otherwise it is the first
+     * user message, and a bare skill `/token` reads as the catalog's title for
+     * that skill, else as the token in words. `title-text="auto"` draws it in the
+     * header; {@link THREAD_TITLE_EVENT} says when it changes.
+     */
+    get threadTitle(): string;
+    /**
+     * Whether an interaction is in flight: the composer's own state, the one that
+     * shows Stop. It spans every tool round, a retry and a checkpoint
+     * continuation as well as a send, which {@link SUBMIT_EVENT} alone does not.
+     * Reflected as `data-running` on the element, for a host's CSS.
+     */
+    get running(): boolean;
+    /**
+     * The height of the bottom bar in CSS px, and 0 when none is drawn: under
+     * any collapse-to but "bar", and on a phone while the panel is open, where
+     * the panel is the screen. The bar is fixed over the page, so a host pads
+     * its own page by this much; {@link BAR_HEIGHT_EVENT} says when it changes.
+     */
+    get barHeight(): number;
+    /**
+     * The width in CSS px a docked panel covers at rest, and 0 when it covers
+     * none of the page: the rail while collapsed to it, the panel while open, 0
+     * under every other placement, under collapse-to="none" or a launcher while
+     * collapsed, on a phone while open (the panel is the screen) and under
+     * --ag-ui-position: static, where the host's layout already makes room. The
+     * panel is fixed over the page, so a host pads its own by this much;
+     * {@link DOCK_WIDTH_EVENT} says when it changes, never per animation frame.
+     */
+    get dockWidth(): number;
+    /**
+     * The element the panel rises from under collapse-to="none", right-aligned
+     * to it: typically the host's own button in its own bar. Takes precedence
+     * over the anchor attribute, which names one by selector. One that resolves
+     * to nothing leaves the panel in its placement's own corner, with a console
+     * warning.
+     */
+    get anchor(): Element | null;
+    set anchor(value: Element | null);
+    /**
+     * Describe the panel to whoever is asking -- in practice the agent, through
+     * the opt-in chat-surface tools.
+     *
+     * `movable` folds two separate reasons into the one answer a caller needs:
+     * a placement that places itself owns its position, and a panel that fills
+     * the screen has nowhere to go. Reporting them apart would make every caller
+     * re-derive the same conjunction. A corner panel docked under
+     * `collapse-to="bar"` or `"none"` is movable on a wide viewport, like the
+     * corner panel it is.
+     */
+    describeSurface(): ChatSurfaceReport;
+    /**
+     * Send the panel to a corner, and report whether it went.
+     *
+     * A third claimant on the axes a placement and a user drag already share, and
+     * it takes them the same way the drag does rather than inventing a second
+     * mechanism: the same commit path, so the launcher travels with the panel,
+     * the corner it opens from is re-picked, and switching placement hands
+     * everything back. What it must not do is claim a move it did not make --
+     * hence the boolean, and hence {@link describeSurface} existing so a caller
+     * can ask first. A docked panel moves too, within the room above its bar or
+     * anchor, and remembers the spot as a header drag would.
+     */
+    moveTo(corner: ChatCorner, options?: {
+        readonly announce?: boolean;
+    }): boolean;
+    /**
+     * Drop the size the user dragged in the current placement, and its stored
+     * copy, so the placement's default and the host's `--ag-ui-width` /
+     * `--ag-ui-height` apply again. Other placements keep theirs.
+     * Under `collapse-to="bar"` or `"none"` it also returns a panel the user
+     * dragged off its dock to the dock, and forgets the stored spot; a corner
+     * panel keeps a dragged position.
+     */
+    resetSize(): void;
+    /**
+     * Whether the panel is maximized (reflected as the `maximized` attribute).
+     * Never stored: a reload opens at the placement's own size.
+     */
+    get maximized(): boolean;
+    set maximized(value: boolean);
+    /**
+     * Grow the open panel to `--ag-ui-maximized-width` / `--ag-ui-maximized-height`,
+     * or restore it to the size it had, and emit a {@link MAXIMIZE_EVENT}. Refused
+     * where the header offers no control: `page`, `full`, `embedded`, an unknown
+     * placement, and a viewport of 600px or less.
+     */
+    setMaximized(maximized: boolean): void;
+    /** Flip the maximized state. Bound to the built-in header control. */
+    toggleMaximized(): void;
+    /** Flip the collapsed state. Bound to the built-in header toggle. */
+    toggleCollapsed(): void;
+    /**
+     * Flip the scheme word of the `theme` attribute between `light` and `dark`
+     * and persist the choice per tab. Bound to the optional built-in header theme
+     * toggle (`data-theme-toggle`). The theme name and any host words are kept:
+     * `soft` becomes `soft dark`, and `soft dark` becomes `soft light`. With no
+     * scheme word (`auto`, or a host rule setting `color-scheme` on the element),
+     * it flips away from the scheme the panel is drawn in.
+     */
+    toggleTheme(): void;
+    /**
+     * Open the thread-history drawer: the imperative route to the control that
+     * renders as `::part(history-button)`.
+     *
+     * A host that hides `::part(header)` for its own title bar hides the history,
+     * new-chat and collapse buttons with it. Each has a method so that chrome can
+     * be rebuilt: this one, {@link openCheckpoints}, {@link newChat},
+     * {@link toggleCollapsed} and {@link toggleTheme}.
+     */
+    openThreads(options?: {
+        readonly anchor?: Element;
+    }): void;
+    /**
+     * Open the checkpoints panel (the `::part(checkpoints-button)` route).
+     *
+     * It lists the runs the `data-runs-url` server reports as continuable;
+     * without that attribute the built-in button is never rendered and this opens
+     * an empty panel.
+     */
+    openCheckpoints(): void;
+    /** Close the conversation list, if it is open. */
+    closeThreads(): void;
+    /** Close the checkpoints panel, if it is open. */
+    closeCheckpoints(): void;
+    /**
+     * Put a stored thread on screen, as picking it in the conversation list does,
+     * for a host that lists conversations in its own chrome.
+     *
+     * Resolves once the thread has been replayed, when {@link THREAD_EVENT} has
+     * fired; a second call for the thread already loading settles with that load.
+     * If the store rejects the load, the element stays on the thread it was on,
+     * fires nothing, and the promise rejects with the store's error.
+     * **A run in flight is cancelled**, as the list and {@link newChat} do;
+     * a host that would rather wait reads {@link running} first. The thread
+     * already on screen is left alone, and so is everything before the element
+     * connects, since until then it has no store to read the thread from.
+     */
+    switchThread(threadId: string): Promise<void>;
+    /**
+     * Delete a stored thread, as the conversation list's delete does. Deleting the
+     * thread on screen cancels its run and puts a fresh thread in its place, and
+     * {@link THREAD_EVENT} reports it; deleting another leaves the screen alone.
+     * Does nothing before the element connects.
+     */
+    deleteThread(threadId: string): void;
+    /**
+     * Open the checkpoints panel, or close it if it is already open — what the
+     * built-in checkpoints button does, because a control that opens a panel is read as the
+     * control that also dismisses it. {@link openCheckpoints} stays open-only for a
+     * host that means exactly that.
+     */
+    toggleCheckpoints(): void;
+    /**
+     * Start a fresh conversation: drop the in-memory run state, clear the
+     * transcript, and mint a new thread id.
+     *
+     * The conversation being left is kept, and stays in the history drawer to
+     * return to. Deleting one is the drawer row's own action; a button that
+     * starts something new must not be the button that destroys what was there.
+     *
+     * Focus moves to the composer, unless the widget is collapsed and the
+     * composer is not on screen: starting a conversation is a request to type
+     * one. The page is not scrolled to bring the composer into view.
+     */
+    newChat(): void;
+    /**
+     * Ask the same question again and replace the answer.
+     *
+     * History is truncated to the most recent user message inclusive and the run
+     * repeats, so the agent answers what it was asked rather than being told its
+     * last answer was wrong. Returns `false` when there is nothing to retry, or
+     * while anything that holds a send is in flight: a run, a send or another
+     * retry whose run has not started yet, a checkpoint continuation, or a
+     * restore of the stored conversation that is still loading. It does not wait
+     * for a restore as a send does: nothing is on screen to retry yet, and after
+     * the load it would re-ask the previous visit's last question. Also `false`
+     * when host code it
+     * runs before its run starts -- the store's save, or an activity or tool
+     * renderer the replay draws through -- has stopped it by starting a new chat
+     * or changing `user-key`. A tool or context provider that stops it does so
+     * inside the client's resume, past the last point this can see: nothing is
+     * sent, and this resolves `true`, because both a run starting and a Stop let
+     * go of the hold it checks. Rejects with the store's error when the store
+     * refuses the save, and then the conversation is as it was.
+     *
+     * Public because a host with its own message UI wants the same button, and
+     * because the failed-run notice reaches it from outside the action row.
+     *
+     * **A retried turn re-runs its tools**, which for a page-driving agent is not
+     * neutral: the previous attempt already clicked what it clicked, and this
+     * does not undo it. Confirmation still applies, so a destructive tool asks
+     * again -- unless the user waived it for this session.
+     */
+    retryLastTurn(): Promise<boolean>;
+    /**
+     * Append a message bubble and return it.
+     *
+     * Assistant content renders as sanitised markdown/HTML; user content stays
+     * literal text, which also avoids rendering user-authored markup.
+     *
+     * Assistant bubbles land in the current answer group, opening one if needed;
+     * a user bubble closes the prior group and sits directly in the list, the
+     * well wrapping only the assistant turn.
+     */
+    appendMessage(role: MessageRole, content: string): HTMLDivElement;
+    /**
+     * Send a message as if the user had typed it — renders the user bubble,
+     * dispatches {@link SUBMIT_EVENT}, and starts the run.
+     *
+     * The programmatic half of the composer, for a host driving its own input.
+     * Everything the built-in Send does happens here; Send reads the composer,
+     * clears it, and calls this.
+     *
+     * `attachments` are durable {@link AttachmentRef}s — what {@link attachFile}
+     * resolves to and what {@link ATTACHMENT_EVENT} reports.
+     *
+     * Resolves `true` once the turn has been handed to the client for its run,
+     * which is when the interaction settles, frontend-tool rounds included; a
+     * run a tool or context provider then stops still counts, as it does for
+     * {@link retryLastTurn}. Resolves `false` when nothing was sent.
+     *
+     * Nothing is sent for an empty message, nor while a run or a picked
+     * checkpoint's continuation is in flight, since a second concurrent run
+     * would orphan the first. A send is in flight from the moment it is taken
+     * rather than from its run's start, so nothing is sent from a
+     * {@link SUBMIT_EVENT} listener or for a second call in the same task
+     * either. Nor with no `endpoint`, which says so in the transcript. Nor
+     * behind a reload's restore that will resume a run a navigating tool
+     * interrupted, since that restore ends by starting the run.
+     *
+     * **While the element restores a stored conversation with no run to resume
+     * -- on connect, {@link reload}, a thread picked from the drawer, a change
+     * from one `user-key` to another -- it waits, then sends.** The turn has to follow the
+     * conversation it is part of: sent at once, it went out without it, the
+     * conversation was then drawn under it, and its save replaced the stored
+     * one. So the bubble, the {@link SUBMIT_EVENT} and the request all come after
+     * the replay, by the length of the store's load. A New chat, a thread
+     * switch, a change from one `user-key` to another, a reload or the element
+     * leaving the page while it waits drops it, resolving `false`: the
+     * conversation it was addressed to is no longer on screen. Leaving the page
+     * resolves it only once the load answers or the element is back, since
+     * that is when the restore learns it was stopped. A first `user-key` on an
+     * anonymous conversation adopts it rather than replacing it, and stops
+     * nothing. A second call while one waits is
+     * refused, as a second call in the same task is.
+     *
+     * Unlike the built-in Send it does not queue: it returns, and the caller
+     * keeps what it tried to send. Nor does it consult the tray -- what you pass
+     * is what is sent.
+     */
+    sendMessage(content: string, attachments?: readonly AttachmentRef[]): Promise<boolean>;
+    /**
+     * Queue a file for upload into the attachment tray, exactly as the file
+     * picker and drag-and-drop do — validation, progress chip, and all.
+     *
+     * Returns `false` when uploads are not configured (no `data-attachments-url`
+     * and no {@link uploadHandler}) — the only signal a host gets, since the tray
+     * does not exist to report anything then.
+     *
+     * Uploading is asynchronous: watch {@link ATTACHMENT_EVENT} for the resulting
+     * {@link AttachmentRef} and pass it to {@link sendMessage} once `pending`
+     * reaches zero.
+     */
+    attachFile(file: File): boolean;
+    /**
+     * Turn on chart rendering, by whichever route this consumer wants.
+     *
+     * Both routes converge on one renderer deliberately. Built apart they become
+     * two chart implementations with two sets of bugs, and the choice between them
+     * is about *where the data lives* rather than how a bar should look:
+     *
+     * - `"tool"` registers the built-in `render_chart`. The agent decides a chart
+     *   helps and calls it, so the numbers are in its context and it can discuss
+     *   them afterwards. Costs one model round, and works over any transport.
+     * - `"activity"` draws a server-pushed `ACTIVITY_SNAPSHOT` of type `chart`.
+     *   No round trip, and the data never enters the model's context at all —
+     *   which is what makes it the one for a large or sensitive dataset. Only this
+     *   route can update a chart in place as the server computes.
+     *
+     * Off unless asked for, both of them: a component that renders whatever
+     * arrives is not something to switch on for everybody.
+     */
+    enableCharts(routes?: readonly ("tool" | "activity")[]): void;
+    /**
+     * Teach this element to draw one kind of AG-UI activity.
+     *
+     * `activity_type` is one of exactly two fields the protocol leaves an open
+     * string, and it is the **content** one: an activity is materialised into a
+     * message, persisted with the thread, and replayed on every restore. Its
+     * sibling `CUSTOM` carries an imperative and is dispatched to the page
+     * instead ({@link CUSTOM_AGENT_EVENT}).
+     *
+     * That asymmetry decides which carrier a server should use. Content has a
+     * place in the conversation and should come back; an imperative has no place
+     * and no meaning once acted on.
+     *
+     * ```js
+     * chat.registerActivityRenderer({
+     *   type: "build_status",
+     *   render: (content) => {
+     *     const el = document.createElement("div");
+     *     el.textContent = `Build ${content.status}`;
+     *     return el;
+     *   },
+     * });
+     * ```
+     *
+     * Registering a type twice replaces the earlier renderer, so a host can
+     * override a built-in -- `chart` and `compaction` are registrations like any
+     * other, not privileged branches.
+     *
+     * ⚠ `render` runs again on every thread load. See {@link ActivityRenderer}
+     * for what that requires of it.
+     */
+    registerActivityRenderer(registration: ActivityRegistration): void;
+    /**
+     * Activity types that arrived with nobody registered to draw them.
+     *
+     * Deliberately the only trace an unhandled activity leaves. Ignoring an
+     * unknown name is the protocol's own answer and the whole point of an open
+     * field, so warning would fire on every forward-compatible server -- but
+     * "nothing happened and nothing was said" is impossible to debug, so the set
+     * is readable. Accumulates for the element's lifetime, across threads.
+     */
+    get unhandledActivityTypes(): readonly string[];
+}
+//# sourceMappingURL=ag_ui_chat.d.ts.map