samagotchi 0.54.0 → 0.55.0

data/lib/samagotchi/web/public/llm_context_chip.js

@@ -12,6 +12,8 @@
 // choice for the next create only (POST /api/sessions' llm_context), never
 // remembered: nothing is sent unless the user sets one.
 
+import { html, nothing } from "./vendor/lit-html.js";
+
 export const STRATEGIES = [
   { value: "none", label: "none" },
   { value: "stale", label: "stale" },
@@ -70,11 +72,12 @@ export function chipModel(summary, { kind = SESSION } = {}) {
   return { text: `llm ctx ${summary.strategy}${own ? ` · ${kind}` : ""}`, title, own };
 }
 
-export function chipHtml(summary, escapeHtml) {
+// The session bar's chip (a lit-html template; info_bar.js), nothing
+// without a summary.
+export function chipTemplate(summary) {
   const chip = chipModel(summary);
-  if (!chip) return "";
-  return `<button type="button" class="model llmctx-chip${chip.own ? " own" : ""}" title="${escapeHtml(chip.title)}" ` +
-    `aria-haspopup="dialog">${escapeHtml(chip.text)}</button>`;
+  if (!chip) return nothing;
+  return html`<button type="button" class=${`model llmctx-chip${chip.own ? " own" : ""}`} title=${chip.title} aria-haspopup="dialog">${chip.text}</button>`;
 }
 
 // The /llm-context line for the form's values. With +initial+ (the values
@@ -201,8 +204,8 @@ export function popoverPlace(rect, { width, height, innerWidth, innerHeight }) {
   return height > room ? { ...place, maxHeight: room } : place;
 }
 
-// The chip's popover. el: where the chip is drawn (#infoText, redrawn every
-// tick: clicks are delegated); summary(): the open session's llm_context;
+// The chip's popover. el: where the chip is drawn (#infoText, info_bar.js:
+// clicks are delegated); summary(): the open session's llm_context;
 // session(): the open session's id; running(): a turn runs; run(line):
 // sends the command.
 // The start page's (kind NEW_CHAT): summary() is the picked model's,

data/lib/samagotchi/web/public/question_cards.js

@@ -19,7 +19,8 @@ import {
   relayedToView, resultText, summaryText,
 } from "./question_card.js";
 import { sessionHash } from "./route.js";
-import { clientLabel, continueLine, isOwn } from "./turn_events.js";
+import { clientLabel, isOwn } from "./turn_events.js";
+import { continueLine } from "./commands.js";
 
 // @param sessionId () => the open session's id (answers go there)
 // @param clientId this tab's id in the session's events

data/lib/samagotchi/web/public/refs.js

@@ -0,0 +1,134 @@
+// Refs: quiet links from what a turn touched to the thing itself. A ref is
+// a kind and a target: today a file tool's row title (the server's FileRef,
+// {kind: "file", path, line?, end_line?}) and that row's diff lines (the
+// same file at a line). The DOM carries data-ref-kind and the target's
+// attributes, never what a click does: that is an action, kept per kind in
+// REF_ACTIONS, and a click runs the first one available to this viewer. A
+// ref with none (a phone: no editor) stays plain text; the page marks the
+// kinds that have one on its body (refs-<kind>), which the hover styling
+// keys on.
+
+import { escapeHtml } from "./format.js";
+
+// The data attributes a ref's element carries.
+export function refAttrs(ref) {
+  if (!ref?.kind) return "";
+  const attr = (name, value) => (value ? ` data-ref-${name}="${escapeHtml(String(value))}"` : "");
+  return ` data-ref-kind="${escapeHtml(ref.kind)}"${attr("path", ref.path)}${attr("line", ref.line)}${attr("end-line", ref.end_line)}`;
+}
+
+// The URL +template+ ({path}, {line}; web.editor) opens +path+ at +line+
+// (1 when none) with: each path segment encoded, the slashes kept. "" with
+// no template or path.
+export function editorUrl(template, path, line) {
+  if (!template || !path) return "";
+  const encoded = String(path).split("/").map(encodeURIComponent).join("/");
+  return template.replaceAll("{path}", encoded).replaceAll("{line}", String(line || 1));
+}
+
+// What a ref can do, per kind, in order: the first available one is a
+// click's. +viewer+ is what this page's viewer can do ({editor, editorUrl}:
+// the server's capabilities.editor and editor_url).
+export const REF_ACTIONS = Object.freeze({
+  file: Object.freeze([
+    Object.freeze({
+      id: "editor",
+      available: (viewer) => viewer?.editor === true && !!viewer.editorUrl,
+      url: (target, viewer) => editorUrl(viewer.editorUrl, target.path, target.line),
+      // The hover hint: it opens the file as it is now.
+      hint: (target) => `Open the current file in your editor${target.line ? ` at line ${target.line}` : ""}`,
+    }),
+  ]),
+});
+
+// The first action +viewer+ has for a ref of +kind+, else null.
+export function refAction(kind, viewer, actions = REF_ACTIONS) {
+  return (actions[kind] || []).find((action) => action.available(viewer)) || null;
+}
+
+// The kinds that have an action for +viewer+ (the page's refs-<kind> classes).
+export function availableKinds(viewer, actions = REF_ACTIONS) {
+  return Object.keys(actions).filter((kind) => refAction(kind, viewer, actions));
+}
+
+// What a click on +el+ points at: {kind, path, line, owner} or null. A row
+// title opens its file at the lines the call named (an edit without any at
+// its first changed line); a diff line (or a hunk header) in a row with a
+// ref opens the row's file at that line. A diff line outside a row (an
+// approval card's dry run) is none.
+export function refTarget(el) {
+  const title = el?.closest?.("[data-ref-kind]");
+  if (title) {
+    const owner = title.closest(".activity-row");
+    return { ...targetOf(title), line: Number(title.dataset.refLine) || firstChange(owner), owner: owner || title };
+  }
+  const diffLine = el?.closest?.(".diff-line[data-line]");
+  const owner = diffLine?.closest(".activity-row");
+  const ref = owner?.querySelector("[data-ref-kind]");
+  if (!ref) return null;
+  return { ...targetOf(ref), line: Number(diffLine.dataset.line), owner };
+}
+
+function targetOf(el) {
+  return { kind: el.dataset.refKind, path: el.dataset.refPath || "" };
+}
+
+// An edit/write without a line range opens at its first changed line (its
+// diff knows it, the call doesn't); null without a diff.
+function firstChange(row) {
+  const line = row?.querySelector(".diff-line.diff-add[data-line], .diff-line.diff-del[data-line]");
+  return line ? Number(line.dataset.line) : null;
+}
+
+// A drag that selected text in the clicked ref's row isn't a click on the
+// ref. A selection elsewhere on the page (or a collapsed one) doesn't count.
+function selectingIn(owner, selection) {
+  if (!selection || selection.isCollapsed || !owner) return false;
+  return [selection.anchorNode, selection.focusNode].some((node) => node && owner.contains(node));
+}
+
+function defaultOpen(url) {
+  // The e2e seam (spec/e2e): a spec defines it before the page loads.
+  if (typeof window.__chiRefOpen === "function") window.__chiRefOpen(url);
+  else window.location.href = url;
+}
+
+// One delegated listener on +root+ for every ref on the page. +viewer+()
+// is read per click and hover, so a capabilities change (another session,
+// a reload) is seen; +open+(url) opens an action's URL.
+export function installRefClicks(root, viewer, { open = defaultOpen, selection = () => window.getSelection?.() } = {}) {
+  root.addEventListener("click", (e) => {
+    if (e.button !== 0 || e.defaultPrevented) return;
+    const target = refTarget(e.target);
+    if (!target) return;
+    const action = refAction(target.kind, viewer());
+    if (!action) return;
+    if (selectingIn(target.owner, selection())) return;
+    const url = action.url(target, viewer());
+    if (!url) return;
+    e.preventDefault();
+    e.stopPropagation();
+    open(url);
+  });
+  // The hover hint, on the ref's own element, worked out on each hover
+  // (the viewer can change): its own title (a row title's hover) first,
+  // then the action's hint when there is one.
+  root.addEventListener("mouseover", (e) => {
+    const target = refTarget(e.target);
+    if (!target) return;
+    const el = e.target.closest("[data-ref-kind]") || e.target.closest(".diff-line[data-line]");
+    if (!el) return;
+    if (el.dataset.refTitle === undefined) el.dataset.refTitle = el.getAttribute("title") || "";
+    const own = el.dataset.refTitle;
+    const action = refAction(target.kind, viewer());
+    const title = [own, action ? action.hint(target) : ""].filter(Boolean).join("\n");
+    if (title) el.setAttribute("title", title);
+    else el.removeAttribute("title");
+  });
+}
+
+// The body's classes for +viewer+: refs-<kind> for each kind with an action.
+export function setRefKinds(body, viewer, actions = REF_ACTIONS) {
+  const kinds = availableKinds(viewer, actions);
+  for (const kind of Object.keys(actions)) body.classList.toggle(`refs-${kind}`, kinds.includes(kind));
+}

data/lib/samagotchi/web/public/restore.js

@@ -0,0 +1,81 @@
+// Pure helpers for a failed turn's prompt handed back (prompt_restored):
+// what goes back into this tab's composer, and when (a restore that comes
+// before its /turn ack waits for it). Split out of turn_events.js.
+
+import { clientLabel, isOwn, withImages } from "./turn_events.js";
+
+// What a prompt_restored (the worker rolled a failed turn back and handed its
+// prompt back) does in this tab: `refill` is the text for an empty composer,
+// only for a prompt this page sent (`sentIds`, its acks' enqueued_ids), so a
+// replay after a reload never refills stale text; `own`/`label` mark the
+// failed bubble shown again after the resync.
+export function restoreAction(event, { myId, sentIds, composerEmpty }) {
+  const origin = event?.origin || {};
+  const own = isOwn(origin.client_id, myId);
+  const sent = own && !!origin.enqueued_id && sentIds.has(origin.enqueued_id);
+  // The images go back as chips with the text.
+  return withImages({
+    refill: sent && composerEmpty ? event.prompt : null,
+    own,
+    label: own ? null : clientLabel(origin.client_id),
+  }, sent && composerEmpty ? event.images : null);
+}
+
+// A turn that fails fast can have its prompt_restored come over the stream
+// before the /turn ack names its enqueued_id: `early` (a Map) keeps such a
+// restore of this tab's own prompt by that id, and the ack takes it back
+// (restoreOnAck), so the prompt goes into the composer the ack would clear.
+export function keepEarlyRestore(event, early, { myId, sentIds }) {
+  const origin = event?.origin || {};
+  const id = origin.enqueued_id;
+  if (!isOwn(origin.client_id, myId) || !id || sentIds.has(id)) return false;
+  early.set(id, event);
+  return true;
+}
+
+// The ack's enqueued_id (already in sentIds) was restored early: what the
+// composer gets back (as restoreAction for an empty composer), else null.
+export function restoreOnAck(enqueuedId, early, { myId, sentIds }) {
+  const event = enqueuedId && early.get(enqueuedId);
+  if (!event) return null;
+  early.delete(enqueuedId);
+  return restoreAction(event, { myId, sentIds, composerEmpty: true });
+}
+
+// The /turn this kept entry was for failed: no ack comes, so nothing would
+// take it back. The whole map goes: this tab sends one turn at a time, so
+// every entry waits for an ack that is now never coming (an older one is
+// left over from a send that failed the same way).
+export function dropEarlyRestores(early) {
+  const count = early.size;
+  early.clear();
+  return count;
+}
+
+// The composer's text with a restored prompt put back into it: the restored
+// text alone when nothing is typed, else the typed text with the restored
+// prompt under it (the user typed between the restore and the ack; their
+// text must not be replaced).
+export function restoreInto(refill, current) {
+  const restored = String(refill ?? "");
+  const typed = String(current ?? "");
+  if (!restored) return typed;
+  if (!typed.trim()) return restored;
+  return `${typed.replace(/\n+$/, "")}\n${restored}`;
+}
+
+// What the composer holds once a /turn ack lands (4.13): the composer still
+// carries the text that was just sent, so that text goes (it is the history's
+// now) — but text typed since the send stays, and a prompt restored before
+// this ack (restoreOnAck's refill) is put back without replacing it. The
+// sent text is trimmed (turnText), so the composer's is too before they are
+// compared: a trailing newline or space must not keep the message; and an
+// image-only send (placeholders sent) leaves nothing worth keeping.
+// @param sent the text the turn was sent with
+// @param current the composer's text as the ack lands
+// @param refill the prompt an early restore handed back, if any
+export function composerAfterAck({ sent = "", current = "", refill = "" } = {}) {
+  const typed = String(current ?? "").trim();
+  const kept = !typed || typed === String(sent ?? "").trim() ? "" : current;
+  return restoreInto(refill, kept);
+}

data/lib/samagotchi/web/public/session_state.js

@@ -4,6 +4,8 @@
 // the previous session set, its "delegated by" parent, its commands, never
 // shows for the next one).
 
+import { savedCtxPct } from "./ctx.js";
+import { firstPreview, previewForCard } from "./format.js";
 import { normalizeTiming } from "./timing.js";
 
 export function emptySessionState() {
@@ -46,3 +48,53 @@ export function emptySessionState() {
     timing: normalizeTiming(),
   };
 }
+
+// The fields a session's payload (GET /sessions/:id) sets, read from it
+// alone. ctxPct is left out when the payload has no saved fill, ctxWindow
+// and ctxWindowSource when it has no window: the page keeps what it had
+// (a running turn's replay streams over it).
+export function sessionStateFrom(data) {
+  const s = data.session;
+  const state = {
+    status: s.status,
+    model: s.model_name,
+    served: s.served_model ? [s.served_model, s.served_model_for, s.served_expected_by || null] : null,
+    dir: s.working_directory,
+    owner: s.owner || null,
+    timing: normalizeTiming(data.timing),
+  };
+  // The saved fill, so a reloaded or stopped session shows it before its
+  // next turn.
+  const savedPct = savedCtxPct(data.timing?.context, s.llm_context?.budget_tokens);
+  if (savedPct !== null) state.ctxPct = savedPct;
+  if (data.timing?.context?.window_tokens) {
+    state.ctxWindow = data.timing.context.window_tokens;
+    state.ctxWindowSource = data.timing.context.window_source || null;
+  }
+  state.firstPreview = sessionFirstPreview(data);
+  state.usedMemories = s.used_memory_names || [];
+  state.preloadedMemories = s.preloaded_memory_names || [];
+  state.mutedMemories = s.muted_memory_names || [];
+  state.promptNotes = Array.isArray(s.prompt_notes) ? s.prompt_notes : [];
+  state.llmContext = s.llm_context || null;
+  state.thinking = s.thinking || null;
+  state.parentId = s.parent_id || null;
+  state.continues = s.continues || null;
+  state.commands = Array.isArray(data.commands) ? data.commands : [];
+  return state;
+}
+
+// The info bar's title: the first user message when the payload has
+// messages, else the card's preview, else the first prompt of its history.
+function sessionFirstPreview(data) {
+  const s = data.session;
+  let preview = s.first_preview || previewForCard(s);
+  if (data.messages && data.messages.length) {
+    const first = data.messages.find((m) => m.role === "user");
+    if (first && first.content) preview = firstPreview(first.content);
+  } else if (!preview && data.history && data.history.length) {
+    const txt = firstPreview(data.history[0]);
+    if (txt) preview = txt;
+  }
+  return preview;
+}

data/lib/samagotchi/web/public/stream_handlers.js

@@ -0,0 +1,324 @@
+// The open session's stream event handlers (GET /stream's typed events, by
+// type); renderSessionView replays a snapshot through them too. Split out
+// of app.js; no markup of its own: the page passes its views and hooks.
+//
+// Everything that changes while the page runs is read through deps at the
+// event, never captured at creation: the open session (selected()), its
+// fields (state(): resetSessionState replaces the object), the page's
+// capabilities, the composer's text. A session switch mid-stream is handled
+// as before: the handlers act on whatever is open when the event comes.
+//
+// deps:
+//   selected()            the open session's id, or null
+//   state()               the open session's fields (session_state.js)
+//   clientId              this tab's id (own prompts and commands)
+//   capabilities()        the page's capabilities (card.js shownElsewhere)
+//   historyEl             the history element (keepFollowing, the failed-turn redraw)
+//   liveTurn, turnDom, shownTexts, questionCards, contextChips,
+//   llmContextControl, thinkingControl      the page's views
+//   sentIds, earlyRestores                  restore.js's bookkeeping
+//   stream: {takeGuess(), restart()}        the stream was opened from a
+//                         guess (takeGuess: whether, and forget it); restart:
+//                         close the stream and resync
+//   composer: {empty(), refill(text), setChips(chips)}
+//   getSession(id, opts)  data.js
+//   resync(), updateInfoBar(), applyPromptOps(data), showSteers(steers),
+//   markRecapStale(), setTurnRunning(running), setLiveStatus(status),
+//   endTurnView(kind, endText, opts), appendChunk(text), readTurnEnd(),
+//   applyFinalMarkdown(messages), refreshTimingFromSession(),
+//   makeUserBubble(prompt, opts), addEndBubble(text), commandBubble(id),
+//   addCommandBubble(view), addNoteBubble(note), findInTurnRoots(selector),
+//   setUsedMemories(names), showRecap(text), showGuardrailWarning(text, label),
+//   showHookNotice(data), onInitEvent(type, data), upsertCard(card),
+//   refreshCardBodies()   the page's hooks
+
+import { routeChunk } from "./chunk_router.js";
+import { extractCtxPct, generationTokens } from "./ctx.js";
+import { failedTurnText } from "./format.js";
+import { cancelLineText } from "./timing.js";
+import { keepFollowing } from "./scroll.js";
+import { shownElsewhere } from "./card.js";
+import { restoredChips } from "./images.js";
+import {
+  clientLabel, displayWait, emptyRetryLine, initWaitLine, isOwn, llmContextNotice, reminderText, replaysDrawnTurn,
+  retryStatusLine, steerCutLine, turnOutput,
+} from "./turn_events.js";
+import { commandView, drawCommandBubble, historyHasCommandBubble } from "./commands.js";
+import { keepEarlyRestore, restoreAction } from "./restore.js";
+
+export function createStreamHandlers(deps) {
+  const {
+    selected, state, clientId, capabilities, historyEl,
+    liveTurn, turnDom, shownTexts, questionCards, contextChips, llmContextControl, thinkingControl,
+    sentIds, earlyRestores, stream, composer, getSession,
+    resync, updateInfoBar, applyPromptOps, showSteers, markRecapStale, setTurnRunning, setLiveStatus, endTurnView,
+    appendChunk, readTurnEnd, applyFinalMarkdown, refreshTimingFromSession, makeUserBubble, addEndBubble,
+    commandBubble, addCommandBubble, addNoteBubble, findInTurnRoots, setUsedMemories, showRecap,
+    showGuardrailWarning, showHookNotice, onInitEvent, upsertCard, refreshCardBodies,
+  } = deps;
+
+  return {
+    generation_chunk: (data) => {
+      // Route the chunk's bytes to the text bubble and the thinking block (see
+      // chunk_router.js). Raw `content` is only a fallback for an older server.
+      const { text, thinking } = routeChunk(data);
+      liveTurn.timing.setNote("");
+      turnDom.chunk({ text, thinking, iteration: data.iteration ?? null });
+      const current = state();
+      const pct = extractCtxPct(data, current.ctxWindow, current.llmContext?.budget_tokens);
+      if (pct !== null && !Number.isNaN(pct)) {
+        current.ctxPct = pct;
+        updateInfoBar();
+      }
+    },
+    generation_started: (data) => {
+      if (data?.context_window_tokens) {
+        const current = state();
+        current.ctxWindow = data.context_window_tokens;
+        current.ctxWindowSource = data.context_window_source || null;
+      }
+      liveTurn.timing.setNote("");
+      turnDom.generationStarted(data || {});
+    },
+    generation_completed: (data) => {
+      liveTurn.timing.setNote("");
+      const current = state();
+      if (data?.served_model) current.served = [data.served_model, data.requested_model, data.served_expected_by || null];
+      // The generation's speed and the session's token totals, from the server.
+      current.timing.tokens = generationTokens(current.timing.tokens, data);
+      if (data?.served_model || data?.tokens) updateInfoBar();
+      turnDom.generationCompleted();
+    },
+    // Prompts sent while a turn ran merge into it at an iteration boundary:
+    // input_merged names them (their bubbles turn "steered"), then
+    // pending_input_merged carries the merged text, shown only for prompts
+    // this tab has no bubble for. Its `answer` (the answer the merge
+    // superseded) is the TUI's line: here it streamed as that step's text.
+    input_merged: (data) => applyPromptOps(data),
+    pending_input_merged: (data) => {
+      applyPromptOps(data);
+      showSteers(data.steers);
+    },
+    turn_enqueued: (data) => applyPromptOps(data),
+    turn_started: (data) => keepFollowing(historyEl, () => {
+      if (stream.takeGuess()) {
+        // A replay of a turn the render drew: re-read and stream from there.
+        if (replaysDrawnTurn(data, state().timing.turnRecords)) {
+          stream.restart();
+          return;
+        }
+      }
+      // A finished turn still in the stage goes first: the start op looks
+      // for a queued prompt among its rows.
+      turnDom.handOff?.({ immediate: true });
+      markRecapStale();
+      shownTexts.turnStarted();
+      const promptBubble = applyPromptOps(data);
+      setTurnRunning(true);
+      setLiveStatus("running");
+      liveTurn.timing.detach();
+      turnDom.turnStarted({ ...data, promptBubble });
+      liveTurn.timing.start(data.started_at, data.turn_id || null);
+    }),
+    turn_completed: async (data) => {
+      endTurnView("completed", null, { emptyAnswer: data.turn_summary?.empty_answer || null });
+      const out = turnOutput(data);
+      if (out) appendChunk(out);
+      // after_turn hooks are running and may present the answer: its
+      // answer_display (display: null when they didn't) comes next. A worker
+      // that dies before it never sends one: workerGone releases the wait, and
+      // displayWait's timeout ends it whatever happens (4.14).
+      const display = data.display_pending ? displayWait() : null;
+      if (display) liveTurn.displayPending = display;
+      liveTurn.endRead = readTurnEnd();
+      await liveTurn.endRead;
+      // The answer bubble the turn view held at its box's height pops now
+      // that the rendered markdown is in it (or the re-read failed: then the
+      // plain text pops), and the display if one was coming, so the links
+      // never swap in after the pop. The hold reveals by itself after
+      // HOLD_MS whatever comes. The stage has no hold.
+      if (display) await display.promise;
+      turnDom.answerReady?.();
+    },
+    // An after_turn hook presented the answer (AnswerDisplay): it comes after
+    // turn_completed, so re-read the answer once that read is done.
+    answer_display: async (data) => {
+      try {
+        await liveTurn.endRead;
+        if (!selected() || !data.display) return;
+        const d = await getSession(selected(), { tail: true, recent: true });
+        if (Array.isArray(d.messages)) applyFinalMarkdown(d.messages);
+      } catch (_) {
+      } finally {
+        liveTurn.releaseDisplay();
+      }
+    },
+    turn_canceled: (data) => {
+      endTurnView("canceled", cancelLineText(data.cancellation_reason || "", data.cancelled_by), { stopped: true });
+      setLiveStatus("idle");
+      refreshTimingFromSession();
+    },
+    // The turn raised (e.g. the model server stayed unreachable). The worker
+    // stays up: it rolls the turn back and hands the prompt back
+    // (prompt_restored), and the prompts queued behind it run as usual. A turn
+    // that got to tool steps stays as it is (kept_steps; no prompt_restored).
+    turn_failed: (data) => {
+      const text = failedTurnText(data);
+      // Only a rolled-back turn's line waits for its prompt_restored.
+      liveTurn.failedText = Number.isInteger(data.kept_steps) ? null : text;
+      endTurnView("failed", text);
+      setLiveStatus("idle");
+    },
+    // The rolled-back turn left the session: render it from the server again,
+    // then show the prompt once more, marked failed (with why). This tab's own
+    // prompt goes back into an empty composer.
+    prompt_restored: async (data) => {
+      keepEarlyRestore(data, earlyRestores, { myId: clientId, sentIds });
+      const { refill, label, images: restoredImages } = restoreAction(data, { myId: clientId, sentIds, composerEmpty: composer.empty() });
+      if (refill) composer.refill(refill);
+      if (restoredImages?.length) composer.setChips(restoredChips(selected(), restoredImages));
+      const failedText = liveTurn.failedText;
+      liveTurn.failedText = null;
+      await resync();
+      // The re-render drew it from the session (failed_turn): drawn again
+      // below with this event's label and images.
+      const drawn = historyEl.querySelector(".bubble.user[data-failed-turn]");
+      if (drawn) {
+        if (drawn.nextElementSibling?.classList.contains("cancel")) drawn.nextElementSibling.remove();
+        drawn.remove();
+      }
+      // Not an echo waiting for its turn_enqueued: it keeps its enqueued_id, so
+      // a resend's echo isn't matched to it.
+      makeUserBubble(data.prompt || "", { state: "failed", label, enqueuedId: data.origin?.enqueued_id || `failed:${Date.now()}`, images: data.images });
+      if (failedText) addEndBubble(failedText);
+    },
+    // A session command ran in the worker (any client's). One that changed
+    // the conversation (!rollback, !cmd, a continue answered no) re-reads it.
+    command_ran: async (data) => {
+      const view = commandView(data, clientId);
+      if (view.modelName && view.modelName !== state().model) {
+        state().model = view.modelName;
+        state().served = null;
+        updateInfoBar();
+      }
+      // /llm-context changed what the next turn runs under.
+      if (data.llm_context) {
+        state().llmContext = data.llm_context;
+        updateInfoBar();
+        llmContextControl.refresh();
+      }
+      // /thinking (or /model) changed the level the next turn runs at.
+      if (data.thinking) {
+        state().thinking = data.thinking;
+        updateInfoBar();
+        thinkingControl.refresh();
+      }
+      if (view.resync) await resync();
+      // A card's action that isn't anytime (the step-limit question's
+      // /continue) has no bubble: nothing to remove. An anytime or queued
+      // one's bubble was drawn at its command_queued: filled in here. One
+      // queued for after the turn ran after it: its bubble moves from among
+      // the turn's rows to after its answer and timing line.
+      const queued = view.anytime || view.queued ? commandBubble(view.commandId) : null;
+      if (view.hidden) queued?.remove();
+      else if (queued && view.queued && !view.anytime) {
+        queued.remove();
+        addCommandBubble(view);
+      } else if (queued) drawCommandBubble(queued, view);
+      // A command that changed the conversation (!cmd): the redrawn history
+      // ends with its command bubble already (the saved "!(…)\n<output>"
+      // message renders as one) — no second bubble, or the output shows twice.
+      else if (view.resync && historyHasCommandBubble(findInTurnRoots(".bubble.command"), view.line)) { /* drawn by the resync */ }
+      else addCommandBubble(view);
+    },
+    // An anytime command (/help, a plugin's /btw) runs at once, beside a
+    // turn: its bubble goes here, so the cards it shows come after it. One
+    // queued for after the turn (/model X mid-turn) shows waiting here.
+    command_queued: (data) => {
+      // A card's action waits for its command_ran: shown only if it answers.
+      if ((data.anytime || data.waits) && !data.card && !commandBubble(data.command_id)) addCommandBubble(commandView(data, clientId));
+    },
+    // Due reminders went into the turn (a reminder turn has no prompt bubble).
+    reminder_injected: (data) => addCommandBubble({ label: null, line: reminderText(data), text: "" }),
+    // A context note joined the conversation (between turns; no turn runs).
+    context_added: (data) => {
+      addNoteBubble({ label: data.label, content: data.text || "" });
+      // An attached context source's note: its chip changed.
+      if (data.context_source) contextChips.refresh();
+    },
+    continue_offered: (data) => questionCards.renderContinue(data),
+    continue_resolved: (data) => questionCards.resolveContinue(data),
+    tool_call_started: (data) => turnDom.toolStarted(data),
+    tool_call_completed: (data) => turnDom.toolCompleted(data),
+    // The engine's list, after every memory read and at a turn's end.
+    used_memories_updated: (data) => {
+      if (Array.isArray(data.used_memory_names)) setUsedMemories(data.used_memory_names);
+    },
+    context_status: (data) => {
+      const current = state();
+      const pct = extractCtxPct(data, current.ctxWindow, current.llmContext?.budget_tokens);
+      if (pct !== null) {
+        current.ctxPct = pct;
+        updateInfoBar();
+      }
+    },
+    question_requested: (data) => {
+      const pq = data.pending_question;
+      if (pq && pq.id) questionCards.renderQuestion(pq);
+    },
+    question_answered: (data) => {
+      questionCards.resolveQuestion(data.id, { answer: data.answer });
+    },
+    // A delegate's question relayed to its parent's card, or no longer.
+    question_relay: (data) => questionCards.markRelayed(data.id, data.relayed_to),
+    question_cancelled: (data) => {
+      questionCards.resolveQuestion(data.id, { cancelled: true, reason: data.reason });
+    },
+    // One collected just as a turn started describes the chat before it.
+    recap_ready: (data) => {
+      // After the turn it covers, never above it.
+      turnDom.handOff?.({ immediate: true });
+      if (!liveTurn.running) showRecap(data.recap);
+    },
+    guardrail_warning: (data) => showGuardrailWarning(data.message, data.label || "guardrails"),
+    // A notice during a turn is a row of its current step. One the page
+    // shows elsewhere (a hook's links in the rendered answer) isn't drawn,
+    // not even in the stage trail; a joined turn's notices come here too.
+    hook_notice: (data) => {
+      if (shownElsewhere(data, capabilities())) return;
+      if (!turnDom.notice(data)) showHookNotice(data);
+    },
+    // The loop asks again after an empty answer: a row of the empty step
+    // (a reload puts it back from the snapshot's cards).
+    empty_answer_retry: (data) => { turnDom.notice({ line: emptyRetryLine(data) }); },
+    steer_cut: (data) => { turnDom.notice({ line: steerCutLine(data), cls: "steer-cut" }); },
+    // A batch of LLM context edits the server applied: a ✂ row of the
+    // current step, its hover listing the outputs.
+    llm_context_edited: (data) => { turnDom.notice(llmContextNotice(data)); },
+    // The provider is asked again after an error, or the turn waits for
+    // plugins' setup: a note on the live timing line until it streams.
+    generation_retrying: (data) => {
+      // A dropped stream's step asked again: what it streamed is void.
+      if (data?.restarted) turnDom.generationRestarted(data);
+      liveTurn.timing.setNote(retryStatusLine(data));
+    },
+    plugin_init_wait: (data) => liveTurn.timing.setNote(initWaitLine(data)),
+    plugin_init_started: (data) => onInitEvent("plugin_init_started", data),
+    plugin_init_finished: (data) => onInitEvent("plugin_init_finished", data),
+    // A plugin's card, or a new version of one (the same id).
+    card: (data) => {
+      upsertCard(data);
+      if (data.body) refreshCardBodies();
+    },
+    // The stream's cursor could not be replayed: render from scratch.
+    reset: () => resync(),
+    // Synthetic (snapshotEvents): a prompt merged into the turn in progress.
+    merged_input: (data) => {
+      const origin = (data.origins || [])[0] || {};
+      const own = isOwn(origin.client_id, clientId);
+      makeUserBubble(data.content, {
+        state: "steered", own, enqueuedId: origin.enqueued_id || null, label: own ? null : clientLabel(origin.client_id),
+      });
+    },
+  };
+}