@artooi/agents-web-components 0.0.0-stage → 0.1.1

package/src/core/run_handlers.ts

@@ -0,0 +1,524 @@
+import {
+  CUSTOM_AGENT_EVENT,
+  INVALIDATE_CUSTOM_NAME,
+  INVALIDATE_EVENT,
+  MESSAGE_ROLE,
+  RUN_FINISHED_EVENT,
+  SUBAGENT_CUSTOM_NAME,
+  TOOL_CALL_STATUS,
+} from "../constants.js";
+import { attachCopyButtons } from "../ui/excerpts/attach_copy_buttons.js";
+import type { RunAnnouncer } from "../ui/progress/run_announcer.js";
+import type { SubAgentProgress } from "../ui/progress/subagent_progress.js";
+import type { AnswerActions } from "../ui/transcript/answer_actions.js";
+import type { AnswerStream } from "../ui/transcript/answer_stream.js";
+import type { Transcript } from "../ui/transcript/transcript.js";
+import type { UiStrings } from "../ui/ui_strings.js";
+import type { ActivityRegistry } from "./activity_registry.js";
+import type { AgUiClientHandlers } from "./agui_client.js";
+import type { CustomAgentDetail } from "./events/custom_agent_detail.js";
+import type { InvalidateDetail } from "./events/invalidate_detail.js";
+import type { RunFinishedDetail } from "./events/run_finished_detail.js";
+import type { ToolRun } from "./events/tool_run.js";
+import type { MessageRole } from "./message_role.js";
+import { toolStatusFromOutcome } from "./tool_outcome.js";
+
+/** What the run's event handlers need from the element that owns them. */
+export interface RunHandlersHost {
+  /** The custom element, which the run's events are dispatched on. */
+  readonly element: HTMLElement;
+  /** The transcript the run draws into. */
+  readonly transcript: Transcript;
+  /** The answer streaming into its bubble. */
+  readonly stream: AnswerStream;
+  /** The action row under each finished answer. */
+  readonly actions: AnswerActions;
+  /** The activity renderers, and the blocks they drew. */
+  readonly activities: ActivityRegistry;
+  /** A delegated sub-agent's progress, on the card that delegated. */
+  readonly subagents: SubAgentProgress;
+  /** The screen-reader status region. */
+  readonly announcer: RunAnnouncer;
+  /** The resolved string table. */
+  readonly strings: () => UiStrings;
+  /** Whether an interaction is already in flight, which the composer owns. */
+  readonly running: () => boolean;
+  /** Swap the composer between Send and Stop; settling sends a queued turn. */
+  readonly setRunning: (running: boolean) => void;
+  /** The element's `appendMessage`, which a failed run's bubble opens through. */
+  readonly appendMessage: (role: MessageRole, content: string) => HTMLDivElement;
+  /** Note an assistant answer finished on `threadId`, which may be unseen. */
+  readonly noteUnread: (threadId: string) => void;
+}
+
+/**
+ * What one conversation's runs accumulate for the host between an
+ * interaction's first round and its settle.
+ *
+ * A record per conversation rather than fields on the controller, because a
+ * run can outlive the conversation it belongs to. Cancelling is a request, not
+ * an ending: a stopped run reports how it ended once its request has closed --
+ * or once a host tool's handler, which cancelling cannot interrupt, has
+ * returned -- and by then New chat may have cleared the transcript and the next
+ * message may already be running. Each handler table keeps the record it was
+ * built with, so that report describes the run that made it and nothing the
+ * next conversation did.
+ */
+interface RunLedger {
+  /**
+   * Tool calls made during the current interaction, in the order they started,
+   * so {@link RUN_FINISHED_EVENT} can report them once the whole thing settles.
+   * Spans tool rounds and an approval interrupt; emptied when the event fires.
+   */
+  readonly tools: { readonly id: string; readonly name: string }[];
+  /**
+   * Which of those calls had a result streamed back, and so ran on the server.
+   *
+   * Kept here rather than read from the transcript's cards, because New chat
+   * clears the transcript and a run it cut off reports afterwards: a booking
+   * the server made would come out as the host's own tool, which is the one
+   * side the documented listener skips a refetch for.
+   */
+  readonly serverSettled: Set<string>;
+  /**
+   * Keys announced during this interaction, de-duplicated in first-seen order.
+   *
+   * Per element, never module-level: a second mounted chat is a second run, and
+   * sharing this would tell one page to refetch on the other's writes. Emptied
+   * by {@link RunHandlers.#dispatchRunFinished}, which is the one place that has
+   * read it.
+   */
+  readonly invalidated: Set<string>;
+  /**
+   * Whether this turn already announced how it ended.
+   *
+   * `onSettled` is the terminal guarantee and fires however the run ended, so
+   * it is the only place that can promise the user hears *something*. But a
+   * stopped or failed run has already said the truer thing from `onCancelled`
+   * or `onError`, and "assistant answered" after "response stopped" is worse
+   * than silence.
+   */
+  announcedOutcome: boolean;
+  /** How the interaction ended so far; read and reset when the run-finished event fires. */
+  outcome: RunFinishedDetail["outcome"];
+}
+
+/** An empty ledger, for a conversation nothing has run in yet. */
+function emptyLedger(): RunLedger {
+  return {
+    tools: [],
+    serverSettled: new Set<string>(),
+    invalidated: new Set<string>(),
+    announcedOutcome: false,
+    outcome: "completed",
+  };
+}
+
+/** Handlers with the same signatures as `table`, each doing nothing once `attached` is false. */
+function whileAttached<T extends object>(table: T, attached: () => boolean): T {
+  const guarded: Record<string, (...args: unknown[]) => void> = {};
+  for (const [name, handler] of Object.entries(table) as [string, (...args: unknown[]) => void][]) {
+    guarded[name] = (...args) => {
+      if (attached()) {
+        handler(...args);
+      }
+    };
+  }
+  return guarded as T;
+}
+
+/**
+ * The AG-UI event handlers a run is drawn by, and what one interaction
+ * accumulates for the host between its first round and its settle: the tool
+ * calls it made, the keys it invalidated, and whether it already said how it
+ * ended.
+ *
+ * A controller rather than a factory. The handlers hold nothing of their own,
+ * but that bookkeeping is state, and it has never belonged to one handler
+ * table: a table is built per client -- the conversation's own, rebuilt after
+ * a reset, and one for each checkpoint continuation -- and every table built
+ * for one conversation reports into the same bookkeeping. {@link forClient}
+ * still returns a fresh table per call.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class RunHandlers {
+  readonly #host: RunHandlersHost;
+  /**
+   * The bookkeeping of the conversation on screen. Replaced rather than
+   * emptied by {@link detach}, so a table built before then keeps its own.
+   */
+  #ledger: RunLedger = emptyLedger();
+
+  constructor(host: RunHandlersHost) {
+    this.#host = host;
+  }
+
+  /**
+   * Detach every handler table built so far, because the conversation they
+   * drew into has been cleared away.
+   *
+   * The element calls this when it resets, having first cancelled what was
+   * running. A cancelled run still ends later, and a detached table still
+   * reports to the host what that run did: a run stopped part-way may already
+   * have written something, and {@link RUN_FINISHED_EVENT} fires on
+   * cancellation for exactly that reason. Everything else it would do -- draw a
+   * stopped note, announce, put the composer back to Send, settle the pending
+   * cards -- would land in a transcript and a composer that now belong to
+   * another conversation, possibly mid-run, and is dropped. So is any event the
+   * run streams after the reset, invalidations included: an abort closes the
+   * request those would arrive on, so what a cancelled run still delivers is
+   * how it ended.
+   */
+  detach(): void {
+    this.#ledger = emptyLedger();
+  }
+
+  /**
+   * A handler table for one AG-UI client. Every table built for the current
+   * conversation draws into the same transcript and shares its bookkeeping, so
+   * a continuation run reports into the interaction the user is looking at.
+   *
+   * `threadId` is the thread the client was built for, named on the
+   * run-finished detail. Taken here rather than read when the run settles,
+   * because a stopped run settles after the reset that stopped it, when the
+   * thread on screen is already the next one.
+   */
+  forClient(threadId: string): AgUiClientHandlers {
+    const ledger = this.#ledger;
+    const attached = (): boolean => ledger === this.#ledger;
+    const { onSettled, onError, onCancelled, ...drawing } = this.#tableFor(ledger, threadId);
+    const guarded = whileAttached({ onError, onCancelled }, attached);
+    return {
+      ...whileAttached(drawing, attached),
+      // Recorded outside the check, like the settle: a detached run's ending is
+      // still true, and the ledger is the only place it can be kept for the report.
+      onError: (message) => {
+        ledger.outcome = "failed";
+        guarded.onError(message);
+      },
+      onCancelled: () => {
+        ledger.outcome = "stopped";
+        guarded.onCancelled();
+      },
+      onSettled: () => {
+        if (attached()) {
+          onSettled();
+        }
+        // Last, so a listener that refetches sees a transcript that has already
+        // stopped changing -- and outside the check, because what a run did is
+        // true whichever conversation is on screen when it ends.
+        this.#dispatchRunFinished(ledger, threadId);
+      },
+    };
+  }
+
+  /**
+   * The handler table itself, recording into `ledger`. {@link forClient}
+   * decides how much of it still runs once the table is detached. An answer is
+   * attributed to `threadId`, the thread the client was built for.
+   */
+  #tableFor(ledger: RunLedger, threadId: string): AgUiClientHandlers {
+    return {
+      onRunStart: () => {
+        // Per *round*, so guard on the turn: a run that calls three tools fires
+        // this three times and the user needs telling once.
+        if (!this.#host.running()) {
+          ledger.announcedOutcome = false;
+          this.#host.announcer.announce(this.#host.strings().announceResponding);
+        }
+        this.#host.setRunning(true);
+        // Open the answer group on the turn's first run so the pending
+        // indicator (and everything after) lands inside the well. Idempotent:
+        // later rounds of the same turn reuse it.
+        this.#host.transcript.ensureGroup();
+        this.#host.transcript.showPending();
+      },
+      onReasoningStart: () => {
+        // The model is thinking: swap the pending dots for a live thoughts
+        // region at the top of the turn's answer group.
+        this.#host.transcript.hidePending();
+        // A later round in the same turn finds the region already there, and
+        // restarts its clock and its live label.
+        this.#host.transcript.showThoughts().begin();
+      },
+      onReasoningDelta: (buffer) => {
+        this.#host.transcript.showThoughts().stream(buffer);
+      },
+      onReasoningEnd: () => {
+        // Settle the header to how long it took, but leave the region expanded
+        // until the answer text starts: it collapses on the first text delta.
+        this.#host.transcript.settleThoughts();
+      },
+      onTextDelta: (buffer) => {
+        this.#host.transcript.hidePending();
+        // The answer has begun — fold the thoughts away so they don't crowd it.
+        this.#host.transcript.collapseThoughts();
+        this.#host.stream.queue(buffer);
+        this.#host.stream.countDelta();
+      },
+      onTextEnd: (buffer, message) => {
+        // A text message that carried no content is a declaration, not an
+        // answer, and drawing one puts an empty bubble above every tool call.
+        //
+        // `TOOL_CALL_START` names the assistant message a call belongs to, and
+        // a response whose first part is a tool call has no text to open that
+        // message with. pydantic-ai 2.37 started opening and closing an empty
+        // one there so the id names a message the stream actually announced --
+        // before that it named one no event carried, which a client could only
+        // answer by inventing an id of its own that matches nothing echoed
+        // back. So this envelope is a correctness fix upstream, it is legal
+        // AG-UI, and any server may send one.
+        //
+        // `ConversationHistory.replay` already declines to draw a bubble for
+        // an assistant message with no text. Without the same rule
+        // here the live transcript and the reloaded one disagree about the
+        // same conversation, which is the harder half of the bug to notice.
+        if (buffer === "") {
+          this.#host.stream.end();
+          return;
+        }
+        const bubble = this.#host.stream.into(buffer);
+        // Only reveal word-by-word when the message arrived at once. If it
+        // streamed across multiple deltas it already revealed progressively, so
+        // wrapping it now would replay the finished response one word at a time.
+        if (this.#host.stream.deltas <= 1) {
+          this.#host.transcript.revealWords(bubble);
+        }
+        attachCopyButtons(bubble, this.#host.strings());
+        this.#host.actions.attach(bubble, message);
+        this.#host.stream.end();
+        this.#host.noteUnread(threadId);
+      },
+      onToolCall: (call) => {
+        this.#host.transcript.hidePending();
+        // A call ends the reasoning before it, whether or not its end arrived,
+        // and a turn of reasoning then calls has no text delta to settle it.
+        this.#host.transcript.settleThoughts();
+        // A skill activation is an ordinary `load_capability` tool call — the
+        // deferred-capability mechanism pydantic-ai already uses — so it arrives
+        // here rather than on a channel of its own. Render it as a notice and
+        // *return*: falling through would show a raw tool card beside the chip,
+        // which is worse than the card alone.
+        if (this.#host.transcript.noticeIfSkillLoad(call)) {
+          return;
+        }
+        // Recorded after the skill-load return: a capability load is the agent
+        // arranging itself, not work a host's data could have moved under.
+        ledger.tools.push({ id: call.id, name: call.name });
+        this.#host.transcript.cardFor(call);
+      },
+      onActivity: (activityType, content, messageId) => {
+        this.#host.activities.draw(messageId, activityType, content);
+      },
+      onCustomEvent: (name, value) => {
+        if (name === INVALIDATE_CUSTOM_NAME) {
+          this.#dispatchInvalidation(ledger, value);
+          return;
+        }
+        if (name === SUBAGENT_CUSTOM_NAME) {
+          this.#host.subagents.report(value);
+          return;
+        }
+        // Straight out to the host page, uninterpreted. This is the imperative
+        // carrier: whatever it means, it means it to the page, not to the
+        // transcript -- so it is dispatched and deliberately not rendered,
+        // persisted or replayed. A host that does not know the name simply has
+        // no listener, which is the graceful outcome the open field is for.
+        this.#host.element.dispatchEvent(
+          new CustomEvent<CustomAgentDetail>(CUSTOM_AGENT_EVENT, {
+            detail: { name, value },
+            bubbles: true,
+            composed: true,
+          }),
+        );
+      },
+      // The delegation's own lifetime, on the protocol's events rather than the
+      // CUSTOM channel its steps ride. Both end at the same panel.
+      onSubAgentStarted: (subagentRunId, agent, parentToolCallId) => {
+        this.#host.subagents.start(subagentRunId, agent, parentToolCallId);
+      },
+      onSubAgentFinished: (subagentRunId) => {
+        this.#host.subagents.finish(subagentRunId);
+      },
+      onSubAgentError: (subagentRunId, message) => {
+        this.#host.subagents.fail(subagentRunId, message);
+      },
+      onMessagesSnapshot: () => {
+        // Honoured for persistence and announced, not re-rendered.
+        //
+        // The store follows the server, because the server is authoritative
+        // about what the conversation *is* -- and it would follow it anyway:
+        // `@ag-ui/client` replaces `agent.messages` before any subscriber runs,
+        // and the run loop persists `agent.messages`. Done in silence, the
+        // screen and the store would disagree until a reload served a
+        // transcript the reader had never seen.
+        //
+        // Not re-rendered from the snapshot: a snapshot can land mid-run, and rebuilding the
+        // transcript then would destroy the in-flight run's own UI state -- the streaming
+        // bubble, the open answer group, and every tool card keyed by call id,
+        // some of which are still waiting on results. Telling the reader costs
+        // none of that, and this is the same answer the same question already
+        // got for compaction, one handler up.
+        this.#host.transcript.appendNotice(
+          "\u{1F504}",
+          this.#host.strings().historyReplaced,
+          "history-replaced",
+        );
+      },
+      onToolResult: (toolCallId, content, outcome) => {
+        const card = this.#host.transcript.card(toolCallId);
+        if (card === undefined) {
+          return;
+        }
+        // Settled as the server says it ended, not as "it ended": a refusal
+        // settled as DONE is a green card, and a booking the server declined
+        // reads, at a glance, as a booking that was made. An absent or
+        // unrecognised outcome still means DONE, so a server that never states
+        // one renders every call as done.
+        card.settle(toolStatusFromOutcome(outcome), content);
+        this.#host.transcript.markServerSettled(toolCallId);
+        ledger.serverSettled.add(toolCallId);
+        // The card stops being the live thing the moment it settles, and the
+        // server goes straight back to the model with the result -- a wait with
+        // nothing on screen to own it, and the longest one in a run when the
+        // result is a large inlined attachment being re-sent with every request.
+        // The dots go back where ``onToolCall`` took them from, after the card,
+        // and whatever comes next clears them: reasoning, the first text delta,
+        // the round ending, or ``onSettled``'s terminal guarantee.
+        //
+        // Not the same case as the one ``ToolDispatch.execute`` refuses to show
+        // them for. That runs after the run has ended, so there is nothing left to
+        // clear them and they would hang -- which is what happened before 0.2.1
+        // and is why they were removed from here too. The terminal guarantee
+        // that shipped in the same release is what makes showing them safe now.
+        this.#host.transcript.showPending();
+      },
+      onActivityChanged: (messageId, activityType, content) => {
+        this.#host.activities.draw(messageId, activityType, content);
+      },
+      onRunEnd: () => {
+        // Per-round end; the button stays on Stop until the whole interaction
+        // settles — the user must be able to cancel between tool rounds.
+        this.#host.transcript.hidePending();
+        this.#host.stream.end();
+      },
+      onError: (message) => {
+        ledger.announcedOutcome = true;
+        this.#host.announcer.announce(this.#host.strings().announceFailed);
+        this.#host.transcript.hidePending();
+        const bubble = this.#host.appendMessage(MESSAGE_ROLE.ASSISTANT, `⚠️ ${message}`);
+        bubble.classList.add("message--failed");
+        // A failure is the one message whose action row is only worth having
+        // for Retry: there is nothing here worth copying and nothing to rate.
+        // A dropped connection with no way back was the whole of the gap --
+        // uploads had a retry and runs did not.
+        //
+        // Not a `run-notice`: that element's contract is that it "never
+        // settles, takes no action, and carries no controls", and is explicitly
+        // "distinct from an error, which is a failure". This is a failure, so
+        // it stays an error and gains the control instead.
+        this.#host.actions.attach(bubble, { rateable: false });
+        this.#host.transcript.revealWords(bubble);
+        this.#host.stream.end();
+      },
+      onCancelled: () => {
+        // Deliberate stop, not a failure: keep whatever partial text already
+        // streamed and add a muted note instead of an error bubble.
+        ledger.announcedOutcome = true;
+        this.#host.announcer.announce(this.#host.strings().announceStopped);
+        this.#host.transcript.hidePending();
+        this.#host.transcript.appendStoppedNote();
+        this.#host.stream.end();
+      },
+      onSettled: () => {
+        // Terminal guarantee: whatever path ended the run, return to rest.
+        if (!ledger.announcedOutcome) {
+          this.#host.announcer.announce(this.#host.strings().announceAnswerReady);
+        }
+        this.#host.transcript.hidePending();
+        this.#host.setRunning(false);
+        this.#host.stream.end();
+        // A tool card still pending at settle would hang forever: a call Stop or
+        // RUN_ERROR ended before it ran, a server tool whose result never
+        // streamed because the connection dropped, an approved call Stop kept
+        // from resuming. None of them finished and nobody refused them, so the
+        // card says exactly that, in the words the client sends the agent for
+        // the same call on the next request.
+        for (const card of this.#host.transcript.cards()) {
+          if (!card.settled) {
+            card.settle(TOOL_CALL_STATUS.INTERRUPTED, this.#host.strings().callNotFinished);
+          }
+        }
+        this.#host.transcript.closeGroup();
+      },
+    };
+  }
+
+  /**
+   * Tell the host the interaction is over and what ran in it.
+   *
+   * Last thing in `onSettled`, so a listener that refetches sees a transcript
+   * that has already stopped changing. `side` is read from the streamed-result
+   * bookkeeping rather than from the tool list: whether a call executed on the
+   * server is a fact about the run, and a name can appear on both sides across a
+   * conversation.
+   */
+  #dispatchRunFinished(ledger: RunLedger, threadId: string): void {
+    const tools: ToolRun[] = ledger.tools.map(({ id, name }) => ({
+      name,
+      side: ledger.serverSettled.has(id) ? "server" : "client",
+    }));
+    const invalidated = [...ledger.invalidated];
+    ledger.tools.length = 0;
+    ledger.serverSettled.clear();
+    ledger.invalidated.clear();
+    const outcome = ledger.outcome;
+    ledger.outcome = "completed";
+    this.#host.element.dispatchEvent(
+      new CustomEvent<RunFinishedDetail>(RUN_FINISHED_EVENT, {
+        detail: { threadId, tools, invalidated, outcome },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  /**
+   * Route one invalidation to the host, and remember it for the run summary.
+   *
+   * Dispatched immediately rather than only at the end, because that is what
+   * makes a long multi-step run feel live -- the list refreshes as the third of
+   * eight writes lands. The accumulated set rides
+   * {@link RUN_FINISHED_EVENT} as well, so a host that would rather refetch once
+   * upgrades by reading one extra field instead of adding a listener.
+   *
+   * Nothing is rendered, persisted or replayed. An invalidation is an
+   * imperative: it has no place in the transcript and no meaning once acted on,
+   * and replaying one on every thread load would be a refetch storm. That is the
+   * whole reason the server sends it as `CUSTOM` rather than as an activity.
+   */
+  #dispatchInvalidation(ledger: RunLedger, value: unknown): void {
+    const payload = (value ?? {}) as { keys?: unknown; reason?: unknown };
+    // Defensive about the payload, not about the name: `value` is typed
+    // `unknown` by the protocol, so a server can put anything there, and a
+    // malformed announcement must not take the run down with it.
+    const keys = Array.isArray(payload.keys)
+      ? payload.keys.filter((key): key is string => typeof key === "string")
+      : [];
+    if (keys.length === 0) {
+      return;
+    }
+    for (const key of keys) {
+      ledger.invalidated.add(key);
+    }
+    this.#host.element.dispatchEvent(
+      new CustomEvent<InvalidateDetail>(INVALIDATE_EVENT, {
+        detail: { keys, reason: typeof payload.reason === "string" ? payload.reason : null },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+}

package/src/core/run_index.ts

@@ -0,0 +1,114 @@
+import { withCredentials } from "./utils.js";
+
+/** 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;
+  /**
+   * The run's first user message, one line, already truncated by the server —
+   * the only field in a row a person recognises a conversation by.
+   *
+   * Optional because a server predating the field does not send it, and
+   * `null` where the run holds no words to show (seeded from history alone, or
+   * opened with an image and no caption). A row without one falls back to the
+   * time plus a short id.
+   */
+  readonly preview?: string | null;
+}
+
+/** Live header source, read per request so rotated tokens / CSRF reach the server. */
+type HeadersProvider = () => Record<string, string>;
+
+/** Live cookie policy, read per request; see `RemoteConversationStore`'s note. */
+type CredentialsProvider = () => RequestCredentials | undefined;
+
+/**
+ * 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, and a run that never reached a provider-valid
+ * boundary has none. Offer the action only for those rows ({@link continuable}
+ * filters them) and treat the rest as informational.
+ *
+ * Resume and fork are siblings of the index rather than separate configuration
+ * — django-ag-ui mounts `runs/`, `resume/<id>/` and `fork/<id>/` under one
+ * prefix — so this one URL locates all three.
+ */
+export class RunIndex {
+  readonly #url: string;
+  readonly #headers: HeadersProvider;
+  readonly #credentials: CredentialsProvider;
+
+  constructor(
+    url: string,
+    headers: HeadersProvider = () => ({}),
+    credentials: CredentialsProvider = () => undefined,
+  ) {
+    this.#url = url.endsWith("/") ? url : `${url}/`;
+    this.#headers = headers;
+    this.#credentials = credentials;
+  }
+
+  /**
+   * The user's runs, or `[]` when the endpoint is unreachable or errors — the
+   * caller renders its empty state rather than a transport fault the user can
+   * do nothing about.
+   */
+  async list(): Promise<readonly RunRow[]> {
+    try {
+      const response = await fetch(
+        this.#url,
+        withCredentials(
+          {
+            method: "GET",
+            headers: { Accept: "application/json", ...this.#headers() },
+          },
+          this.#credentials(),
+        ),
+      );
+      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.
+   *
+   * String surgery on the trailing `runs/` rather than `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)}/`;
+  }
+}