@artooi/ag-ui-web-component 0.24.0 → 0.25.0

package/src/core/ag_ui_chat.ts

@@ -1596,6 +1596,11 @@ export class AgUiChat extends HTMLElement {
    * {@link toggleCollapsed} and {@link toggleTheme}.
    */
   openThreads(): void {
+    // Two overlapping surfaces, so opening one dismisses the other. Clicking away
+    // already covers the built-in buttons, but a host driving its own chrome
+    // through these methods raises no pointer event — and the drawer would then
+    // open *underneath* a popover still floating over it.
+    this.#checkpoints.close();
     void this.#refreshDrawer();
     this.#drawer.open();
   }
@@ -1608,10 +1613,31 @@ export class AgUiChat extends HTMLElement {
    * an empty panel.
    */
   openCheckpoints(): void {
+    // The other half of the pair — see `openThreads`.
+    this.#drawer.close();
     void this.#refreshCheckpoints();
     this.#checkpoints.open();
   }
 
+  /** Close the checkpoints panel, if it is open. */
+  closeCheckpoints(): void {
+    this.#checkpoints.close();
+  }
+
+  /**
+   * Open the checkpoints panel, or close it if it is already open — what the
+   * built-in ⭯ button does, because a control that opens a panel is read as the
+   * control that also dismisses it. {@link openCheckpoints} stays open-only for a
+   * host that means exactly that.
+   */
+  toggleCheckpoints(): void {
+    if (this.#checkpoints.open_) {
+      this.#checkpoints.close();
+      return;
+    }
+    this.openCheckpoints();
+  }
+
   /**
    * Start a fresh conversation: forget the persisted history, drop the
    * in-memory run state, clear the transcript, and mint a new thread id.
@@ -1933,8 +1959,11 @@ export class AgUiChat extends HTMLElement {
     const history = this.#headerButton("history", this.#strings.chatHistory, "☰");
     history.addEventListener("click", () => this.openThreads());
 
-    const checkpoints = this.#headerButton("checkpoints", this.#strings.checkpoints, "⭯");
-    checkpoints.addEventListener("click", () => this.openCheckpoints());
+    // ↺ rather than ⭯: the same idea in a glyph that has a font behind it in
+    // every browser. The obscure one rendered as an unreadable mark at 14px, and a
+    // header control nobody can name is one nobody presses.
+    const checkpoints = this.#headerButton("checkpoints", this.#strings.checkpoints, "↺");
+    checkpoints.addEventListener("click", () => this.toggleCheckpoints());
 
     const newChat = this.#headerButton("new", this.#strings.newChat, "✚");
     newChat.addEventListener("click", () => this.newChat());
@@ -2077,6 +2106,25 @@ export class AgUiChat extends HTMLElement {
       this.#checkpoints.element,
     );
 
+    // Clicking away dismisses the checkpoints popover. Escape already did, and the
+    // drawer has a backdrop that swallows the click — this popover has neither, so
+    // it could only be closed by answering it.
+    //
+    // `pointerdown`, and the header button excluded: pointerdown runs *before* the
+    // button's own click, so closing here and toggling there would land back open.
+    // Composed path rather than `target`, because the event is retargeted at the
+    // shadow boundary and every one of these nodes is inside it.
+    this.#chat.addEventListener("pointerdown", (event) => {
+      if (!this.#checkpoints.open_) {
+        return;
+      }
+      const path = event.composedPath();
+      if (path.includes(this.#checkpoints.element) || path.includes(checkpoints)) {
+        return;
+      }
+      this.#checkpoints.close();
+    });
+
     // What a collapsed widget shrinks to: a round floating button, or the slim
     // edge rail under `placement="sidebar"` — one element, shaped by CSS.
     // A sibling of the panel, so it survives the panel being hidden.
@@ -2590,56 +2638,82 @@ 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).
    *
+   * **One card per gated call, in that call's own tool card, all at once.** A run
+   * can defer several calls, and the wire answers each independently — so the UI
+   * has to let a person answer each independently, which means saying which is
+   * which. The prompt cannot: it comes from the tool's `x-confirm` and is
+   * identical for every call of that tool. The tool card can, by position, and it
+   * is already showing the arguments. Asking them serially was the other half of
+   * the problem: the second question only appeared once the first was answered,
+   * so a person could neither compare them nor tell that more were coming.
+   *
+   * Each gated card is marked `deferred` for the wait. That is not cosmetic — at
+   * `pending` it read "running…" while the stream was over and the server idle.
+   *
    * 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. An approved tool runs on the follow-up resume run and streams its
-   * result into the same pending card; a denied one settles here, since no
-   * result will ever arrive.
+   * result into the same card (returned to `pending`, since it now really is
+   * running); a denied one settles here, as no result will ever arrive.
    */
   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 = {};
-      const phrase = confirmPhrase(interrupt) ?? interrupt.message;
-      if (phrase !== undefined) {
-        request.message = phrase;
-      }
-      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;
-      // Same annotation as the client-side confirmation gate. Without it the
-      // two gates read differently for the same act: a locally-confirmed call
-      // said who let it through and a server-gated one said nothing, which is
-      // backwards, since the server-side gate is the one guarding the tools
-      // that actually run on the backend.
-      card?.recordDecision(approved ? "approved" : "declined");
-      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);
-      }
-    }
+    const signal = this.#confirmAbort.signal;
+    const answered = await Promise.all(
+      interrupts.map(async (interrupt) => {
+        const card =
+          interrupt.toolCallId !== undefined
+            ? this.#toolCards.get(interrupt.toolCallId)
+            : undefined;
+        const request: ApprovalRequest = {};
+        const phrase = confirmPhrase(interrupt) ?? interrupt.message;
+        if (phrase !== undefined) {
+          request.message = phrase;
+        }
+        const toolName = card?.element.getAttribute("data-tool-name");
+        if (toolName !== null && toolName !== undefined) {
+          request.toolName = toolName;
+        }
+        card?.mark(TOOL_CALL_STATUS.DEFERRED);
+        // A host-supplied renderer takes full control of the approval UI. The
+        // built-in card renders into the gated call's own card, falling back to
+        // the answer group when the interrupt names no call we hold one for.
+        const approved =
+          this.approvalRenderer !== null
+            ? await this.approvalRenderer(request, { signal })
+            : await requestApproval(card?.approvalSlot ?? this.#ensureGroup(), request, {
+                signal,
+                strings: this.#strings,
+              });
+        // Same annotation as the client-side confirmation gate. Without it the
+        // two gates read differently for the same act: a locally-confirmed call
+        // said who let it through and a server-gated one said nothing, which is
+        // backwards, since the server-side gate is the one guarding the tools
+        // that actually run on the backend.
+        card?.recordDecision(approved ? "approved" : "declined");
+        if (approved) {
+          card?.mark(TOOL_CALL_STATUS.PENDING);
+        } else {
+          // No TOOL_CALL_RESULT will stream for a denied tool — settle its card
+          // now rather than leaving it hanging until the onSettled sweep.
+          card?.settle(TOOL_CALL_STATUS.DECLINED, this.#strings.declinedAction);
+        }
+        return { id: interrupt.id, approved };
+      }),
+    );
+    this.#updateEmptyState();
+    this.#messages.scrollTop = this.#messages.scrollHeight;
     this.#confirmAbort = null;
+    const responses: Record<string, InterruptResponse> = {};
+    for (const { id, approved } of answered) {
+      responses[id] = approved
+        ? { status: "resolved", payload: { approved: true } }
+        : { status: "cancelled" };
+    }
     return responses;
   }
 

package/src/core/run_index.ts

@@ -8,6 +8,16 @@ export interface RunRow {
   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, which is what every row used to be.
+   */
+  readonly preview?: string | null;
 }
 
 /** Live header source, read per request so rotated tokens / CSRF reach the server. */

package/src/ui/checkpoint_menu.ts

@@ -161,18 +161,43 @@ export class CheckpointMenu {
     row.className = "checkpoint-row";
     row.setAttribute("part", "checkpoint-row");
 
+    const preview =
+      run.preview !== undefined && run.preview !== null && run.preview !== "" ? run.preview : null;
+    const time =
+      run.started_at === null
+        ? null
+        : relativeTime(Date.parse(run.started_at), Date.now(), this.#strings);
+
     const label = document.createElement("span");
     label.className = "checkpoint-label";
     label.setAttribute("part", "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;
+    // What the run was about, if the server says. Otherwise the time, and only
+    // then the id — a person recognises the first, reads the second, and
+    // recognises nothing at all in the third.
+    label.textContent = preview ?? time ?? run.run_id;
     row.append(label);
 
+    if (preview !== null && time !== null) {
+      // Demoted to a chip: with words in the label the time is no longer what
+      // identifies the run, but it still orders it.
+      const when = document.createElement("span");
+      when.className = "checkpoint-time";
+      when.setAttribute("part", "checkpoint-time");
+      when.textContent = time;
+      row.append(when);
+    } else if (run.started_at !== null) {
+      // No words to show, so the id has to do the identifying: two runs a few
+      // seconds apart both read "just now", and picking between them is picking
+      // blind. Shown rather than left in a tooltip, since a hover is not an
+      // identity either — and eight characters beats a full id on the row.
+      const short = document.createElement("span");
+      short.className = "checkpoint-id";
+      short.setAttribute("part", "checkpoint-id");
+      short.textContent = run.run_id.slice(0, 8);
+      short.title = run.run_id;
+      row.append(short);
+    }
+
     if (run.parent_run_id !== null) {
       // Lineage, so a branch doesn't read as a duplicate of its parent.
       const branch = document.createElement("span");

package/src/ui/styles.ts

@@ -973,6 +973,13 @@ export const STYLES = `
   to { transform: rotate(360deg); }
 }
 
+/* Deferred: no spinner, because nothing is spinning. A steady accent dot, since
+   the state is waiting-on-you rather than an outcome. */
+.tool-call[data-status="deferred"] .tool-call-icon {
+  border-radius: 50%;
+  background: var(--_accent);
+}
+
 /* Settled: a themeable glyph coloured by outcome. */
 .tool-call[data-status="done"] .tool-call-icon::before {
   content: var(--_tool-icon-done);
@@ -1015,6 +1022,10 @@ export const STYLES = `
   color: var(--_muted);
 }
 
+.tool-call[data-status="deferred"] .tool-call-status {
+  color: var(--_accent);
+}
+
 .tool-call[data-status="done"] .tool-call-status {
   color: var(--_success);
 }
@@ -1108,12 +1119,41 @@ export const STYLES = `
 
 /* A pending card has no result yet, and in the modes where the arguments are
    hidden too there is nothing behind the toggle. Hide the control rather than
-   offer one that expands onto nothing. */
+   offer one that expands onto nothing. A deferred card is the same, and its
+   arguments are shown unconditionally by the rules below. */
 .tool-call[data-status="pending"] .tool-call-toggle,
+.tool-call[data-status="deferred"] .tool-call-toggle,
 :host([data-tool-display="inline"]) .tool-call[data-status="pending"] .tool-call-toggle {
   display: none;
 }
 
+/* The approval prompt for a gated call, rendered inside that call's own card.
+   Empty on every card nobody is being asked about, so it collapses instead of
+   adding a gap to each one. */
+.tool-call-approval:empty {
+  display: none;
+}
+
+.tool-call-approval {
+  margin-top: 8px;
+}
+
+/* A card that is asking a question shows what it is asking about, in every
+   display mode. Three gated calls of one tool ask the same words, so the
+   arguments are the only thing telling them apart, and a density setting must
+   not be able to hide the answer to "which one is this". */
+:host([data-tool-display="minimal"]) .tool-call[data-status="deferred"] .tool-call-body {
+  display: flex;
+}
+
+/* The arguments region only, never every section: the result region carries the
+   hidden attribute until a result exists, and a display value here overrides it,
+   framing an empty RESULT heading under the question. */
+:host([data-tool-display="compact"]) .tool-call[data-status="deferred"] .tool-call-section--args,
+:host([data-tool-display="inline"]) .tool-call[data-status="deferred"] .tool-call-section--args {
+  display: flex;
+}
+
 .tool-call-toggle {
   align-self: flex-start;
   border: none;
@@ -1333,6 +1373,20 @@ export const STYLES = `
   opacity: 0.6;
 }
 
+/* The same trap the attachment tray carries a note about, two rules along: an
+   author display beats the UA stylesheet's rule for the hidden property, so a
+   button the element has explicitly hidden keeps laying out and painting. The
+   clip is hidden until a host supplies an upload handler or an attachments URL,
+   and without this it is a visible control that cannot do anything.
+
+   The mic needs no such rule, and the asymmetry is worth knowing before adding
+   one: it is not hidden when unconfigured, it is never built. The voice wiring
+   returns before constructing the button, leaving only an empty voice slot that
+   is display: contents. A hidden-state rule for the mic would match nothing. */
+.attach-btn[hidden] {
+  display: none;
+}
+
 /* Send closes the row on the right: a circle, the only filled control in the
    composer, so "the thing that acts" reads at a glance. */
 .send {
@@ -1942,47 +1996,123 @@ export const STYLES = `
   opacity: 0.7;
 }
 
+/* A row is a label and two buttons, and nothing about the row itself is
+   pressable. It used to light up on hover, which is the affordance of something
+   clickable and made the buttons look like decoration on a clickable strip. The
+   resting surface groups the row instead, so hover can mean what it says: only
+   the buttons respond to it. */
+/* A row is a label and two buttons, and nothing about the row itself is
+   pressable. It used to light up on hover, which is the affordance of something
+   clickable and made the buttons look like decoration on a clickable strip. The
+   resting surface groups the row instead, so hover can mean what it says: only
+   the buttons respond to it.
+
+   It wraps for the same reason the tool-call head does. Every child but the label
+   is fixed-width, so in a narrow panel the label is the only thing that can give
+   -- and a flex-basis of zero lets it give everything. Adding the run id was
+   enough to crush "just now" to zero pixels: present, correct, and invisible.
+   Wrapping puts the buttons on their own line instead. */
 .checkpoint-row {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
   gap: 0.5rem;
-  padding: 0.25rem;
+  padding: 0.3125rem 0.4375rem;
   border-radius: 0.375rem;
-}
-
-.checkpoint-row:hover {
   background: var(--_hover);
 }
 
+/* Grows into spare room, and refuses to shrink past the shortest thing it ever
+   says. A time is short and bounded, so there is no case for eliding it. */
 .checkpoint-label {
-  flex: 1;
+  flex: 1 1 auto;
+  min-width: 7ch;
   font-size: 0.8125rem;
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
 }
 
+/* When the label holds the run's first message, the time moves here: still worth
+   showing, no longer what identifies the row. Muted and unshrinkable, so it does
+   not compete with the words beside it. */
+.checkpoint-time {
+  flex: 0 0 auto;
+  font-size: 0.6875rem;
+  opacity: 0.7;
+  white-space: nowrap;
+}
+
+/* Enough of the run id to tell two runs apart when both say "just now". Muted
+   and monospaced: it is a reference, not a name. */
+.checkpoint-id {
+  flex: 0 0 auto;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.6875rem;
+  opacity: 0.55;
+}
+
+/* On the panel's own surface, not the row's: the row now paints the hover token
+   itself, and a badge the same colour as what it sits on is not a badge. */
 .checkpoint-branch {
   font-size: 0.6875rem;
   padding: 0 0.375rem;
   border-radius: 999px;
-  background: var(--_hover);
+  background: var(--_assistant-bg);
   opacity: 0.8;
 }
 
+/* The two things in the row that actually do something, so they are the two
+   things that look like it: a filled surface at rest rather than a transparent
+   outline, which on top of the old row highlight was nearly invisible. */
 .checkpoint-action {
   font: inherit;
   font-size: 0.75rem;
+  line-height: 1.4;
   cursor: pointer;
-  padding: 0.125rem 0.5rem;
+  padding: 0.1875rem 0.5625rem;
   border: 1px solid var(--_border);
   border-radius: 0.375rem;
-  background: transparent;
+  background: var(--_bg);
   color: inherit;
+  transition:
+    background var(--_motion) var(--_ease),
+    border-color var(--_motion) var(--_ease),
+    transform var(--_motion) var(--_ease);
 }
 
-.checkpoint-action:hover {
+/* Resume is what a reader wants nine times in ten; fork is the deliberate choice
+   beside it. Filled and outlined, the same pair the confirmation and approval
+   cards already use for their primary and secondary action. */
+.checkpoint-resume {
+  font-weight: 600;
+  border-color: var(--_accent);
+  background: var(--_accent);
+  color: #ffffff;
+}
+
+.checkpoint-fork:hover {
   background: var(--_hover);
+  border-color: var(--_accent);
+}
+
+/* The filled one cannot go lighter on hover without losing its contrast with the
+   white label, so it dims instead. */
+.checkpoint-resume:hover {
+  opacity: 0.88;
+}
+
+/* Pressed: a pixel down, so the click is felt as well as seen. */
+.checkpoint-action:active {
+  transform: translateY(1px);
+}
+
+/* Keyboard focus was invisible here, in a panel that traps focus and is reached
+   by Tab -- so the one navigation path guaranteed to land on these buttons was
+   the one with nothing to show for it. */
+.checkpoint-action:focus-visible {
+  outline: 2px solid var(--_accent);
+  outline-offset: 2px;
 }
 
 .drawer-backdrop {

package/src/ui/tool_call_card.ts

@@ -7,13 +7,17 @@ export type ToolCallStatus = (typeof TOOL_CALL_STATUS)[keyof typeof TOOL_CALL_ST
 /** How much detail a card renders. */
 export type ToolDisplayMode = (typeof TOOL_DISPLAY)[keyof typeof TOOL_DISPLAY];
 
-/** The terminal states a card settles into (everything but `pending`). */
-export type SettledStatus = Exclude<ToolCallStatus, typeof TOOL_CALL_STATUS.PENDING>;
+/** The two states a card can sit in before an outcome exists. */
+export type UnsettledStatus = typeof TOOL_CALL_STATUS.PENDING | typeof TOOL_CALL_STATUS.DEFERRED;
+
+/** The terminal states a card settles into (everything unsettled excluded). */
+export type SettledStatus = Exclude<ToolCallStatus, UnsettledStatus>;
 
 /** Short pill text shown for each status, drawn from the string table. */
 function statusLabels(strings: UiStrings): Record<ToolCallStatus, string> {
   return {
     [TOOL_CALL_STATUS.PENDING]: strings.toolRunning,
+    [TOOL_CALL_STATUS.DEFERRED]: strings.toolDeferred,
     [TOOL_CALL_STATUS.DONE]: strings.toolDone,
     [TOOL_CALL_STATUS.ERROR]: strings.toolError,
     [TOOL_CALL_STATUS.DECLINED]: strings.toolDeclined,
@@ -64,6 +68,21 @@ export class ToolCallCard {
   /** The card's root element; append this into the message list. */
   readonly element: HTMLDivElement;
 
+  /**
+   * Where a question about *this* call renders — the approval prompt for a
+   * server-side tool the run deferred.
+   *
+   * It belongs to the card rather than to the transcript because a run can defer
+   * several calls at once, and a prompt written per *tool* ("Add this event to
+   * the board?") is identical for every one of them. Rendered into the answer
+   * group they were three anonymous copies of one question, below the three
+   * cards they gated; rendered here, position identifies them and the arguments
+   * are already on screen above the question.
+   *
+   * Empty until used, and hidden while empty by the shadow CSS.
+   */
+  readonly approvalSlot: HTMLDivElement;
+
   readonly #status: HTMLSpanElement;
   readonly #decision: HTMLSpanElement;
   readonly #toggle: HTMLButtonElement;
@@ -143,7 +162,26 @@ export class ToolCallCard {
     body.setAttribute("part", "tool-card-body");
     body.append(argsSection.root, resultSection.root);
 
-    this.element.append(head, this.#toggle, body);
+    this.approvalSlot = document.createElement("div");
+    this.approvalSlot.className = "tool-call-approval";
+    this.approvalSlot.setAttribute("part", "tool-card-approval");
+
+    this.element.append(head, this.#toggle, body, this.approvalSlot);
+  }
+
+  /**
+   * Move between the two states that are not an outcome — `pending` (running)
+   * and `deferred` (gated, waiting on a person).
+   *
+   * Ignored once {@link settle} has run: a card that was declined must not be
+   * talked back into looking live by a late event.
+   */
+  mark(status: UnsettledStatus): void {
+    if (this.#settled) {
+      return;
+    }
+    this.element.setAttribute("data-status", status);
+    this.#status.textContent = statusLabels(this.#strings)[status];
   }
 
   /**

package/src/ui/ui_strings.ts

@@ -84,6 +84,8 @@ export interface UiStrings {
   // ── Tool-call card ──────────────────────────────────────────────────────────
   /** Status pill while the call runs. */
   toolRunning: string;
+  /** Status pill on a gated call the run deferred, waiting on a person. */
+  toolDeferred: string;
   /** Status pill on success. */
   toolDone: string;
   /** Status pill on error. */
@@ -244,6 +246,7 @@ export const DEFAULT_UI_STRINGS: UiStrings = {
   transcriptionFailed: "Transcription failed",
 
   toolRunning: "running…",
+  toolDeferred: "waiting for you",
   toolDone: "✓ done",
   toolError: "⚠ error",
   toolDeclined: "⊘ declined",

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.24.0";
+export const VERSION: string = "0.25.0";