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

package/src/core/create_http_agent.ts

@@ -18,6 +18,12 @@ export interface HttpAgentOptions {
   threadId?: string;
   /** Rehydrated history to seed the agent with (durable conversation). */
   initialMessages?: readonly Message[];
+  /**
+   * AG-UI shared state to seed the agent with. `@ag-ui/client` sends it as
+   * `RunAgentInput.state` on every run and replaces it in place when the
+   * server streams `STATE_SNAPSHOT` / `STATE_DELTA`.
+   */
+  initialState?: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -31,6 +37,7 @@ export function createHttpAgent(options: HttpAgentOptions): AbstractAgent {
   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

package/src/core/run_index.ts

@@ -0,0 +1,91 @@
+/** 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;
+}
+
+/** Live header source, read per request so rotated tokens / CSRF reach the server. */
+type HeadersProvider = () => Record<string, string>;
+
+/**
+ * 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; a run that never reached a provider-valid
+ * boundary has none, so resuming it would start from nothing. Callers should
+ * offer the action only for those rows and treat the rest as informational — a
+ * crashed run worth showing, not worth continuing. {@link continuable} filters
+ * for exactly that.
+ *
+ * **Resume and fork are siblings of the index**, not separate configuration.
+ * django-ag-ui mounts all three under one prefix whenever a step store is
+ * configured (`runs/`, `resume/<id>/`, `fork/<id>/`), so one URL locates them
+ * all and there is no way to configure a half-working set.
+ */
+export class RunIndex {
+  readonly #url: string;
+  readonly #headers: HeadersProvider;
+
+  constructor(url: string, headers: HeadersProvider = () => ({})) {
+    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(): Promise<readonly RunRow[]> {
+    try {
+      const response = await fetch(this.#url, {
+        method: "GET",
+        headers: { Accept: "application/json", ...this.#headers() },
+      });
+      if (!response.ok) {
+        return [];
+      }
+      const body = (await response.json()) as { runs?: readonly RunRow[] };
+      return body.runs ?? [];
+    } catch {
+      return [];
+    }
+  }
+
+  /** The rows a client may actually continue. */
+  async continuable(): Promise<readonly RunRow[]> {
+    return (await this.list()).filter((run) => run.continuable);
+  }
+
+  /** The endpoint that continues `runId` as a new run. */
+  resumeUrl(runId: string): string {
+    return this.#sibling("resume", runId);
+  }
+
+  /** The endpoint that branches `runId` into a new run, leaving the source untouched. */
+  forkUrl(runId: string): string {
+    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: string, runId: string): string {
+    const prefix = this.#url.slice(0, -"runs/".length);
+    return `${prefix}${verb}/${encodeURIComponent(runId)}/`;
+  }
+}

package/src/index.ts

@@ -4,6 +4,7 @@ export {
   ELEMENT_TAG,
   MAX_TOOL_ROUNDS,
   MESSAGE_ROLE,
+  STATE_EVENT,
   SUBMIT_EVENT,
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
@@ -16,6 +17,7 @@ export {
 export {
   AgUiChat,
   type MessageRole,
+  type StateDetail,
   type SubmitDetail,
   type ToggleDetail,
 } from "./core/ag_ui_chat.js";
@@ -45,6 +47,7 @@ export {
 } from "./core/create_http_agent.js";
 export { defineAgUiChat } from "./core/define_ag_ui_chat.js";
 export { RemoteConversationStore } from "./core/remote_conversation_store.js";
+export { RunIndex, type RunRow } from "./core/run_index.js";
 export {
   type TranscribeHandler,
   type TranscribeOptions,
@@ -92,6 +95,16 @@ export {
   type ResolvePageTarget,
 } from "./tools/page_action_tools.js";
 export { createPageMapContext, type PageMap } from "./tools/page_map.js";
+/**
+ * @deprecated Renamed to `createPageStateTools` / `PageState`. The old names
+ * read as AG-UI shared-state sync, which this component does not implement.
+ */
+export {
+  createPageStateTools,
+  createStateHookTools,
+  type PageState,
+  type StateHook,
+} from "./tools/page_state.js";
 export { parseToolCatalog, type ToolCatalogEntry } from "./tools/parse_tool_catalog.js";
 export {
   createRouteTools,
@@ -99,13 +112,13 @@ export {
   type RouteMap,
   type RouteWithParams,
 } from "./tools/route_map.js";
-export { createStateHookTools, type StateHook } from "./tools/state_hook.js";
 export {
   type ApprovalOptions,
   type ApprovalRenderer,
   type ApprovalRequest,
   requestApproval,
 } from "./ui/approval_card.js";
+export { CheckpointMenu, type CheckpointVerb } from "./ui/checkpoint_menu.js";
 export {
   type ConfirmationOptions,
   type ConfirmationRequest,

package/src/tools/page_state.ts

@@ -0,0 +1,72 @@
+import { X_DESTRUCTIVE_KEY, X_SUMMARY_KEY } from "../constants.js";
+import type { ClientTool } from "./client_tool_registry.js";
+
+/**
+ * A binding from a named piece of host page 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.
+ *
+ * This is **not** AG-UI shared state. `STATE_SNAPSHOT` / `STATE_DELTA` are
+ * protocol events carrying state between agent and client; this is a pair of
+ * ordinary client tools the agent calls like any other. The two are unrelated,
+ * which is why this no longer carries the word "hook" — the old name read as
+ * protocol state sync, which this component does not implement.
+ */
+export interface PageState {
+  /** 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 PageState}: always a `read_<name>` (read-only)
+ * tool, plus a `set_<name>` (`x-destructive`) tool when `write` is supplied.
+ */
+export function createPageStateTools(binding: PageState): ClientTool[] {
+  const tools: ClientTool[] = [
+    {
+      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 !== undefined) {
+    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;
+}
+
+/**
+ * @deprecated Renamed to {@link PageState}. The old name read as AG-UI
+ * shared-state sync (`STATE_SNAPSHOT` / `STATE_DELTA`), which this component
+ * does not implement. Will be removed in a future major.
+ */
+export type StateHook = PageState;
+
+/**
+ * @deprecated Renamed to {@link createPageStateTools}. Will be removed in a
+ * future major.
+ */
+export const createStateHookTools = createPageStateTools;

package/src/ui/checkpoint_menu.ts

@@ -0,0 +1,153 @@
+import type { RunRow } from "../core/run_index.js";
+import { relativeTime } from "./relative_time.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
+/** How the host continues a picked run. */
+export type CheckpointVerb = "resume" | "fork";
+
+/**
+ * The checkpoint panel: continuable runs, each offering **resume** or **fork**.
+ *
+ * A separate surface from the thread drawer on purpose — they are different
+ * axes. A thread is a conversation you switch *to*; a checkpoint is a run you
+ * continue *from*, and one thread can hold many. Folding them into one list
+ * would make "resume" look like "open", which it isn't: resuming starts a new
+ * run seeded from a snapshot.
+ *
+ * Only rows the server marked `continuable` are worth offering, so the host
+ * feeds those; a run with no snapshot would resume from nothing. Pure DOM in
+ * the spirit of {@link SkillsMenu} — the host appends {@link element}, toggles
+ * it, feeds rows via {@link setRuns}, and acts on {@link onPick}.
+ */
+export class CheckpointMenu {
+  /** The panel root. Append to the chat shell; hidden until opened. */
+  readonly element: HTMLDivElement;
+
+  readonly #onPick: (runId: string, verb: CheckpointVerb) => void;
+  readonly #list: HTMLDivElement;
+  readonly #heading: HTMLSpanElement;
+  #strings: UiStrings;
+  #runs: readonly RunRow[] = [];
+
+  constructor(
+    onPick: (runId: string, verb: CheckpointVerb) => void,
+    strings: UiStrings = 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: readonly RunRow[]): void {
+    this.#runs = runs;
+    this.#render();
+  }
+
+  /** Re-localize a panel built before the host's strings resolved. */
+  setStrings(strings: UiStrings): void {
+    this.#strings = strings;
+    this.element.setAttribute("aria-label", strings.checkpoints);
+    this.#heading.textContent = strings.checkpoints;
+    this.#render();
+  }
+
+  open(): void {
+    this.element.hidden = false;
+  }
+
+  close(): void {
+    this.element.hidden = true;
+  }
+
+  get open_(): boolean {
+    return !this.element.hidden;
+  }
+
+  #render(): void {
+    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: RunRow): HTMLDivElement {
+    const row = document.createElement("div");
+    row.className = "checkpoint-row";
+    row.setAttribute("part", "checkpoint-row");
+
+    const label = document.createElement("span");
+    label.className = "checkpoint-label";
+    // A run id is opaque to a person, so the time is the identifying detail;
+    // the id rides `title` for anyone who needs to correlate with server logs.
+    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) {
+      // Lineage, so a branch doesn't read as a duplicate of its parent.
+      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: string, verb: CheckpointVerb, label: string): HTMLButtonElement {
+    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;
+  }
+}

package/src/ui/styles.ts

@@ -1229,6 +1229,82 @@ export const 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;

package/src/ui/ui_strings.ts

@@ -157,6 +157,16 @@ export interface UiStrings {
   minutesAgo: string;
   /** Hours ago. Token: `{n}`. */
   hoursAgo: string;
+  /** Title of the checkpoint panel. */
+  checkpoints: string;
+  /** Empty state when no run can be continued. */
+  noCheckpoints: string;
+  /** Action: continue a run from its last checkpoint. */
+  resumeRun: string;
+  /** Action: branch a run without touching the original. */
+  forkRun: string;
+  /** Badge on a run that branched from another. */
+  forkedRun: string;
   /** Days ago. Token: `{n}`. */
   daysAgo: string;
   /** Weeks ago. Token: `{n}`. */
@@ -171,6 +181,11 @@ export const DEFAULT_UI_STRINGS: UiStrings = {
   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…",

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.11.0";
+export const VERSION: string = "0.13.0";

package/dist/tools/state_hook.d.ts

@@ -1,23 +0,0 @@
-import type { ClientTool } from "./client_tool_registry.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 declare function createStateHookTools(hook: StateHook): ClientTool[];
-//# sourceMappingURL=state_hook.d.ts.map

package/dist/tools/state_hook.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"state_hook.d.ts","sourceRoot":"","sources":["../../src/tools/state_hook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAC5D,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,EAAE,CA4BlE"}

package/src/tools/state_hook.ts

@@ -1,53 +0,0 @@
-import { X_DESTRUCTIVE_KEY, X_SUMMARY_KEY } from "../constants.js";
-import type { ClientTool } from "./client_tool_registry.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: [],
-        [X_SUMMARY_KEY]: `Read ${hook.name}`,
-      },
-      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,
-        [X_SUMMARY_KEY]: `Update ${hook.name}`,
-      },
-      handler: (args) => write(args),
-    });
-  }
-  return tools;
-}