@artooi/ag-ui-web-component 0.1.0

package/dist/index.js

@@ -0,0 +1,1159 @@
+// src/agui_client.ts
+import { randomUUID } from "@ag-ui/client";
+
+// src/constants.ts
+var ELEMENT_TAG = "ag-ui-chat";
+var SUBMIT_EVENT = "ag-ui-submit";
+var MESSAGE_ROLE = {
+  USER: "user",
+  ASSISTANT: "assistant"
+};
+var X_DESTRUCTIVE_KEY = "x-destructive";
+var X_NAVIGATES_KEY = "x-navigates";
+var MAX_TOOL_ROUNDS = 10;
+var TOOL_CALL_STATUS = {
+  PENDING: "pending",
+  DONE: "done",
+  ERROR: "error",
+  DECLINED: "declined"
+};
+
+// src/agui_client.ts
+var AgUiClient = class {
+  #agent;
+  #handlers;
+  #getTools;
+  #getContext;
+  #executeTool;
+  #onPersist;
+  constructor(config) {
+    this.#agent = config.agent;
+    this.#handlers = config.handlers;
+    this.#getTools = config.getTools ?? (() => []);
+    this.#getContext = config.getContext ?? (() => []);
+    this.#executeTool = config.executeTool ?? null;
+    this.#onPersist = config.onPersist ?? (() => {
+    });
+  }
+  /** Whether a run is currently in flight. */
+  get running() {
+    return this.#agent.isRunning;
+  }
+  /** The current conversation history (for persistence / rehydration). */
+  get messages() {
+    return this.#agent.messages;
+  }
+  /**
+   * Append a user message and run the agent to completion.
+   *
+   * When the agent calls frontend tools, this executes them and re-runs the
+   * agent with the results, looping until the agent stops calling frontend
+   * tools (bounded by {@link MAX_TOOL_ROUNDS}).
+   */
+  async send(content) {
+    this.#agent.addMessage({ id: randomUUID(), role: "user", content });
+    this.#onPersist(this.#agent.messages);
+    await this.#run();
+  }
+  /**
+   * Resume the run loop after a navigating tool's result was supplied
+   * post-reload (via {@link addToolResult}). Unlike {@link send}, adds no user
+   * message — it simply continues the conversation already in history.
+   */
+  async resume() {
+    await this.#run();
+  }
+  /** Append a frontend tool result to history (used by the resume path). */
+  addToolResult(toolCallId, content) {
+    this.#agent.addMessage({ id: randomUUID(), role: "tool", content, toolCallId });
+    this.#onPersist(this.#agent.messages);
+  }
+  async #run() {
+    try {
+      await this.#runLoop();
+    } catch (error) {
+      this.#handlers.onError(error instanceof Error ? error.message : String(error));
+    }
+  }
+  async #runLoop() {
+    for (let round = 0; round < MAX_TOOL_ROUNDS; round += 1) {
+      const pending = [];
+      await this.#agent.runAgent(
+        { tools: this.#getTools(), context: this.#getContext() },
+        this.#buildSubscriber(pending)
+      );
+      this.#onPersist(this.#agent.messages);
+      if (this.#executeTool === null || pending.length === 0) {
+        return;
+      }
+      let executed = false;
+      for (const call of pending) {
+        const result = await this.#executeTool(call);
+        if (result === null) {
+          continue;
+        }
+        if (result.halt === true) {
+          return;
+        }
+        this.#agent.addMessage({
+          id: randomUUID(),
+          role: "tool",
+          content: result.content,
+          toolCallId: call.id
+        });
+        this.#onPersist(this.#agent.messages);
+        executed = true;
+      }
+      if (!executed) {
+        return;
+      }
+    }
+  }
+  #buildSubscriber(pending) {
+    const h = this.#handlers;
+    return {
+      onRunInitialized() {
+        h.onRunStart();
+      },
+      onTextMessageContentEvent({ textMessageBuffer }) {
+        h.onTextDelta(textMessageBuffer);
+      },
+      onTextMessageEndEvent({ textMessageBuffer }) {
+        h.onTextEnd(textMessageBuffer);
+      },
+      onToolCallEndEvent({ event, toolCallName, toolCallArgs }) {
+        const call = {
+          id: event.toolCallId,
+          name: toolCallName,
+          args: toolCallArgs
+        };
+        pending.push(call);
+        h.onToolCall(call);
+      },
+      onRunErrorEvent({ event }) {
+        h.onError(event.message);
+      },
+      onRunFinalized() {
+        h.onRunEnd();
+      }
+    };
+  }
+};
+
+// src/client_tool_registry.ts
+var ClientToolRegistry = class {
+  #tools = /* @__PURE__ */ new Map();
+  /** Register a tool. Throws if the name is already taken. */
+  register(tool) {
+    if (this.#tools.has(tool.name)) {
+      throw new Error(`tool "${tool.name}" already registered`);
+    }
+    this.#tools.set(tool.name, tool);
+  }
+  has(name) {
+    return this.#tools.has(name);
+  }
+  /** Return a registered tool or throw. */
+  get(name) {
+    const tool = this.#tools.get(name);
+    if (tool === void 0) {
+      throw new Error(`tool "${name}" is not registered`);
+    }
+    return tool;
+  }
+  /** AG-UI tool definitions for `RunAgentInput.tools`. */
+  tools() {
+    return [...this.#tools.values()].map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters
+    }));
+  }
+};
+
+// src/confirmation_modal.ts
+function requestConfirmation(host, request) {
+  return new Promise((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 \u201C${request.toolName}\u201D?`;
+    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) => {
+      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();
+  });
+}
+
+// src/conversation_store.ts
+import { randomUUID as randomUUID2 } from "@ag-ui/client";
+var THREAD_KEY = "ag-ui-chat:thread";
+var MESSAGES_PREFIX = "ag-ui-chat:messages:";
+var CHECKPOINT_PREFIX = "ag-ui-chat:checkpoint:";
+var SessionStorageStore = class {
+  threadId() {
+    const existing = sessionStorage.getItem(THREAD_KEY);
+    if (existing !== null) {
+      return existing;
+    }
+    const id = randomUUID2();
+    sessionStorage.setItem(THREAD_KEY, id);
+    return id;
+  }
+  loadMessages(threadId) {
+    return Promise.resolve(this.#readJson(MESSAGES_PREFIX + threadId));
+  }
+  saveMessages(threadId, messages) {
+    sessionStorage.setItem(MESSAGES_PREFIX + threadId, JSON.stringify(messages));
+  }
+  loadCheckpoint(threadId) {
+    return this.#readJson(CHECKPOINT_PREFIX + threadId);
+  }
+  saveCheckpoint(threadId, checkpoint) {
+    const key = CHECKPOINT_PREFIX + threadId;
+    if (checkpoint === null) {
+      sessionStorage.removeItem(key);
+      return;
+    }
+    sessionStorage.setItem(key, JSON.stringify(checkpoint));
+  }
+  clear(threadId) {
+    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(key) {
+    const raw = sessionStorage.getItem(key);
+    if (raw === null) {
+      return null;
+    }
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/create_http_agent.ts
+import { HttpAgent } from "@ag-ui/client";
+function createHttpAgent(options) {
+  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 !== void 0 ? { threadId: options.threadId } : {},
+    ...options.initialMessages !== void 0 ? { initialMessages: [...options.initialMessages] } : {}
+  });
+}
+
+// src/is_destructive.ts
+function isDestructive(parameters) {
+  return parameters[X_DESTRUCTIVE_KEY] === true;
+}
+
+// src/is_navigates.ts
+function isNavigates(parameters) {
+  return parameters[X_NAVIGATES_KEY] === true;
+}
+
+// src/page_map.ts
+function createPageMapContext(getPageMap, autoInject) {
+  if (!autoInject || getPageMap === null) {
+    return [];
+  }
+  return [{ description: "page_map", value: JSON.stringify(getPageMap()) }];
+}
+
+// src/route_map.ts
+function withQuery(path, params) {
+  if (params === void 0) {
+    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}`;
+}
+function createRouteTools(getRouteMap, getNavigate) {
+  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 === void 0) {
+          throw new Error(`unknown route "${String(routeId)}"`);
+        }
+        const path = withQuery(route.path, args["params"]);
+        const navigate = getNavigate();
+        if (navigate !== null) {
+          navigate(path);
+        } else {
+          window.location.assign(path);
+        }
+        return { navigated: true, path };
+      }
+    }
+  ];
+}
+
+// src/state_hook.ts
+function createStateHookTools(hook) {
+  const tools = [
+    {
+      name: `read_${hook.name}`,
+      description: `Read the "${hook.name}" state.`,
+      parameters: { type: "object", properties: {}, required: [] },
+      handler: () => hook.read()
+    }
+  ];
+  const write = hook.write;
+  if (write !== void 0) {
+    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;
+}
+
+// src/styles.ts
+var STYLES = `
+:host {
+  /* Colors */
+  --ag-ui-bg: #ffffff;
+  --ag-ui-fg: #1a1a2e;
+  --ag-ui-accent: #4f46e5;
+  --ag-ui-user-bg: #4f46e5;
+  --ag-ui-user-fg: #ffffff;
+  --ag-ui-assistant-bg: #f1f1f6;
+  --ag-ui-input-bg: var(--ag-ui-bg);
+  --ag-ui-tool-bg: var(--ag-ui-assistant-bg);
+  --ag-ui-tool-fg: var(--ag-ui-accent);
+  --ag-ui-header-bg: var(--ag-ui-accent);
+  --ag-ui-header-fg: #ffffff;
+  --ag-ui-border: #e2e2ec;
+  --ag-ui-radius: 12px;
+
+  /* Status accents for tool-call cards. */
+  --ag-ui-success: #15803d;
+  --ag-ui-danger: #b91c1c;
+  --ag-ui-muted: #6b7280;
+
+  /* Surface \u2014 set --ag-ui-shadow: none for a flush, embedded panel. */
+  --ag-ui-shadow: 0 12px 32px rgba(20, 20, 50, 0.18);
+  --ag-ui-font: inherit;
+  --ag-ui-font-size: 14px;
+
+  /* Layout \u2014 override from outside to dock the widget anywhere.
+     Set --ag-ui-position: static (and place this element in your own
+     grid/flex layout) to embed it in the page flow instead of floating. */
+  --ag-ui-position: fixed;
+  --ag-ui-z-index: 2147483000;
+  --ag-ui-width: 380px;
+  --ag-ui-height: 560px;
+  --ag-ui-inset: auto 24px 24px auto;
+  --ag-ui-max-width: calc(100vw - 48px);
+  --ag-ui-max-height: calc(100vh - 48px);
+
+  position: var(--ag-ui-position);
+  inset: var(--ag-ui-inset);
+  z-index: var(--ag-ui-z-index);
+  width: var(--ag-ui-width);
+  max-width: var(--ag-ui-max-width);
+  height: var(--ag-ui-height);
+  max-height: var(--ag-ui-max-height);
+  display: flex;
+  font-family: var(--ag-ui-font);
+  font-size: var(--ag-ui-font-size);
+  color: var(--ag-ui-fg);
+}
+
+.chat {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  background: var(--ag-ui-bg);
+  border: 1px solid var(--ag-ui-border);
+  border-radius: var(--ag-ui-radius);
+  box-shadow: var(--ag-ui-shadow);
+  overflow: hidden;
+}
+
+.header {
+  padding: 12px 16px;
+  font-weight: 600;
+  border-bottom: 1px solid var(--ag-ui-border);
+  background: var(--ag-ui-header-bg);
+  color: var(--ag-ui-header-fg);
+}
+
+.messages {
+  flex: 1;
+  overflow-y: auto;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.message {
+  max-width: 80%;
+  padding: 8px 12px;
+  border-radius: 14px;
+  line-height: 1.4;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.message--user {
+  align-self: flex-end;
+  background: var(--ag-ui-user-bg);
+  color: var(--ag-ui-user-fg);
+  border-bottom-right-radius: 4px;
+}
+
+.message--assistant {
+  align-self: flex-start;
+  background: var(--ag-ui-assistant-bg);
+  border-bottom-left-radius: 4px;
+}
+
+.tool-call {
+  align-self: flex-start;
+  max-width: 80%;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  font-size: 12px;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  padding: 8px 10px;
+  border-radius: 8px;
+  background: var(--ag-ui-tool-bg);
+  border: 1px solid var(--ag-ui-border);
+  color: var(--ag-ui-tool-fg);
+}
+
+.tool-call-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.tool-call-name {
+  font-weight: 600;
+  word-break: break-word;
+}
+
+.tool-call-status {
+  flex: none;
+  padding: 1px 8px;
+  border-radius: 999px;
+  font-size: 11px;
+  font-weight: 600;
+  background: rgba(127, 127, 127, 0.16);
+  color: var(--ag-ui-muted);
+}
+
+.tool-call[data-status="done"] .tool-call-status {
+  color: var(--ag-ui-success);
+}
+
+.tool-call[data-status="error"] .tool-call-status {
+  color: var(--ag-ui-danger);
+}
+
+.tool-call[data-status="declined"] .tool-call-status {
+  color: var(--ag-ui-muted);
+}
+
+.tool-call-args,
+.tool-call-result {
+  margin: 0;
+  padding: 6px 8px;
+  max-height: 160px;
+  overflow: auto;
+  background: var(--ag-ui-bg);
+  border: 1px solid var(--ag-ui-border);
+  border-radius: 6px;
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: var(--ag-ui-fg);
+}
+
+.tool-call-toggle {
+  align-self: flex-start;
+  border: none;
+  padding: 0;
+  background: none;
+  font: inherit;
+  font-weight: 600;
+  color: var(--ag-ui-accent);
+  cursor: pointer;
+}
+
+.tool-call-toggle::before {
+  content: "\u25B8 ";
+}
+
+.tool-call-toggle[aria-expanded="true"]::before {
+  content: "\u25BE ";
+}
+
+.input-row {
+  display: flex;
+  gap: 8px;
+  padding: 12px;
+  border-top: 1px solid var(--ag-ui-border);
+}
+
+.input {
+  flex: 1;
+  resize: none;
+  background: var(--ag-ui-input-bg);
+  border: 1px solid var(--ag-ui-border);
+  border-radius: 8px;
+  padding: 8px 10px;
+  font: inherit;
+  color: inherit;
+  outline: none;
+}
+
+.input:focus {
+  border-color: var(--ag-ui-accent);
+}
+
+.send {
+  border: none;
+  border-radius: 8px;
+  padding: 0 16px;
+  background: var(--ag-ui-accent);
+  color: #ffffff;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.send:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.modal-overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 16px;
+  background: rgba(20, 20, 50, 0.4);
+  backdrop-filter: blur(2px);
+}
+
+.modal {
+  width: 100%;
+  max-width: 320px;
+  background: var(--ag-ui-bg);
+  border-radius: 12px;
+  box-shadow: 0 16px 40px rgba(20, 20, 50, 0.3);
+  overflow: hidden;
+}
+
+.modal-title {
+  padding: 12px 16px;
+  font-weight: 600;
+  border-bottom: 1px solid var(--ag-ui-border);
+}
+
+.modal-body {
+  padding: 12px 16px 4px;
+}
+
+.modal-args {
+  margin: 0 16px 12px;
+  padding: 8px 10px;
+  max-height: 140px;
+  overflow: auto;
+  font-size: 12px;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  background: var(--ag-ui-assistant-bg);
+  border-radius: 8px;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.modal-actions {
+  display: flex;
+  gap: 8px;
+  padding: 0 16px 16px;
+  justify-content: flex-end;
+}
+
+.modal-btn {
+  border: 1px solid var(--ag-ui-border);
+  border-radius: 8px;
+  padding: 8px 14px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+  background: var(--ag-ui-bg);
+  color: var(--ag-ui-fg);
+}
+
+.modal-btn--confirm {
+  border-color: var(--ag-ui-accent);
+  background: var(--ag-ui-accent);
+  color: #ffffff;
+}
+`;
+
+// src/tool_call_card.ts
+var STATUS_LABEL = {
+  [TOOL_CALL_STATUS.PENDING]: "running\u2026",
+  [TOOL_CALL_STATUS.DONE]: "\u2713 done",
+  [TOOL_CALL_STATUS.ERROR]: "\u26A0 error",
+  [TOOL_CALL_STATUS.DECLINED]: "\u2298 declined"
+};
+var RESULT_LABEL = {
+  [TOOL_CALL_STATUS.DONE]: "Result",
+  [TOOL_CALL_STATUS.ERROR]: "Error",
+  [TOOL_CALL_STATUS.DECLINED]: "Declined"
+};
+var ToolCallCard = class {
+  /** The card's root element; append this into the message list. */
+  element;
+  #status;
+  constructor(name, args) {
+    this.element = document.createElement("div");
+    this.element.className = "tool-call";
+    this.element.setAttribute("data-tool-name", name);
+    this.element.setAttribute("data-status", TOOL_CALL_STATUS.PENDING);
+    const head = document.createElement("div");
+    head.className = "tool-call-head";
+    const label = document.createElement("span");
+    label.className = "tool-call-name";
+    label.textContent = `\u{1F527} ${name}`;
+    this.#status = document.createElement("span");
+    this.#status.className = "tool-call-status";
+    this.#status.textContent = STATUS_LABEL[TOOL_CALL_STATUS.PENDING];
+    head.append(label, this.#status);
+    const argsEl = document.createElement("pre");
+    argsEl.className = "tool-call-args";
+    argsEl.textContent = JSON.stringify(args, null, 2);
+    this.element.append(head, argsEl);
+  }
+  /**
+   * Flip the status pill to ``status`` and append a collapsed body holding
+   * ``text`` (the JSON result, an error message, a decline notice, or a
+   * server-executed note) behind a click-to-expand toggle.
+   */
+  settle(status, text) {
+    this.element.setAttribute("data-status", status);
+    this.#status.textContent = STATUS_LABEL[status];
+    const toggle = document.createElement("button");
+    toggle.type = "button";
+    toggle.className = "tool-call-toggle";
+    toggle.setAttribute("aria-expanded", "false");
+    toggle.textContent = RESULT_LABEL[status];
+    const output = document.createElement("pre");
+    output.className = "tool-call-result";
+    output.textContent = text;
+    output.hidden = true;
+    toggle.addEventListener("click", () => {
+      const expand = output.hidden;
+      output.hidden = !expand;
+      toggle.setAttribute("aria-expanded", String(expand));
+    });
+    this.element.append(toggle, output);
+  }
+};
+
+// src/ag_ui_chat.ts
+var AgUiChat = class extends HTMLElement {
+  /** Agent factory; override to inject a custom or fake agent (tests). */
+  agentFactory = createHttpAgent;
+  /** Extra HTTP headers for the AG-UI endpoint (e.g. CSRF). */
+  headers = {};
+  /** When true, destructive tools execute without a confirmation modal. */
+  autoConfirm = false;
+  /**
+   * 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 registerStateHook}; override to supply a
+   * fully custom catalog.
+   */
+  getTools = () => [
+    ...this.#routeTools().map((t) => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters
+    })),
+    ...this.#toolRegistry.tools()
+  ];
+  /**
+   * Per-run context provider. Defaults to the compact page map (when a
+   * {@link getPageMap} provider is set and {@link autoInjectPageMap} is on).
+   */
+  getContext = () => createPageMapContext(this.getPageMap, this.autoInjectPageMap);
+  /**
+   * Navigable routes the agent can jump to via the built-in `route.*` tools.
+   * A compact summary also rides in each run's context.
+   */
+  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 = null;
+  /** Provider for the per-run page map; see {@link getContext}. */
+  getPageMap = null;
+  /** Whether to auto-inject the page map into context each run. */
+  autoInjectPageMap = true;
+  /**
+   * 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 = new SessionStorageStore();
+  /**
+   * 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 = () => ({
+    navigated: true,
+    url: window.location.href
+  });
+  #toolRegistry = new ClientToolRegistry();
+  /** Tool-call cards awaiting execution, keyed by call id. */
+  #toolCards = /* @__PURE__ */ new Map();
+  #root;
+  #chat;
+  #messages;
+  #input;
+  #send;
+  #client = null;
+  #streamingBubble = null;
+  #threadId = "";
+  #initialMessages = [];
+  constructor() {
+    super();
+    this.#root = this.attachShadow({ mode: "open" });
+    this.#chat = document.createElement("div");
+    this.#messages = document.createElement("div");
+    this.#input = document.createElement("textarea");
+    this.#send = document.createElement("button");
+  }
+  /** Declare a frontend tool the agent may call. */
+  registerTool(tool) {
+    this.#toolRegistry.register(tool);
+  }
+  /** Bind a piece of host state to `read_<name>` / `set_<name>` tools. */
+  registerStateHook(hook) {
+    for (const tool of createStateHookTools(hook)) {
+      this.#toolRegistry.register(tool);
+    }
+  }
+  /** The built-in `route.*` tools, present only when a route map is set. */
+  #routeTools() {
+    if (this.routeMap.length === 0) {
+      return [];
+    }
+    return createRouteTools(
+      () => this.routeMap,
+      () => this.navigate
+    );
+  }
+  /** Resolve a tool by name: built-in route tools first, then the registry. */
+  #resolveTool(name) {
+    const route = this.#routeTools().find((t) => t.name === name);
+    if (route !== void 0) {
+      return route;
+    }
+    return this.#toolRegistry.has(name) ? this.#toolRegistry.get(name) : null;
+  }
+  /** The AG-UI endpoint URL, read from the `endpoint` attribute. */
+  get endpoint() {
+    return this.getAttribute("endpoint") ?? "";
+  }
+  connectedCallback() {
+    this.#render();
+    this.#threadId = this.conversationStore.threadId();
+    void this.#rehydrate();
+  }
+  /**
+   * Restore the conversation from the store on mount, then — if a navigating
+   * tool reloaded the page mid-run — resume the loop by supplying that tool's
+   * result from the page we landed on.
+   */
+  async #rehydrate() {
+    const messages = await this.conversationStore.loadMessages(this.#threadId);
+    if (messages !== null) {
+      this.#initialMessages = messages;
+      for (const message of messages) {
+        this.#renderHistoricMessage(message);
+      }
+    }
+    const checkpoint = this.conversationStore.loadCheckpoint(this.#threadId);
+    if (checkpoint !== null) {
+      await this.#resumeFrom(checkpoint);
+    }
+  }
+  /** Render a restored message as a chat bubble (text turns only). */
+  #renderHistoricMessage(message) {
+    if (typeof message.content !== "string" || message.content === "") {
+      return;
+    }
+    if (message.role === MESSAGE_ROLE.USER) {
+      this.appendMessage(MESSAGE_ROLE.USER, message.content);
+    } else if (message.role === MESSAGE_ROLE.ASSISTANT) {
+      this.appendMessage(MESSAGE_ROLE.ASSISTANT, message.content);
+    }
+  }
+  /** Complete the checkpointed navigating tool call and continue the run. */
+  async #resumeFrom(checkpoint) {
+    this.conversationStore.saveCheckpoint(this.#threadId, null);
+    const client = this.#ensureClient();
+    client.addToolResult(checkpoint.toolCallId, JSON.stringify(this.navigationResult(checkpoint)));
+    await client.resume();
+  }
+  /** Append a message bubble and return it. */
+  appendMessage(role, content) {
+    const bubble = document.createElement("div");
+    bubble.className = `message message--${role}`;
+    bubble.textContent = content;
+    this.#messages.appendChild(bubble);
+    this.#messages.scrollTop = this.#messages.scrollHeight;
+    return bubble;
+  }
+  #render() {
+    const style = document.createElement("style");
+    style.textContent = STYLES;
+    this.#chat.className = "chat";
+    const header = document.createElement("div");
+    header.className = "header";
+    header.textContent = this.getAttribute("title-text") ?? "Assistant";
+    this.#messages.className = "messages";
+    const inputRow = document.createElement("div");
+    inputRow.className = "input-row";
+    this.#input.className = "input";
+    this.#input.rows = 2;
+    this.#input.placeholder = "Ask anything\u2026";
+    this.#input.addEventListener("keydown", (event) => this.#onKeydown(event));
+    this.#send.className = "send";
+    this.#send.type = "button";
+    this.#send.textContent = "Send";
+    this.#send.addEventListener("click", () => {
+      void this.#submit();
+    });
+    inputRow.append(this.#input, this.#send);
+    this.#chat.append(header, this.#messages, inputRow);
+    this.#root.append(style, this.#chat);
+  }
+  #onKeydown(event) {
+    if (event.key === "Enter" && !event.shiftKey) {
+      event.preventDefault();
+      void this.#submit();
+    }
+  }
+  async #submit() {
+    const content = this.#input.value.trim();
+    if (content === "") {
+      return;
+    }
+    this.appendMessage(MESSAGE_ROLE.USER, content);
+    this.#input.value = "";
+    this.dispatchEvent(
+      new CustomEvent(SUBMIT_EVENT, {
+        detail: { content },
+        bubbles: true,
+        composed: true
+      })
+    );
+    await this.#client_send(content);
+  }
+  async #client_send(content) {
+    if (this.endpoint === "") {
+      return;
+    }
+    await this.#ensureClient().send(content);
+  }
+  #ensureClient() {
+    if (this.#client === null) {
+      const agent = this.agentFactory({
+        endpoint: this.endpoint,
+        headers: this.headers,
+        threadId: this.#threadId,
+        initialMessages: this.#initialMessages
+      });
+      this.#client = new AgUiClient({
+        agent,
+        handlers: this.#handlers(),
+        getTools: () => this.getTools(),
+        getContext: () => this.getContext(),
+        executeTool: (call) => this.#executeTool(call),
+        onPersist: (messages) => this.conversationStore.saveMessages(this.#threadId, messages)
+      });
+    }
+    return this.#client;
+  }
+  async #executeTool(call) {
+    const card = this.#cardFor(call);
+    this.#toolCards.delete(call.id);
+    const tool = this.#resolveTool(call.name);
+    if (tool === null) {
+      card.settle(TOOL_CALL_STATUS.DONE, "Executed on the server.");
+      return null;
+    }
+    if (isDestructive(tool.parameters) && !this.autoConfirm) {
+      const accepted = await requestConfirmation(this.#chat, {
+        toolName: call.name,
+        args: call.args
+      });
+      if (!accepted) {
+        const message = "User declined the action.";
+        card.settle(TOOL_CALL_STATUS.DECLINED, message);
+        return { content: message };
+      }
+    }
+    const navigates = isNavigates(tool.parameters) && this.navigate === null;
+    if (navigates) {
+      this.conversationStore.saveCheckpoint(this.#threadId, { toolCallId: call.id });
+    }
+    try {
+      const result = await tool.handler(call.args);
+      if (navigates) {
+        card.settle(TOOL_CALL_STATUS.DONE, "Navigating\u2026");
+        return { content: "", halt: true };
+      }
+      const content = JSON.stringify(result ?? null);
+      card.settle(TOOL_CALL_STATUS.DONE, content);
+      return { content };
+    } catch (error) {
+      if (navigates) {
+        this.conversationStore.saveCheckpoint(this.#threadId, null);
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      card.settle(TOOL_CALL_STATUS.ERROR, message);
+      return { content: `Error: ${message}`, error: message };
+    }
+  }
+  #handlers() {
+    return {
+      onRunStart: () => {
+        this.#send.disabled = true;
+      },
+      onTextDelta: (buffer) => {
+        this.#streamInto(buffer);
+      },
+      onTextEnd: (buffer) => {
+        this.#streamInto(buffer);
+        this.#streamingBubble = null;
+      },
+      onToolCall: (call) => {
+        this.#cardFor(call);
+      },
+      onRunEnd: () => {
+        this.#send.disabled = false;
+        this.#streamingBubble = null;
+      },
+      onError: (message) => {
+        this.appendMessage(MESSAGE_ROLE.ASSISTANT, `\u26A0\uFE0F ${message}`);
+        this.#send.disabled = false;
+        this.#streamingBubble = null;
+      }
+    };
+  }
+  #streamInto(buffer) {
+    if (this.#streamingBubble === null) {
+      this.#streamingBubble = this.appendMessage(MESSAGE_ROLE.ASSISTANT, "");
+    }
+    this.#streamingBubble.textContent = buffer;
+    this.#messages.scrollTop = this.#messages.scrollHeight;
+  }
+  /**
+   * The card for ``call``, creating and appending it on first sight.
+   *
+   * {@link AgUiClientHandlers.onToolCall} creates the card (pending) during the
+   * run; {@link #executeTool} later retrieves the same card to settle it.
+   */
+  #cardFor(call) {
+    const existing = this.#toolCards.get(call.id);
+    if (existing !== void 0) {
+      return existing;
+    }
+    const card = new ToolCallCard(call.name, call.args);
+    this.#toolCards.set(call.id, card);
+    this.#messages.appendChild(card.element);
+    this.#messages.scrollTop = this.#messages.scrollHeight;
+    return card;
+  }
+};
+
+// src/animations.ts
+var ACCENT = "#4f46e5";
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function typeInto(el, value, options = {}) {
+  const charDelayMs = options.charDelayMs ?? 35;
+  el.value = "";
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+  for (const char of value) {
+    el.value += char;
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+    if (charDelayMs > 0) {
+      await delay(charDelayMs);
+    }
+  }
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+}
+async function highlightThenClick(el, options = {}) {
+  const highlightMs = options.highlightMs ?? 280;
+  const previousOutline = el.style.outline;
+  const previousOffset = el.style.outlineOffset;
+  el.style.outline = `2px solid ${ACCENT}`;
+  el.style.outlineOffset = "2px";
+  await delay(highlightMs);
+  el.style.outline = previousOutline;
+  el.style.outlineOffset = previousOffset;
+  el.click();
+}
+function scrollIntoCenterView(el) {
+  el.scrollIntoView({ block: "center", inline: "nearest", behavior: "smooth" });
+}
+async function focusWithFlash(el, options = {}) {
+  const flashMs = options.flashMs ?? 200;
+  el.focus();
+  const previousShadow = el.style.boxShadow;
+  el.style.boxShadow = `0 0 0 3px rgba(79, 70, 229, 0.4)`;
+  await delay(flashMs);
+  el.style.boxShadow = previousShadow;
+}
+
+// src/define_ag_ui_chat.ts
+function defineAgUiChat() {
+  if (customElements.get(ELEMENT_TAG) === void 0) {
+    customElements.define(ELEMENT_TAG, AgUiChat);
+  }
+}
+
+// src/dom_driver.ts
+async function fillField(el, value, options = {}) {
+  scrollIntoCenterView(el);
+  await focusWithFlash(el, { flashMs: options.flashMs ?? 0 });
+  await typeInto(el, value, options);
+}
+async function clickElement(el, options = {}) {
+  scrollIntoCenterView(el);
+  await highlightThenClick(el, options);
+}
+function setControlValue(el, value) {
+  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 }));
+}
+
+// src/version.ts
+var VERSION = "0.1.0";
+export {
+  AgUiChat,
+  AgUiClient,
+  ClientToolRegistry,
+  ELEMENT_TAG,
+  MAX_TOOL_ROUNDS,
+  MESSAGE_ROLE,
+  SUBMIT_EVENT,
+  SessionStorageStore,
+  TOOL_CALL_STATUS,
+  ToolCallCard,
+  VERSION,
+  X_DESTRUCTIVE_KEY,
+  X_NAVIGATES_KEY,
+  clickElement,
+  createHttpAgent,
+  createPageMapContext,
+  createRouteTools,
+  createStateHookTools,
+  defineAgUiChat,
+  fillField,
+  focusWithFlash,
+  highlightThenClick,
+  isDestructive,
+  isNavigates,
+  requestConfirmation,
+  scrollIntoCenterView,
+  setControlValue,
+  typeInto
+};
+//# sourceMappingURL=index.js.map