cortena-ui 1.4.2 → 1.6.0

package/src/agent-chat/store.ts

@@ -0,0 +1,1234 @@
+"use client";
+
+/**
+ * The chat state, and the hook that drives an `AgentChatClient` from React.
+ *
+ * The accumulation rules are ported from `cortena-shared/src/stores/use-chat.ts`
+ * (Cortena monorepo) so a run leaves this state in the same place it leaves
+ * cortenaweb's. The ones that are not obvious, and that a rewrite gets wrong:
+ *
+ * - A `delta` carries a snapshot, so text and A2UI blocks are **replaced**, not
+ *   appended. Appending doubles every character.
+ * - Thinking is never replaced by something shorter. The upstream emitter can
+ *   fall back to increments when a snapshot is unavailable, and treating one of
+ *   those as a snapshot truncates the accumulated chain of thought.
+ * - On `final`, a second assistant message in the same turn folds the previous
+ *   visible text into the chain of thought rather than adding a second bubble,
+ *   and keeps the A2UI blocks of the message it folded away — the surface is
+ *   still on screen and still interactive.
+ * - A reply that is only a drawn surface has no text, so `text || a2ui.length`
+ *   is the test for "there is something to show". Testing text alone silently
+ *   dropped everything the agent drew.
+ */
+
+import * as React from "react";
+import { type A2UIChatBlock, extractA2UIBlocks, foldA2UIBlocks } from "./a2ui-block";
+import {
+  isProvisionalSessionKey,
+  isSessionOfAgent,
+  mintSessionKey,
+  parseHistoryMessages,
+  readStoredSessionKey,
+  readStoredSteps,
+  separateThinking,
+  STEP_LIMIT,
+  wouldShrinkHistory,
+  writeStoredSessionKey,
+  writeStoredSteps,
+} from "./session";
+import { confirmationRequiredLabel, isGenericLabel, stepLabel, truncate } from "./step-label";
+import type {
+  AgentApprovalDecision,
+  AgentApprovalRequest,
+  AgentChatClient,
+  AgentChatEvent,
+  AgentChatHistoryResponse,
+  AgentChatMessage,
+  AgentChatStep,
+  AgentSession,
+  AgentSessionsListResponse,
+  AgentToolEvent,
+  AgentToolResultMeta,
+  AgentToolResultMetadata,
+} from "./types";
+
+export interface AgentToolEntry {
+  id: string;
+  name: string;
+  status: "running" | "complete" | "error";
+  input?: unknown;
+  output?: unknown;
+  startedAt: number;
+  completedAt?: number;
+}
+
+export interface AgentChatState {
+  sessionKey: string | null;
+  messages: AgentChatMessage[];
+  streaming: boolean;
+  streamText: string;
+  streamThinkingText: string;
+  streamA2ui: A2UIChatBlock[];
+  runId: string | null;
+  hasMoreHistory: boolean;
+  loadingHistory: boolean;
+  toolOrder: string[];
+  tools: Record<string, AgentToolEntry>;
+  /**
+   * The turn's tool calls in plain words, in arrival order (SKILLS-9).
+   *
+   * The same calls as `tools`, worded rather than dumped, and rendered under
+   * the assistant turn instead of in the strip at the foot. Cleared when the
+   * next run starts, so the list is always "what is happening now" or "what
+   * just happened", never a transcript.
+   */
+  steps: AgentChatStep[];
+  /**
+   * Ids of steps the `STEP_LIMIT` cap has already dropped.
+   *
+   * A runaway turn pushes the first calls off the front of the list, and their
+   * results arrive afterwards. Without this the store saw an id it did not
+   * know, took it for a call nobody announced, and appended a fresh
+   * "Working: tool" line at the BOTTOM of the strip — the oldest call in the
+   * turn, drawn as the newest, with no words on it. Bounded, because it exists
+   * to recognise a handful of stragglers, not to keep a transcript.
+   */
+  retiredSteps: string[];
+  approvals: AgentApprovalRequest[];
+  /**
+   * Transcript RECORDS loaded, which is not `messages.length`.
+   *
+   * `parseHistoryMessages` folds a turn — an assistant preamble, the tool call,
+   * the tool result, the answer — into one visible message, so the two numbers
+   * diverge on the very first agent turn. `offset` is an offset into the
+   * server's records, and paging with the folded count asked for records the
+   * screen already had and skipped the ones it did not: "load older" silently
+   * lost messages the further back a user read.
+   */
+  historyCount: number;
+  sessions: AgentSession[];
+  loadingSessions: boolean;
+  /** A failure the user has to be told about, e.g. no template for the slug. */
+  error: string | null;
+}
+
+const EMPTY: AgentChatState = {
+  sessionKey: null,
+  messages: [],
+  streaming: false,
+  streamText: "",
+  streamThinkingText: "",
+  streamA2ui: [],
+  runId: null,
+  hasMoreHistory: false,
+  loadingHistory: false,
+  toolOrder: [],
+  tools: {},
+  steps: [],
+  retiredSteps: [],
+  approvals: [],
+  historyCount: 0,
+  sessions: [],
+  loadingSessions: false,
+  error: null,
+};
+
+type Action =
+  | { kind: "chat"; event: AgentChatEvent }
+  | { kind: "tool"; event: AgentToolEvent }
+  | { kind: "approval/request"; request: AgentApprovalRequest }
+  | { kind: "approval/resolved"; id: string }
+  | { kind: "approval/denied"; id: string }
+  | { kind: "approval/failed"; request: AgentApprovalRequest; message: string }
+  | { kind: "session"; key: string | null }
+  | { kind: "send"; message: AgentChatMessage | null; runId: string; sessionKey: string }
+  | { kind: "send/failed"; message: string }
+  | { kind: "abort" }
+  | { kind: "history/loading" }
+  | {
+      kind: "history/loaded";
+      sessionKey: string;
+      messages: AgentChatMessage[];
+      hasMore: boolean;
+      records: number;
+    }
+  | { kind: "history/older"; messages: AgentChatMessage[]; hasMore: boolean; records: number }
+  | { kind: "history/failed" }
+  | { kind: "sessions/loading" }
+  | { kind: "sessions/loaded"; sessions: AgentSession[] }
+  | { kind: "steps/restored"; steps: AgentChatStep[] }
+  | { kind: "error"; message: string | null };
+
+function generateId(): string {
+  return `msg-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+
+function extractText(message?: AgentChatEvent["message"]): string {
+  return (message?.content ?? [])
+    .filter((c) => c.type === "text" && c.text)
+    .map((c) => c.text!)
+    .join("");
+}
+
+function extractThinking(message?: AgentChatEvent["message"]): string {
+  const blocks = (message?.content ?? [])
+    .filter((c) => c.type === "thinking")
+    .map((c) => c.thinking ?? c.text ?? "")
+    .filter(Boolean);
+  return blocks.join("\n\n");
+}
+
+function reduce(state: AgentChatState, action: Action): AgentChatState {
+  switch (action.kind) {
+    case "chat":
+      return reduceChat(state, action.event);
+    case "tool":
+      return reduceTool(state, action.event);
+    case "approval/request":
+      return state.approvals.some((r) => r.id === action.request.id)
+        ? state
+        : { ...state, approvals: [...state.approvals, action.request] };
+    case "approval/resolved":
+      return { ...state, approvals: state.approvals.filter((r) => r.id !== action.id) };
+    case "approval/denied":
+      // The user said no. The call the run paused on is never going to happen,
+      // so it stops waiting — `stopped`, not `error`, for the same reason the
+      // Stop button is: nothing failed. Steps still RUNNING are untouched; a
+      // deny answers one question, it does not end the rest of the turn.
+      return {
+        ...state,
+        approvals: state.approvals.filter((r) => r.id !== action.id),
+        steps: endRunningSteps(state.steps, { kind: "denied" }),
+      };
+    case "approval/failed":
+      // The decision did not land, so the card comes back — with the reason on
+      // it. Removing it optimistically and then swallowing the failure left
+      // the user certain they had answered and the run paused for ever.
+      return state.approvals.some((r) => r.id === action.request.id)
+        ? state
+        : {
+            ...state,
+            approvals: [...state.approvals, { ...action.request, error: action.message }],
+          };
+    case "session":
+      return action.key === state.sessionKey
+        ? state
+        : { ...EMPTY, sessions: state.sessions, sessionKey: action.key };
+    case "send":
+      return {
+        ...state,
+        sessionKey: action.sessionKey,
+        messages: action.message ? [...state.messages, action.message] : state.messages,
+        streaming: true,
+        streamText: "",
+        streamThinkingText: "",
+        streamA2ui: [],
+        runId: action.runId,
+        toolOrder: [],
+        tools: {},
+        // The steps of the previous turn describe work that is over. Leaving
+        // them under the next answer reads as though the agent were still
+        // doing them.
+        steps: [],
+        retiredSteps: [],
+        // A new run is a new set of pending decisions. An approval card left
+        // over from the previous run points at a run that is over, and
+        // answering it sends a decision nothing is waiting for.
+        approvals: [],
+        error: null,
+      };
+    case "send/failed":
+      return {
+        ...state,
+        streaming: false,
+        runId: null,
+        messages: [
+          ...state.messages,
+          {
+            id: generateId(),
+            role: "assistant",
+            text: action.message,
+            timestamp: Date.now(),
+            isError: true,
+          },
+        ],
+      };
+    case "abort":
+      // Reset immediately so the composer flips Stop -> Send without waiting on
+      // a server event an aborted run does not reliably send.
+      return {
+        ...state,
+        streaming: false,
+        streamText: "",
+        streamThinkingText: "",
+        streamA2ui: [],
+        runId: null,
+        // The run they belonged to is gone; the decisions go with it.
+        approvals: [],
+        // A stopped run sends no end event for the call in flight, so a step
+        // left running spins for ever under an answer that will never come.
+        // Stopped, not failed: the user asked for it.
+        steps: endRunningSteps(state.steps, { kind: "stopped" }),
+      };
+    case "history/loading":
+      return { ...state, loadingHistory: true };
+    case "history/loaded":
+      if (
+        wouldShrinkHistory({
+          currentSessionKey: state.sessionKey,
+          loadedSessionKey: action.sessionKey,
+          currentCount: state.messages.length,
+          loadedCount: action.messages.length,
+        })
+      ) {
+        return {
+          ...state,
+          sessionKey: action.sessionKey,
+          hasMoreHistory: action.hasMore,
+          loadingHistory: false,
+          historyCount: action.records,
+        };
+      }
+      return {
+        ...state,
+        sessionKey: action.sessionKey,
+        messages: action.messages,
+        hasMoreHistory: action.hasMore,
+        loadingHistory: false,
+        historyCount: action.records,
+        // Avoids an orphan streaming bubble beside reloaded history.
+        streaming: false,
+        streamText: "",
+        streamThinkingText: "",
+        streamA2ui: [],
+      };
+    case "history/older":
+      return {
+        ...state,
+        messages: [...action.messages, ...state.messages],
+        hasMoreHistory: action.hasMore,
+        loadingHistory: false,
+        historyCount: state.historyCount + action.records,
+      };
+    case "history/failed":
+      return { ...state, loadingHistory: false };
+    case "sessions/loading":
+      return { ...state, loadingSessions: true };
+    case "sessions/loaded":
+      return { ...state, sessions: action.sessions, loadingSessions: false };
+    case "steps/restored":
+      // Only ever into an empty strip. A restore that arrives after the user
+      // has already started a new run would otherwise resurrect the last one.
+      return state.steps.length > 0 ? state : { ...state, steps: action.steps.slice(-STEP_LIMIT) };
+    case "error":
+      return { ...state, error: action.message };
+    default:
+      return state;
+  }
+}
+
+function reduceChat(state: AgentChatState, event: AgentChatEvent): AgentChatState {
+  // Events from another session are dropped, or one window's run leaks into
+  // another window's transcript. A provisional key is the exception: the server
+  // echoes it back today, but if it ever canonicalised the key instead, dropping
+  // the event would silently kill the whole first turn.
+  if (event.sessionKey && state.sessionKey && event.sessionKey !== state.sessionKey) {
+    if (!isProvisionalSessionKey(state.sessionKey)) {
+      return state;
+    }
+    state = { ...state, sessionKey: event.sessionKey };
+  } else if (event.sessionKey && !state.sessionKey) {
+    state = { ...state, sessionKey: event.sessionKey };
+  }
+
+  switch (event.state) {
+    case "delta": {
+      const text = extractText(event.message);
+      const thinking = extractThinking(event.message);
+      const a2ui = extractA2UIBlocks(event.message);
+      const next: AgentChatState = { ...state, streaming: true };
+      if (text) {
+        next.streamText = text;
+      }
+      if (a2ui.length > 0) {
+        next.streamA2ui = a2ui;
+      }
+      // Never replace accumulated thinking with something shorter.
+      const acceptThinking = !!thinking && thinking.length >= state.streamThinkingText.length;
+      if (acceptThinking) {
+        next.streamThinkingText = thinking;
+      }
+      return text || acceptThinking || a2ui.length > 0 ? next : state;
+    }
+    case "final": {
+      const finalText = extractText(event.message);
+      const finalThinking = extractThinking(event.message);
+      const finalA2ui = extractA2UIBlocks(event.message);
+      const text = finalText || state.streamText;
+      const thinkingFromBlocks = finalThinking || state.streamThinkingText;
+      const a2ui = foldA2UIBlocks(finalA2ui.length > 0 ? finalA2ui : state.streamA2ui);
+      // The run id deliberately SURVIVES a final. A run can end more than
+      // once — an interrupt for an approval, then the continuation — and
+      // clearing it here meant the second final saw `runId: null`, could not
+      // fold, and pushed a second bubble: one answer to one question, drawn
+      // as two. `send` sets the next run's id, and `abort`, `error` and
+      // `send/failed` each clear it, so nothing outlives the turn it belongs
+      // to.
+      const cleared = {
+        streaming: false,
+        streamText: "",
+        streamThinkingText: "",
+        streamA2ui: [] as A2UIChatBlock[],
+        // The run is over, so nothing is still running. A result event can go
+        // missing — a reconnect drops the tail — and the spinner then outlived
+        // the answer it was drawn beside. The label is untouched: a plain
+        // RUN_FINISHED means the run succeeded, so the step did too.
+        //
+        // An INTERRUPT is not that. cortenacore ends the run to ask for an
+        // approval or to hand a frontend tool to the client, and the tool call
+        // is still open: the continuation is a second run that ends it. Ticking
+        // it here claimed a write had gone through while the card asking
+        // permission for it was still on screen.
+        steps: endRunningSteps(
+          state.steps,
+          event.interrupted ? { kind: "paused" } : { kind: "finished" },
+        ),
+      };
+
+      if (!text && a2ui.length === 0) {
+        // No text and nothing drawn: fold whatever thinking accumulated into
+        // the previous turn rather than dropping it.
+        const accumulated = state.streamThinkingText;
+        const last = state.messages[state.messages.length - 1];
+        if (!accumulated || !foldsInto(last, state.runId)) {
+          return { ...state, ...cleared };
+        }
+        const messages = [...state.messages];
+        messages[messages.length - 1] = {
+          ...last,
+          timestamp: Date.now(),
+          thinkingText: [last.thinkingText ?? "", accumulated].filter(Boolean).join("\n\n"),
+        };
+        return { ...state, ...cleared, messages };
+      }
+
+      const { thinkingText: tagThinking, mainText } = separateThinking(text);
+      const thinkingText = thinkingFromBlocks || tagThinking;
+      const displayText = thinkingFromBlocks ? text : mainText;
+      const messages = [...state.messages];
+      const last = messages[messages.length - 1];
+
+      if (foldsInto(last, state.runId)) {
+        const combined = [last.thinkingText ?? "", last.text.trim()].filter(Boolean).join("\n\n");
+        const updated = [combined, thinkingText].filter(Boolean).join("\n\n");
+        messages[messages.length - 1] = {
+          ...last,
+          text: displayText,
+          timestamp: Date.now(),
+          ...(updated ? { thinkingText: updated } : { thinkingText: undefined }),
+          ...(a2ui.length > 0 || last.a2ui?.length
+            ? { a2ui: foldA2UIBlocks([...(last.a2ui ?? []), ...a2ui]) }
+            : {}),
+        };
+      } else {
+        messages.push({
+          id: generateId(),
+          role: "assistant",
+          text: displayText,
+          timestamp: Date.now(),
+          // The run this bubble belongs to, so the NEXT run's `final` cannot
+          // fold its answer into it.
+          ...(state.runId ? { runId: state.runId } : {}),
+          ...(thinkingText ? { thinkingText } : {}),
+          ...(a2ui.length > 0 ? { a2ui } : {}),
+        });
+      }
+      return { ...state, ...cleared, messages };
+    }
+    case "error":
+      return {
+        ...state,
+        streaming: false,
+        streamText: "",
+        streamThinkingText: "",
+        streamA2ui: [],
+        runId: null,
+        // A RUN_ERROR is the end of every call still in flight, whether or not
+        // the transport got round to sending a result for it.
+        steps: endRunningSteps(state.steps, {
+          kind: "failed",
+          message: truncate(event.errorMessage ?? "The run failed.", ERROR_LIMIT),
+        }),
+        messages: [
+          ...state.messages,
+          {
+            id: generateId(),
+            role: "assistant",
+            text: event.errorMessage ?? "An error occurred",
+            timestamp: Date.now(),
+            isError: true,
+          },
+        ],
+      };
+    default:
+      return state;
+  }
+}
+
+/**
+ * May a `final` fold into this message?
+ *
+ * Only when it is an assistant bubble from the SAME run. Two assistant
+ * messages in one turn are one answer with an interruption in the middle, and
+ * folding them is right. Two assistant messages from different runs are two
+ * answers to two questions, and folding them rewrote the earlier answer with
+ * the later one — visibly, in a transcript the user had already read.
+ *
+ * A message with no `runId` is history, which never folds either.
+ */
+function foldsInto(
+  last: AgentChatMessage | undefined,
+  runId: string | null,
+): last is AgentChatMessage {
+  return (
+    last !== undefined &&
+    last.role === "assistant" &&
+    !last.isError &&
+    runId !== null &&
+    last.runId === runId
+  );
+}
+
+function reduceTool(state: AgentChatState, event: AgentToolEvent): AgentChatState {
+  const id = event.data.id;
+  if (!id) {
+    return state;
+  }
+  const existing = state.tools[id];
+  const base: AgentToolEntry = existing ?? {
+    id,
+    name: event.data.name ?? "tool",
+    status: "running",
+    startedAt: event.data.startedAt ?? Date.now(),
+  };
+  let entry: AgentToolEntry;
+  switch (event.event) {
+    case "tool.start":
+      entry = { ...base, name: event.data.name ?? base.name, status: "running" };
+      break;
+    case "tool.args":
+      entry = { ...base, input: event.data.input };
+      break;
+    case "tool.progress":
+      entry = { ...base, output: event.data.output };
+      break;
+    case "tool.complete":
+      entry = {
+        ...base,
+        status: "complete",
+        output: event.data.output,
+        completedAt: event.data.completedAt ?? Date.now(),
+      };
+      break;
+    case "tool.error":
+      entry = {
+        ...base,
+        status: "error",
+        output: event.data.output,
+        completedAt: event.data.completedAt ?? Date.now(),
+      };
+      break;
+    default:
+      return state;
+  }
+  const stepped = reduceStep(state, event, id);
+  return {
+    ...state,
+    tools: { ...state.tools, [id]: entry },
+    toolOrder: state.toolOrder.includes(id) ? state.toolOrder : [...state.toolOrder, id],
+    steps: stepped.steps,
+    retiredSteps: stepped.retiredSteps,
+  };
+}
+
+/* ── steps ───────────────────────────────────────────────────────────────── */
+
+/** The step list and the retired ids, which only ever move together. */
+interface StepUpdate {
+  steps: AgentChatStep[];
+  retiredSteps: string[];
+}
+
+/**
+ * `TOOL_CALL_RESULT.metadata`, read defensively.
+ *
+ * `null` when nothing usable arrived, which a transport that predates the
+ * contract will produce. A step with no metadata at all is treated as a
+ * success by `tool.complete` and as a failure by `tool.error`, which is the
+ * most either event can honestly claim on its own.
+ *
+ * Note what is NOT here: any reading of `content`. The result text is the
+ * model's copy of the reply, in whatever shape the tool returned, and the
+ * client's previous attempt to find `ok: false` in it matched nothing real —
+ * a Cortena tool result is `{ content: [...], details }`, so the envelope it
+ * was looking for was two levels down when it existed at all.
+ */
+export function readResultMetadata(raw: unknown): AgentToolResultMetadata | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return null;
+  }
+  const record = raw as Record<string, unknown>;
+  const meta = readMeta(record.meta);
+  return {
+    ...(typeof record.toolName === "string" ? { toolName: record.toolName } : {}),
+    isError: record.isError === true,
+    ...(meta ? { meta } : {}),
+  };
+}
+
+function readMeta(raw: unknown): AgentToolResultMeta | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return null;
+  }
+  const record = raw as Record<string, unknown>;
+  const meta: AgentToolResultMeta = {
+    ...(typeof record.status === "number" ? { status: record.status } : {}),
+    ...(typeof record.code === "string" ? { code: record.code } : {}),
+    ...(typeof record.message === "string" ? { message: record.message } : {}),
+  };
+  return Object.keys(meta).length > 0 ? meta : null;
+}
+
+/**
+ * Is this the broker asking for a yes rather than reporting a failure?
+ *
+ * The broker refuses a catalogued write with `409 confirmation_required` until
+ * the call carries `confirmed: true`. It is the safety rail working, and the
+ * step says so instead of showing the user a red cross for it.
+ *
+ * Keyed on the CODE, never on the status. `409` is also an ordinary conflict —
+ * a task already claimed, a version that moved under a write — and wording one
+ * of those as "Needs your confirmation" invites the user to retry something
+ * that will never work.
+ */
+function isConfirmationRequired(meta: AgentToolResultMeta | undefined): boolean {
+  return meta?.code === "confirmation_required";
+}
+
+/** Longest failure message put on a step. */
+const ERROR_LIMIT = 200;
+
+/**
+ * The human part of a tool result, for a failure that carried no `meta`.
+ *
+ * A Cortena tool returns `{ content: [{ type: "text", text }], details }`,
+ * JSON-stringified by the mapper, so the text blocks are the message and the
+ * rest is machinery. Anything else — a plain string, a shape this does not
+ * recognise — is used as it stands. Bounded and sanitised either way.
+ */
+function resultText(output: unknown): string {
+  const direct = typeof output === "string" ? output : "";
+  let value: unknown = output;
+  if (direct) {
+    try {
+      value = JSON.parse(direct);
+    } catch {
+      return truncate(direct, ERROR_LIMIT);
+    }
+  }
+  if (typeof value === "object" && value !== null) {
+    const content = (value as { content?: unknown }).content;
+    if (Array.isArray(content)) {
+      const text = content
+        .map((part) =>
+          typeof part === "object" &&
+          part !== null &&
+          typeof (part as { text?: unknown }).text === "string"
+            ? (part as { text: string }).text
+            : "",
+        )
+        .filter(Boolean)
+        .join(" ");
+      if (text) {
+        return truncate(text, ERROR_LIMIT);
+      }
+    }
+  }
+  return truncate(direct, ERROR_LIMIT);
+}
+
+/** What a failed step says: the server's message, or the result text. */
+function errorMessageOf(meta: AgentToolResultMeta | undefined, output: unknown): string {
+  const fromMeta = meta?.message ? truncate(meta.message, ERROR_LIMIT) : "";
+  return fromMeta || resultText(output) || "The call failed.";
+}
+
+/** The call's input as an object, or nothing when it never parsed as one. */
+function readArgs(input: unknown): Record<string, unknown> | undefined {
+  return typeof input === "object" && input !== null && !Array.isArray(input)
+    ? (input as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * Close every step still running, however the run ended.
+ *
+ * A step's spinner is a promise that something is happening, and the transport
+ * does not keep it: a run that errors, is stopped, or simply finishes with a
+ * result event lost on the way leaves a line spinning for ever under an answer
+ * that has already arrived. Three outcomes, because they are three different
+ * facts about the user's work:
+ *
+ * - `failed` — the run itself broke. Red, with the reason.
+ * - `stopped` — the user pressed Stop. Neutral: nothing went wrong.
+ * - `finished` — a plain RUN_FINISHED. The run SUCCEEDED, so the calls it made
+ *   succeeded too; the words they finished with are still true, and only the
+ *   spinner changes.
+ * - `paused` — RUN_FINISHED with `outcome.type === "interrupt"`. The call is
+ *   still open and the run will resume, so the step neither ticks nor spins:
+ *   it waits, visibly, and the result closes it later.
+ * - `denied` — the user refused the approval the run paused on. Only PAUSED
+ *   steps end, and they end `stopped`.
+ *
+ * `running` and `paused` are both OPEN, which is what the first three outcomes
+ * close: an abort or a run error while a step waits for an approval must not
+ * leave it waiting for ever.
+ */
+type StepOutcome =
+  | { kind: "failed"; message: string }
+  | { kind: "stopped" }
+  | { kind: "finished" }
+  | { kind: "paused" }
+  | { kind: "denied" };
+
+/** Is this step still open — spinning, or waiting on the user? */
+function isOpenStep(step: AgentChatStep): boolean {
+  return step.status === "running" || step.status === "paused";
+}
+
+function endRunningSteps(steps: AgentChatStep[], outcome: StepOutcome): AgentChatStep[] {
+  const closes = (step: AgentChatStep) =>
+    outcome.kind === "paused"
+      ? step.status === "running"
+      : outcome.kind === "denied"
+        ? step.status === "paused"
+        : isOpenStep(step);
+  if (!steps.some(closes)) {
+    return steps;
+  }
+  const endedAt = Date.now();
+  return steps.map((step) => {
+    if (!closes(step)) {
+      return step;
+    }
+    if (outcome.kind === "paused") {
+      // No `endedAt`: nothing has ended. It is the absence of `running` that
+      // stops the strip's ticking counter.
+      return { ...step, status: "paused" as const };
+    }
+    if (outcome.kind === "failed") {
+      return { ...step, status: "error" as const, endedAt, errorMessage: outcome.message };
+    }
+    if (outcome.kind === "stopped" || outcome.kind === "denied") {
+      return { ...step, status: "stopped" as const, endedAt };
+    }
+    return { ...step, status: "done" as const, endedAt };
+  });
+}
+
+/**
+ * A step appended, with the list capped at `STEP_LIMIT`.
+ *
+ * A turn with more calls than this is a loop, not a plan, and an uncapped list
+ * grows without bound in memory and re-renders the whole strip on every event
+ * of it. The most recent are kept: they are what the user is waiting on, and
+ * the ids of the ones dropped are kept so a late result for one is recognised
+ * rather than mistaken for a call nobody announced.
+ */
+function append(
+  steps: AgentChatStep[],
+  retiredSteps: string[],
+  step: AgentChatStep,
+): StepUpdate {
+  const next = [...steps, step];
+  if (next.length <= STEP_LIMIT) {
+    return { steps: next, retiredSteps };
+  }
+  const dropped = next.slice(0, next.length - STEP_LIMIT).map((s) => s.id);
+  return {
+    steps: next.slice(-STEP_LIMIT),
+    retiredSteps: [...retiredSteps, ...dropped].slice(-RETIRED_LIMIT),
+  };
+}
+
+/** Most dropped ids remembered. Enough for stragglers, not a transcript. */
+const RETIRED_LIMIT = 100;
+
+function replaceStep(
+  steps: AgentChatStep[],
+  index: number,
+  next: AgentChatStep,
+): AgentChatStep[] {
+  const copy = [...steps];
+  copy[index] = next;
+  return copy;
+}
+
+/**
+ * One tool event, folded into the step list.
+ *
+ * Start and end are paired by the AG-UI `toolCallId`, not by position: calls
+ * overlap, and a run that issues two searches at once ended the wrong one when
+ * the list was treated as a stack.
+ *
+ * The label is recomputed when the arguments land, because they land in a
+ * SECOND event. `TOOL_CALL_START` carries the name only, so a label fixed at
+ * start time is "Working: engram_search" for the whole of the call — the one
+ * line the wording map exists to avoid.
+ */
+function reduceStep(
+  state: AgentChatState,
+  event: AgentToolEvent,
+  id: string,
+): StepUpdate {
+  const { steps, retiredSteps } = state;
+  const keep: StepUpdate = { steps, retiredSteps };
+  const index = steps.findIndex((step) => step.id === id);
+  const existing = index === -1 ? undefined : steps[index];
+
+  // A call the cap already dropped. Its result is arriving after fifty other
+  // calls pushed it off the front, and there is nothing left to update: the
+  // only alternatives are a stale line back at the bottom of the strip or
+  // silence, and silence about the fiftieth-oldest call of a runaway turn is
+  // the right answer.
+  if (!existing && retiredSteps.includes(id)) {
+    return keep;
+  }
+
+  if (event.event === "tool.start") {
+    // A start for a call that has already ENDED is a replay, not a restart.
+    // A reconnect re-streams the run from the top, so every call of it starts
+    // again; taking that at face value put a finished run's steps back into
+    // spinners, with no second result coming to take them out again.
+    if (existing && !isOpenStep(existing)) {
+      return keep;
+    }
+    const toolName = event.data.name ?? existing?.toolName ?? "tool";
+    const step: AgentChatStep = {
+      id,
+      toolName,
+      ...(existing?.args ? { args: existing.args } : {}),
+      label: stepLabel(toolName, existing?.args, "running"),
+      startedAt: event.data.startedAt ?? existing?.startedAt ?? Date.now(),
+      status: "running",
+    };
+    return existing && index !== -1
+      ? { steps: replaceStep(steps, index, step), retiredSteps }
+      : append(steps, retiredSteps, step);
+  }
+
+  // Anything else about a call nobody announced. The strip still shows it —
+  // a result with no start is a call that happened, and silence about it is
+  // worse than a line with a generic label.
+  const base: AgentChatStep = existing ?? {
+    id,
+    toolName: event.data.name ?? "tool",
+    label: stepLabel(event.data.name ?? "tool", undefined, "running"),
+    startedAt: event.data.startedAt ?? Date.now(),
+    status: "running",
+  };
+  const at = index === -1 ? steps.length : index;
+  const put = (next: AgentChatStep): StepUpdate =>
+    index === -1
+      ? append(steps, retiredSteps, next)
+      : { steps: replaceStep(steps, at, next), retiredSteps };
+
+  switch (event.event) {
+    case "tool.args": {
+      const args = readArgs(event.data.input);
+      if (!args) {
+        return keep;
+      }
+      // The broker asked for a confirmation before the arguments landed, so
+      // the question it asked is "that action". It has a name now, and the
+      // card the user is reading is the one place the name matters.
+      if (base.label === CONFIRMATION_FALLBACK) {
+        return put({ ...base, args, label: confirmationRequiredLabel(args) });
+      }
+      // A finished step keeps the words it finished with — unless those words
+      // are the fallback. Arguments can land after the result on a short call,
+      // and "Working: broker_invoke", ticked, is the one line the wording map
+      // exists to avoid; a real sentence is better late than never. A label
+      // the arguments already produced is never rewritten.
+      const open = isOpenStep(base);
+      const relabel = open || isGenericLabel(base.toolName, base.label);
+      return put({
+        ...base,
+        args,
+        label: relabel ? stepLabel(base.toolName, args, open ? "running" : "done") : base.label,
+      });
+    }
+    case "tool.progress":
+      return keep;
+    case "tool.complete":
+    case "tool.error":
+      return put(endStep(base, event));
+    default:
+      return keep;
+  }
+}
+
+/** The confirmation label with no operation on it; see `tool.args` above. */
+const CONFIRMATION_FALLBACK = confirmationRequiredLabel(undefined);
+
+/**
+ * A start event's step, ended by its result.
+ *
+ * The whole outcome decision, in one place, against
+ * `TOOL_CALL_RESULT.metadata` and nothing else:
+ *
+ * - `isError` with `meta.code === "confirmation_required"` — not a failure.
+ *   The broker is asking a question, and the step is relabelled to ask it.
+ * - `isError` otherwise — a failure, worded from `meta.message` when there is
+ *   one and from the result text when there is not.
+ * - neither — done.
+ */
+function endStep(base: AgentChatStep, event: AgentToolEvent): AgentChatStep {
+  const metadata: AgentToolResultMetadata | null = readResultMetadata(event.data.metadata);
+  // Either witness is enough. `tool.error` is what the bridge emits when the
+  // metadata says `isError`, but it is also what a transport that predates the
+  // contract emits with no metadata at all — and a metadata object that
+  // arrived without an `isError` field then made `isError` false and drew a
+  // failed call as a success.
+  const isError = metadata?.isError === true || event.event === "tool.error";
+  const meta: AgentToolResultMeta | undefined = metadata?.meta;
+  const endedAt = event.data.completedAt ?? Date.now();
+
+  if (isError && isConfirmationRequired(meta)) {
+    return { ...base, status: "done", endedAt, label: confirmationRequiredLabel(base.args) };
+  }
+  if (isError) {
+    return { ...base, status: "error", endedAt, errorMessage: errorMessageOf(meta, event.data.output) };
+  }
+  return { ...base, status: "done", endedAt, label: stepLabel(base.toolName, base.args, "done") };
+}
+
+/* ── the hook ────────────────────────────────────────────────────────────── */
+
+/** How long a burst of step changes is collapsed for before it is written. */
+const STEP_WRITE_DEBOUNCE_MS = 250;
+
+export interface UseAgentChatOptions {
+  client: AgentChatClient;
+  /**
+   * Names the `sessionStorage` slot the current session key lives in. Two
+   * pop-ups with different scopes never share a key, which is what keeps one
+   * extension's chat out of another's.
+   */
+  storageScope: string;
+  /** Skip reading and writing `sessionStorage`; for a transient mount. */
+  ephemeral?: boolean;
+  thinking?: "low" | "medium" | "high";
+}
+
+export interface UseAgentChatResult extends AgentChatState {
+  send: (text: string, attachments?: unknown[]) => void;
+  sendAction: (action: NonNullable<Parameters<AgentChatClient["send"]>[0]["a2uiAction"]>) => void;
+  abort: () => void;
+  resolveApproval: (id: string, decision: AgentApprovalDecision) => void;
+  newSession: () => void;
+  resumeSession: (key: string) => void;
+  loadOlder: () => void;
+  refreshSessions: () => void;
+}
+
+export function useAgentChat({
+  client,
+  storageScope,
+  ephemeral,
+  thinking,
+}: UseAgentChatOptions): UseAgentChatResult {
+  const [state, dispatch] = React.useReducer(reduce, EMPTY);
+  const stateRef = React.useRef(state);
+  stateRef.current = state;
+
+  // Subscribe once per client. A collapsed pop-up keeps this mounted — the
+  // panel is hidden, not unmounted — so a run started before the collapse
+  // keeps streaming into the state the pill's unread dot is read from.
+  React.useEffect(() => {
+    const offChat = client.onChat((event) => dispatch({ kind: "chat", event }));
+    const offTool = client.onTool((event) => dispatch({ kind: "tool", event }));
+    const offApproval = client.onApproval((event) => {
+      if (event.type === "request") {
+        dispatch({ kind: "approval/request", request: event.request });
+      } else {
+        dispatch({ kind: "approval/resolved", id: event.id });
+      }
+    });
+    return () => {
+      offChat();
+      offTool();
+      offApproval();
+    };
+  }, [client]);
+
+  const refreshSessions = React.useCallback(() => {
+    dispatch({ kind: "sessions/loading" });
+    void client
+      .request<AgentSessionsListResponse>("sessions.list", { includeDerivedTitles: true })
+      .then((response) => {
+        // Filtered to this agent: a shared control plane lists every session on
+        // the pod, and an extension must never show another agent's chats.
+        const sessions = (response?.sessions ?? []).filter((s) =>
+          isSessionOfAgent(s.key, client.agentId),
+        );
+        dispatch({ kind: "sessions/loaded", sessions });
+      })
+      .catch((err: unknown) => {
+        dispatch({ kind: "sessions/loaded", sessions: [] });
+        dispatch({ kind: "error", message: errorText(err) });
+      });
+  }, [client]);
+
+  const loadHistory = React.useCallback(
+    (sessionKey: string) => {
+      dispatch({ kind: "history/loading" });
+      void client
+        .request<AgentChatHistoryResponse>("chat.history", { sessionKey, limit: 100 })
+        .then((response) => {
+          const records = response?.messages ?? [];
+          dispatch({
+            kind: "history/loaded",
+            sessionKey,
+            messages: parseHistoryMessages(records),
+            hasMore: response?.hasMore ?? false,
+            records: records.length,
+          });
+        })
+        .catch(() => dispatch({ kind: "history/failed" }));
+    },
+    [client],
+  );
+
+  // Restore this window's session, or mint one. `sessionStorage`, not
+  // `localStorage`: a second window must not adopt the first window's session.
+  const restored = React.useRef(false);
+  React.useEffect(() => {
+    if (restored.current) {
+      return;
+    }
+    restored.current = true;
+    const stored = ephemeral ? null : readStoredSessionKey(storageScope);
+    const key = stored && isSessionOfAgent(stored, client.agentId) ? stored : null;
+    if (key) {
+      dispatch({ kind: "session", key });
+      // Before the history load, and after the `session` reset it would
+      // otherwise be cleared by. `chat.history` has no steps in it — the
+      // server never sees them — so this slot is the only way back.
+      const steps = ephemeral ? [] : readStoredSteps(storageScope, key);
+      if (steps.length > 0) {
+        dispatch({ kind: "steps/restored", steps });
+      }
+      loadHistory(key);
+    }
+    refreshSessions();
+  }, [client, ephemeral, loadHistory, refreshSessions, storageScope]);
+
+  /**
+   * Keep the per-window store in step with the strip, on a debounce.
+   *
+   * Skipped while there is no session key, which is also the first commit —
+   * writing then would empty the slot the effect above is about to read.
+   *
+   * Debounced because a busy run changes `steps` several times per call —
+   * start, arguments, result — and each write serialises the whole list and
+   * hands it to a SYNCHRONOUS storage API on the main thread. A quarter of a
+   * second collapses a call's worth of edits into one write and is far below
+   * anything a reload could notice.
+   */
+  const pendingSteps = React.useRef<{ sessionKey: string; steps: AgentChatStep[] } | null>(null);
+  React.useEffect(() => {
+    if (ephemeral || !state.sessionKey) {
+      return;
+    }
+    const sessionKey = state.sessionKey;
+    const steps = state.steps;
+    pendingSteps.current = { sessionKey, steps };
+    const id = setTimeout(() => {
+      pendingSteps.current = null;
+      writeStoredSteps(storageScope, sessionKey, steps);
+    }, STEP_WRITE_DEBOUNCE_MS);
+    return () => clearTimeout(id);
+  }, [ephemeral, state.sessionKey, state.steps, storageScope]);
+
+  // Flushed on the way out. The unmount is the case the slot exists for — a
+  // pop-up collapsing, a host remounting the surface mid-run — and a debounce
+  // that dropped its last write on unmount would lose exactly the strip it was
+  // meant to preserve.
+  React.useEffect(() => {
+    return () => {
+      const pending = pendingSteps.current;
+      if (!ephemeral && pending) {
+        pendingSteps.current = null;
+        writeStoredSteps(storageScope, pending.sessionKey, pending.steps);
+      }
+    };
+  }, [ephemeral, storageScope]);
+
+  const setSession = React.useCallback(
+    (key: string) => {
+      dispatch({ kind: "session", key });
+      if (!ephemeral) {
+        writeStoredSessionKey(storageScope, key);
+      }
+    },
+    [ephemeral, storageScope],
+  );
+
+  const run = React.useCallback(
+    (text: string, extra: Partial<Parameters<AgentChatClient["send"]>[0]> = {}) => {
+      const current = stateRef.current;
+      // One run at a time. A second `send` on a streaming session opens a
+      // second stream into one store: two sets of deltas overwrite each
+      // other's snapshot, `final` folds one run's answer into the other's
+      // bubble, and `abort` can only reach whichever the client thinks is
+      // active. The composer disables Send while a run is live; this is the
+      // same rule for Enter, for a2ui actions and for a caller of the hook.
+      if (current.streaming) {
+        return;
+      }
+      const sessionKey = current.sessionKey ?? mintSessionKey(client.agentId);
+      if (!current.sessionKey && !ephemeral) {
+        writeStoredSessionKey(storageScope, sessionKey);
+      }
+      const runId = generateId();
+      // An action with no typed text is a click, not a sentence: a user bubble
+      // for it would put `{"name":"createTask"}` in the transcript as though
+      // the user had said it.
+      const message: AgentChatMessage | null =
+        text || (!extra.a2uiAction && !extra.mcpAppAction)
+          ? { id: runId, role: "user", text, timestamp: Date.now(), runId }
+          : null;
+      dispatch({ kind: "send", message, runId, sessionKey });
+      void client
+        .send({
+          sessionKey,
+          message: text,
+          runId,
+          ...(thinking ? { thinking } : {}),
+          ...extra,
+        })
+        .then(() => refreshSessions())
+        .catch((err: unknown) => dispatch({ kind: "send/failed", message: errorText(err) }));
+    },
+    [client, ephemeral, refreshSessions, storageScope, thinking],
+  );
+
+  const send = React.useCallback(
+    (text: string, attachments?: unknown[]) => {
+      run(text, attachments?.length ? { attachments } : {});
+    },
+    [run],
+  );
+
+  const sendAction = React.useCallback(
+    (a2uiAction: NonNullable<Parameters<AgentChatClient["send"]>[0]["a2uiAction"]>) => {
+      run("", { a2uiAction });
+    },
+    [run],
+  );
+
+  const abort = React.useCallback(() => {
+    const { runId, sessionKey } = stateRef.current;
+    dispatch({ kind: "abort" });
+    void client
+      .abort({
+        ...(runId ? { runId } : {}),
+        ...(sessionKey ? { sessionKey } : {}),
+      })
+      .catch(() => {
+        // Best-effort: local state is already reset, and dropping the stream
+        // aborts the run server-side anyway.
+      });
+  }, [client]);
+
+  const resolveApproval = React.useCallback(
+    (id: string, decision: AgentApprovalDecision) => {
+      const request = stateRef.current.approvals.find((r) => r.id === id);
+      if (!request) {
+        return;
+      }
+      // A deny also ends the step the run paused on: the call is not going to
+      // happen, and a line left waiting for an approval the user has already
+      // refused is the state this whole path exists to avoid.
+      dispatch(
+        decision === "deny" ? { kind: "approval/denied", id } : { kind: "approval/resolved", id },
+      );
+      // Bound to the run and the session the REQUEST arrived on, never to
+      // whatever is in flight now. The two come apart the moment a user opens
+      // another session while a command waits for an answer.
+      void client
+        .resolveApproval(id, decision, {
+          runId: request.runId,
+          sessionKey: request.sessionKey,
+        })
+        .catch((err: unknown) => {
+          dispatch({ kind: "approval/failed", request, message: errorText(err) });
+        });
+    },
+    [client],
+  );
+
+  const newSession = React.useCallback(() => {
+    setSession(mintSessionKey(client.agentId));
+  }, [client, setSession]);
+
+  const resumeSession = React.useCallback(
+    (key: string) => {
+      setSession(key);
+      loadHistory(key);
+    },
+    [loadHistory, setSession],
+  );
+
+  const loadOlder = React.useCallback(() => {
+    const current = stateRef.current;
+    if (!current.sessionKey || current.loadingHistory || !current.hasMoreHistory) {
+      return;
+    }
+    dispatch({ kind: "history/loading" });
+    void client
+      .request<AgentChatHistoryResponse>("chat.history", {
+        sessionKey: current.sessionKey,
+        limit: 100,
+        // Records, not bubbles. See `historyCount`.
+        offset: current.historyCount,
+      })
+      .then((response) => {
+        const records = response?.messages ?? [];
+        dispatch({
+          kind: "history/older",
+          messages: parseHistoryMessages(records),
+          hasMore: response?.hasMore ?? false,
+          records: records.length,
+        });
+      })
+      .catch(() => dispatch({ kind: "history/failed" }));
+  }, [client]);
+
+  return {
+    ...state,
+    send,
+    sendAction,
+    abort,
+    resolveApproval,
+    newSession,
+    resumeSession,
+    loadOlder,
+    refreshSessions,
+  };
+}
+
+function errorText(err: unknown): string {
+  return err instanceof Error ? err.message : "The agent could not be reached";
+}