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

package/dist/core/remote_conversation_store.d.ts

@@ -0,0 +1,71 @@
+import type { Message } from "@ag-ui/core";
+import { type ClientConversationStore, type NavigationCheckpoint, type ThreadMeta } from "./conversation_store.js";
+/** Live header source, read per request so rotated tokens / CSRF reach the server. */
+type HeadersProvider = () => Record<string, string>;
+/**
+ * Live cookie policy, read per request. A provider rather than a value: the
+ * store is built once on connect, but a host may configure the element after
+ * inserting it, and a captured value would pin that first frame's setting.
+ */
+type CredentialsProvider = () => RequestCredentials | undefined;
+/**
+ * A {@link ClientConversationStore} backed by a server thread-index endpoint —
+ * django-ag-ui's owner-scoped `ThreadsView`, the URL passed to `<ag-ui-chat>`
+ * as `data-threads-url`:
+ *
+ * - `GET  <url>`        → list the user's threads (metadata only);
+ * - `GET  <url><id>/`   → that thread's messages;
+ * - `PATCH <url><id>/`  → rename (`{ "title": … }`);
+ * - `DELETE <url><id>/` → delete.
+ *
+ * Wraps a local store (default {@link SessionStorageStore}) for the client-only
+ * concerns — active thread id, navigation checkpoint, message cache — and as
+ * the fallback when a request fails. Rename and delete apply optimistically via
+ * a local overlay, so the drawer reflects them before the fire-and-forget
+ * round-trip lands.
+ *
+ * Pass `cacheMessages: false` to keep message bodies out of the browser
+ * entirely; see the constructor.
+ */
+export declare class RemoteConversationStore implements ClientConversationStore {
+    #private;
+    /**
+     * @param cacheMessages Whether to mirror message bodies into the local store.
+     *
+     * `true` (the default, and the behaviour this class has always had) keeps a
+     * local copy of every turn, so the transcript still replays when the thread
+     * endpoint is unreachable. `false` is for the deployment that chose a
+     * server-backed store precisely so transcripts do not sit in the browser:
+     * regulated content, a shared workstation, an operator who has to be able to
+     * say where the conversation lives. It is not the same as passing a local
+     * store that does nothing — the local store also owns the active thread id,
+     * the navigation checkpoint and the "nothing sent here yet" marker, all of
+     * which must keep working — so the opt-out is scoped to the bodies alone.
+     *
+     * The cost is deliberate and worth stating: with no local copy there is
+     * nothing to fall back to, so a failed request shows an empty transcript
+     * rather than a stale one, and the drawer's offline list loses its previews
+     * (a preview is an excerpt of a message, which is the very thing being kept
+     * off the client).
+     */
+    constructor(url: string, headers?: HeadersProvider, local?: ClientConversationStore, credentials?: CredentialsProvider, cacheMessages?: boolean);
+    threadId(): string;
+    setActiveThread(threadId: string): void;
+    /**
+     * Delegated to the local store, which owns the active id — and deliberately
+     * silent on the wire: the server learns of a thread when its first message is
+     * persisted, so an abandoned new chat costs no round-trip and leaves no row.
+     */
+    newThread(): string;
+    /** Delegated, so wrapping a store does not lose what it knows about its own ids. */
+    isUnsent(threadId: string): boolean;
+    saveMessages(threadId: string, messages: readonly Message[]): void;
+    loadCheckpoint(threadId: string): NavigationCheckpoint | null;
+    saveCheckpoint(threadId: string, checkpoint: NavigationCheckpoint | null): void;
+    renameThread(threadId: string, title: string): void;
+    clear(threadId: string): void;
+    listThreads(): Promise<readonly ThreadMeta[]>;
+    loadMessages(threadId: string): Promise<readonly Message[] | null>;
+}
+export {};
+//# sourceMappingURL=remote_conversation_store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote_conversation_store.d.ts","sourceRoot":"","sources":["../../src/core/remote_conversation_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAEzB,KAAK,UAAU,EAEhB,MAAM,yBAAyB,CAAC;AAajC,sFAAsF;AACtF,KAAK,eAAe,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpD;;;;GAIG;AACH,KAAK,mBAAmB,GAAG,MAAM,kBAAkB,GAAG,SAAS,CAAC;AAEhE;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,uBAAwB,YAAW,uBAAuB;;IAiBrE;;;;;;;;;;;;;;;;;;OAkBG;IACH,YACE,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,eAA4B,EACrC,KAAK,GAAE,uBAAmD,EAC1D,WAAW,GAAE,mBAAqC,EAClD,aAAa,UAAO,EAOrB;IAED,QAAQ,IAAI,MAAM,CAGjB;IAED,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAGtC;IAED;;;;OAIG;IACH,SAAS,IAAI,MAAM,CAGlB;IAED,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAElC;IAED,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAiBjE;IAED,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAE5D;IAED,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAE9E;IAED,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIlD;IAED,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAK5B;IAEK,WAAW,IAAI,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAUlD;IAkBK,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC,CAkBvE;CAoEF"}

package/dist/core/run_handlers.d.ts

@@ -0,0 +1,85 @@
+import type { RunAnnouncer } from "../ui/progress/run_announcer.js";
+import type { SubAgentProgress } from "../ui/progress/subagent_progress.js";
+import type { AnswerActions } from "../ui/transcript/answer_actions.js";
+import type { AnswerStream } from "../ui/transcript/answer_stream.js";
+import type { Transcript } from "../ui/transcript/transcript.js";
+import type { UiStrings } from "../ui/ui_strings.js";
+import type { ActivityRegistry } from "./activity_registry.js";
+import type { AgUiClientHandlers } from "./agui_client.js";
+import type { MessageRole } from "./message_role.js";
+/** What the run's event handlers need from the element that owns them. */
+export interface RunHandlersHost {
+    /** The custom element, which the run's events are dispatched on. */
+    readonly element: HTMLElement;
+    /** The transcript the run draws into. */
+    readonly transcript: Transcript;
+    /** The answer streaming into its bubble. */
+    readonly stream: AnswerStream;
+    /** The action row under each finished answer. */
+    readonly actions: AnswerActions;
+    /** The activity renderers, and the blocks they drew. */
+    readonly activities: ActivityRegistry;
+    /** A delegated sub-agent's progress, on the card that delegated. */
+    readonly subagents: SubAgentProgress;
+    /** The screen-reader status region. */
+    readonly announcer: RunAnnouncer;
+    /** The resolved string table. */
+    readonly strings: () => UiStrings;
+    /** Whether an interaction is already in flight, which the composer owns. */
+    readonly running: () => boolean;
+    /** Swap the composer between Send and Stop; settling sends a queued turn. */
+    readonly setRunning: (running: boolean) => void;
+    /** The element's `appendMessage`, which a failed run's bubble opens through. */
+    readonly appendMessage: (role: MessageRole, content: string) => HTMLDivElement;
+    /** Note an assistant answer finished on `threadId`, which may be unseen. */
+    readonly noteUnread: (threadId: string) => void;
+}
+/**
+ * The AG-UI event handlers a run is drawn by, and what one interaction
+ * accumulates for the host between its first round and its settle: the tool
+ * calls it made, the keys it invalidated, and whether it already said how it
+ * ended.
+ *
+ * A controller rather than a factory. The handlers hold nothing of their own,
+ * but that bookkeeping is state, and it has never belonged to one handler
+ * table: a table is built per client -- the conversation's own, rebuilt after
+ * a reset, and one for each checkpoint continuation -- and every table built
+ * for one conversation reports into the same bookkeeping. {@link forClient}
+ * still returns a fresh table per call.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export declare class RunHandlers {
+    #private;
+    constructor(host: RunHandlersHost);
+    /**
+     * Detach every handler table built so far, because the conversation they
+     * drew into has been cleared away.
+     *
+     * The element calls this when it resets, having first cancelled what was
+     * running. A cancelled run still ends later, and a detached table still
+     * reports to the host what that run did: a run stopped part-way may already
+     * have written something, and {@link RUN_FINISHED_EVENT} fires on
+     * cancellation for exactly that reason. Everything else it would do -- draw a
+     * stopped note, announce, put the composer back to Send, settle the pending
+     * cards -- would land in a transcript and a composer that now belong to
+     * another conversation, possibly mid-run, and is dropped. So is any event the
+     * run streams after the reset, invalidations included: an abort closes the
+     * request those would arrive on, so what a cancelled run still delivers is
+     * how it ended.
+     */
+    detach(): void;
+    /**
+     * A handler table for one AG-UI client. Every table built for the current
+     * conversation draws into the same transcript and shares its bookkeeping, so
+     * a continuation run reports into the interaction the user is looking at.
+     *
+     * `threadId` is the thread the client was built for, named on the
+     * run-finished detail. Taken here rather than read when the run settles,
+     * because a stopped run settles after the reset that stopped it, when the
+     * thread on screen is already the next one.
+     */
+    forClient(threadId: string): AgUiClientHandlers;
+}
+//# sourceMappingURL=run_handlers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run_handlers.d.ts","sourceRoot":"","sources":["../../src/core/run_handlers.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAK3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,SAAS,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,gFAAgF;IAChF,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,KAAK,cAAc,CAAC;IAC/E,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACjD;AA8ED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,WAAW;;IAQtB,YAAY,IAAI,EAAE,eAAe,EAEhC;IAED;;;;;;;;;;;;;;;OAeG;IACH,MAAM,IAAI,IAAI,CAEb;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CA2B9C;CAqTF"}

package/dist/core/run_index.d.ts

@@ -0,0 +1,58 @@
+/** One row of the server run index (django-ag-ui's `RunsView` wire shape). */
+export interface RunRow {
+    readonly run_id: string;
+    readonly thread_id: string | null;
+    readonly parent_run_id: string | null;
+    readonly started_at: string | null;
+    /** Whether the run has a snapshot to seed from — see {@link RunIndex}. */
+    readonly continuable: boolean;
+    /**
+     * The run's first user message, one line, already truncated by the server —
+     * the only field in a row a person recognises a conversation by.
+     *
+     * Optional because a server predating the field does not send it, and
+     * `null` where the run holds no words to show (seeded from history alone, or
+     * opened with an image and no caption). A row without one falls back to the
+     * time plus a short id.
+     */
+    readonly preview?: string | null;
+}
+/** Live header source, read per request so rotated tokens / CSRF reach the server. */
+type HeadersProvider = () => Record<string, string>;
+/** Live cookie policy, read per request; see `RemoteConversationStore`'s note. */
+type CredentialsProvider = () => RequestCredentials | undefined;
+/**
+ * Reads the server's run index and derives the resume / fork URLs beside it.
+ *
+ * Backed by django-ag-ui's owner-scoped `RunsView` — the URL passed to
+ * `<ag-ui-chat>` as `data-runs-url`:
+ *
+ * - `GET <url>` → the user's runs, newest first.
+ *
+ * Only `continuable` rows can be resumed: the server reports whether a run has
+ * a saved snapshot to seed from, and a run that never reached a provider-valid
+ * boundary has none. Offer the action only for those rows ({@link continuable}
+ * filters them) and treat the rest as informational.
+ *
+ * Resume and fork are siblings of the index rather than separate configuration
+ * — django-ag-ui mounts `runs/`, `resume/<id>/` and `fork/<id>/` under one
+ * prefix — so this one URL locates all three.
+ */
+export declare class RunIndex {
+    #private;
+    constructor(url: string, headers?: HeadersProvider, credentials?: CredentialsProvider);
+    /**
+     * The user's runs, or `[]` when the endpoint is unreachable or errors — the
+     * caller renders its empty state rather than a transport fault the user can
+     * do nothing about.
+     */
+    list(): Promise<readonly RunRow[]>;
+    /** The rows a client may actually continue. */
+    continuable(): Promise<readonly RunRow[]>;
+    /** The endpoint that continues `runId` as a new run. */
+    resumeUrl(runId: string): string;
+    /** The endpoint that branches `runId` into a new run, leaving the source untouched. */
+    forkUrl(runId: string): string;
+}
+export {};
+//# sourceMappingURL=run_index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run_index.d.ts","sourceRoot":"","sources":["../../src/core/run_index.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,sFAAsF;AACtF,KAAK,eAAe,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpD,kFAAkF;AAClF,KAAK,mBAAmB,GAAG,MAAM,kBAAkB,GAAG,SAAS,CAAC;AAEhE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,QAAQ;;IAKnB,YACE,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,eAA4B,EACrC,WAAW,GAAE,mBAAqC,EAKnD;IAED;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAoBvC;IAED,+CAA+C;IACzC,WAAW,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAE9C;IAED,wDAAwD;IACxD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/B;IAED,uFAAuF;IACvF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7B;CAaF"}

package/dist/core/storage_scope.d.ts

@@ -0,0 +1,118 @@
+import { type ClientConversationStore, SessionStorageStore } from "./conversation_store.js";
+/** What the storage scope needs from the element that owns it. */
+export interface StorageScopeHost {
+    /** The element's `id`, the namespace it prefers. */
+    readonly id: () => string;
+    /** The element's `endpoint`, the namespace it falls back to. */
+    readonly endpoint: () => string;
+}
+/**
+ * Which storage keys are this element's: the namespace it claims in the
+ * document, the key a layout preference is stored under, and the built-in
+ * conversation store scoped to it.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`. The one thing it shares is the record
+ * of claimed namespaces above, which is what keeps two elements apart.
+ */
+export declare class StorageScope {
+    #private;
+    constructor(host: StorageScopeHost);
+    /**
+     * Resolve the per-instance storage namespace, before any key is read or
+     * written, so this instance doesn't share collapsed/theme/thread state with
+     * another on the same origin.
+     */
+    claim(): void;
+    /**
+     * Give the namespace back. A disconnect is not necessarily a farewell — a
+     * DOM move and a framework re-render both look like one — and an element
+     * that could not reclaim its own namespace on the way back in would lose its
+     * conversation to a false collision.
+     */
+    release(): void;
+    /**
+     * The conversation store's namespace: this element's, scoped to the principal
+     * `key` names.
+     *
+     * Only the conversation is principal-scoped. The panel's own collapsed / size
+     * / theme preferences stay on the element's own namespace, because they are
+     * this element's UI state rather than anyone's data — they carry no word of
+     * what was said — and because they are read once while connecting, so
+     * re-scoping them under a live element would rearrange the panel around a
+     * user who had only just signed in.
+     */
+    conversationNamespace(key: string): string;
+    /**
+     * Namespace the built-in default store, and hand back the store to use. A
+     * host-injected store is used verbatim; the built-in one is remembered
+     * either way, because it is the element's own store and a later `user-key`
+     * change may move it to another namespace.
+     */
+    scopeStore(store: ClientConversationStore, key: string): ClientConversationStore;
+    /**
+     * Rebuild the built-in store under `namespace`, or `null` when `current` --
+     * the store the element is using now, unwrapped from any remote it wrapped
+     * it in -- is not the one this scope handed out.
+     *
+     * Asked of the store in use rather than of what connecting remembered,
+     * because the two part company the moment a host assigns a store of its own
+     * to a connected element. Remembering was enough to tell a host's store from
+     * the built-in one at connect; after it, the built-in one was still
+     * remembered, so a key change replaced the host's store with a fresh
+     * `sessionStorage` one -- and a host that had chosen to keep message bodies
+     * off the client found every one of them cached in the tab again. A store
+     * the element did not make holds its data somewhere the element cannot see,
+     * and has to scope itself.
+     */
+    rescopeStore(current: ClientConversationStore, namespace: string): SessionStorageStore | null;
+    /** This instance's namespaced form of an origin-scoped storage key. */
+    key(base: string): string;
+    /** Read a namespaced origin-scoped value. */
+    readScopedItem(base: string): string | null;
+    /**
+     * Read a layout preference: where the widget sits, how big it is, which
+     * theme it wears.
+     *
+     * These live in `localStorage` rather than beside the transcript, because a
+     * layout preference is not a conversation. The transcript is deliberately
+     * per-tab -- two tabs are two conversations, and closing the tab ends it --
+     * and everything else inherited that scoping without earning it. A user who
+     * dragged the panel clear of their own UI did it again in the next tab, and
+     * again after every restart.
+     *
+     * Whether the widget is *currently open* stays per-tab with the transcript.
+     * It is a statement about this tab rather than a preference: carrying it
+     * across would pop the panel open on every new tab because it was opened
+     * once, somewhere else.
+     *
+     * Falls back to the per-tab copy, which is all a browser that denies
+     * `localStorage` has.
+     */
+    readPreference(base: string): string | null;
+    /**
+     * Persist a layout preference as durably as this browser allows: to
+     * `localStorage` so it outlives the tab, and to the per-tab store as well.
+     *
+     * The second write is not redundancy for its own sake. A privacy mode can
+     * deny `localStorage` while allowing `sessionStorage`, and losing the
+     * durable copy should degrade to the per-tab behaviour this replaced rather
+     * than to no persistence at all. The read above prefers the durable copy, so
+     * a tab that has both cannot be shadowed by its own stale one.
+     *
+     * Neither write is worth an exception. A refused per-tab write warns once
+     * per scope rather than once per write, because the size path writes on
+     * every step.
+     */
+    writePreference(base: string, value: string): void;
+    /** Write a per-tab value under this scope's key, sharing its one refused-write warning. */
+    writeSession(base: string, value: string): void;
+    /**
+     * Drop a layout preference from both stores.
+     *
+     * The mirror of {@link writePreference}, and it has to clear both for the
+     * same reason that writes both: leaving either copy behind means the value
+     * comes back on the next read.
+     */
+    clearPreference(base: string): void;
+}
+//# sourceMappingURL=storage_scope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage_scope.d.ts","sourceRoot":"","sources":["../../src/core/storage_scope.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,uBAAuB,EAC5B,mBAAmB,EAGpB,MAAM,yBAAyB,CAAC;AAkBjC,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,EAAE,MAAM,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;;IAyBvB,YAAY,IAAI,EAAE,gBAAgB,EAEjC;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAEZ;IAED;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAKd;IAED;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzC;IAED;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,uBAAuB,EAAE,GAAG,EAAE,MAAM,GAAG,uBAAuB,CAO/E;IAED;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAM5F;IAED,uEAAuE;IACvE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExB;IAED,6CAA6C;IAC7C,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE1C;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU1C;IAED;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAQjD;IAED,2FAA2F;IAC3F,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE9C;IAED;;;;;;OAMG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAYlC;CAyDF"}

package/dist/core/tool_outcome.d.ts

@@ -0,0 +1,27 @@
+import { TOOL_OUTCOME } from "../constants.js";
+import type { SettledStatus } from "../ui/progress/tool_call_card.js";
+/**
+ * How a tool call ended, in the wire's own words. See {@link TOOL_OUTCOME}.
+ *
+ * Absent is the fourth case and the common one: a server that has never heard
+ * of the field says nothing, and nothing means success.
+ */
+export type ToolOutcome = (typeof TOOL_OUTCOME)[keyof typeof TOOL_OUTCOME];
+/**
+ * The card status a wire outcome settles into.
+ *
+ * Takes `unknown` rather than {@link ToolOutcome} on purpose: both callers read
+ * this off a boundary the type system does not police -- a key in an AG-UI
+ * event's `metadata`, which the protocol declares open and does not validate,
+ * and a JSON blob out of the conversation store -- so the narrowing belongs
+ * here, once, instead of at each of them.
+ *
+ * **Everything unrecognised maps to `DONE`.** Not because unknown values are
+ * expected to be successes, but because the alternative is worse in the
+ * direction that matters: a card claiming a call failed when it did not is a
+ * lie the user acts on, while a card claiming success has at least the result
+ * text under it for them to read. A future release may add words, and forward
+ * compatibility is the point of the open field.
+ */
+export declare function toolStatusFromOutcome(outcome: unknown): SettledStatus;
+//# sourceMappingURL=tool_outcome.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool_outcome.d.ts","sourceRoot":"","sources":["../../src/core/tool_outcome.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAWrE"}

package/dist/core/transcribe_audio.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The composer's voice-transcription contract: take a recorded audio `Blob` and
+ * resolve to the transcript text. The built-in handler is
+ * {@link transcribeAudio}; a host swaps in its own (a Web Speech adapter, a
+ * direct-to-provider call) via `AgUiChat.transcribeHandler` without touching
+ * the mic button.
+ */
+export type TranscribeHandler = (audio: Blob) => Promise<string>;
+/** Options for {@link transcribeAudio}. */
+export interface TranscribeOptions {
+    /** The transcription endpoint (`data-transcribe-url`). */
+    readonly url: string;
+    /** Extra HTTP headers (CSRF / auth), read fresh per request. */
+    readonly headers?: Record<string, string>;
+    /**
+     * Cookie policy, as `fetch`'s own `credentials` mode. Unset leaves the
+     * browser default (`same-origin`), which sends no cookies to an endpoint on
+     * another origin; a cookie-authenticated cross-origin deployment needs
+     * `"include"`.
+     */
+    readonly credentials?: RequestCredentials;
+}
+/**
+ * POST a recorded clip to the transcription endpoint and resolve to its text.
+ *
+ * The clip goes as multipart under the `audio` field with the element's
+ * `headers`, mirroring {@link uploadAttachment}, and the server replies
+ * `{ "text": "<transcript>" }`. A non-2xx response or a network error rejects
+ * so the mic button can surface the failure.
+ */
+export declare function transcribeAudio(audio: Blob, options: TranscribeOptions): Promise<string>;
+//# sourceMappingURL=transcribe_audio.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe_audio.d.ts","sourceRoot":"","sources":["../../src/core/transcribe_audio.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEjE,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4B9F"}

package/dist/core/upload_attachment.d.ts

@@ -0,0 +1,44 @@
+import type { AttachmentRef } from "./attachment.js";
+/**
+ * The composer's upload contract: take a `File`, report `0..1` progress, and
+ * resolve to a durable {@link AttachmentRef}. The built-in handler is
+ * {@link uploadAttachment}; a host swaps in its own (a `tus-js-client` or
+ * direct-to-S3 adapter) via `AgUiChat.uploadHandler` without touching the tray,
+ * the chips, or the AG-UI wire, refs being transport-agnostic.
+ *
+ * The optional `signal` fires when the tray removes a chip or the element is
+ * torn down; a handler that honours it should abort its own transport, so a
+ * cancelled upload doesn't orphan a server-side file.
+ */
+export type UploadHandler = (file: File, onProgress: (fraction: number) => void, signal?: AbortSignal) => Promise<AttachmentRef>;
+/** Options for {@link uploadAttachment}. */
+export interface UploadOptions {
+    /** The attachments endpoint (`data-attachments-url`). */
+    readonly url: string;
+    /** Extra HTTP headers (CSRF / auth), read fresh per upload. */
+    readonly headers?: Record<string, string>;
+    /**
+     * Cookie policy, spelled as `fetch`'s `credentials` mode for consistency with
+     * the other endpoints, but carried by `XMLHttpRequest`'s two-state
+     * `withCredentials`: `"include"` sets it and every other value leaves it off,
+     * matching `"same-origin"`. `"omit"` therefore cannot be honoured for a
+     * same-origin upload, XHR always sending cookies there; use a custom
+     * {@link UploadHandler} if that matters.
+     */
+    readonly credentials?: RequestCredentials;
+    /** Progress callback, `0..1`, fired as the body uploads. */
+    readonly onProgress?: (fraction: number) => void;
+    /** Abort signal to cancel the in-flight upload. */
+    readonly signal?: AbortSignal | undefined;
+}
+/**
+ * Upload one file to the attachments endpoint and resolve to its durable
+ * {@link AttachmentRef}.
+ *
+ * Uses `XMLHttpRequest` rather than `fetch` for real upload-progress events.
+ * The file goes as multipart under the `file` field with the element's
+ * `headers`, so CSRF / auth ride along; a non-2xx response or a network/abort
+ * error rejects, letting the tray show an error chip.
+ */
+export declare function uploadAttachment(file: File, options: UploadOptions): Promise<AttachmentRef>;
+//# sourceMappingURL=upload_attachment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"upload_attachment.d.ts","sourceRoot":"","sources":["../../src/core/upload_attachment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACtC,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5B,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CA6C3F"}

package/dist/core/utils.d.ts

@@ -0,0 +1,117 @@
+import type { Message } from "@ag-ui/core";
+import type { ClientConversationStore } from "./conversation_store.js";
+/**
+ * Overlay a `credentials` mode onto a fetch `init`, or hand the `init` back
+ * untouched when none is configured.
+ *
+ * Absent and `undefined` differ: `exactOptionalPropertyTypes` rejects an
+ * explicit `credentials: undefined`, and writing one anyway would state a mode
+ * where the point is to leave the browser's own default in place.
+ */
+export declare function withCredentials(init: RequestInit | undefined, credentials: RequestCredentials | undefined): RequestInit | undefined;
+/**
+ * Start a new conversation in `store` and return its id.
+ *
+ * `newThread` is optional on the interface, so a store without it is
+ * driven the only other way the interface allows: mint an id here and make it
+ * active. That path loses the store's own note that the thread is new, so a
+ * remote store would go on to ask the server for a conversation that cannot
+ * exist yet — which is why every store in this package implements the method.
+ *
+ * What neither path does is clear the thread being left behind. Starting a
+ * conversation is not a reason to destroy the previous one.
+ */
+export declare function mintThread(store: ClientConversationStore): string;
+/**
+ * Announce host credentials about to leave the document's origin.
+ *
+ * `endpoint` and its six sibling URL attributes are plain HTML, and a page that
+ * interpolates one from a query parameter or from tenant-authored
+ * configuration has handed an attacker the destination. The browser preflights
+ * the custom header, any server willing to answer `Access-Control-Allow-Headers`
+ * receives it, and the token leaves on the element's very first request —
+ * before the user has done anything. Nothing else in this package compares a
+ * configured URL against an expected origin, so without this the delivery is
+ * silent, which is the only part of that sequence worth changing.
+ *
+ * A warning rather than a refusal because a cross-origin agent is a documented
+ * deployment: refusing would break working installations to defend against a
+ * page that is already interpolating untrusted data into its own markup. What
+ * it removes is the silence.
+ *
+ * `warned` is supplied by the caller rather than held here, per this package's
+ * rule against shared mutable state: two elements on one page must each get
+ * their own notice, and the set lives exactly as long as its owner.
+ *
+ * Every configured URL goes through this, not the agent endpoint alone. The
+ * tool catalog, the skills list, the thread and attachment endpoints and the
+ * upload target are all named by the same kind of host attribute and all carry
+ * the same headers, so covering one of them and not the rest would report the
+ * least interesting of the seven.
+ */
+export declare function warnOnCrossOriginCredentials(url: string | URL, credentialNames: readonly string[], trustedOrigins: readonly string[], warned: Set<string>): void;
+/**
+ * The tokens of a comma-separated attribute value, trimmed, with empty ones
+ * dropped -- so `"scroll, drag,"` is `["scroll", "drag"]`.
+ *
+ * Shared by every attribute that names a set of opt-ins, so each one reads a
+ * stray space or a trailing comma the same way.
+ */
+export declare function commaTokens(value: string): string[];
+/**
+ * `messages` with a result for every tool call that has none, each placed at the
+ * end of the round that made the call.
+ *
+ * **Why every call.** Several model providers reject a request carrying a tool
+ * call with no result, and a conversation that sends one cannot continue. A run
+ * leaves calls unanswered in more ways than any one path can list: Stop while
+ * the stream is still arriving, a round ending on `RUN_ERROR`, a name no tool
+ * here owns, a server that never streamed a result, a page reloaded mid-run.
+ * Answering whatever is unanswered, rather than each of those where it happens,
+ * is what keeps a path nobody listed from sending one.
+ *
+ * **Where each result goes.** At the end of its round: the assistant turns
+ * carrying calls, then the results that follow them. That is the shape the run
+ * loop writes for a round it executed, and a provider reads a result only in the
+ * turn straight after the calls; appended at the end of history, it would sit
+ * behind a user turn or a reply the conversation has moved on to. A call with a
+ * result after a *later* turn is left alone, since it is answered.
+ *
+ * `answer` builds the one message for a call id, so the caller decides what is
+ * true to say and where the label for a reload goes. Calls in `except` are about
+ * to be answered by something else -- a resumed approval, or a navigation
+ * result -- and must not be answered twice.
+ *
+ * Returns `messages` itself when nothing is owed.
+ *
+ * Every condition deciding a round's end is one branch arc, which a coverage
+ * gate reports as covered with any part of it deleted. Each is held by a test in
+ * `ag_ui_chat_unanswered_tool_calls.test.ts`: a result continuing the round by
+ * "answers it after the round's own results"; a turn without calls closing it by
+ * "sends a not-finished result for a call that arrived before it"; a turn with
+ * calls after a result closing it by "answers each round's open call before the
+ * next round starts"; the answered check by "sends the decline Stop gave the
+ * open approval"; and the exclusion by "leaves the call it resumes for the
+ * server to answer".
+ */
+export declare function answerUnansweredCalls(messages: readonly Message[], answer: (toolCallId: string) => Message, except?: ReadonlySet<string>): readonly Message[];
+/**
+ * A key a message carries in its `metadata`, or the same key at the message's
+ * top level when its metadata has none.
+ *
+ * Two keys are read this way, a tool message's `outcome` and a user message's
+ * `attachments`, and both for the same reason. `@ag-ui/client` 1.0 strips every
+ * key its schemas do not declare, off an inbound event and off the outgoing
+ * input, and `metadata` is the one place it declares open by key, so that is
+ * where this component writes them. A conversation stored by an earlier release
+ * has them at the top level instead, and a reload has to replay it as it
+ * settled.
+ *
+ * Metadata first, so a message carrying both says what the newer writer said.
+ * The result is `unknown` because it comes out of a store, which is not trusted
+ * to hold the shape anything here wrote; the caller narrows it. `Object()` boxes
+ * an absent, `null` or primitive `metadata` into an object with neither key,
+ * which reads as no metadata without a branch per shape.
+ */
+export declare function metadataOrTopLevel(message: Message, key: "outcome" | "attachments"): unknown;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,WAAW,EAAE,kBAAkB,GAAG,SAAS,GAC1C,WAAW,GAAG,SAAS,CAEzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAOjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,eAAe,EAAE,SAAS,MAAM,EAAE,EAClC,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAClB,IAAI,CAwBN;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAKnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,EACvC,MAAM,GAAE,WAAW,CAAC,MAAM,CAAa,GACtC,SAAS,OAAO,EAAE,CAiCpB;AAqBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,GAAG,aAAa,GAAG,OAAO,CAG5F"}