@artooi/ag-ui-web-component 0.1.0

package/src/client_tool_registry.ts

@@ -0,0 +1,56 @@
+import type { Tool } from "@ag-ui/core";
+
+/**
+ * A tool the frontend declares and executes itself.
+ *
+ * `parameters` is a JSON Schema (and may carry the `x-destructive` extension).
+ * `handler` receives the parsed arguments and returns a result that is
+ * JSON-serialised into the AG-UI tool-result message sent back to the agent.
+ */
+export interface ClientTool {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+
+/**
+ * Holds the frontend tools a host has declared on an `<ag-ui-chat>` element.
+ *
+ * Produces AG-UI {@link Tool} definitions for `RunAgentInput.tools` and looks
+ * up handlers when the agent calls a tool. Pure (no DOM); the element owns one
+ * instance.
+ */
+export class ClientToolRegistry {
+  readonly #tools = new Map<string, ClientTool>();
+
+  /** Register a tool. Throws if the name is already taken. */
+  register(tool: ClientTool): void {
+    if (this.#tools.has(tool.name)) {
+      throw new Error(`tool "${tool.name}" already registered`);
+    }
+    this.#tools.set(tool.name, tool);
+  }
+
+  has(name: string): boolean {
+    return this.#tools.has(name);
+  }
+
+  /** Return a registered tool or throw. */
+  get(name: string): ClientTool {
+    const tool = this.#tools.get(name);
+    if (tool === undefined) {
+      throw new Error(`tool "${name}" is not registered`);
+    }
+    return tool;
+  }
+
+  /** AG-UI tool definitions for `RunAgentInput.tools`. */
+  tools(): Tool[] {
+    return [...this.#tools.values()].map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    }));
+  }
+}

package/src/confirmation_modal.ts

@@ -0,0 +1,69 @@
+/** What the confirmation modal displays. */
+export interface ConfirmationRequest {
+  toolName: string;
+  args: Record<string, unknown>;
+}
+
+/**
+ * Render a confirmation modal into ``host`` and resolve when the user decides.
+ *
+ * Resolves ``true`` if the user confirms, ``false`` if they cancel or dismiss
+ * via the backdrop. The modal is appended to ``host`` (the chat container
+ * inside the element's shadow root) and removed once resolved.
+ */
+export function requestConfirmation(
+  host: Node & ParentNode,
+  request: ConfirmationRequest,
+): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const overlay = document.createElement("div");
+    overlay.className = "modal-overlay";
+
+    const dialog = document.createElement("div");
+    dialog.className = "modal";
+
+    const title = document.createElement("div");
+    title.className = "modal-title";
+    title.textContent = "Confirm action";
+
+    const body = document.createElement("div");
+    body.className = "modal-body";
+    body.textContent = `Run “${request.toolName}”?`;
+
+    const args = document.createElement("pre");
+    args.className = "modal-args";
+    args.textContent = JSON.stringify(request.args, null, 2);
+
+    const actions = document.createElement("div");
+    actions.className = "modal-actions";
+
+    const cancel = document.createElement("button");
+    cancel.className = "modal-btn modal-btn--cancel";
+    cancel.type = "button";
+    cancel.textContent = "Cancel";
+
+    const confirm = document.createElement("button");
+    confirm.className = "modal-btn modal-btn--confirm";
+    confirm.type = "button";
+    confirm.textContent = "Run";
+
+    const close = (accepted: boolean): void => {
+      overlay.remove();
+      resolve(accepted);
+    };
+
+    cancel.addEventListener("click", () => close(false));
+    confirm.addEventListener("click", () => close(true));
+    overlay.addEventListener("click", (event) => {
+      if (event.target === overlay) {
+        close(false);
+      }
+    });
+
+    actions.append(cancel, confirm);
+    dialog.append(title, body, args, actions);
+    overlay.append(dialog);
+    host.appendChild(overlay);
+    confirm.focus();
+  });
+}

package/src/constants.ts

@@ -0,0 +1,48 @@
+// The package's single home for enums and constant-like values. Per
+// CLAUDE.md this is the only file allowed to export multiple symbols.
+
+/** The Custom Element tag name registered by {@link defineAgUiChat}. */
+export const ELEMENT_TAG = "ag-ui-chat";
+
+/**
+ * Event dispatched by `<ag-ui-chat>` when the user submits a message.
+ * `detail` carries `{ content: string }`. Later phases wire this to the
+ * AG-UI client; for now it is the public seam for host integration.
+ */
+export const SUBMIT_EVENT = "ag-ui-submit";
+
+/** Roles a chat message can take. */
+export const MESSAGE_ROLE = {
+  USER: "user",
+  ASSISTANT: "assistant",
+} as const;
+
+/**
+ * JSON-Schema extension key marking a tool as destructive. Mirrors the
+ * `django-ag-ui` server side. When a tool's `parameters` carries
+ * `{ "x-destructive": true }`, the element gates its execution behind the
+ * confirmation modal (unless `autoConfirm` is set).
+ */
+export const X_DESTRUCTIVE_KEY = "x-destructive";
+
+/**
+ * JSON-Schema extension key marking a tool as navigating — its handler triggers
+ * a full page reload (an MPA navigation). When a tool's `parameters` carries
+ * `{ "x-navigates": true }`, the element checkpoints the call before the reload
+ * and resumes the run loop once the next page mounts. Mirrors `x-destructive`.
+ */
+export const X_NAVIGATES_KEY = "x-navigates";
+
+/** Upper bound on frontend tool-call → re-run rounds within one send. */
+export const MAX_TOOL_ROUNDS = 10;
+
+/**
+ * Lifecycle status of a rendered tool-call card. A card opens as `PENDING`
+ * while the call runs, then settles to `DONE`, `ERROR`, or `DECLINED`.
+ */
+export const TOOL_CALL_STATUS = {
+  PENDING: "pending",
+  DONE: "done",
+  ERROR: "error",
+  DECLINED: "declined",
+} as const;

package/src/conversation_store.ts

@@ -0,0 +1,103 @@
+import { randomUUID } from "@ag-ui/client";
+import type { Message } from "@ag-ui/core";
+
+/**
+ * A checkpoint recorded just before a navigating tool reloads the page.
+ *
+ * The reload destroys the in-memory run loop, so the element persists this
+ * marker first; on the next mount it supplies the tool's result and resumes.
+ */
+export interface NavigationCheckpoint {
+  /** The tool-call id whose result must be supplied after the reload. */
+  readonly toolCallId: string;
+}
+
+/**
+ * Client-side persistence seam for the conversation and a pending-navigation
+ * checkpoint, keyed by `thread_id`.
+ *
+ * The default {@link SessionStorageStore} keeps everything per-tab in
+ * `sessionStorage`, so the chat survives the full page reloads of a
+ * multi-page app. A host may inject a server-backed store instead (e.g. one
+ * that rehydrates from a history endpoint); `loadMessages` is therefore
+ * async-friendly. The checkpoint methods stay synchronous — the marker is a
+ * tiny local hint a server store can derive from history and no-op.
+ */
+export interface ClientConversationStore {
+  /** A stable conversation id, generated and persisted on first read. */
+  threadId(): string;
+  /** Load the persisted message history, or `null` when none exists. */
+  loadMessages(threadId: string): Promise<readonly Message[] | null>;
+  /** Persist the message history. */
+  saveMessages(threadId: string, messages: readonly Message[]): void;
+  /** Load the pending-navigation checkpoint, or `null` when none is set. */
+  loadCheckpoint(threadId: string): NavigationCheckpoint | null;
+  /** Set the pending-navigation checkpoint, or clear it when given `null`. */
+  saveCheckpoint(threadId: string, checkpoint: NavigationCheckpoint | null): void;
+  /** Forget the conversation and checkpoint (e.g. a "new chat" action). */
+  clear(threadId: string): void;
+}
+
+const THREAD_KEY = "ag-ui-chat:thread";
+const MESSAGES_PREFIX = "ag-ui-chat:messages:";
+const CHECKPOINT_PREFIX = "ag-ui-chat:checkpoint:";
+
+/**
+ * Default {@link ClientConversationStore}: per-tab `sessionStorage`.
+ *
+ * Survives full page reloads and same-tab navigation, clears on tab close —
+ * the right scope for an embedded agent's conversation in a multi-page app.
+ * One thread id per tab; the message history and checkpoint are namespaced by
+ * it so two tabs hold independent conversations.
+ */
+export class SessionStorageStore implements ClientConversationStore {
+  threadId(): string {
+    const existing = sessionStorage.getItem(THREAD_KEY);
+    if (existing !== null) {
+      return existing;
+    }
+    const id = randomUUID();
+    sessionStorage.setItem(THREAD_KEY, id);
+    return id;
+  }
+
+  loadMessages(threadId: string): Promise<readonly Message[] | null> {
+    return Promise.resolve(this.#readJson<Message[]>(MESSAGES_PREFIX + threadId));
+  }
+
+  saveMessages(threadId: string, messages: readonly Message[]): void {
+    sessionStorage.setItem(MESSAGES_PREFIX + threadId, JSON.stringify(messages));
+  }
+
+  loadCheckpoint(threadId: string): NavigationCheckpoint | null {
+    return this.#readJson<NavigationCheckpoint>(CHECKPOINT_PREFIX + threadId);
+  }
+
+  saveCheckpoint(threadId: string, checkpoint: NavigationCheckpoint | null): void {
+    const key = CHECKPOINT_PREFIX + threadId;
+    if (checkpoint === null) {
+      sessionStorage.removeItem(key);
+      return;
+    }
+    sessionStorage.setItem(key, JSON.stringify(checkpoint));
+  }
+
+  clear(threadId: string): void {
+    sessionStorage.removeItem(MESSAGES_PREFIX + threadId);
+    sessionStorage.removeItem(CHECKPOINT_PREFIX + threadId);
+    sessionStorage.removeItem(THREAD_KEY);
+  }
+
+  /** Parse a stored JSON value, returning `null` when absent or corrupt. */
+  #readJson<T>(key: string): T | null {
+    const raw = sessionStorage.getItem(key);
+    if (raw === null) {
+      return null;
+    }
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/create_http_agent.ts

@@ -0,0 +1,40 @@
+import { type AbstractAgent, HttpAgent } from "@ag-ui/client";
+import type { Message } from "@ag-ui/core";
+
+/** Config for {@link createHttpAgent}. */
+export interface HttpAgentOptions {
+  endpoint: string;
+  headers?: Record<string, string>;
+  /** Stable conversation id, so the agent's runs share a thread. */
+  threadId?: string;
+  /** Rehydrated history to seed the agent with (durable conversation). */
+  initialMessages?: readonly Message[];
+}
+
+/**
+ * Build an AG-UI {@link HttpAgent} pointed at ``endpoint``.
+ *
+ * This is the default agent factory used by ``<ag-ui-chat>``. Tests and
+ * advanced hosts override the element's ``agentFactory`` to inject a
+ * different {@link AbstractAgent} (e.g. a fake, or a middleware-wrapped one).
+ */
+export function createHttpAgent(options: HttpAgentOptions): AbstractAgent {
+  return new HttpAgent({
+    url: options.endpoint,
+    headers: options.headers ?? {},
+    // HttpAgent invokes its configured fetch as a method (`this.fetch(...)`),
+    // which would rebind the global `fetch` to the agent instance and trigger
+    // "Illegal invocation" in browsers. Wrap it so `fetch` is always called as
+    // a free function with the correct receiver.
+    fetch: (url, init) => fetch(url, init),
+    // Spread conditionally: under `exactOptionalPropertyTypes` an explicit
+    // `undefined` is not assignable to these optional config fields.
+    ...(options.threadId !== undefined ? { threadId: options.threadId } : {}),
+    ...(options.initialMessages !== undefined
+      ? { initialMessages: [...options.initialMessages] }
+      : {}),
+  });
+}
+
+/** Signature of the agent factory the element calls to build its agent. */
+export type AgentFactory = (options: HttpAgentOptions) => AbstractAgent;

package/src/define_ag_ui_chat.ts

@@ -0,0 +1,15 @@
+import { AgUiChat } from "./ag_ui_chat.js";
+import { ELEMENT_TAG } from "./constants.js";
+
+/**
+ * Register the `<ag-ui-chat>` Custom Element.
+ *
+ * Idempotent: calling it more than once (or after another module already
+ * registered the tag) is a no-op. Registration is an explicit step rather
+ * than an import side effect so the package is SSR-safe and tree-shakeable.
+ */
+export function defineAgUiChat(): void {
+  if (customElements.get(ELEMENT_TAG) === undefined) {
+    customElements.define(ELEMENT_TAG, AgUiChat);
+  }
+}

package/src/dom_driver.ts

@@ -0,0 +1,60 @@
+import {
+  focusWithFlash,
+  type HighlightClickOptions,
+  highlightThenClick,
+  scrollIntoCenterView,
+  type TextLikeElement,
+  type TypeOptions,
+  typeInto,
+} from "./animations.js";
+
+/**
+ * Generic, framework-free DOM-driving primitives.
+ *
+ * Each operates on an element the caller has already located. Host packages
+ * (e.g. `django-admin-agent`) wrap these with environment-aware lookups —
+ * `fill_field(name, value)` finds `#id_<name>` then calls {@link fillField}.
+ */
+
+export interface FillFieldOptions extends TypeOptions, FlashOptionsLike {}
+
+interface FlashOptionsLike {
+  flashMs?: number;
+}
+
+/** Scroll to, focus (with a flash), and type ``value`` into a text field. */
+export async function fillField(
+  el: TextLikeElement,
+  value: string,
+  options: FillFieldOptions = {},
+): Promise<void> {
+  scrollIntoCenterView(el);
+  await focusWithFlash(el, { flashMs: options.flashMs ?? 0 });
+  await typeInto(el, value, options);
+}
+
+/** Scroll to, highlight, and click an element. */
+export async function clickElement(
+  el: HTMLElement,
+  options: HighlightClickOptions = {},
+): Promise<void> {
+  scrollIntoCenterView(el);
+  await highlightThenClick(el, options);
+}
+
+/**
+ * Set a `<select>` or checkbox value without typing animation, dispatching the
+ * ``input`` and ``change`` events frameworks listen for.
+ */
+export function setControlValue(
+  el: HTMLInputElement | HTMLSelectElement,
+  value: string | boolean,
+): void {
+  if (el instanceof HTMLInputElement && el.type === "checkbox") {
+    el.checked = Boolean(value);
+  } else {
+    el.value = String(value);
+  }
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+// Public surface re-exports. Per CLAUDE.md, this is the only re-export point.
+export { AgUiChat, type MessageRole, type SubmitDetail } from "./ag_ui_chat.js";
+export {
+  AgUiClient,
+  type AgUiClientConfig,
+  type AgUiClientHandlers,
+  type AgUiRunInputs,
+  type AgUiToolCall,
+  type ExecuteTool,
+  type ToolExecution,
+} from "./agui_client.js";
+export {
+  type FlashOptions,
+  focusWithFlash,
+  type HighlightClickOptions,
+  highlightThenClick,
+  scrollIntoCenterView,
+  type TextLikeElement,
+  type TypeOptions,
+  typeInto,
+} from "./animations.js";
+export { type ClientTool, ClientToolRegistry } from "./client_tool_registry.js";
+export { type ConfirmationRequest, requestConfirmation } from "./confirmation_modal.js";
+export {
+  ELEMENT_TAG,
+  MAX_TOOL_ROUNDS,
+  MESSAGE_ROLE,
+  SUBMIT_EVENT,
+  TOOL_CALL_STATUS,
+  X_DESTRUCTIVE_KEY,
+  X_NAVIGATES_KEY,
+} from "./constants.js";
+export {
+  type ClientConversationStore,
+  type NavigationCheckpoint,
+  SessionStorageStore,
+} from "./conversation_store.js";
+export {
+  type AgentFactory,
+  createHttpAgent,
+  type HttpAgentOptions,
+} from "./create_http_agent.js";
+export { defineAgUiChat } from "./define_ag_ui_chat.js";
+export {
+  clickElement,
+  type FillFieldOptions,
+  fillField,
+  setControlValue,
+} from "./dom_driver.js";
+export { isDestructive } from "./is_destructive.js";
+export { isNavigates } from "./is_navigates.js";
+export { createPageMapContext, type PageMap } from "./page_map.js";
+export { createRouteTools, type Route, type RouteMap } from "./route_map.js";
+export { createStateHookTools, type StateHook } from "./state_hook.js";
+export {
+  type SettledStatus,
+  ToolCallCard,
+  type ToolCallStatus,
+} from "./tool_call_card.js";
+export { VERSION } from "./version.js";

package/src/is_destructive.ts

@@ -0,0 +1,11 @@
+import { X_DESTRUCTIVE_KEY } from "./constants.js";
+
+/**
+ * Whether a tool's JSON-Schema `parameters` marks it destructive.
+ *
+ * Reads the `x-destructive` extension stamped by the server (`django-ag-ui`'s
+ * `build_input_schema`) or by a host declaring a tool directly.
+ */
+export function isDestructive(parameters: Record<string, unknown>): boolean {
+  return parameters[X_DESTRUCTIVE_KEY] === true;
+}

package/src/is_navigates.ts

@@ -0,0 +1,12 @@
+import { X_NAVIGATES_KEY } from "./constants.js";
+
+/**
+ * Whether a tool's JSON-Schema `parameters` marks it as navigating.
+ *
+ * Reads the `x-navigates` extension. A navigating tool's handler reloads the
+ * page (MPA navigation), so the element checkpoints the call and resumes the
+ * run loop after the next page mounts, rather than awaiting a result inline.
+ */
+export function isNavigates(parameters: Record<string, unknown>): boolean {
+  return parameters[X_NAVIGATES_KEY] === true;
+}

package/src/page_map.ts

@@ -0,0 +1,25 @@
+import type { Context } from "@ag-ui/core";
+
+/**
+ * A compact snapshot of the current page's actionable surface (field
+ * names/types/labels, button labels+handles — not values). Host-defined shape;
+ * kept small because it rides in every `RunAgentInput.context`.
+ */
+export type PageMap = Record<string, unknown>;
+
+/**
+ * Build the per-run context entry for the page map.
+ *
+ * Returns a single `page_map` context item when auto-injection is on and a
+ * provider is set, else nothing. Recomputed each run so it reflects the page
+ * the agent is currently looking at.
+ */
+export function createPageMapContext(
+  getPageMap: (() => PageMap) | null,
+  autoInject: boolean,
+): Context[] {
+  if (!autoInject || getPageMap === null) {
+    return [];
+  }
+  return [{ description: "page_map", value: JSON.stringify(getPageMap()) }];
+}

package/src/route_map.ts

@@ -0,0 +1,83 @@
+import type { ClientTool } from "./client_tool_registry.js";
+import { X_NAVIGATES_KEY } from "./constants.js";
+
+/** A single navigable route the host declares for the agent. */
+export interface Route {
+  /** Stable id the agent uses with `navigate_to_route`. */
+  readonly id: string;
+  /** The URL path to navigate to. */
+  readonly path: string;
+  /** Human label shown to the agent. */
+  readonly title?: string;
+  /** Optional grouping (e.g. an app or section). */
+  readonly group?: string;
+  /** Optional longer description of when to use the route. */
+  readonly description?: string;
+}
+
+/** The host-declared catalog of navigable routes. */
+export type RouteMap = readonly Route[];
+
+/** Append `params` to `path` as a query string (no-op when empty). */
+function withQuery(path: string, params: Record<string, unknown> | undefined): string {
+  if (params === undefined) {
+    return path;
+  }
+  const usp = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    usp.set(key, String(value));
+  }
+  const query = usp.toString();
+  return query === "" ? path : `${path}?${query}`;
+}
+
+/**
+ * The built-in `route.*` tools, bound to live getters so a host can set
+ * `routeMap` / `navigate` before or after mount.
+ *
+ * `list_routes` is read-only; `navigate_to_route` is marked `x-navigates` so an
+ * MPA reload checkpoints + resumes. When the host supplies a `navigate(path)`
+ * callback (an SPA), the element routes client-side instead and the run loop
+ * simply continues — see `AgUiChat`'s execute path.
+ */
+export function createRouteTools(
+  getRouteMap: () => RouteMap,
+  getNavigate: () => ((path: string) => void) | null,
+): ClientTool[] {
+  return [
+    {
+      name: "list_routes",
+      description: "List the routes the app can navigate to.",
+      parameters: { type: "object", properties: {}, required: [] },
+      handler: () => getRouteMap(),
+    },
+    {
+      name: "navigate_to_route",
+      description: "Navigate to one of the app's routes by its id.",
+      parameters: {
+        type: "object",
+        properties: {
+          route_id: { type: "string" },
+          params: { type: "object" },
+        },
+        required: ["route_id"],
+        [X_NAVIGATES_KEY]: true,
+      },
+      handler: (args) => {
+        const routeId = args["route_id"];
+        const route = getRouteMap().find((r) => r.id === routeId);
+        if (route === undefined) {
+          throw new Error(`unknown route "${String(routeId)}"`);
+        }
+        const path = withQuery(route.path, args["params"] as Record<string, unknown> | undefined);
+        const navigate = getNavigate();
+        if (navigate !== null) {
+          navigate(path);
+        } else {
+          window.location.assign(path);
+        }
+        return { navigated: true, path };
+      },
+    },
+  ];
+}

package/src/state_hook.ts

@@ -0,0 +1,44 @@
+import type { ClientTool } from "./client_tool_registry.js";
+import { X_DESTRUCTIVE_KEY } from "./constants.js";
+
+/**
+ * A binding from a named piece of host application state to agent tools.
+ *
+ * Ergonomic sugar over `registerTool` for SPA state (Redux/Zustand/signals):
+ * generates a read tool and, when `write` is given, a destructive set tool.
+ */
+export interface StateHook {
+  /** Base name; tools become `read_<name>` and `set_<name>`. */
+  readonly name: string;
+  /** Returns the current state value. */
+  readonly read: () => unknown;
+  /** Mutates the state from the agent-supplied args. Omit for read-only. */
+  readonly write?: (args: Record<string, unknown>) => unknown;
+  /** JSON-Schema for the set tool's args. Defaults to an open object. */
+  readonly schema?: Record<string, unknown>;
+}
+
+/**
+ * Build the tools for a {@link StateHook}: always a `read_<name>` (read-only)
+ * tool, plus a `set_<name>` (`x-destructive`) tool when `write` is supplied.
+ */
+export function createStateHookTools(hook: StateHook): ClientTool[] {
+  const tools: ClientTool[] = [
+    {
+      name: `read_${hook.name}`,
+      description: `Read the "${hook.name}" state.`,
+      parameters: { type: "object", properties: {}, required: [] },
+      handler: () => hook.read(),
+    },
+  ];
+  const write = hook.write;
+  if (write !== undefined) {
+    tools.push({
+      name: `set_${hook.name}`,
+      description: `Update the "${hook.name}" state.`,
+      parameters: { ...(hook.schema ?? { type: "object" }), [X_DESTRUCTIVE_KEY]: true },
+      handler: (args) => write(args),
+    });
+  }
+  return tools;
+}