@artooi/ag-ui-web-component 0.11.0 → 0.13.0

package/dist/index.js

@@ -2,6 +2,7 @@
 var ELEMENT_TAG = "ag-ui-chat";
 var SUBMIT_EVENT = "ag-ui-submit";
 var TOGGLE_EVENT = "ag-ui-toggle";
+var STATE_EVENT = "ag-ui-state";
 var MESSAGE_ROLE = {
   USER: "user",
   ASSISTANT: "assistant"
@@ -318,6 +319,38 @@ function createPageMapContext(getPageMap, autoInject) {
   return [{ description: "page_map", value: JSON.stringify(getPageMap()) }];
 }
 
+// src/tools/page_state.ts
+function createPageStateTools(binding) {
+  const tools = [
+    {
+      name: `read_${binding.name}`,
+      description: `Read the "${binding.name}" state.`,
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        [X_SUMMARY_KEY]: `Read ${binding.name}`
+      },
+      handler: () => binding.read()
+    }
+  ];
+  const write = binding.write;
+  if (write !== void 0) {
+    tools.push({
+      name: `set_${binding.name}`,
+      description: `Update the "${binding.name}" state.`,
+      parameters: {
+        ...binding.schema ?? { type: "object" },
+        [X_DESTRUCTIVE_KEY]: true,
+        [X_SUMMARY_KEY]: `Update ${binding.name}`
+      },
+      handler: (args) => write(args)
+    });
+  }
+  return tools;
+}
+var createStateHookTools = createPageStateTools;
+
 // src/tools/parse_tool_catalog.ts
 function parseToolCatalog(data) {
   const out = {};
@@ -412,37 +445,6 @@ function createRouteTools(getRouteMap, getNavigate) {
   ];
 }
 
-// src/tools/state_hook.ts
-function createStateHookTools(hook) {
-  const tools = [
-    {
-      name: `read_${hook.name}`,
-      description: `Read the "${hook.name}" state.`,
-      parameters: {
-        type: "object",
-        properties: {},
-        required: [],
-        [X_SUMMARY_KEY]: `Read ${hook.name}`
-      },
-      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,
-        [X_SUMMARY_KEY]: `Update ${hook.name}`
-      },
-      handler: (args) => write(args)
-    });
-  }
-  return tools;
-}
-
 // src/ui/ui_strings.ts
 var DEFAULT_UI_STRINGS = {
   title: "Assistant",
@@ -451,6 +453,11 @@ var DEFAULT_UI_STRINGS = {
   collapse: "Collapse",
   expand: "Expand",
   toggleTheme: "Toggle theme",
+  checkpoints: "Continue a run",
+  noCheckpoints: "Nothing to continue yet.",
+  resumeRun: "Resume",
+  forkRun: "Fork",
+  forkedRun: "branched",
   conversation: "Conversation",
   thinking: "Assistant is thinking\u2026",
   thoughts: "Thoughts",
@@ -841,6 +848,138 @@ function accepts(accept, file) {
   });
 }
 
+// src/ui/relative_time.ts
+function relativeTime(timestamp, now = Date.now(), strings = DEFAULT_UI_STRINGS) {
+  if (!Number.isFinite(timestamp)) {
+    return strings.justNow;
+  }
+  const seconds = Math.round((now - timestamp) / 1e3);
+  if (seconds < 60) {
+    return strings.justNow;
+  }
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) {
+    return strings.minutesAgo.replace("{n}", String(minutes));
+  }
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) {
+    return strings.hoursAgo.replace("{n}", String(hours));
+  }
+  const days = Math.round(hours / 24);
+  if (days < 7) {
+    return strings.daysAgo.replace("{n}", String(days));
+  }
+  return strings.weeksAgo.replace("{n}", String(Math.round(days / 7)));
+}
+
+// src/ui/checkpoint_menu.ts
+var CheckpointMenu = class {
+  /** The panel root. Append to the chat shell; hidden until opened. */
+  element;
+  #onPick;
+  #list;
+  #heading;
+  #strings;
+  #runs = [];
+  constructor(onPick, strings = DEFAULT_UI_STRINGS) {
+    this.#onPick = onPick;
+    this.#strings = strings;
+    this.element = document.createElement("div");
+    this.element.className = "checkpoints";
+    this.element.setAttribute("part", "checkpoints");
+    this.element.setAttribute("role", "dialog");
+    this.element.setAttribute("aria-label", strings.checkpoints);
+    this.element.hidden = true;
+    const header = document.createElement("div");
+    header.className = "checkpoints-header";
+    header.setAttribute("part", "checkpoints-header");
+    this.#heading = document.createElement("span");
+    this.#heading.className = "checkpoints-title";
+    this.#heading.textContent = strings.checkpoints;
+    header.append(this.#heading);
+    this.#list = document.createElement("div");
+    this.#list.className = "checkpoints-list";
+    this.#list.setAttribute("part", "checkpoints-list");
+    this.element.append(header, this.#list);
+    this.element.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") {
+        event.stopPropagation();
+        this.close();
+      }
+    });
+  }
+  /** Replace the rows. The host passes only `continuable` runs. */
+  setRuns(runs) {
+    this.#runs = runs;
+    this.#render();
+  }
+  /** Re-localize a panel built before the host's strings resolved. */
+  setStrings(strings) {
+    this.#strings = strings;
+    this.element.setAttribute("aria-label", strings.checkpoints);
+    this.#heading.textContent = strings.checkpoints;
+    this.#render();
+  }
+  open() {
+    this.element.hidden = false;
+  }
+  close() {
+    this.element.hidden = true;
+  }
+  get open_() {
+    return !this.element.hidden;
+  }
+  #render() {
+    this.#list.replaceChildren();
+    if (this.#runs.length === 0) {
+      const empty = document.createElement("div");
+      empty.className = "checkpoints-empty";
+      empty.setAttribute("part", "checkpoints-empty");
+      empty.textContent = this.#strings.noCheckpoints;
+      this.#list.append(empty);
+      return;
+    }
+    for (const run of this.#runs) {
+      this.#list.append(this.#row(run));
+    }
+  }
+  #row(run) {
+    const row = document.createElement("div");
+    row.className = "checkpoint-row";
+    row.setAttribute("part", "checkpoint-row");
+    const label = document.createElement("span");
+    label.className = "checkpoint-label";
+    label.textContent = run.started_at === null ? run.run_id : relativeTime(Date.parse(run.started_at), Date.now(), this.#strings);
+    label.title = run.run_id;
+    row.append(label);
+    if (run.parent_run_id !== null) {
+      const branch = document.createElement("span");
+      branch.className = "checkpoint-branch";
+      branch.setAttribute("part", "checkpoint-branch");
+      branch.textContent = this.#strings.forkedRun;
+      branch.title = run.parent_run_id;
+      row.append(branch);
+    }
+    row.append(
+      this.#action(run.run_id, "resume", this.#strings.resumeRun),
+      this.#action(run.run_id, "fork", this.#strings.forkRun)
+    );
+    return row;
+  }
+  #action(runId, verb, label) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = `checkpoint-action checkpoint-${verb}`;
+    button.setAttribute("part", `checkpoint-action checkpoint-${verb}`);
+    button.textContent = label;
+    button.addEventListener("click", () => {
+      this.close();
+      this.#onPick(runId, verb);
+    });
+    return button;
+  }
+};
+
 // src/ui/confirmation_card.ts
 function actionButton2(modifier, label) {
   const button = document.createElement("button");
@@ -4952,6 +5091,82 @@ var STYLES = `
   display: none;
 }
 
+.checkpoints {
+  position: absolute;
+  inset-block-start: 3rem;
+  inset-inline: 0.75rem;
+  z-index: 6;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  padding: 0.5rem;
+  border: 1px solid var(--agui-border, #d7d7dc);
+  border-radius: 0.5rem;
+  background: var(--agui-surface, #fff);
+  box-shadow: 0 6px 24px rgb(0 0 0 / 12%);
+  max-height: 60%;
+  overflow-y: auto;
+}
+
+.checkpoints[hidden] {
+  display: none;
+}
+
+.checkpoints-title {
+  font-size: 0.75rem;
+  font-weight: 600;
+  opacity: 0.7;
+}
+
+.checkpoints-empty {
+  padding: 0.5rem 0.25rem;
+  font-size: 0.8125rem;
+  opacity: 0.7;
+}
+
+.checkpoint-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.25rem;
+  border-radius: 0.375rem;
+}
+
+.checkpoint-row:hover {
+  background: var(--agui-hover, #f3f3f5);
+}
+
+.checkpoint-label {
+  flex: 1;
+  font-size: 0.8125rem;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.checkpoint-branch {
+  font-size: 0.6875rem;
+  padding: 0 0.375rem;
+  border-radius: 999px;
+  background: var(--agui-hover, #f3f3f5);
+  opacity: 0.8;
+}
+
+.checkpoint-action {
+  font: inherit;
+  font-size: 0.75rem;
+  cursor: pointer;
+  padding: 0.125rem 0.5rem;
+  border: 1px solid var(--agui-border, #d7d7dc);
+  border-radius: 0.375rem;
+  background: transparent;
+  color: inherit;
+}
+
+.checkpoint-action:hover {
+  background: var(--agui-hover, #f3f3f5);
+}
+
 .drawer-backdrop {
   position: absolute;
   inset: 0;
@@ -5182,30 +5397,6 @@ var ThoughtsBlock = class {
   }
 };
 
-// src/ui/relative_time.ts
-function relativeTime(timestamp, now = Date.now(), strings = DEFAULT_UI_STRINGS) {
-  if (!Number.isFinite(timestamp)) {
-    return strings.justNow;
-  }
-  const seconds = Math.round((now - timestamp) / 1e3);
-  if (seconds < 60) {
-    return strings.justNow;
-  }
-  const minutes = Math.round(seconds / 60);
-  if (minutes < 60) {
-    return strings.minutesAgo.replace("{n}", String(minutes));
-  }
-  const hours = Math.round(minutes / 60);
-  if (hours < 24) {
-    return strings.hoursAgo.replace("{n}", String(hours));
-  }
-  const days = Math.round(hours / 24);
-  if (days < 7) {
-    return strings.daysAgo.replace("{n}", String(days));
-  }
-  return strings.weeksAgo.replace("{n}", String(Math.round(days / 7)));
-}
-
 // src/ui/thread_drawer.ts
 var ThreadDrawer = class {
   /** The drawer root (backdrop + panel). Append to the chat shell; hidden until opened. */
@@ -5728,6 +5919,22 @@ var AgUiClient = class {
     this.#onPersist = config.onPersist ?? (() => {
     });
     this.#connectionLostMessage = config.connectionLostMessage ?? "Connection lost";
+    const onStateChanged = config.onStateChanged;
+    if (onStateChanged !== void 0) {
+      this.#agent.subscribe({
+        onStateChanged: ({ state }) => {
+          onStateChanged(state);
+        }
+      });
+    }
+  }
+  /** The current AG-UI shared state, as the agent last applied it. */
+  get state() {
+    return this.#agent.state;
+  }
+  /** Replace the shared state; the next run sends it as `RunAgentInput.state`. */
+  setState(state) {
+    this.#agent.setState({ ...state });
   }
   /** Whether a run is currently in flight. */
   get running() {
@@ -6125,6 +6332,7 @@ function createHttpAgent(options) {
   return new HttpAgent({
     url: options.endpoint,
     headers: options.headers ?? {},
+    initialState: { ...options.initialState ?? {} },
     // 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
@@ -6256,6 +6464,60 @@ var RemoteConversationStore = class {
   }
 };
 
+// src/core/run_index.ts
+var RunIndex = class {
+  #url;
+  #headers;
+  constructor(url, headers = () => ({})) {
+    this.#url = url.endsWith("/") ? url : `${url}/`;
+    this.#headers = headers;
+  }
+  /**
+   * The user's runs, or `[]` when the endpoint is unreachable or answers with
+   * an error. A history affordance that cannot load is empty, never broken:
+   * the caller renders its empty state rather than surfacing a transport fault
+   * the user can do nothing about.
+   */
+  async list() {
+    try {
+      const response = await fetch(this.#url, {
+        method: "GET",
+        headers: { Accept: "application/json", ...this.#headers() }
+      });
+      if (!response.ok) {
+        return [];
+      }
+      const body = await response.json();
+      return body.runs ?? [];
+    } catch {
+      return [];
+    }
+  }
+  /** The rows a client may actually continue. */
+  async continuable() {
+    return (await this.list()).filter((run) => run.continuable);
+  }
+  /** The endpoint that continues `runId` as a new run. */
+  resumeUrl(runId) {
+    return this.#sibling("resume", runId);
+  }
+  /** The endpoint that branches `runId` into a new run, leaving the source untouched. */
+  forkUrl(runId) {
+    return this.#sibling("fork", runId);
+  }
+  /**
+   * `<mount>/<verb>/<runId>/`, derived from the index URL's own prefix.
+   *
+   * Built by string surgery on the trailing `runs/` rather than with `new URL`,
+   * because the configured value may be root-relative (`/agent/runs/`) — the
+   * common case in a Django template — and `new URL` needs an absolute base.
+   */
+  #sibling(verb, runId) {
+    const prefix = this.#url.slice(0, -"runs/".length);
+    return `${prefix}${verb}/${encodeURIComponent(runId)}/`;
+  }
+};
+
 // src/core/transcribe_audio.ts
 async function transcribeAudio(audio, options) {
   const form = new FormData();
@@ -6404,7 +6666,7 @@ var AgUiChat = class extends HTMLElement {
   /**
    * 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
+   * via {@link registerTool} / {@link registerPageState}; override to supply a
    * fully custom catalog.
    */
   getTools = () => [
@@ -6528,6 +6790,10 @@ var AgUiChat = class extends HTMLElement {
   #title;
   #skillsMenu;
   #drawer;
+  /** Checkpoint panel; rows load only when `data-runs-url` is set. */
+  #checkpoints;
+  /** Built lazily from `data-runs-url`; `null` when the host didn't opt in. */
+  #runIndex = null;
   #skillHint;
   /** File-picker button + hidden input + tray slot; the tray mounts on connect. */
   #attachButton;
@@ -6548,6 +6814,10 @@ var AgUiChat = class extends HTMLElement {
   /** Refs attached to the message currently being sent (the context manifest). */
   #runAttachments = [];
   #client = null;
+  // Seed for the next client. Once one exists it owns the live value (the
+  // agent applies STATE_SNAPSHOT / STATE_DELTA into it), so this is only the
+  // starting point — `sharedState` reads through to the client when present.
+  #sharedState = {};
   // Whether an interaction is in flight (first onRunStart → onSettled). Drives
   // the Send⇄Stop button: `agent.isRunning` is false between frontend-tool
   // rounds, but the user must still be able to stop there.
@@ -6618,6 +6888,70 @@ var AgUiChat = class extends HTMLElement {
         this.#deleteThread(threadId);
       }
     });
+    this.#checkpoints = new CheckpointMenu((runId, verb) => {
+      void this.#continueRun(runId, verb);
+    });
+  }
+  /** The run index, built once from `data-runs-url`; `null` when unset. */
+  #runs() {
+    const url = this.getAttribute("data-runs-url");
+    if (url === null || url === "") {
+      return null;
+    }
+    if (this.#runIndex === null) {
+      this.#runIndex = new RunIndex(url, () => this.headers);
+    }
+    return this.#runIndex;
+  }
+  /**
+   * Continue `runId` as a **new** run, seeded server-side from its snapshot.
+   *
+   * Uses a short-lived agent pointed at the resume / fork endpoint and seeded
+   * with **no** history, so the request carries only the turn typed here — the
+   * contract those endpoints assume, since the server supplies the prior turns
+   * from the snapshot and re-sending them would duplicate. Building a separate
+   * agent makes that structural: the main agent keeps its own history, and
+   * "only the new turn" can't be got wrong by forgetting to clear it. The
+   * fresh `run_id` the endpoints also require comes free — a new agent mints
+   * one per run.
+   *
+   * Handlers are the element's own, so the continuation streams into the same
+   * transcript the user is looking at.
+   */
+  async #continueRun(runId, verb) {
+    const index = this.#runs();
+    if (index === null) {
+      return;
+    }
+    const content = this.#input.value.trim();
+    if (content === "") {
+      return;
+    }
+    this.#input.value = "";
+    const endpoint = verb === "resume" ? index.resumeUrl(runId) : index.forkUrl(runId);
+    const agent = this.agentFactory({
+      endpoint,
+      headers: this.headers,
+      getHeaders: () => this.headers,
+      threadId: this.#threadId,
+      // The seed the endpoints assume: nothing. The snapshot is the history.
+      initialMessages: []
+    });
+    const client = new AgUiClient({
+      agent,
+      handlers: this.#handlers(),
+      getTools: () => this.getTools(),
+      getContext: () => this.getContext(),
+      executeTool: (call) => this.#executeTool(call),
+      resolveInterrupts: (interrupts) => this.#resolveInterrupts(interrupts),
+      connectionLostMessage: this.#strings.connectionLost
+    });
+    await client.send(content);
+  }
+  /** Load the checkpoint panel with the runs that can actually be continued. */
+  async #refreshCheckpoints() {
+    const index = this.#runs();
+    this.#checkpoints.setRuns(index === null ? [] : await index.continuable());
   }
   /** Attributes whose late changes must reflect in already-rendered chrome. */
   static get observedAttributes() {
@@ -6630,12 +6964,40 @@ var AgUiChat = class extends HTMLElement {
   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)) {
+  /**
+   * AG-UI **shared state** for this conversation — the protocol's own state
+   * channel, sent as `RunAgentInput.state` on every run and replaced in place
+   * when the server streams `STATE_SNAPSHOT` / `STATE_DELTA`. Assigning seeds
+   * the next run; reading returns whatever the agent last applied.
+   *
+   * Listen for {@link STATE_EVENT} to react to server-driven changes.
+   *
+   * Not to be confused with {@link registerPageState}, which exposes host
+   * state to the agent as ordinary *tools*.
+   */
+  get sharedState() {
+    return this.#client?.state ?? this.#sharedState;
+  }
+  set sharedState(state) {
+    this.#sharedState = { ...state };
+    this.#client?.setState(this.#sharedState);
+  }
+  /** Bind a piece of host page state to `read_<name>` / `set_<name>` tools. */
+  registerPageState(binding) {
+    for (const tool of createPageStateTools(binding)) {
       this.#toolRegistry.register(tool);
     }
   }
+  /**
+   * @deprecated Renamed to {@link registerPageState}. The old name read as
+   * AG-UI shared-state sync (`STATE_SNAPSHOT` / `STATE_DELTA`), which this
+   * component does not implement — these are ordinary client tools over host
+   * page state. Behaviour is unchanged; this alias will be removed in a future
+   * major.
+   */
+  registerStateHook(binding) {
+    this.registerPageState(binding);
+  }
   /** The built-in `route.*` tools, present only when a route map is set. */
   #routeTools() {
     if (this.routeMap.length === 0) {
@@ -6797,6 +7159,7 @@ var AgUiChat = class extends HTMLElement {
     }
     this.#render();
     this.#drawer.setStrings(this.#strings);
+    this.#checkpoints.setStrings(this.#strings);
     if (this.#readScopedItem(COLLAPSED_KEY) === "1") {
       this.setAttribute("collapsed", "");
     }
@@ -7338,11 +7701,20 @@ Use the read_attachment tool with an id to read a file's contents.`
       void this.#refreshDrawer();
       this.#drawer.open();
     });
+    const checkpoints = this.#headerButton("checkpoints", this.#strings.checkpoints, "\u2B6F");
+    checkpoints.addEventListener("click", () => {
+      void this.#refreshCheckpoints();
+      this.#checkpoints.open();
+    });
     const newChat = this.#headerButton("new", this.#strings.newChat, "\u271A");
     newChat.addEventListener("click", () => this.newChat());
     const collapse = this.#headerButton("collapse", this.#strings.collapse, "\u2014");
     collapse.addEventListener("click", () => this.toggleCollapsed());
-    controls.append(history, newChat);
+    if (this.#runs() !== null) {
+      controls.append(history, checkpoints, newChat);
+    } else {
+      controls.append(history, newChat);
+    }
     if (this.getAttribute("data-theme-toggle") !== null) {
       this.#themeToggle.type = "button";
       this.#themeToggle.className = "header-btn header-btn--theme";
@@ -7419,7 +7791,8 @@ Use the read_attachment tool with an id to read a file's contents.`
       this.#attachSlot,
       inputRow,
       footer,
-      this.#drawer.element
+      this.#drawer.element,
+      this.#checkpoints.element
     );
     this.#rail.className = "rail";
     this.#rail.type = "button";
@@ -7550,7 +7923,8 @@ Use the read_attachment tool with an id to read a file's contents.`
         // re-reads this on each call.
         getHeaders: () => this.headers,
         threadId: this.#threadId,
-        initialMessages: this.#initialMessages
+        initialMessages: this.#initialMessages,
+        initialState: this.#sharedState
       });
       this.#client = new AgUiClient({
         agent,
@@ -7560,11 +7934,23 @@ Use the read_attachment tool with an id to read a file's contents.`
         executeTool: (call) => this.#executeTool(call),
         resolveInterrupts: (interrupts) => this.#resolveInterrupts(interrupts),
         onPersist: (messages) => this.conversationStore.saveMessages(this.#threadId, messages),
+        onStateChanged: (state) => this.#onSharedStateChanged(state),
         connectionLostMessage: this.#strings.connectionLost
       });
     }
     return this.#client;
   }
+  /** Mirror the agent's applied state and tell the host it moved. */
+  #onSharedStateChanged(state) {
+    this.#sharedState = { ...state };
+    this.dispatchEvent(
+      new CustomEvent(STATE_EVENT, {
+        detail: { state: this.#sharedState },
+        bubbles: true,
+        composed: true
+      })
+    );
+  }
   /** Whether ``call`` should be gated behind the confirmation card. */
   async #needsConfirmation(call, tool) {
     if (this.autoConfirm) {
@@ -7870,10 +8256,11 @@ function setControlValue(el, value) {
 }
 
 // src/version.ts
-var VERSION = "0.11.0";
+var VERSION = "0.13.0";
 export {
   AgUiChat,
   AgUiClient,
+  CheckpointMenu,
   ClientToolRegistry,
   ConnectionLostError,
   DEFAULT_UI_STRINGS,
@@ -7882,6 +8269,8 @@ export {
   MESSAGE_ROLE,
   PAGE_ACTIONS,
   RemoteConversationStore,
+  RunIndex,
+  STATE_EVENT,
   SUBMIT_EVENT,
   SessionStorageStore,
   TOGGLE_EVENT,
@@ -7897,6 +8286,7 @@ export {
   createHttpAgent,
   createPageActionTools,
   createPageMapContext,
+  createPageStateTools,
   createRouteTools,
   createStateHookTools,
   defineAgUiChat,