@artooi/ag-ui-web-component 0.10.0 → 0.12.0

package/src/core/ag_ui_chat.ts

@@ -1,4 +1,4 @@
-import type { Context, Message, Tool } from "@ag-ui/core";
+import type { Context, Interrupt, Message, Tool } from "@ag-ui/core";
 import {
   DEFAULT_ATTACHMENT_MAX_BYTES,
   MESSAGE_ROLE,
@@ -20,10 +20,21 @@ import { createPageMapContext, type PageMap } from "../tools/page_map.js";
 import { parseToolCatalog } from "../tools/parse_tool_catalog.js";
 import { createRouteTools, type RouteMap } from "../tools/route_map.js";
 import { createStateHookTools, type StateHook } from "../tools/state_hook.js";
+import {
+  type ApprovalRenderer,
+  type ApprovalRequest,
+  requestApproval,
+} from "../ui/approval_card.js";
 import { renderAttachmentChips } from "../ui/attachment_chips.js";
 import { AttachmentTray } from "../ui/attachment_tray.js";
+import { CheckpointMenu, type CheckpointVerb } from "../ui/checkpoint_menu.js";
 import { type ConfirmationRequest, requestConfirmation } from "../ui/confirmation_card.js";
 import { prettifyToolName } from "../ui/prettify_tool_name.js";
+import {
+  type QuestionRenderer,
+  type QuestionRequest,
+  requestQuestion,
+} from "../ui/question_card.js";
 import { renderMarkdown } from "../ui/render_markdown.js";
 import { wrapWords } from "../ui/reveal_words.js";
 import { SkillsMenu } from "../ui/skills_menu.js";
@@ -37,6 +48,7 @@ import {
   AgUiClient,
   type AgUiClientHandlers,
   type AgUiToolCall,
+  type InterruptResponse,
   type ToolExecution,
 } from "./agui_client.js";
 import { type AttachmentRef, messageAttachments } from "./attachment.js";
@@ -47,6 +59,7 @@ import {
 } from "./conversation_store.js";
 import { type AgentFactory, createHttpAgent } from "./create_http_agent.js";
 import { RemoteConversationStore } from "./remote_conversation_store.js";
+import { RunIndex } from "./run_index.js";
 import { type TranscribeHandler, transcribeAudio } from "./transcribe_audio.js";
 import { type UploadHandler, uploadAttachment } from "./upload_attachment.js";
 
@@ -101,6 +114,36 @@ export class AgUiChat extends HTMLElement {
   /** When true, destructive tools execute without a confirmation modal. */
   autoConfirm = false;
 
+  /**
+   * When true, the built-in `ask_user` frontend tool is offered to the agent:
+   * calling it renders an inline question card (radio choices and/or a free-text
+   * field) and returns the user's answer. Off by default — like the other
+   * built-in tool groups (route / page-action), it is opt-in so it doesn't
+   * change the advertised catalog until a host asks for it.
+   */
+  askUser = false;
+
+  /**
+   * Optional full replacement for the `ask_user` question UI. When set, calling
+   * `ask_user` invokes this instead of the built-in inline card: the host
+   * renders whatever it likes (a native modal, a framework component, …) and
+   * resolves with the answer. Unset (default) uses the built-in
+   * {@link requestQuestion} card — style that via the `strings` override and the
+   * `question*` CSS `::part()`s. Requires {@link askUser} to be enabled.
+   */
+  askUserRenderer: QuestionRenderer | null = null;
+
+  /**
+   * Optional full replacement for the server-side-tool approval UI. When set, an
+   * approval interrupt invokes this instead of the built-in inline approval
+   * card: the host renders whatever it likes and resolves `true` to approve /
+   * `false` to deny. Unset (default) uses the built-in {@link requestApproval}
+   * card — style that via the `strings` override and the `approval*` CSS
+   * `::part()`s. The gate itself is enabled server-side; this only changes how
+   * the decision is collected.
+   */
+  approvalRenderer: ApprovalRenderer | null = null;
+
   /**
    * Optional per-call confirmation predicate. When set, it is authoritative:
    * given a tool name + args it decides whether *this* call needs confirmation
@@ -254,6 +297,10 @@ export class AgUiChat extends HTMLElement {
   readonly #title: HTMLSpanElement;
   readonly #skillsMenu: SkillsMenu;
   readonly #drawer: ThreadDrawer;
+  /** Checkpoint panel; rows load only when `data-runs-url` is set. */
+  readonly #checkpoints: CheckpointMenu;
+  /** Built lazily from `data-runs-url`; `null` when the host didn't opt in. */
+  #runIndex: RunIndex | null = null;
   readonly #skillHint: HTMLDivElement;
   /** File-picker button + hidden input + tray slot; the tray mounts on connect. */
   readonly #attachButton: HTMLButtonElement;
@@ -346,6 +393,73 @@ export class AgUiChat 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(): RunIndex | null {
+    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: string, verb: CheckpointVerb): Promise<void> {
+    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(): Promise<void> {
+    const index = this.#runs();
+    this.#checkpoints.setRuns(index === null ? [] : await index.continuable());
   }
 
   /** Attributes whose late changes must reflect in already-rendered chrome. */
@@ -430,9 +544,84 @@ export class AgUiChat extends HTMLElement {
     return createPageActionTools(enabled, (target) => this.resolvePageTarget(target));
   }
 
-  /** All built-in (route + page + page-action) frontend tools. */
+  /** All built-in (route + page + page-action + ask_user) frontend tools. */
   #builtinTools(): ClientTool[] {
-    return [...this.#routeTools(), ...this.#pageTools(), ...this.#pageActionTools()];
+    return [
+      ...this.#routeTools(),
+      ...this.#pageTools(),
+      ...this.#pageActionTools(),
+      ...this.#askUserTool(),
+    ];
+  }
+
+  /**
+   * The built-in `ask_user` frontend tool, or `[]` when {@link askUser} is off.
+   *
+   * A generic "ask the user a typed question" primitive: the agent calls it, the
+   * client executes it locally via the normal frontend-tool path (rendering a
+   * {@link requestQuestion} card), and the chosen/typed answer flows back as the
+   * tool result — no new protocol, reusing the machinery already in place.
+   */
+  #askUserTool(): ClientTool[] {
+    if (!this.askUser) {
+      return [];
+    }
+    return [
+      {
+        name: "ask_user",
+        description:
+          "Ask the user a question and wait for their answer. Provide `options` for a " +
+          "multiple-choice prompt; set `allow_custom` to also accept a free-text answer.",
+        parameters: {
+          type: "object",
+          properties: {
+            question: { type: "string", description: "The question to ask the user." },
+            options: {
+              type: "array",
+              items: { type: "string" },
+              description: "Preset choices offered as radio buttons.",
+            },
+            allow_custom: {
+              type: "boolean",
+              description: "Allow a free-text answer in addition to any options.",
+            },
+          },
+          required: ["question"],
+        },
+        handler: (args) => this.#askUser(args),
+      },
+    ];
+  }
+
+  /** Render the `ask_user` question card and resolve with the user's answer. */
+  async #askUser(args: Record<string, unknown>): Promise<string> {
+    const question = typeof args["question"] === "string" ? args["question"] : "";
+    const request: QuestionRequest = { question };
+    const rawOptions = args["options"];
+    if (Array.isArray(rawOptions)) {
+      request.options = rawOptions.filter((option): option is string => typeof option === "string");
+    }
+    if (args["allow_custom"] === true) {
+      request.allowCustom = true;
+    }
+    // The run is suspended on the card; a Stop aborts the controller, resolving
+    // it with an empty answer (the run is then cancelled).
+    this.#confirmAbort = new AbortController();
+    const signal = this.#confirmAbort.signal;
+    this.#hidePending();
+    // A host-supplied renderer takes full control of the UI; otherwise the
+    // built-in inline card renders into the current answer group.
+    const answer =
+      this.askUserRenderer !== null
+        ? await this.askUserRenderer(request, { signal })
+        : await requestQuestion(this.#ensureGroup(), request, {
+            signal,
+            strings: this.#strings,
+          });
+    this.#confirmAbort = null;
+    this.#updateEmptyState();
+    this.#messages.scrollTop = this.#messages.scrollHeight;
+    return answer;
   }
 
   /** Resolve a tool by name: built-in tools first, then the registry. */
@@ -494,6 +683,7 @@ export class AgUiChat extends HTMLElement {
     }
     this.#render();
     this.#drawer.setStrings(this.#strings);
+    this.#checkpoints.setStrings(this.#strings);
     if (this.#readScopedItem(COLLAPSED_KEY) === "1") {
       this.setAttribute("collapsed", "");
     }
@@ -1113,13 +1303,28 @@ export class AgUiChat extends HTMLElement {
       this.#drawer.open();
     });
 
+    const checkpoints = this.#headerButton("checkpoints", this.#strings.checkpoints, "⭯");
+    checkpoints.addEventListener("click", () => {
+      void this.#refreshCheckpoints();
+      this.#checkpoints.open();
+    });
+
     const newChat = this.#headerButton("new", this.#strings.newChat, "✚");
     newChat.addEventListener("click", () => this.newChat());
 
     const collapse = this.#headerButton("collapse", this.#strings.collapse, "—");
     collapse.addEventListener("click", () => this.toggleCollapsed());
 
-    controls.append(history, newChat);
+    // Only offered when the server actually indexes runs — without
+    // `data-runs-url` there is nothing to continue and the button would open
+    // a permanently empty panel. Asks `#runs()` rather than re-testing the
+    // attribute, so "configured" means one thing everywhere (an empty value
+    // is unset, not a relative URL to the current page).
+    if (this.#runs() !== null) {
+      controls.append(history, checkpoints, newChat);
+    } else {
+      controls.append(history, newChat);
+    }
     // Optional built-in theme toggle: off unless the host opts in, so
     // it never competes with a host-supplied switch in `slot="header-actions"`.
     if (this.getAttribute("data-theme-toggle") !== null) {
@@ -1180,6 +1385,7 @@ export class AgUiChat extends HTMLElement {
     });
 
     this.#skillHint.className = "skill-hint";
+    this.#skillHint.setAttribute("part", "skill-hint");
     this.#skillHint.hidden = true;
 
     // File-upload affordance: a 📎 button (hidden until `data-attachments-url`
@@ -1222,6 +1428,7 @@ export class AgUiChat extends HTMLElement {
       inputRow,
       footer,
       this.#drawer.element,
+      this.#checkpoints.element,
     );
 
     // The collapsed-sidebar rail: a slim edge strip (the expand affordance),
@@ -1388,6 +1595,7 @@ export class AgUiChat extends HTMLElement {
         getTools: () => this.getTools(),
         getContext: () => this.getContext(),
         executeTool: (call) => this.#executeTool(call),
+        resolveInterrupts: (interrupts) => this.#resolveInterrupts(interrupts),
         onPersist: (messages) => this.conversationStore.saveMessages(this.#threadId, messages),
         connectionLostMessage: this.#strings.connectionLost,
       });
@@ -1478,6 +1686,57 @@ export class AgUiChat extends HTMLElement {
     }
   }
 
+  /**
+   * Render an approval card per server-side-tool interrupt and collect the
+   * user's decisions (approve → run it, deny → decline it).
+   *
+   * The run is suspended on these cards; a Stop while any is open aborts the
+   * shared {@link #confirmAbort} controller, resolving every still-open card as
+   * denied (and the client loop then sees the cancellation and stops). An
+   * approved tool runs on the follow-up (resume) run and streams its result
+   * back into the same pending card; a denied one is settled here, since no
+   * result will ever arrive for it.
+   */
+  async #resolveInterrupts(
+    interrupts: readonly Interrupt[],
+  ): Promise<Record<string, InterruptResponse>> {
+    const responses: Record<string, InterruptResponse> = {};
+    // One controller covers the whole batch: a single Stop denies all of them.
+    this.#confirmAbort = new AbortController();
+    this.#hidePending();
+    for (const interrupt of interrupts) {
+      const request: ApprovalRequest = {};
+      if (interrupt.message !== undefined) {
+        request.message = interrupt.message;
+      }
+      const card =
+        interrupt.toolCallId !== undefined ? this.#toolCards.get(interrupt.toolCallId) : undefined;
+      const toolName = card?.element.getAttribute("data-tool-name");
+      if (toolName !== null && toolName !== undefined) {
+        request.toolName = toolName;
+      }
+      const signal = this.#confirmAbort.signal;
+      // A host-supplied renderer takes full control of the approval UI;
+      // otherwise the built-in inline card renders into the current answer group.
+      const approved =
+        this.approvalRenderer !== null
+          ? await this.approvalRenderer(request, { signal })
+          : await requestApproval(this.#ensureGroup(), request, { signal, strings: this.#strings });
+      this.#updateEmptyState();
+      this.#messages.scrollTop = this.#messages.scrollHeight;
+      if (approved) {
+        responses[interrupt.id] = { status: "resolved", payload: { approved: true } };
+      } else {
+        responses[interrupt.id] = { status: "cancelled" };
+        // No TOOL_CALL_RESULT will stream for a denied tool — settle its pending
+        // card now rather than leaving it hanging until the onSettled sweep.
+        card?.settle(TOOL_CALL_STATUS.DECLINED, this.#strings.declinedAction);
+      }
+    }
+    this.#confirmAbort = null;
+    return responses;
+  }
+
   #handlers(): AgUiClientHandlers {
     return {
       onRunStart: () => {

package/src/core/agui_client.ts

@@ -1,5 +1,11 @@
-import { type AbstractAgent, type AgentSubscriber, randomUUID } from "@ag-ui/client";
-import type { Context, Message, Tool } from "@ag-ui/core";
+import {
+  type AbstractAgent,
+  type AgentSubscriber,
+  buildResumeArray,
+  type RunAgentParameters,
+  randomUUID,
+} from "@ag-ui/client";
+import type { Context, Interrupt, Message, ResumeEntry, Tool } from "@ag-ui/core";
 import { MAX_TOOL_ROUNDS } from "../constants.js";
 import type { AttachmentRef } from "./attachment.js";
 
@@ -33,6 +39,27 @@ export interface ToolExecution {
  */
 export type ExecuteTool = (call: AgUiToolCall) => Promise<ToolExecution | null>;
 
+/**
+ * One user decision for a server-side-tool approval interrupt. Structurally
+ * matches `@ag-ui/client`'s (non-exported) `ResumeResponse`, the payload
+ * {@link buildResumeArray} turns into a `ResumeEntry`: `resolved` approves (with
+ * an optional `payload`, e.g. `{ approved: true }`), `cancelled` denies.
+ */
+export type InterruptResponse = { status: "resolved"; payload?: unknown } | { status: "cancelled" };
+
+/**
+ * Resolves the approval interrupts a run finished on, keyed by interrupt id.
+ *
+ * When a gated **server-side** tool defers instead of executing, the run
+ * finishes on an AG-UI interrupt outcome; the host renders an approval card per
+ * interrupt and returns each decision here, and the loop resumes the run with
+ * the answers. Omit for agents that never gate server-side tools — an
+ * unresolved interrupt then simply ends the loop.
+ */
+export type ResolveInterrupts = (
+  interrupts: readonly Interrupt[],
+) => Promise<Record<string, InterruptResponse>>;
+
 /**
  * Callbacks the {@link AgUiClient} invokes as a run progresses. The host
  * (the `<ag-ui-chat>` element) implements these to render streaming text and
@@ -93,6 +120,11 @@ export interface AgUiClientConfig extends AgUiRunInputs {
   handlers: AgUiClientHandlers;
   /** Executes frontend tool calls. Omit for server-only tool sets. */
   executeTool?: ExecuteTool;
+  /**
+   * Resolves server-side-tool approval interrupts. Omit when no server-side
+   * tool is gated for approval — an interrupt then ends the loop unanswered.
+   */
+  resolveInterrupts?: ResolveInterrupts;
   /**
    * Invoked with the latest history whenever it changes, so the host can
    * persist it for durability across page reloads. Omit to keep the
@@ -134,6 +166,7 @@ export class AgUiClient {
   readonly #getTools: () => Tool[];
   readonly #getContext: () => Context[];
   readonly #executeTool: ExecuteTool | null;
+  readonly #resolveInterrupts: ResolveInterrupts | null;
   readonly #onPersist: (messages: readonly Message[]) => void;
   readonly #connectionLostMessage: string;
   // Set by cancel(); reset at the top of each #run(). Checked by the loop so
@@ -146,6 +179,7 @@ export class AgUiClient {
     this.#getTools = config.getTools ?? (() => []);
     this.#getContext = config.getContext ?? (() => []);
     this.#executeTool = config.executeTool ?? null;
+    this.#resolveInterrupts = config.resolveInterrupts ?? null;
     this.#onPersist = config.onPersist ?? (() => {});
     this.#connectionLostMessage = config.connectionLostMessage ?? "Connection lost";
   }
@@ -241,6 +275,11 @@ export class AgUiClient {
   }
 
   async #runLoop(): Promise<void> {
+    // Carries the resolved approval answers into the *next* run when a round
+    // finished on a server-side-tool interrupt. Distinct from the public
+    // resume() navigation-reload path (which continues an unfinished
+    // frontend-tool round after a page load) — this stays inside one #run().
+    let resume: ResumeEntry[] | undefined;
     for (let round = 0; round < MAX_TOOL_ROUNDS; round += 1) {
       // A cancel during the previous round's frontend-tool execution lands
       // here: the running handler completed, but no further round starts.
@@ -248,11 +287,16 @@ export class AgUiClient {
         return;
       }
       const pending: AgUiToolCall[] = [];
-      const runState = { terminal: false, errored: false };
-      await this.#agent.runAgent(
-        { tools: this.#getTools(), context: this.#getContext() },
-        this.#buildSubscriber(pending, runState),
-      );
+      const runState: RunState = { terminal: false, errored: false, interrupts: [] };
+      const params: RunAgentParameters = {
+        tools: this.#getTools(),
+        context: this.#getContext(),
+      };
+      if (resume !== undefined) {
+        params.resume = resume;
+      }
+      await this.#agent.runAgent(params, this.#buildSubscriber(pending, runState));
+      resume = undefined;
       this.#onPersist(this.#agent.messages);
       // Cancelled mid-stream: the user said stop — don't execute the tool
       // calls collected before the abort.
@@ -272,6 +316,22 @@ export class AgUiClient {
       if (runState.errored) {
         return;
       }
+      // A gated server-side tool deferred instead of executing: the run finished
+      // on an interrupt outcome. Ask the host to resolve each interrupt, then
+      // re-enter the loop carrying the answers — the follow-up run runs or denies
+      // the tool (its result streams back as TOOL_CALL_RESULT). Takes precedence
+      // over the frontend-tool sweep below: a server-side tool isn't ours to run.
+      if (runState.interrupts.length > 0) {
+        if (this.#resolveInterrupts === null) {
+          return;
+        }
+        const responses = await this.#resolveInterrupts(runState.interrupts);
+        if (this.#cancelled) {
+          return;
+        }
+        resume = buildResumeArray(runState.interrupts, responses);
+        continue;
+      }
       if (this.#executeTool === null || pending.length === 0) {
         return;
       }
@@ -301,10 +361,7 @@ export class AgUiClient {
     }
   }
 
-  #buildSubscriber(
-    pending: AgUiToolCall[],
-    runState: { terminal: boolean; errored: boolean },
-  ): AgentSubscriber {
+  #buildSubscriber(pending: AgUiToolCall[], runState: RunState): AgentSubscriber {
     const h = this.#handlers;
     return {
       onRunInitialized() {
@@ -340,6 +397,16 @@ export class AgUiClient {
       onReasoningEndEvent() {
         h.onReasoningEnd();
       },
+      onRunFinishedEvent(params) {
+        // RUN_FINISHED is terminal for both a normal finish and an interrupt.
+        // Capturing the interrupts here (rather than reading the agent's
+        // `pendingInterrupts` field afterwards) keeps the loop self-contained
+        // and independent of that field's cross-run clearing semantics.
+        runState.terminal = true;
+        if (params.outcome === "interrupt") {
+          runState.interrupts = params.interrupts;
+        }
+      },
       onRunErrorEvent({ event }) {
         runState.terminal = true;
         runState.errored = true;
@@ -353,6 +420,14 @@ export class AgUiClient {
   }
 }
 
+/** Per-run mutable flags the subscriber writes and {@link AgUiClient} reads. */
+interface RunState {
+  terminal: boolean;
+  errored: boolean;
+  /** Approval interrupts a run finished on (empty for a normal finish). */
+  interrupts: Interrupt[];
+}
+
 /**
  * Whether a rejection came from aborting the run's fetch. Belt-and-suspenders
  * with the `#cancelled` flag: some `@ag-ui/client` versions re-throw the

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

@@ -27,6 +27,8 @@ export {
   type AgUiToolCall,
   ConnectionLostError,
   type ExecuteTool,
+  type InterruptResponse,
+  type ResolveInterrupts,
   type ToolExecution,
 } from "./core/agui_client.js";
 export { type AttachmentRef, messageAttachments } from "./core/attachment.js";
@@ -43,6 +45,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,
@@ -98,12 +101,25 @@ export {
   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,
   requestConfirmation,
 } from "./ui/confirmation_card.js";
 export { prettifyToolName } from "./ui/prettify_tool_name.js";
+export {
+  type QuestionOptions,
+  type QuestionRenderer,
+  type QuestionRequest,
+  requestQuestion,
+} from "./ui/question_card.js";
 export { type RenderMarkdownOptions, renderMarkdown } from "./ui/render_markdown.js";
 export {
   type SettledStatus,