cortena-ui 1.4.2 → 1.6.0

package/src/components/agent-chat.tsx

@@ -0,0 +1,1006 @@
+"use client";
+
+/**
+ * AgentChat — the chat surface an extension's own agent runs in.
+ *
+ * §17 of how-to-create-a-cortena-extension, audit rule P-25. Moved here from
+ * `cortenaweb/components/chat/**` so there is one chat and not two: a cut-down
+ * widget diverges on approvals, A2UI and MCP Apps within one release, and every
+ * fix then has to be made twice. cortenaweb adopts this component as a
+ * follow-up; until then the two are kept in step by hand.
+ *
+ * Everything comes from the `AgentChatClient` prop — nothing here knows about
+ * HTTP, AG-UI or a store — which is what lets `test/agent-chat.test.tsx` drive
+ * the whole surface from a fake that replays scripted event sequences.
+ *
+ * Not in this package, on purpose: the MCP App frame. Rendering an extension's
+ * own screen means a sandboxed iframe, a `srcdoc` CSP, a JSON-RPC postMessage
+ * bridge and a `tools/invoke` proxy holding a credential — a host concern, not
+ * a component one. `renderToolCall` is the seam: return a node for a tool call
+ * and it replaces the card, return nothing and the default card is drawn.
+ */
+
+import {
+  Check,
+  ChevronDown,
+  ChevronRight,
+  MessageSquarePlus,
+  Send,
+  ShieldCheck,
+  ShieldX,
+  Sparkles,
+  Square,
+  X,
+} from "lucide-react";
+import * as React from "react";
+import { A2UIRenderer } from "@/a2ui/renderer";
+import { A2UIErrorCard } from "@/a2ui/views";
+import type { A2UIAction, A2UIMessage } from "@/a2ui/message";
+import { Badge } from "@/components/badge";
+import { Button } from "@/components/button";
+import { ErrorBanner } from "@/components/error-banner";
+import { Markdown } from "@/components/markdown";
+import { Spinner } from "@/components/spinner";
+import { Textarea } from "@/components/textarea";
+import { isHiddenMessage, STORED_TEXT_LIMIT } from "@/agent-chat/session";
+import { isGenericLabel, truncate } from "@/agent-chat/step-label";
+import { type AgentToolEntry, useAgentChat } from "@/agent-chat/store";
+import type {
+  AgentApprovalRequest,
+  AgentChatClient,
+  AgentChatMessage,
+  AgentChatStep,
+  AgentSession,
+} from "@/agent-chat/types";
+import { sessionTitle } from "@/agent-chat/types";
+import type { A2UIChatBlock } from "@/agent-chat/a2ui-block";
+import { cn } from "@/lib/cn";
+
+/* ── stick to bottom ─────────────────────────────────────────────────────── */
+
+/**
+ * Should the list jump back to the bottom after its content grew?
+ *
+ * Judged against the height BEFORE the growth. Measuring afterwards asks "is
+ * the newest content already visible", which is false by construction for any
+ * append taller than the threshold — a paragraph, a code block, an image — so
+ * the re-pin skipped exactly when it was needed.
+ */
+export function shouldStickToBottom(params: {
+  prevScrollHeight: number;
+  scrollTop: number;
+  clientHeight: number;
+  threshold?: number;
+}): boolean {
+  const { prevScrollHeight, scrollTop, clientHeight, threshold = 150 } = params;
+  if (prevScrollHeight <= 0) {
+    return true;
+  }
+  return prevScrollHeight - scrollTop - clientHeight < threshold;
+}
+
+/* ── thinking ────────────────────────────────────────────────────────────── */
+
+export interface AgentThinkingProps {
+  text: string;
+  /** Open by default while the turn is live, collapsed once it is finished. */
+  defaultOpen?: boolean;
+  streaming?: boolean;
+}
+
+function AgentThinking({ text, defaultOpen, streaming }: AgentThinkingProps) {
+  const [open, setOpen] = React.useState(defaultOpen ?? false);
+  if (!text) {
+    return null;
+  }
+  return (
+    <div data-slot="agent-chat-thinking" className="mt-1">
+      <button
+        type="button"
+        aria-expanded={open}
+        onClick={() => setOpen((v) => !v)}
+        className={cn(
+          "inline-flex items-center gap-1 rounded-[var(--ds-radius-sm)] px-1 py-0.5",
+          "text-[length:var(--ds-text-caption)] text-[color:var(--ds-muted-foreground)]",
+          "transition-colors duration-[var(--ds-duration-fast)] hover:text-[color:var(--ds-foreground)]",
+        )}
+      >
+        {open ? <ChevronDown className="size-3" aria-hidden /> : <ChevronRight className="size-3" aria-hidden />}
+        {streaming ? "Thinking…" : "Chain of thought"}
+      </button>
+      {open ? (
+        <div
+          data-slot="agent-chat-thinking-body"
+          className={cn(
+            "mt-1 max-h-64 overflow-auto rounded-[var(--ds-radius-sm)] border border-[var(--ds-border-subtle)]",
+            "bg-[var(--ds-muted)] px-3 py-2 whitespace-pre-wrap",
+            "text-[length:var(--ds-text-caption)] text-[color:var(--ds-muted-foreground)]",
+          )}
+        >
+          {text}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/* ── progress steps ──────────────────────────────────────────────────────── */
+
+/**
+ * How long a step runs before it starts saying how long it has been running.
+ *
+ * Under this, a timer is noise: every call takes a second or two and a number
+ * ticking beside each one is a fidget spinner. Over it, the user has begun to
+ * wonder whether anything is happening at all, and the number is the answer.
+ */
+const ELAPSED_AFTER_MS = 8_000;
+
+/**
+ * `Date.now()`, re-read once a second while `active`.
+ *
+ * The interval only exists while something is running, so a finished chat sits
+ * idle rather than re-rendering the whole transcript once a second for ever.
+ */
+function useTickingNow(active: boolean): number {
+  const [now, setNow] = React.useState(() => Date.now());
+  React.useEffect(() => {
+    if (!active) {
+      return;
+    }
+    setNow(Date.now());
+    const id = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(id);
+  }, [active]);
+  return now;
+}
+
+export interface AgentStepsProps {
+  steps: readonly AgentChatStep[];
+}
+
+/**
+ * What the agent is doing, one plain sentence per tool call (SKILLS-9).
+ *
+ * This is the surface a person watches while they wait, and it is deliberately
+ * not the tool strip: the strip is the record — names, arguments, output, the
+ * MCP App seam — and reading it requires knowing what `broker_invoke` is. The
+ * strip stays at the foot for anyone who wants the detail.
+ *
+ * NOT a live region of its own. The strip is drawn inside the transcript, and
+ * the transcript is already `role="log" aria-live="polite"` — two nested live
+ * regions is one announcement per change from the inner one and another from
+ * the outer, which is how a screen reader ends up saying every step twice.
+ * `aria-label` stays: it names the group for anyone who navigates to it.
+ */
+function AgentSteps({ steps }: AgentStepsProps) {
+  const running = steps.some((step) => step.status === "running");
+  const now = useTickingNow(running);
+  if (steps.length === 0) {
+    return null;
+  }
+  return (
+    <div
+      data-slot="agent-chat-steps"
+      aria-label="Progress"
+      className="mt-1 flex flex-col gap-0.5"
+    >
+      {steps.map((step) => {
+        const elapsed = step.status === "running" ? now - step.startedAt : 0;
+        const seconds = elapsed >= ELAPSED_AFTER_MS ? Math.floor(elapsed / 1000) : 0;
+        // Held out of the announcement while the line is still the fallback.
+        // The arguments arrive one event after the start, so every call passes
+        // through "Working: broker_invoke" for a few hundred milliseconds, and
+        // a live region reads it out — then reads the real sentence over the
+        // top of it. The row is still drawn; it joins the announcement the
+        // moment it has something to say, or when it ends, whichever is first.
+        const held = step.status === "running" && isGenericLabel(step.toolName, step.label);
+        return (
+          <p
+            key={step.id}
+            data-slot="agent-chat-step"
+            data-status={step.status}
+            // The tool name is the model's, not ours, and an attribute is a
+            // poor place for 9 kB of it.
+            data-tool={truncate(step.toolName, STORED_TEXT_LIMIT)}
+            {...(held ? { "aria-hidden": true } : {})}
+            className={cn(
+              "flex items-start gap-2 text-[length:var(--ds-text-caption-lg)]",
+              step.status === "error"
+                ? "text-[color:var(--ds-destructive)]"
+                : "text-[color:var(--ds-muted-foreground)]",
+            )}
+          >
+            <span
+              aria-hidden
+              className="mt-0.5 inline-flex size-3.5 shrink-0 items-center justify-center"
+            >
+              {step.status === "running" ? (
+                <Spinner size={12} aria-hidden />
+              ) : step.status === "error" ? (
+                <X className="size-3" />
+              ) : step.status === "stopped" ? (
+                <Square className="size-2.5" />
+              ) : step.status === "paused" ? (
+                // A plain dot, drawn in the muted colour: neither a spinner
+                // (nothing is happening) nor a tick (nothing has happened).
+                <span className="size-1.5 rounded-full bg-[color:var(--ds-muted-foreground)]" />
+              ) : (
+                <Check className="size-3 text-[color:var(--ds-success)]" />
+              )}
+            </span>
+            <span className="min-w-0">
+              {/* Keyed on the words. A step is re-worded in place when its
+                  arguments land, and a text node mutated under a live region
+                  is a change some screen readers do not announce at all; a new
+                  key makes it a node replacement, which they all do. */}
+              <span key={step.label} data-slot="agent-chat-step-label">
+                {step.label}
+              </span>
+              {/* The seconds change once a second, and a live region reads the
+                  whole line again each time they do. The count is for the eye:
+                  a screen reader hearing "Fetching tasks task list" once, and
+                  again when it lands, is told everything it needs. */}
+              {seconds > 0 ? (
+                <span aria-hidden data-slot="agent-chat-step-elapsed">{` · ${seconds}s`}</span>
+              ) : null}
+              {step.status === "stopped" ? (
+                <span data-slot="agent-chat-step-note">{" — Stopped"}</span>
+              ) : null}
+              {step.status === "paused" ? (
+                <span data-slot="agent-chat-step-note">{" — Waiting for your approval"}</span>
+              ) : null}
+              {step.status === "error" && step.errorMessage ? (
+                <span data-slot="agent-chat-step-error">{` — ${step.errorMessage}`}</span>
+              ) : null}
+            </span>
+          </p>
+        );
+      })}
+    </div>
+  );
+}
+
+/* ── A2UI blocks ─────────────────────────────────────────────────────────── */
+
+export interface AgentA2UIBlocksProps {
+  blocks: readonly A2UIChatBlock[] | undefined;
+  /** Set on the streaming bubble: actions are disabled while the turn is live. */
+  streaming?: boolean;
+  onAction?: (action: A2UIAction) => void;
+}
+
+/**
+ * Every block of one message, in arrival order.
+ *
+ * A block carrying a transport `error` — an unclosed fence, a body that did not
+ * parse — gets an error card rather than being dropped. A block that is merely
+ * malformed inside is the renderer's error to draw, and it draws the parts that
+ * were fine.
+ */
+function AgentA2UIBlocks({ blocks, streaming, onAction }: AgentA2UIBlocksProps) {
+  if (!blocks || blocks.length === 0) {
+    return null;
+  }
+  return (
+    <div className="mt-2 flex flex-col gap-3" data-slot="agent-chat-a2ui">
+      {blocks.map((block, index) => (
+        <div key={`${block.surfaceId}:${index}`}>
+          {block.error ? (
+            <A2UIErrorCard title="The agent's UI did not arrive complete" detail={block.error} />
+          ) : null}
+          {block.messages.length > 0 ? (
+            <A2UIRenderer
+              // The payload stays `unknown[]`: it is the agent's, and only the
+              // renderer validates it. Every node goes through the catalogue's
+              // schema before it is drawn.
+              message={block.messages as A2UIMessage[]}
+              // A surface still streaming must not fire actions at the agent
+              // from a half-built form, so it is read-only until final.
+              {...(streaming || !onAction ? {} : { onAction })}
+            />
+          ) : null}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/* ── bubbles ─────────────────────────────────────────────────────────────── */
+
+function AssistantAvatar() {
+  return (
+    <span
+      data-slot="agent-chat-avatar"
+      aria-hidden
+      className={cn(
+        "grid size-7 shrink-0 place-items-center rounded-[var(--ds-radius-sm)]",
+        "border border-[var(--ds-ring)] bg-[var(--ds-primary-soft)] text-[color:var(--ds-primary)]",
+      )}
+    >
+      <Sparkles className="size-3.5" aria-hidden />
+    </span>
+  );
+}
+
+export interface AgentMessageBubbleProps {
+  message: AgentChatMessage;
+  agentName: string;
+  /**
+   * True while a run is live. Every A2UI surface in the transcript goes
+   * read-only, not just the one being drawn: an earlier surface is still a
+   * form wired to `sendAction`, and pressing it mid-run starts a second
+   * concurrent turn on the same session.
+   */
+  streaming?: boolean;
+  onAction?: (action: A2UIAction) => void;
+}
+
+function AgentMessageBubble({ message, agentName, streaming, onAction }: AgentMessageBubbleProps) {
+  if (isHiddenMessage(message)) {
+    return null;
+  }
+  if (message.isError) {
+    return (
+      <div data-slot="agent-chat-message" data-role="error">
+        <ErrorBanner message={message.text} />
+      </div>
+    );
+  }
+  if (message.role === "user") {
+    return (
+      <div data-slot="agent-chat-message" data-role="user" className="flex w-full justify-end">
+        <div
+          className={cn(
+            "max-w-[85%] rounded-[var(--ds-radius-lg)] border border-[var(--ds-border-subtle)]",
+            "bg-[var(--ds-popover)] px-3.5 py-2 text-[color:var(--ds-foreground)]",
+          )}
+        >
+          <Markdown compact>{message.text}</Markdown>
+        </div>
+      </div>
+    );
+  }
+  return (
+    <div data-slot="agent-chat-message" data-role="assistant" className="flex w-full gap-3">
+      <AssistantAvatar />
+      <div className="min-w-0 flex-1">
+        <span
+          className={cn(
+            "text-[length:var(--ds-text-caption)] font-semibold",
+            "text-[color:var(--ds-foreground)]",
+          )}
+        >
+          {agentName}
+        </span>
+        <AgentThinking text={message.thinkingText ?? ""} />
+        {message.text ? (
+          <div className="mt-1">
+            <Markdown compact>{message.text}</Markdown>
+          </div>
+        ) : null}
+        <AgentA2UIBlocks
+          blocks={message.a2ui}
+          {...(streaming ? { streaming } : {})}
+          {...(onAction ? { onAction } : {})}
+        />
+      </div>
+    </div>
+  );
+}
+
+export interface AgentStreamingBubbleProps {
+  agentName: string;
+  text: string;
+  thinkingText: string;
+  a2ui: readonly A2UIChatBlock[];
+  /** The turn's tool calls in plain words, drawn under the agent's name. */
+  steps?: readonly AgentChatStep[];
+}
+
+/**
+ * The assistant bubble while a turn is live.
+ *
+ * The filter chain is deliberately not applied: streaming text is
+ * agent-authored prose in progress, and the filters are about finished
+ * messages. Markdown is not processed either — partially arrived source
+ * (`**bo`) looks worse than its raw form — so the streaming view is plain text
+ * under `whitespace-pre-wrap` and `Markdown` takes over on `final`.
+ */
+function AgentStreamingBubble({
+  agentName,
+  text,
+  thinkingText,
+  a2ui,
+  steps,
+}: AgentStreamingBubbleProps) {
+  return (
+    <div data-slot="agent-chat-streaming" className="flex w-full gap-3">
+      <AssistantAvatar />
+      <div className="min-w-0 flex-1">
+        <span
+          className={cn(
+            "text-[length:var(--ds-text-caption)] font-semibold",
+            "text-[color:var(--ds-foreground)]",
+          )}
+        >
+          {agentName}
+        </span>
+        <AgentSteps steps={steps ?? []} />
+        {thinkingText ? <AgentThinking text={thinkingText} defaultOpen streaming /> : null}
+        {text ? (
+          <div
+            data-slot="agent-chat-streaming-text"
+            className="mt-1 break-words whitespace-pre-wrap text-[color:var(--ds-foreground)]"
+          >
+            {text}
+          </div>
+        ) : null}
+        <AgentA2UIBlocks blocks={a2ui} streaming />
+      </div>
+    </div>
+  );
+}
+
+/* ── tool cards ──────────────────────────────────────────────────────────── */
+
+/** A `ui://` resource in a tool result is an MCP App: the extension's own screen. */
+export function readMcpAppUri(output: unknown): string | null {
+  const text =
+    typeof output === "string" ? output : output === undefined ? "" : JSON.stringify(output);
+  return text.match(/"uri"\s*:\s*"(ui:\/\/[^"]+)"/)?.[1] ?? null;
+}
+
+function summarise(input: unknown): string {
+  if (input === undefined || input === null) {
+    return "";
+  }
+  if (typeof input === "string") {
+    return input;
+  }
+  const record = input as Record<string, unknown>;
+  for (const key of ["command", "cmd", "query", "path", "url", "name"]) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) {
+      return value;
+    }
+  }
+  const json = JSON.stringify(input);
+  return json.length > 120 ? `${json.slice(0, 117)}…` : json;
+}
+
+export interface AgentToolCardProps {
+  entry: AgentToolEntry;
+}
+
+/**
+ * The default card. It shows the tool's name, its input and its output — the
+ * input being the part that was missing for the whole of the AG-UI path,
+ * because the bridge had no `TOOL_CALL_ARGS` case.
+ */
+function AgentToolCard({ entry }: AgentToolCardProps) {
+  const [open, setOpen] = React.useState(false);
+  const summary = summarise(entry.input);
+  return (
+    <div
+      data-slot="agent-tool-card"
+      data-tool={entry.name}
+      data-status={entry.status}
+      className={cn(
+        "overflow-hidden rounded-[var(--ds-radius-sm)] border border-[var(--ds-border-subtle)]",
+        "bg-[var(--ds-muted)]",
+      )}
+    >
+      <button
+        type="button"
+        aria-expanded={open}
+        onClick={() => setOpen((v) => !v)}
+        className={cn(
+          "flex w-full items-center gap-2.5 px-3 py-2 text-left",
+          "transition-colors duration-[var(--ds-duration-fast)] hover:bg-[var(--ds-hover)]",
+        )}
+      >
+        <span className="inline-flex size-3.5 shrink-0 items-center justify-center">
+          {entry.status === "running" ? (
+            <Spinner size={14} />
+          ) : (
+            <span
+              aria-hidden
+              className={cn(
+                "size-2 rounded-[var(--ds-radius-full)]",
+                entry.status === "error" ? "bg-[var(--ds-destructive)]" : "bg-[var(--ds-success)]",
+              )}
+            />
+          )}
+        </span>
+        <span className="font-mono text-[length:var(--ds-text-caption)] text-[color:var(--ds-primary)]">
+          {entry.name}
+        </span>
+        {summary ? (
+          <span
+            data-slot="agent-tool-card-input"
+            className="min-w-0 truncate text-[length:var(--ds-text-caption)] text-[color:var(--ds-muted-foreground)]"
+          >
+            {summary}
+          </span>
+        ) : null}
+        <span className="ml-auto shrink-0 text-[color:var(--ds-text-tertiary)]">
+          {open ? <ChevronDown className="size-3" /> : <ChevronRight className="size-3" />}
+        </span>
+      </button>
+      {open ? (
+        <div className="border-t border-[var(--ds-border-subtle)] bg-[var(--ds-background)] px-3 py-2">
+          {entry.input !== undefined ? (
+            <pre
+              data-slot="agent-tool-card-args"
+              className="max-h-40 overflow-auto font-mono text-[length:var(--ds-text-caption-sm)] whitespace-pre-wrap text-[color:var(--ds-muted-foreground)]"
+            >
+              {typeof entry.input === "string" ? entry.input : JSON.stringify(entry.input, null, 2)}
+            </pre>
+          ) : null}
+          {entry.output !== undefined && entry.output !== null ? (
+            <pre className="mt-2 max-h-40 overflow-auto font-mono text-[length:var(--ds-text-caption-sm)] whitespace-pre-wrap text-[color:var(--ds-muted-foreground)]">
+              {typeof entry.output === "string"
+                ? entry.output
+                : JSON.stringify(entry.output, null, 2)}
+            </pre>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export interface AgentApprovalCardProps {
+  request: AgentApprovalRequest;
+  onResolve: (id: string, decision: "allow-once" | "allow-always" | "deny") => void;
+}
+
+/**
+ * `exec` as a render-and-wait card: the run is paused on this decision.
+ *
+ * The three answers are the three cortenacore accepts. "Always allow" is not a
+ * nicety — without it the same command is asked about on every turn, and a user
+ * who has to answer the same question repeatedly stops reading the question.
+ */
+function AgentApprovalCard({ request, onResolve }: AgentApprovalCardProps) {
+  const command =
+    typeof request.args.command === "string" ? request.args.command : request.toolName;
+  return (
+    <div
+      data-slot="agent-approval-card"
+      role="group"
+      aria-label="Command approval required"
+      className={cn(
+        "flex flex-col gap-3 rounded-[var(--ds-radius-md)] border border-[var(--ds-border)]",
+        "bg-[var(--ds-card)] p-3",
+      )}
+    >
+      <div className="flex items-center gap-2">
+        <ShieldCheck className="size-4 text-[color:var(--ds-primary)]" aria-hidden />
+        <span className="text-[length:var(--ds-text-body-sm)] font-medium text-[color:var(--ds-foreground)]">
+          Approval required
+        </span>
+      </div>
+      <pre className="max-h-32 overflow-auto rounded-[var(--ds-radius-sm)] bg-[var(--ds-muted)] p-2 font-mono text-[length:var(--ds-text-caption)] whitespace-pre-wrap text-[color:var(--ds-foreground)]">
+        {command}
+      </pre>
+      {/* A decision the server refused. The card came back rather than
+          vanishing, so the answer can be given again. */}
+      {request.error ? (
+        <p
+          data-slot="agent-approval-error"
+          role="alert"
+          className="text-[length:var(--ds-text-caption)] text-[color:var(--ds-destructive)]"
+        >
+          {request.error}
+        </p>
+      ) : null}
+      <div className="flex flex-wrap items-center gap-2">
+        <Button size="sm" onClick={() => onResolve(request.id, "allow-once")}>
+          <ShieldCheck aria-hidden />
+          Approve
+        </Button>
+        <Button size="sm" variant="outline" onClick={() => onResolve(request.id, "allow-always")}>
+          Always allow
+        </Button>
+        <Button size="sm" variant="destructive" onClick={() => onResolve(request.id, "deny")}>
+          <ShieldX aria-hidden />
+          Deny
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+/* ── the surface ─────────────────────────────────────────────────────────── */
+
+export interface AgentToolRenderContext {
+  entry: AgentToolEntry;
+  /** The `ui://` resource this result carries, when it carries one. */
+  mcpAppUri: string | null;
+}
+
+export interface AgentChatProps extends Omit<React.ComponentProps<"div">, "children" | "onError"> {
+  /** The transport. `createAguiAgentChatClient` is the AG-UI implementation. */
+  client: AgentChatClient;
+  /** The extension name, shown on each assistant turn. */
+  agentName: string;
+  /**
+   * Names the `sessionStorage` slot this window's session key lives in. Scope
+   * it to the extension id; two chats with different scopes never share a key.
+   */
+  storageScope: string;
+  /** Do not read or write `sessionStorage`; for a guide or a test. */
+  ephemeral?: boolean;
+  thinking?: "low" | "medium" | "high";
+  /** Rendered between the tool strip and the composer — an attachment picker. */
+  attachmentsSlot?: React.ReactNode;
+  /**
+   * Host wiring for a tool call. Return a node to replace the default card —
+   * this is the seam an MCP App frame mounts through, since the sandboxed
+   * iframe, its CSP and the `tools/invoke` proxy are the host's to own.
+   */
+  renderToolCall?: (context: AgentToolRenderContext) => React.ReactNode | undefined;
+  /** Header content, e.g. the pop-up's own window controls. */
+  headerSlot?: React.ReactNode;
+}
+
+function AgentChat({
+  client,
+  agentName,
+  storageScope,
+  ephemeral,
+  thinking,
+  attachmentsSlot,
+  renderToolCall,
+  headerSlot,
+  className,
+  ...props
+}: AgentChatProps) {
+  const chat = useAgentChat({
+    client,
+    storageScope,
+    ...(ephemeral === undefined ? {} : { ephemeral }),
+    ...(thinking === undefined ? {} : { thinking }),
+  });
+  const [drawerOpen, setDrawerOpen] = React.useState(false);
+  const [value, setValue] = React.useState("");
+  const scrollRef = React.useRef<HTMLDivElement>(null);
+  const contentRef = React.useRef<HTMLDivElement>(null);
+  const prevHeightRef = React.useRef(0);
+
+  /**
+   * Re-pin to the bottom whenever the content grows or the viewport shrinks.
+   * A message keeps growing after it mounts — markdown settles, the tool strip
+   * appears between the list and the composer — and every one of those leaves
+   * the newest content under the composer until the reader scrolls by hand.
+   *
+   * Jumping rather than smooth-scrolling: this fires many times a second during
+   * streaming, and queued smooth animations fight each other and lose.
+   */
+  React.useEffect(() => {
+    const scrollEl = scrollRef.current;
+    const contentEl = contentRef.current;
+    if (!scrollEl || !contentEl || typeof ResizeObserver === "undefined") {
+      return;
+    }
+    const observer = new ResizeObserver(() => {
+      const { scrollTop, scrollHeight, clientHeight } = scrollEl;
+      const stick = shouldStickToBottom({
+        prevScrollHeight: prevHeightRef.current,
+        scrollTop,
+        clientHeight,
+      });
+      prevHeightRef.current = scrollHeight;
+      if (stick) {
+        scrollEl.scrollTop = scrollEl.scrollHeight;
+      }
+    });
+    observer.observe(contentEl);
+    observer.observe(scrollEl);
+    return () => observer.disconnect();
+  }, []);
+
+  const submit = React.useCallback(() => {
+    const trimmed = value.trim();
+    // Enter reaches here while a run is live, where the button is a Stop
+    // control and cannot be pressed. One run at a time, by both routes.
+    if (!trimmed || chat.streaming) {
+      return;
+    }
+    chat.send(trimmed);
+    setValue("");
+  }, [chat, value]);
+
+  const onKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      if (event.key === "Escape" && chat.streaming) {
+        // Escape stops the run. It does not close the pop-up while a run is in
+        // flight: the first Escape is nearly always "stop", not "go away".
+        event.preventDefault();
+        event.stopPropagation();
+        chat.abort();
+        return;
+      }
+      if (event.key === "Enter" && !event.shiftKey) {
+        event.preventDefault();
+        submit();
+      }
+    },
+    [chat, submit],
+  );
+
+  const toolEntries = chat.toolOrder
+    .map((id) => chat.tools[id])
+    .filter((entry): entry is AgentToolEntry => entry !== undefined);
+  // The strip outlives the run rather than vanishing with it. The steps of a
+  // finished turn are the record of what the agent did on the user's behalf,
+  // and an MCP App drawn by one of them is a surface the user is meant to work
+  // in — one that disappeared the instant the agent stopped talking would be no
+  // use to anybody. The next run clears it.
+  const showTools = toolEntries.length > 0 || chat.approvals.length > 0;
+  const visible = chat.messages.filter((message) => !isHiddenMessage(message));
+
+  return (
+    <div
+      data-slot="agent-chat"
+      className={cn("flex h-full min-h-0 w-full flex-col bg-[var(--ds-background)]", className)}
+      {...props}
+    >
+      <div
+        data-slot="agent-chat-header"
+        className={cn(
+          "flex shrink-0 items-center gap-2 border-b border-[var(--ds-border-subtle)] px-3 py-2",
+        )}
+      >
+        <Button
+          size="sm"
+          variant="ghost"
+          data-slot="agent-chat-sessions-trigger"
+          aria-expanded={drawerOpen}
+          onClick={() => {
+            setDrawerOpen((open) => !open);
+            chat.refreshSessions();
+          }}
+        >
+          {chat.sessions.length === 1 ? "1 session" : `${chat.sessions.length} sessions`}
+        </Button>
+        <Button
+          size="sm"
+          variant="ghost"
+          data-slot="agent-chat-new-session"
+          aria-label="New session"
+          onClick={() => {
+            chat.newSession();
+            setDrawerOpen(false);
+          }}
+        >
+          <MessageSquarePlus aria-hidden />
+          New
+        </Button>
+        <div className="ml-auto flex items-center gap-1">{headerSlot}</div>
+      </div>
+
+      {drawerOpen ? (
+        <AgentSessionDrawer
+          sessions={chat.sessions}
+          current={chat.sessionKey}
+          loading={chat.loadingSessions}
+          onResume={(key) => {
+            chat.resumeSession(key);
+            setDrawerOpen(false);
+          }}
+        />
+      ) : null}
+
+      <div
+        ref={scrollRef}
+        data-slot="agent-chat-scroll"
+        className="min-h-0 flex-1 overflow-x-hidden overflow-y-auto"
+      >
+        <div
+          ref={contentRef}
+          role="log"
+          aria-live="polite"
+          aria-label={`${agentName} chat`}
+          className="flex min-w-0 flex-col gap-5 px-4 py-4"
+        >
+          {chat.error ? (
+            <ErrorBanner message={chat.error} />
+          ) : null}
+
+          {chat.hasMoreHistory ? (
+            <div className="flex justify-center">
+              <Button
+                size="sm"
+                variant="ghost"
+                data-slot="agent-chat-load-older"
+                disabled={chat.loadingHistory}
+                onClick={chat.loadOlder}
+              >
+                {chat.loadingHistory ? "Loading…" : "Load older messages"}
+              </Button>
+            </div>
+          ) : null}
+
+          {visible.length === 0 && !chat.streaming ? (
+            <p
+              data-slot="agent-chat-empty"
+              className="text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-muted-foreground)]"
+            >
+              Ask {agentName} anything about this screen.
+            </p>
+          ) : null}
+
+          {visible.map((message) => (
+            <AgentMessageBubble
+              key={message.id}
+              message={message}
+              agentName={agentName}
+              streaming={chat.streaming}
+              onAction={chat.sendAction}
+            />
+          ))}
+
+          {chat.streaming ? (
+            <AgentStreamingBubble
+              agentName={agentName}
+              text={chat.streamText}
+              thinkingText={chat.streamThinkingText}
+              a2ui={chat.streamA2ui}
+              steps={chat.steps}
+            />
+          ) : chat.steps.length > 0 ? (
+            // The turn is over but its steps are the record of what was done to
+            // answer it, and they stay until the next run replaces them — the
+            // same rule the tool strip below follows.
+            <AgentSteps steps={chat.steps} />
+          ) : null}
+        </div>
+      </div>
+
+      {showTools ? (
+        <div
+          data-slot="agent-chat-tools"
+          className="flex shrink-0 flex-col gap-1.5 border-t border-[var(--ds-border-subtle)] px-3 py-2"
+        >
+          {toolEntries.length > 0 ? (
+            <Badge variant="neutral" className="w-fit">
+              {toolEntries.length === 1 ? "1 step" : `${toolEntries.length} steps`}
+            </Badge>
+          ) : null}
+          {toolEntries.map((entry) => {
+            const custom = renderToolCall?.({
+              entry,
+              mcpAppUri: readMcpAppUri(entry.output),
+            });
+            return (
+              <React.Fragment key={entry.id}>
+                {custom ?? <AgentToolCard entry={entry} />}
+              </React.Fragment>
+            );
+          })}
+          {chat.approvals.map((request) => (
+            <AgentApprovalCard
+              key={request.id}
+              request={request}
+              onResolve={chat.resolveApproval}
+            />
+          ))}
+        </div>
+      ) : null}
+
+      {attachmentsSlot ? (
+        <div data-slot="agent-chat-attachments" className="shrink-0 px-3">
+          {attachmentsSlot}
+        </div>
+      ) : null}
+
+      <div
+        data-slot="agent-chat-composer"
+        className="flex shrink-0 items-end gap-2 border-t border-[var(--ds-border-subtle)] p-3"
+      >
+        <Textarea
+          data-slot="agent-chat-input"
+          aria-label={`Message ${agentName}`}
+          placeholder={`Message ${agentName}…`}
+          rows={1}
+          className="max-h-40 min-h-9 resize-none"
+          value={value}
+          onChange={(event) => setValue(event.target.value)}
+          onKeyDown={onKeyDown}
+        />
+        {chat.streaming ? (
+          <Button
+            size="icon"
+            variant="outline"
+            data-slot="agent-chat-stop"
+            aria-label="Stop the run"
+            onClick={chat.abort}
+          >
+            <Square aria-hidden />
+          </Button>
+        ) : (
+          <Button
+            size="icon"
+            data-slot="agent-chat-send"
+            aria-label="Send"
+            disabled={!value.trim()}
+            onClick={submit}
+          >
+            <Send aria-hidden />
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/* ── the session drawer ──────────────────────────────────────────────────── */
+
+export interface AgentSessionDrawerProps {
+  sessions: readonly AgentSession[];
+  current: string | null;
+  loading?: boolean;
+  onResume: (key: string) => void;
+}
+
+/**
+ * Every session of this agent, resumable from any window.
+ *
+ * The list is not this window's history: a session started in another window is
+ * here and can be resumed, which is the difference between "sessions are per
+ * window" (which key a window starts on) and "sessions are private to a window"
+ * (which they are not).
+ */
+function AgentSessionDrawer({ sessions, current, loading, onResume }: AgentSessionDrawerProps) {
+  return (
+    <div
+      data-slot="agent-chat-sessions"
+      className={cn(
+        "max-h-56 shrink-0 overflow-y-auto border-b border-[var(--ds-border-subtle)]",
+        "bg-[var(--ds-card)] px-2 py-1.5",
+      )}
+    >
+      {loading && sessions.length === 0 ? (
+        <p className="px-2 py-1 text-[length:var(--ds-text-caption)] text-[color:var(--ds-muted-foreground)]">
+          Loading sessions…
+        </p>
+      ) : null}
+      {!loading && sessions.length === 0 ? (
+        <p className="px-2 py-1 text-[length:var(--ds-text-caption)] text-[color:var(--ds-muted-foreground)]">
+          No earlier sessions.
+        </p>
+      ) : null}
+      {sessions.map((session) => (
+        <button
+          key={session.key}
+          type="button"
+          data-slot="agent-chat-session"
+          data-current={session.key === current ? "" : undefined}
+          onClick={() => onResume(session.key)}
+          className={cn(
+            "flex w-full items-center gap-2 rounded-[var(--ds-radius-sm)] px-2 py-1.5 text-left",
+            "text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-foreground)]",
+            "transition-colors duration-[var(--ds-duration-fast)] hover:bg-[var(--ds-hover)]",
+            session.key === current && "bg-[var(--ds-primary-soft)]",
+          )}
+        >
+          <span className="min-w-0 truncate">{sessionTitle(session)}</span>
+        </button>
+      ))}
+    </div>
+  );
+}
+
+export {
+  AgentA2UIBlocks,
+  AgentApprovalCard,
+  AgentChat,
+  AgentMessageBubble,
+  AgentSessionDrawer,
+  AgentSteps,
+  AgentStreamingBubble,
+  AgentThinking,
+  AgentToolCard,
+};