@lotics/ui 13.10.0 → 14.0.0

package/docs/ai_patterns.md

@@ -93,26 +93,27 @@ transition — never leave a live button waiting on a network round-trip:
 ## Show the work — `AgentRun`
 
 `AgentRun` (`@lotics/ui/agent_run`) is a live feed of the agent's work as a TIMELINE. The prop is
-an ORDERED `items` array (`AgentRunItem`):
+the agent message's **ai-sdk `parts`** (`UIMessagePart[]`) — the same wire shape chat and app
+agents emit; `@lotics/ui` owns the transform from parts to the render timeline, so there is no
+bespoke transcript type. It renders three part kinds:
 
-| Item | Shape | Renders as |
-|---|---|---|
-| `{ type: "text", id, text }` | Answer prose | `Markdown`, a trailing ▍ caret on the last segment while streaming |
-| `{ type: "reasoning", id, text }` | Thinking | COLLAPSED — a muted "Thinking" row; press to reveal the Markdown |
-| `{ type: "step", id, label, status, kind?, input?, output?, errorText?, detail?, peek? }` | A tool/step call | An activity row with a status dot |
-
-Items appear in the order they happened — a real run is think → text → a burst of calls → more
-text, NOT all text on top of a flat step list. Transparent work, NEVER a bare spinner.
-
-**Progressive disclosure.** The feed shows the label + state; the detail is revealed on demand.
-A `step`'s `input`/`output` are hidden in the row but open in a press-to-reveal **peek**
-(auto-built Input / Output `JsonPanel`s). On `status: "error"` the row's dot goes amber, the
-`detail` line reads in the danger ink, and `errorText` shows in the peek's Error panel. Pass an
-explicit `peek` node to render that reveal yourself (it overrides the auto panels). `detail` is
-OPTIONAL — a short human summary (a count), never invented prose or raw I/O (that's
-`input`/`output`).
-
-**Activity grouping.** Consecutive `step` items fold into ONE group. While the agent is mid-tools
+| Part | Renders as |
+|---|---|
+| `text` | Answer prose (`Markdown`), grows as it streams |
+| `reasoning` | Thinking — COLLAPSED, a muted "Thinking" row; press to reveal the Markdown |
+| a tool part — `dynamic-tool` (app agents) or `tool-<name>` (chat) | An activity row with a status dot |
+
+Parts appear in the order they happened — a real run is think → text → a burst of calls → more
+text, NOT all text on top of a flat step list. Content parts with no feed representation
+(`source-*`, `file`, `data-*`, `step-start`, `custom`) are skipped. Transparent work, NEVER a bare spinner.
+
+**Progressive disclosure.** The feed shows the label + state; the detail is revealed on demand. A
+tool part's `input`/`output` are hidden in the row and **expand in place** on press — auto-built
+Input / Output `JsonPanel`s roll out under the row (the same disclosure pattern as "Thinking",
+never a popover). A tool in an `output-error` state flows like any other call — the dot goes
+amber and its `errorText` shows in the expanded Error panel.
+
+**Activity grouping.** Consecutive tool parts fold into ONE group. While the agent is mid-tools
 the tail group is a SINGLE pulsing row whose label swaps in place as each call fires (no growing
 stack of dots); once prose resumes the group settles: a single call becomes one done row, and a
 multi-call group becomes a persistent "{final action} · {n} steps" HEADER (a `complete` terminal
@@ -120,17 +121,28 @@ dot — distinct from the filled `done` step dots; amber `warning` if any call e
 PUT and rolls the calls out BELOW it on press. The run ALWAYS ends on the agent's text — there is
 no global terminal node.
 
-**Tool labels.** A `step` with `kind: "tool"` carries the RAW tool name (`update_records`),
-resolved via a built-in map of the platform record/document tools + an optional `labelForTool`
-override (localize THERE — the kit stays English); unknown names fall back to a prettified form.
-`stepsLabel` localizes the "{n} steps" suffix. `state` (`"streaming" | "done" | "error"`)
-defaults to `streaming` while any step is running, else `done`.
-
-Fed natively by `@lotics/app-sdk`'s `useAgentRun().items` (reasoning + per-tool I/O + state come
-for free — no hand-assembly): `<AgentRun items={run.items} state={…} />` — see
-[the SDK doc](../../app-sdk/docs/ai.md) for the hook.
-
-**Limitation:** the collapsed reasoning row's "Thinking" label and the auto peek's
+**Tool labels.** A tool part carries the RAW tool name (`update_records` from `tool-update_records`,
+or a `dynamic-tool`'s `toolName`), resolved via a built-in map of the platform record/document
+tools + an optional `labelForTool` override (localize THERE — the kit stays English); unknown
+names fall back to a prettified form. `stepsLabel` localizes the "{n} steps" suffix. The tool
+`state` collapses ai's lifecycle to running / done / error (an approval-pending state reads as
+running — a read-only feed has no approval control). The whole-run `state` prop
+(`"streaming" | "done" | "error"`) defaults to `streaming` while any tool is running, else `done`.
+
+**Errors — two kinds, both surfaced, neither shouting.** An INTERMEDIARY tool failure rides in
+that tool's `output-error` part and flows like a normal call — the amber dot marks it (a settled
+group's header goes amber too), the reason waits in the expanded Error panel; real runs retry and
+move on, so the feed doesn't dramatize it. A BREAKING error that terminates the whole run lives
+OUTSIDE `parts` (chat persists it in the message's `errors`; `useAgentRun().error` carries it) —
+pass it as the `error` prop and it renders as a terminal danger row under the transcript.
+
+Fed natively by `@lotics/app-sdk`'s `useAgentRun().parts` (reasoning + per-tool I/O + state come
+for free — no hand-assembly): `<AgentRun parts={run.parts} state={…} error={run.error} />` — see
+[the SDK doc](../../app-sdk/docs/ai.md) for the hook. Requires `ai` as an optional (type-only) peer.
+**Reasoning only shows when the model produces it** — the declared model must support thinking
+(Sonnet 4.6 / Opus 4.8, not Haiku); the renderer shows every reasoning part it's handed.
+
+**Limitation:** the collapsed reasoning row's "Thinking" label and the expanded detail's
 "Input"/"Output"/"Error" panel titles are currently English-only (not on the locale provider and
 not prop-overridable); `labelForTool`/`stepsLabel` localize everything else in the feed.
 

package/docs/catalog.md

@@ -962,11 +962,20 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`composer`** — `Composer`: the adaptive command/chat composer — a compact pill that
   expands for long text + attachments (`pills` + attachment slots, controlled or
   uncontrolled `value`, `onSend`/`onStop`, `sendDisabled` override).
-- **`agent_run`** — `AgentRun` + `AgentRunStep`/`AgentRunItem` + `resolveToolMeta`: the live
-  streaming work feed. AI work ONLY — deterministic work (template fill, an export) shows a
-  `loading` state on its trigger and delivers at once; dressing it as an agent run is theater.
-- **`agent_progress`** — `AgentProgress`: its compact, floating, expandable form — a
-  composer's working state.
+- **`agent_run`** — `AgentRun` + `resolveToolMeta`: the live streaming work feed. Its prop is the
+  agent message's ai-sdk `parts` (`UIMessagePart[]` — text, reasoning, and tool parts), fed straight
+  from `useAgentRun().parts`; renders prose, a collapsed "Thinking" disclosure, and grouped tool
+  steps whose I/O expands in place on press (no popover). A per-tool failure shows amber with the
+  reason in its expanded Error panel; a run-level
+  breaking `error` (outside `parts`) renders as a terminal danger row. Needs `ai` as an optional
+  type-only peer. AI work ONLY —
+  deterministic work (template fill, an export) shows a `loading` state on its trigger and delivers
+  at once; dressing it as an agent run is theater.
+- **`agent_transform`** — internal (no component): the one place that folds an ai-sdk `UIMessage`'s
+  `parts` into the render timeline (`AgentUIPart`, `toSegments`, `lastRunningStep`), shared by
+  `AgentRun` and `AgentProgress`. The sole file permitted to `import type` from `ai`.
+- **`agent_progress`** — `AgentProgress`: `AgentRun`'s compact, floating, expandable form (same
+  `parts` prop) — a composer's working state.
 - **`confidence`** — `Confidence` + `ConfidenceLevel` + `levelFromScore`: calibrated
   high/med/low; localized via the provider.
 - **`change_review`** — the COMPOUND review family — frame: `ChangeReview` provider/stack ·
@@ -1031,4 +1040,5 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   a programmatic focus restore inside the suppression window doesn't re-open the editor it
   just closed.
 - **`json_panel`** — `JsonPanel` (`{title, value}`) + `stringifyData`: a labeled monospace
-  panel for raw/JSON payloads (debug & developer surfaces).
+  panel for raw/JSON payloads (debug & developer surfaces). Height-capped (240) and scrolls
+  inside, so a huge dump (a streamed tool input) can never blow the surface open.

package/examples/tpl_dieline.tsx

@@ -10,7 +10,9 @@ import { InlineTextInput } from "@lotics/ui/inline_text_input";
 import { AgentProgress } from "@lotics/ui/agent_progress";
 import { Composer } from "@lotics/ui/composer";
 import { FileThumbnail, type DisplayFile } from "@lotics/ui/file_thumbnail";
-import { type AgentRunStep, type AgentRunItem } from "@lotics/ui/agent_run";
+import type { UIMessagePart, UIDataTypes, UITools } from "ai";
+
+type Part = UIMessagePart<UIDataTypes, UITools>;
 
 // A real app fills the attachment from `useFileUpload` (the uploaded file's URL);
 // this mock uses an inline placeholder so the example needs no network image.
@@ -34,20 +36,20 @@ const MOCK_PHOTO: DisplayFile = {
 // carries the single Download. All mock — the recipe, not a CAD engine.
 // ─────────────────────────────────────────────────────────────────────────────
 
-type ScriptStep = Omit<AgentRunStep, "status">;
+type ScriptStep = { id: string; label: string };
 type Dims = { L: number; W: number; H: number };
 
 const RECOGNIZE: ScriptStep[] = [
-  { id: "r1", label: "Reading the photo", detail: "A single brown carton on a white sweep, card left for scale." },
-  { id: "r2", label: "reference_dielines.search", kind: "tool" },
-  { id: "r3", label: "Identifying the box style", detail: "Four flaps meet at the centre seam → Regular Slotted Container, FEFCO 0201." },
-  { id: "r4", label: "Estimating dimensions", detail: "Scaling against the reference card — about 320 × 230 × 150 mm." },
-  { id: "r5", label: "Drafting the dieline", kind: "tool" },
+  { id: "r1", label: "Reading the photo" },
+  { id: "r2", label: "reference_dielines.search" },
+  { id: "r3", label: "Identifying the box style" },
+  { id: "r4", label: "Estimating dimensions" },
+  { id: "r5", label: "Drafting the dieline" },
 ];
 
-const editScript = (prompt: string): ScriptStep[] => [
-  { id: "e1", label: "Reading the request", detail: prompt },
-  { id: "e2", label: "Recomputing the dieline", kind: "tool" },
+const EDIT_SCRIPT: ScriptStep[] = [
+  { id: "e1", label: "Reading the request" },
+  { id: "e2", label: "Recomputing the dieline" },
 ];
 
 const ZOOM_MIN = 0.4;
@@ -105,12 +107,13 @@ export function TplDieline() {
     return () => clearTimeout(t);
   }, [run, revealed]);
 
-  const liveItems: AgentRunItem[] = run
-    ? run.script.slice(0, revealed).map((s, i) => ({
-        type: "step",
-        ...s,
-        status: revealed < run.script.length && i === revealed - 1 ? "running" : "done",
-      }))
+  const liveItems: Part[] = run
+    ? run.script.slice(0, revealed).map((s, i): Part => {
+        const running = revealed < run.script.length && i === revealed - 1;
+        return running
+          ? { type: "dynamic-tool", toolName: s.label, toolCallId: s.id, state: "input-available", input: undefined }
+          : { type: "dynamic-tool", toolName: s.label, toolCallId: s.id, state: "output-available", input: undefined, output: undefined };
+      })
     : [];
 
   const startRecognize = () => {
@@ -135,7 +138,7 @@ export function TplDieline() {
     setPhase("working");
     setRevealed(0);
     setRun({
-      script: editScript(text),
+      script: EDIT_SCRIPT,
       onDone: () => {
         const m = /(\d+)\s*mm/i.exec(text);
         const delta = m ? Number(m[1]) : 5;
@@ -209,7 +212,7 @@ export function TplDieline() {
       <View style={{ position: "absolute", left: 0, right: 0, bottom: 24, alignItems: "center", paddingHorizontal: 16, pointerEvents: "none" }}>
         <View style={{ width: "100%", maxWidth: 620, pointerEvents: "auto" }}>
           {phase === "working" ? (
-            <AgentProgress items={liveItems} state="streaming" />
+            <AgentProgress parts={liveItems} state="streaming" />
           ) : (
             <Composer
               value={prompt}

package/examples/tpl_documents.tsx

@@ -22,11 +22,14 @@ import { useSelection } from "@lotics/ui/use_selection";
 import { FloatingActionBar } from "@lotics/ui/floating_action_bar";
 import { Dialog, DialogHeader, DialogHeaderTitle, DialogScrollArea, DialogFooter } from "@lotics/ui/dialog";
 import { CardSelectItem } from "@lotics/ui/card_select_item";
-import { AgentRun, type AgentRunItem, type AgentRunStep } from "@lotics/ui/agent_run";
+import { AgentRun } from "@lotics/ui/agent_run";
 import { type SourceRef } from "@lotics/ui/sources";
 import { ChangeValueInput, Change, ChangeField, ChangeFields, ChangeReasoning, ChangeRecord, ChangeReview, ChangeReviewActions, ChangeReviewHeader, type ChangeStatus } from "@lotics/ui/change_review";
 
 import { CompletionState } from "@lotics/ui/completion_state";
+import type { UIMessagePart, UIDataTypes, UITools } from "ai";
+
+type Part = UIMessagePart<UIDataTypes, UITools>;
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Template · Document desk — THE worked example for everything document-driven
@@ -50,7 +53,7 @@ import { CompletionState } from "@lotics/ui/completion_state";
 // split) and drops the toolbar button.
 // ─────────────────────────────────────────────────────────────────────────────
 
-type ScriptStep = Omit<AgentRunStep, "status">;
+type ScriptStep = { id: string; label: string; detail?: string; kind?: "tool" };
 type Task = "extract" | "check";
 type Phase = "fork" | "running" | "review" | "done";
 
@@ -276,14 +279,16 @@ export function TplDocuments() {
     return () => clearTimeout(t);
   }, [phase, revealed, script.length]);
 
-  const runItems: AgentRunItem[] = [
-    { type: "text", id: "in", text: (task === "check" ? "Comparing the documents against the record and each other." + (brief.trim() ? ` Also: ${brief.trim()}` : "") : "Reading the documents and comparing them with the record.") },
-    ...script.slice(0, Math.min(revealed + 1, script.length)).map((s, i): AgentRunItem => ({
-      type: "step", ...s, detail: i < revealed ? s.detail : undefined, status: i < revealed ? "done" : "running",
-    })),
+  const runItems: Part[] = [
+    { type: "text", text: (task === "check" ? "Comparing the documents against the record and each other." + (brief.trim() ? ` Also: ${brief.trim()}` : "") : "Reading the documents and comparing them with the record.") },
+    ...script.slice(0, Math.min(revealed + 1, script.length)).map((s, i): Part =>
+      i < revealed
+        ? { type: "dynamic-tool", toolName: s.label, toolCallId: s.id, state: "output-available", input: undefined, output: undefined }
+        : { type: "dynamic-tool", toolName: s.label, toolCallId: s.id, state: "input-available", input: undefined },
+    ),
   ];
   if (revealed >= script.length) {
-    runItems.push({ type: "text", id: "out", text: task === "check" ? "Checked 18 fields — 2 disagree, 1 worth noting. The findings are below." : "3 fields already match; 3 need a decision, and the invoice carries 2 lines the order doesn't have yet." });
+    runItems.push({ type: "text", text: task === "check" ? "Checked 18 fields — 2 disagree, 1 worth noting. The findings are below." : "3 fields already match; 3 need a decision, and the invoice carries 2 lines the order doesn't have yet." });
   }
 
   // Apply counts what actually commits: the kept fields.
@@ -498,7 +503,7 @@ export function TplDocuments() {
           </View>
         ) : null}
 
-        {phase === "running" ? <AgentRun items={runItems} state={revealed >= script.length ? "done" : "streaming"} /> : null}
+        {phase === "running" ? <AgentRun parts={runItems} state={revealed >= script.length ? "done" : "streaming"} /> : null}
 
         {phase === "review" && task === "extract" ? (
           <View style={{ gap: 16 }}>
@@ -695,9 +700,11 @@ export function TplDocuments() {
           </View>
         ) : genRunning ? (
           <AgentRun
-            items={genSteps.slice(0, Math.min(genRevealed + 1, genSteps.length)).map((st, i) => ({
-              type: "step", id: st.id, label: st.label, status: i < genRevealed ? "done" : "running",
-            }))}
+            parts={genSteps.slice(0, Math.min(genRevealed + 1, genSteps.length)).map((st, i): Part =>
+              i < genRevealed
+                ? { type: "dynamic-tool", toolName: st.label, toolCallId: st.id, state: "output-available", input: undefined, output: undefined }
+                : { type: "dynamic-tool", toolName: st.label, toolCallId: st.id, state: "input-available", input: undefined },
+            )}
             state={genRevealed >= genSteps.length ? "done" : "streaming"}
           />
         ) : !genDone ? (

package/examples/tpl_lookup.tsx

@@ -6,10 +6,13 @@ import { Divider } from "@lotics/ui/divider";
 import { Callout, CalloutText, CalloutTitle } from "@lotics/ui/callout";
 import { PressableHighlight } from "@lotics/ui/pressable_highlight";
 import { Composer } from "@lotics/ui/composer";
-import { AgentRun, type AgentRunStep, type AgentRunItem } from "@lotics/ui/agent_run";
+import { AgentRun } from "@lotics/ui/agent_run";
 import { Confidence, type ConfidenceLevel } from "@lotics/ui/confidence";
 import { Badge } from "@lotics/ui/badge";
 import { Sources, type SourceRef } from "@lotics/ui/sources";
+import type { UIMessagePart, UIDataTypes, UITools } from "ai";
+
+type Part = UIMessagePart<UIDataTypes, UITools>;
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Template · Answer desk — describe the goods on the LEFT, the agent RANKS the
@@ -134,13 +137,13 @@ const CANDIDATES: Candidate[] = [
   },
 ];
 
-type ScriptStep = Omit<AgentRunStep, "status">;
+type ScriptStep = { id: string; toolName: string; input?: unknown; output?: unknown };
 const SCRIPT: ScriptStep[] = [
-  { id: "r1", label: "Reading the description", detail: "Form, material, processing and presentation extracted." },
-  { id: "r2", label: "tariff_schedule.search", kind: "tool" },
-  { id: "r3", label: "Narrowing the heading", detail: "Matching the goods against chapter notes and exclusions." },
-  { id: "r4", label: "duty_rates.read", kind: "tool" },
-  { id: "r5", label: "Checking import policies", detail: "Permits, certificates and trade-remedy orders for the line." },
+  { id: "r1", toolName: "Reading the description", input: undefined },
+  { id: "r2", toolName: "tariff_schedule.search" },
+  { id: "r3", toolName: "Narrowing the heading", input: undefined },
+  { id: "r4", toolName: "duty_rates.read" },
+  { id: "r5", toolName: "Checking import policies", input: undefined },
 ];
 
 export function TplLookup() {
@@ -182,11 +185,13 @@ export function TplLookup() {
   };
 
   const streaming = phase === "running" && revealed < SCRIPT.length;
-  const items: AgentRunItem[] = SCRIPT.slice(0, revealed).map((s, i) => ({
-    type: "step",
-    ...s,
-    status: streaming && i === revealed - 1 ? "running" : "done",
-  }));
+  const items: Part[] = SCRIPT.slice(0, revealed).map((s, i): Part => {
+    const running = streaming && i === revealed - 1;
+    if (running) {
+      return { type: "dynamic-tool", toolName: s.toolName, toolCallId: s.id, state: "input-available", input: s.input };
+    }
+    return { type: "dynamic-tool", toolName: s.toolName, toolCallId: s.id, state: "output-available", input: s.input, output: s.output };
+  });
 
   return (
     <View style={{ flex: 1, flexDirection: "row", backgroundColor: colors.white }}>
@@ -200,7 +205,7 @@ export function TplLookup() {
 
         <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 16, gap: 16 }}>
           {/* current run */}
-          <AgentRun items={items} state={streaming ? "streaming" : "done"} />
+          <AgentRun parts={items} state={streaming ? "streaming" : "done"} />
 
           {/* Matches surface only once the run settles — the agent's output,
               never a pre-filled list; they sit at the bottom, under the run. */}

package/examples/tpl_record.tsx

@@ -65,10 +65,13 @@ import { SearchInput } from "@lotics/ui/search_input";
 import { useSelection } from "@lotics/ui/use_selection";
 import { FloatingActionBar } from "@lotics/ui/floating_action_bar";
 import { CardSelectItem } from "@lotics/ui/card_select_item";
-import { AgentRun, type AgentRunItem, type AgentRunStep } from "@lotics/ui/agent_run";
+import { AgentRun } from "@lotics/ui/agent_run";
 import { type SourceRef } from "@lotics/ui/sources";
 import { ChangeValueInput, Change, ChangeField, ChangeFields, ChangeReasoning, ChangeRecord, ChangeReview, ChangeReviewActions, ChangeReviewHeader, type ChangeStatus } from "@lotics/ui/change_review";
 import { CompletionState } from "@lotics/ui/completion_state";
+import type { UIMessagePart, UIDataTypes, UITools } from "ai";
+
+type Part = UIMessagePart<UIDataTypes, UITools>;
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Template · Record — THE record surface: the surface IS the editor, every
@@ -431,7 +434,7 @@ const CONTENT_MAX = 720;
 // that forks into extract / cross-check / edit-with-AI. The two templates
 // share this desk — change it in BOTH (the one divergence: generation lives
 // in this page's output sections, in tpl_documents' toolbar dialog).
-type ScriptStep = Omit<AgentRunStep, "status">;
+type ScriptStep = { id: string; toolName: string; input?: unknown; output?: unknown };
 type Task = "extract" | "check";
 type Phase = "fork" | "running" | "review" | "done";
 
@@ -455,15 +458,15 @@ const DOCS: Doc[] = [
 ];
 
 const EXTRACT_STEPS: ScriptStep[] = [
-  { id: "e1", label: "Reading the selected documents", detail: "Page by page, tables included" },
-  { id: "e2", label: "get_record", kind: "tool" },
-  { id: "e3", label: "Extracting field values", detail: "9 fields · 2 order lines" },
-  { id: "e4", label: "Comparing against the record", detail: "3 match · 1 new · 1 change · 1 conflict" },
+  { id: "e1", toolName: "Reading the selected documents" },
+  { id: "e2", toolName: "get_record" },
+  { id: "e3", toolName: "Extracting field values" },
+  { id: "e4", toolName: "Comparing against the record" },
 ];
 const CHECK_STEPS: ScriptStep[] = [
-  { id: "c1", label: "Reading the selected documents", detail: "Quantities, parties, dates and terms" },
-  { id: "c2", label: "get_record", kind: "tool" },
-  { id: "c3", label: "Cross-checking documents and record", detail: "18 fields compared across the sources" },
+  { id: "c1", toolName: "Reading the selected documents" },
+  { id: "c2", toolName: "get_record" },
+  { id: "c3", toolName: "Cross-checking documents and record" },
 ];
 
 // The shapes of an extract decision — an ADD, an UPDATE, a REMOVAL, a source
@@ -959,14 +962,16 @@ export function TplRecord() {
     return () => clearTimeout(t);
   }, [phase, revealed, script.length]);
 
-  const runItems: AgentRunItem[] = [
-    { type: "text", id: "in", text: (task === "check" ? "Comparing the documents against the record and each other." + (brief.trim() ? ` Also: ${brief.trim()}` : "") : "Reading the documents and comparing them with the record.") },
-    ...script.slice(0, Math.min(revealed + 1, script.length)).map((s, i): AgentRunItem => ({
-      type: "step", ...s, detail: i < revealed ? s.detail : undefined, status: i < revealed ? "done" : "running",
-    })),
+  const runItems: Part[] = [
+    { type: "text", text: (task === "check" ? "Comparing the documents against the record and each other." + (brief.trim() ? ` Also: ${brief.trim()}` : "") : "Reading the documents and comparing them with the record.") },
+    ...script.slice(0, Math.min(revealed + 1, script.length)).map((s, i): Part => (
+      i < revealed
+        ? { type: "dynamic-tool", toolName: s.toolName, toolCallId: s.id, state: "output-available", input: s.input, output: s.output }
+        : { type: "dynamic-tool", toolName: s.toolName, toolCallId: s.id, state: "input-available", input: s.input }
+    )),
   ];
   if (revealed >= script.length) {
-    runItems.push({ type: "text", id: "out", text: task === "check" ? "Checked 18 fields — 2 disagree, 1 worth noting. The findings are below." : "3 fields already match; 3 need a decision, and the invoice carries 2 lines the order doesn't have yet." });
+    runItems.push({ type: "text", text: task === "check" ? "Checked 18 fields — 2 disagree, 1 worth noting. The findings are below." : "3 fields already match; 3 need a decision, and the invoice carries 2 lines the order doesn't have yet." });
   }
 
   // Apply counts what actually commits: the kept fields.
@@ -2771,7 +2776,7 @@ export function TplRecord() {
           </View>
         ) : null}
 
-        {phase === "running" ? <AgentRun items={runItems} state={revealed >= script.length ? "done" : "streaming"} /> : null}
+        {phase === "running" ? <AgentRun parts={runItems} state={revealed >= script.length ? "done" : "streaming"} /> : null}
 
         {phase === "review" && task === "extract" ? (
           <View style={{ gap: 16 }}>

package/examples/tpl_task_board.tsx

@@ -27,12 +27,15 @@ import { DataGrid, gridRowStyle, type DataGridColumn, type DataGridGroup } from
 import { CONTROL_RADIUS } from "@lotics/ui/control_surface";
 import { cycleSort, sortBy, type SortState } from "@lotics/ui/sort_header";
 import { Composer } from "@lotics/ui/composer";
-import { AgentRun, type AgentRunItem } from "@lotics/ui/agent_run";
+import { AgentRun } from "@lotics/ui/agent_run";
 import { Change, ChangeReview, ChangeReviewActions, ChangeReviewHeader, ChangeSummary, type ChangeStatus } from "@lotics/ui/change_review";
 import { Dialog, DialogHeader, DialogHeaderTitle, DialogScrollArea, DialogFooter } from "@lotics/ui/dialog";
 import { CompletionState } from "@lotics/ui/completion_state";
 import { Confidence, type ConfidenceLevel } from "@lotics/ui/confidence";
 import { toISODate } from "@lotics/ui/format_date";
+import type { UIMessagePart, UIDataTypes, UITools } from "ai";
+
+type Part = UIMessagePart<UIDataTypes, UITools>;
 
 type TagOption = { value: string; label: string };
 
@@ -253,14 +256,16 @@ export function TplTaskBoard() {
     return () => clearTimeout(t);
   }, [phase, revealed]);
 
-  const runItems: AgentRunItem[] = [
-    { type: "text", id: "intro", text: "I read your notes and pulled out the work." },
-    ...DRAFT_STEPS.slice(0, Math.min(revealed + 1, DRAFT_STEPS.length)).map((s, i): AgentRunItem => ({
-      type: "step", id: `s${i}`, label: s.label, detail: i < revealed ? s.detail : undefined, status: i < revealed ? "done" : "running",
-    })),
+  const runItems: Part[] = [
+    { type: "text", text: "I read your notes and pulled out the work." },
+    ...DRAFT_STEPS.slice(0, Math.min(revealed + 1, DRAFT_STEPS.length)).map((s, i): Part =>
+      i < revealed
+        ? { type: "dynamic-tool", toolName: s.label, toolCallId: `s${i}`, state: "output-available", input: undefined, output: undefined }
+        : { type: "dynamic-tool", toolName: s.label, toolCallId: `s${i}`, state: "input-available", input: undefined },
+    ),
   ];
   if (revealed >= DRAFT_STEPS.length) {
-    runItems.push({ type: "text", id: "outro", text: `Drafted ${DRAFTED.length} tasks — keep the ones that look right, edit any before adding.` });
+    runItems.push({ type: "text", text: `Drafted ${DRAFTED.length} tasks — keep the ones that look right, edit any before adding.` });
   }
 
   const propertyCols: DataGridColumn<Task>[] = [
@@ -384,7 +389,7 @@ export function TplTaskBoard() {
             <Composer onSend={startDraft} placeholder="Paste your notes…" autoFocus sendLabel="Draft tasks" />
           </View>
         ) : null}
-        {phase === "reading" ? <AgentRun items={runItems} state={revealed >= DRAFT_STEPS.length ? "done" : "streaming"} /> : null}
+        {phase === "reading" ? <AgentRun parts={runItems} state={revealed >= DRAFT_STEPS.length ? "done" : "streaming"} /> : null}
         {phase === "review" ? (
           <View style={{ gap: 8 }}>
             <ChangeReviewHeader title="Drafted tasks" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "13.10.0",
+  "version": "14.0.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -264,9 +264,13 @@
     "react-dom": "^19.2.0",
     "react-native": ">=0.85.0",
     "react-native-svg": ">=15.0.0",
-    "react-native-web": ">=0.20.0"
+    "react-native-web": ">=0.20.0",
+    "ai": ">=7.0.0"
   },
   "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
     "expo-image": {
       "optional": true
     },

package/src/agent_progress.tsx

@@ -4,12 +4,16 @@ import { colors } from "./colors";
 import { Text } from "./text";
 import { WaveAvatar } from "./wave_avatar";
 import { PressableHighlight } from "./pressable_highlight";
-import { AgentRun, resolveToolMeta, type AgentRunItem } from "./agent_run";
+import { AgentRun, resolveToolMeta } from "./agent_run";
+import { toSegments, lastRunningStep, type AgentUIPart } from "./agent_transform";
 
 export interface AgentProgressProps {
-  /** The ordered transcript — same shape `AgentRun` takes. */
-  items: AgentRunItem[];
+  /** The agent message's ai-sdk `parts` — same shape `AgentRun` takes. */
+  parts: readonly AgentUIPart[];
   state?: "streaming" | "done" | "error";
+  /** A run-level breaking error, forwarded to the expanded `AgentRun` (a terminal
+   *  danger row). Lives outside `parts` — `useAgentRun().error`. */
+  error?: string;
   /** The collapsed-pill label. Defaults to the running step's label (or
    *  "Working…" / "Done"). */
   label?: string;
@@ -30,16 +34,11 @@ export interface AgentProgressProps {
  * label, so the surface stays calm until you ask to see the steps.
  */
 export function AgentProgress(props: AgentProgressProps) {
-  const { items, state = "streaming", label, labelForTool, stepsLabel, defaultExpanded } = props;
+  const { parts, state = "streaming", error, label, labelForTool, stepsLabel, defaultExpanded } = props;
   const [expanded, setExpanded] = useState(defaultExpanded ?? false);
 
-  const running = [...items].reverse().find((it) => it.type === "step" && it.status === "running");
-  const runningLabel =
-    running && running.type === "step"
-      ? running.kind === "tool"
-        ? resolveToolMeta(running.label, labelForTool).label
-        : running.label
-      : undefined;
+  const running = lastRunningStep(toSegments(parts));
+  const runningLabel = running ? resolveToolMeta(running.toolName, labelForTool).label : undefined;
   const compact = label ?? runningLabel ?? (state === "done" ? "Done" : state === "error" ? "Stopped" : "Working…");
   const streaming = state === "streaming";
 
@@ -48,7 +47,7 @@ export function AgentProgress(props: AgentProgressProps) {
       {expanded ? (
         <View style={styles.panel}>
           <ScrollView style={{ maxHeight: 260 }} contentContainerStyle={{ padding: 16 }}>
-            <AgentRun items={items} state={state} labelForTool={labelForTool} stepsLabel={stepsLabel} />
+            <AgentRun parts={parts} state={state} error={error} labelForTool={labelForTool} stepsLabel={stepsLabel} />
           </ScrollView>
         </View>
       ) : null}

package/src/agent_run.tsx

@@ -5,59 +5,31 @@ import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
 import { Markdown } from "./markdown";
 import { JsonPanel, stringifyData } from "./json_panel";
-import { Peek } from "./peek";
 import { PressableHighlight } from "./pressable_highlight";
 import { Marker, type StepStatus } from "./stepper";
 import { AnimationFadeIn } from "./animation_fade_in";
 import { CONTROL_HEIGHT, CONTROL_RADIUS } from "./control_surface";
 import { useLoticsLocale, type LoticsLocale } from "./locale";
 
-export type AgentStepStatus = "running" | "done" | "error";
-
-export interface AgentRunStep {
-  id: string;
-  /** A `tool` step carries the RAW tool name (`update_records`) — the feed maps
-   *  it to a human label via the default map / `labelForTool`. A `step` carries
-   *  an already-human label. */
-  label: string;
-  status: AgentStepStatus;
-  kind?: "step" | "tool";
-  /** The tool call's input (arguments) and result. When present (and no explicit
-   *  `peek`), the feed reveals them ON DEMAND — a press-to-open peek with an Input /
-   *  Output panel — instead of cluttering the row; the row itself shows only the
-   *  label + state. */
-  input?: unknown;
-  output?: unknown;
-  /** The tool failure message (shown in the peek when `status` is `"error"`). */
-  errorText?: string;
-  /** A note under the label — a short, human summary (a count, a result summary),
-   *  never invented prose. Muted. For raw tool I/O prefer `input`/`output`. */
-  detail?: string;
-  /** Custom content for the press-to-open peek. Overrides the auto-built Input /
-   *  Output panel — pass this to render the reveal yourself. */
-  peek?: ReactNode;
-}
-
-/**
- * The ordered transcript of a run, in the order it happened: the agent's answer
- * prose (`text`), its thinking (`reasoning`, shown collapsed / revealed on demand),
- * and the tools it runs between prose (`step`). A real run is a timeline — text, a
- * burst of tool calls, more text — so the feed is an ordered array, NOT a text
- * block over a flat step list. Consecutive `step` items collapse into ONE activity
- * group; a `step`'s `input`/`output` reveal in a peek on press.
- */
-export type AgentRunItem =
-  | { type: "text"; id: string; text: string }
-  | { type: "reasoning"; id: string; text: string }
-  | ({ type: "step" } & AgentRunStep);
+// The render model comes STRAIGHT from ai-sdk `UIMessage.parts` — no bespoke
+// transcript type. `agent_transform` is the one place that folds parts into the
+// timeline; this file is the renderer.
+import { toSegments, anyRunning, type AgentUIPart, type AgentStep } from "./agent_transform";
 
 export interface AgentRunProps {
-  /** The ordered transcript — text + step items in the order they occurred. */
-  items: AgentRunItem[];
-  /** Whole-run state. `streaming` keeps the trailing text's caret blinking and
-   *  the tail activity group pulsing; `done`/`error` settle every group. Defaults
-   *  to `streaming` while any step is `running`. */
+  /** The agent message's ai-sdk `parts` — the ordered transcript, rendered in
+   *  place. Chat passes `message.parts`; an app passes `useAgentRun().parts`. */
+  parts: readonly AgentUIPart[];
+  /** Whole-run state. `streaming` keeps the tail activity group pulsing;
+   *  `done`/`error` settle every group. Defaults to `streaming` while any tool
+   *  step is running. */
   state?: "streaming" | "done" | "error";
+  /** A run-level BREAKING error — the message that terminated the run (a stream
+   *  error, an API failure, a hit quota). It lives OUTSIDE `parts` (chat stores it
+   *  in the message's `errors`; `useAgentRun().error` carries it), so pass it here;
+   *  it renders as a terminal danger row under the transcript. A per-tool failure
+   *  is different — it rides in that tool's own `output-error` part. */
+  error?: string;
   /** Localize / override a TOOL step's display label by its raw tool name
    *  (`update_records` → "Đang cập nhật dữ liệu"). Return `undefined` to fall
    *  back to the built-in label. */
@@ -107,36 +79,9 @@ export function resolveToolMeta(
   };
 }
 
-/** Resolve a step's display label — a `tool` maps its raw name, a `step` is
- *  already human. */
-function stepLabel(s: AgentRunStep, labelForTool?: (toolName: string) => string | undefined): string {
-  return s.kind === "tool" ? resolveToolMeta(s.label, labelForTool).label : s.label;
-}
-
-// A run is a timeline of segments: prose, thinking, then a group of consecutive
-// tool calls, then more prose. Folding the flat item list into segments is what
-// lets the feed interleave instead of forcing all text to the top.
-type Segment =
-  | { kind: "text"; id: string; text: string }
-  | { kind: "reasoning"; id: string; text: string }
-  | { kind: "group"; id: string; steps: AgentRunStep[] };
-
-function toSegments(items: AgentRunItem[]): Segment[] {
-  const segments: Segment[] = [];
-  for (const item of items) {
-    if (item.type === "text" || item.type === "reasoning") {
-      segments.push({ kind: item.type, id: item.id, text: item.text });
-      continue;
-    }
-    const { type: _t, ...step } = item;
-    const tail = segments[segments.length - 1];
-    if (tail && tail.kind === "group") {
-      segments[segments.length - 1] = { ...tail, steps: [...tail.steps, step] };
-    } else {
-      segments.push({ kind: "group", id: item.id, steps: [step] });
-    }
-  }
-  return segments;
+/** Resolve a tool step's display label from its raw tool name. */
+function stepLabel(s: AgentStep, labelForTool?: (toolName: string) => string | undefined): string {
+  return resolveToolMeta(s.toolName, labelForTool).label;
 }
 
 const INK = colors.zinc[700];
@@ -147,15 +92,14 @@ const INK = colors.zinc[700];
  * tail group is a SINGLE pulsing row whose label swaps in place as each call
  * fires (not a growing stack of dots); once prose resumes the group settles into
  * one row — "{final action} · {n} steps" — that EXPANDS on press to the steps in
- * between. Text segments render as prose, the last one carrying a live caret. The
- * run always ends on the agent's text. Pair with `Composer` + `ChangeReview`.
+ * between. Text segments render as prose. The run always ends on the agent's text.
+ * Pair with `Composer` + `ChangeReview`.
  */
 export function AgentRun(props: AgentRunProps) {
-  const { items, labelForTool, stepsLabel = (n) => `${n} steps`, accessibilityLabel } = props;
-  const anyRunning = items.some((it) => it.type === "step" && it.status === "running");
-  const state = props.state ?? (anyRunning ? "streaming" : "done");
+  const { parts, labelForTool, stepsLabel = (n) => `${n} steps`, accessibilityLabel } = props;
+  const segments = toSegments(parts);
+  const state = props.state ?? (anyRunning(segments) ? "streaming" : "done");
   const streaming = state === "streaming";
-  const segments = toSegments(items);
   const lastIndex = segments.length - 1;
 
   const [expanded, setExpanded] = useState<Record<string, boolean>>({});
@@ -167,7 +111,7 @@ export function AgentRun(props: AgentRunProps) {
         if (seg.kind === "text") {
           return (
             <View key={seg.id} style={styles.narration}>
-              <Markdown>{streaming && i === lastIndex ? `${seg.text} ▍` : seg.text}</Markdown>
+              <Markdown>{seg.text}</Markdown>
             </View>
           );
         }
@@ -186,6 +130,20 @@ export function AgentRun(props: AgentRunProps) {
           />
         );
       })}
+      {/* A run-level BREAKING error terminates the feed with a danger row. It lives
+          outside `parts` (the stream failed), so the caller passes it explicitly. */}
+      {props.error ? (
+        <View style={styles.row}>
+          <View style={styles.dotCol}>
+            <Icon name="circle-alert" size={17} color={colors.red[500]} />
+          </View>
+          <View style={styles.rowBody}>
+            <Text size="sm" color="danger">
+              {props.error}
+            </Text>
+          </View>
+        </View>
+      ) : null}
     </View>
   );
 }
@@ -213,7 +171,7 @@ function ActivityRow(props: {
   );
   if (onPress) {
     return (
-      <PressableHighlight focusRing onPress={onPress} accessibilityRole="button" accessibilityLabel={accessibilityLabel} style={styles.row}>
+      <PressableHighlight focusRing userSelect="none" onPress={onPress} accessibilityRole="button" accessibilityLabel={accessibilityLabel} style={styles.row}>
         {inner}
       </PressableHighlight>
     );
@@ -221,25 +179,14 @@ function ActivityRow(props: {
   return <View style={styles.row}>{inner}</View>;
 }
 
-function StepBody({ label, detail, status }: { label: string; detail?: string; status: AgentStepStatus }) {
-  return (
-    <View style={{ gap: 1 }}>
-      <Text size="sm">{label}</Text>
-      {detail ? (
-        <Text size="xs" color={status === "error" ? "danger" : "muted"}>
-          {detail}
-        </Text>
-      ) : null}
-    </View>
-  );
+function StepBody({ label }: { label: string }) {
+  return <Text size="sm">{label}</Text>;
 }
 
-// The press-to-open reveal for a tool step: the caller's `peek` wins; else Input /
-// Output / Error panels auto-built from the carried I/O; else nothing (no reveal).
-// Raw I/O stays OUT of the row — only shown here, on demand. Panel titles come from
-// the locale (the caller supplies a whole `peek` to override).
-function stepPeek(s: AgentRunStep, labels: LoticsLocale["agentRun"]): ReactNode {
-  if (s.peek) return s.peek;
+// The on-demand reveal for a tool step: Input / Output / Error panels auto-built
+// from the carried I/O; nothing if there's none. Raw I/O stays OUT of the row — only
+// shown here, on demand. Panel titles come from the locale.
+function stepDetail(s: AgentStep, labels: LoticsLocale["agentRun"]): ReactNode {
   const hasInput = s.input !== undefined;
   const hasOutput = s.output !== undefined;
   if (!hasInput && !hasOutput && !s.errorText) return null;
@@ -255,18 +202,28 @@ function stepPeek(s: AgentRunStep, labels: LoticsLocale["agentRun"]): ReactNode
   );
 }
 
-// A step's body, wrapped in a Peek when there's something to reveal (I/O or a
-// caller peek), plain otherwise.
-function StepContent({ s, label }: { s: AgentRunStep; label: string }) {
+// A settled step row. When the step carries I/O (or an error) it EXPANDS IN PLACE on
+// press — the panels roll out under the row (same disclosure pattern as "Thinking"),
+// never a popover — so an errored call reads like any other step until you open it.
+function StepRow({ s, label }: { s: AgentStep; label: string }) {
   const locale = useLoticsLocale();
-  const peek = stepPeek(s, locale.agentRun);
-  const body = <StepBody label={label} detail={s.detail} status={s.status} />;
-  return peek ? (
-    <Peek accessibilityLabel={label} content={peek}>
-      {body}
-    </Peek>
-  ) : (
-    body
+  const [open, setOpen] = useState(false);
+  const detail = stepDetail(s, locale.agentRun);
+  const marker: StepStatus = s.status === "error" ? "warning" : "done";
+  if (!detail) {
+    return (
+      <ActivityRow markerStatus={marker}>
+        <StepBody label={label} />
+      </ActivityRow>
+    );
+  }
+  return (
+    <View>
+      <ActivityRow markerStatus={marker} onPress={() => setOpen((o) => !o)} accessibilityLabel={label} trailing={chevron(open ? "up" : "down")}>
+        <StepBody label={label} />
+      </ActivityRow>
+      {open ? <View style={styles.rowDetail}>{detail}</View> : null}
+    </View>
   );
 }
 
@@ -277,7 +234,7 @@ function ReasoningDisclosure(props: { text: string; streaming?: boolean; expande
   const locale = useLoticsLocale();
   return (
     <View style={styles.group}>
-      <PressableHighlight focusRing onPress={onToggle} accessibilityRole="button" accessibilityLabel={locale.agentRun.thinking} style={styles.row}>
+      <PressableHighlight focusRing userSelect="none" onPress={onToggle} accessibilityRole="button" accessibilityLabel={locale.agentRun.thinking} style={styles.row}>
         <View style={styles.dotCol}>
           <Marker status={streaming ? "current" : "done"} color={colors.zinc[400]} live={!!streaming} />
         </View>
@@ -313,7 +270,7 @@ function chevron(dir: "down" | "up") {
 }
 
 function ToolGroup(props: {
-  steps: AgentRunStep[];
+  steps: AgentStep[];
   active: boolean;
   expanded: boolean;
   onToggle: () => void;
@@ -321,7 +278,7 @@ function ToolGroup(props: {
   stepsLabel: (n: number) => string;
 }) {
   const { steps, active, expanded, onToggle, labelForTool, stepsLabel } = props;
-  const resolve = (s: AgentRunStep) => stepLabel(s, labelForTool);
+  const resolve = (s: AgentStep) => stepLabel(s, labelForTool);
 
   // ACTIVE — one pulsing row whose label swaps in place as each call fires (the
   // label is keyed by the current step's id, so a new call rises + fades into the
@@ -332,7 +289,7 @@ function ToolGroup(props: {
       <View style={styles.group}>
         <ActivityRow markerStatus="current" live>
           <AnimationFadeIn key={current.id} translateY={4}>
-            <StepBody label={resolve(current)} detail={current.detail} status={current.status} />
+            <StepBody label={resolve(current)} />
           </AnimationFadeIn>
         </ActivityRow>
       </View>
@@ -343,13 +300,11 @@ function ToolGroup(props: {
   const final = steps[steps.length - 1];
   const expandable = steps.length > 1;
 
-  // SETTLED, single call — just the one done/warning row (nothing to expand).
+  // SETTLED, single call — one done/warning row (its I/O expands in place on press).
   if (!expandable) {
     return (
       <View style={styles.group}>
-        <ActivityRow markerStatus={final.status === "error" ? "warning" : "done"}>
-          <StepContent s={final} label={resolve(final)} />
-        </ActivityRow>
+        <StepRow s={final} label={resolve(final)} />
       </View>
     );
   }
@@ -372,9 +327,7 @@ function ToolGroup(props: {
       {expanded
         ? steps.map((s) => (
             <AnimationFadeIn key={s.id} translateY={4}>
-              <ActivityRow markerStatus={s.status === "error" ? "warning" : "done"}>
-                <StepContent s={s} label={resolve(s)} />
-              </ActivityRow>
+              <StepRow s={s} label={resolve(s)} />
             </AnimationFadeIn>
           ))
         : null}
@@ -394,9 +347,17 @@ const styles = StyleSheet.create({
     gap: 10,
     minHeight: CONTROL_HEIGHT,
     borderRadius: CONTROL_RADIUS,
+    // The hover/press highlight BLEEDS 8px past the content on each side (negative
+    // margin absorbed by equal padding, the Peek pattern), so its rounded edges
+    // never pinch against the leading dot or the trailing chevron. Content stays
+    // flush-aligned (net zero), so the run's left edge still meets the consumer's gutter.
+    marginHorizontal: -8,
+    paddingHorizontal: 8,
   },
   dotCol: { width: 18, alignItems: "center" },
   rowBody: { flex: 1 },
   // Reasoning body aligns under the "Thinking" label (past the dot column + gap).
   reasoning: { paddingLeft: 28, paddingBottom: 4 },
+  // A step's expanded I/O panels — same left edge as the reasoning body.
+  rowDetail: { paddingLeft: 28, paddingBottom: 6, paddingTop: 2 },
 });

package/src/agent_transform.ts

@@ -0,0 +1,102 @@
+import type { UIMessagePart, UIDataTypes, UITools } from "ai";
+
+// `@lotics/ui` renders an agent run straight from the ai-sdk `UIMessage.parts` — the
+// canonical, versioned wire shape BOTH the chat and app agents already emit. There
+// is no bespoke transcript type: this module is the one place that folds parts into
+// the render timeline, shared by `AgentRun` and `AgentProgress`. Consumers pass their
+// message's `parts` (chat's static `tool-<name>` parts and the app SDK's
+// `dynamic-tool` parts are both handled).
+
+/** An ai-sdk message part, tool-set-agnostic (we only read `type` + a few fields). */
+export type AgentUIPart = UIMessagePart<UIDataTypes, UITools>;
+
+/** A tool step's settle state, collapsed from ai's 7-state tool machine. */
+export type AgentStepStatus = "running" | "done" | "error";
+
+/** One tool call, reduced to what the feed shows. `toolName` is the RAW name — the
+ *  renderer maps it to a human label + icon (`resolveToolMeta`). */
+export interface AgentStep {
+  id: string;
+  toolName: string;
+  status: AgentStepStatus;
+  /** Revealed ON DEMAND (a press-to-open peek), never inline. */
+  input?: unknown;
+  output?: unknown;
+  errorText?: string;
+}
+
+/** The render timeline: prose, thinking, and groups of consecutive tool calls, in
+ *  the order they streamed. */
+export type AgentSegment =
+  | { kind: "text"; id: string; text: string }
+  | { kind: "reasoning"; id: string; text: string }
+  | { kind: "group"; id: string; steps: AgentStep[] };
+
+// A tool part — static (`tool-<name>`) or `dynamic-tool` — is exactly the part union
+// that carries `toolCallId`, so extracting on that field is a sound, cast-free guard.
+function isToolPart(part: AgentUIPart): part is Extract<AgentUIPart, { toolCallId: string }> {
+  return part.type === "dynamic-tool" || part.type.startsWith("tool-");
+}
+
+// ai's tool state machine → the feed's 3 states. Approval-pending/responded read as
+// "running" (a read-only feed has no approval affordance); denied reads as an error.
+function toStatus(state: string): AgentStepStatus {
+  if (state === "output-available") return "done";
+  if (state === "output-error" || state === "output-denied") return "error";
+  return "running";
+}
+
+function toStep(part: Extract<AgentUIPart, { toolCallId: string }>): AgentStep {
+  return {
+    id: part.toolCallId,
+    toolName: part.type === "dynamic-tool" ? part.toolName : part.type.slice("tool-".length),
+    status: toStatus(part.state),
+    input: part.input,
+    output: part.state === "output-available" ? part.output : undefined,
+    errorText: part.state === "output-error" ? part.errorText : undefined,
+  };
+}
+
+/**
+ * Fold a message's parts into the render timeline. Consecutive tool parts collapse
+ * into ONE group (the feed shows a burst as a single expandable row). Prose parts
+ * carry no id in ai's model, so a stable index-based one is synthesized. Part kinds
+ * with no feed representation (`step-start`, `file`, `source-*`, `data-*`, `custom`)
+ * are skipped — the same kinds the chat's own renderer ignores.
+ */
+export function toSegments(parts: readonly AgentUIPart[]): AgentSegment[] {
+  const segments: AgentSegment[] = [];
+  parts.forEach((part, i) => {
+    if (part.type === "text") {
+      if (part.text) segments.push({ kind: "text", id: `text-${i}`, text: part.text });
+      return;
+    }
+    if (part.type === "reasoning") {
+      if (part.text) segments.push({ kind: "reasoning", id: `reasoning-${i}`, text: part.text });
+      return;
+    }
+    if (!isToolPart(part)) return;
+    const step = toStep(part);
+    const tail = segments[segments.length - 1];
+    if (tail?.kind === "group") tail.steps.push(step);
+    else segments.push({ kind: "group", id: step.id, steps: [step] });
+  });
+  return segments;
+}
+
+/** Whether any tool step is still running — the default "is the run streaming" signal. */
+export function anyRunning(segments: readonly AgentSegment[]): boolean {
+  return segments.some((s) => s.kind === "group" && s.steps.some((st) => st.status === "running"));
+}
+
+/** The last still-running tool step, if any — for a compact "currently doing X". */
+export function lastRunningStep(segments: readonly AgentSegment[]): AgentStep | undefined {
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const seg = segments[i];
+    if (seg.kind !== "group") continue;
+    for (let j = seg.steps.length - 1; j >= 0; j--) {
+      if (seg.steps[j].status === "running") return seg.steps[j];
+    }
+  }
+  return undefined;
+}

package/src/json_panel.tsx

@@ -1,4 +1,4 @@
-import { Platform, StyleSheet, View } from "react-native";
+import { Platform, ScrollView, StyleSheet, View } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 
@@ -15,18 +15,22 @@ export function JsonPanel(props: JsonPanelProps) {
         {title}
       </Text>
       <View style={styles.body}>
-        <Text
-          size="xs"
-          style={{
-            fontFamily:
-              Platform.OS === "web"
-                ? "ui-monospace, SFMono-Regular, Menlo, monospace"
-                : "monospace",
-            lineHeight: 18,
-          }}
-        >
-          {value}
-        </Text>
+        {/* A real dump can be tens of KB (a streamed tool input) — the panel caps
+            its height and scrolls inside, so it can never blow a feed open. */}
+        <ScrollView style={styles.scroll} contentContainerStyle={styles.content} nestedScrollEnabled>
+          <Text
+            size="xs"
+            style={{
+              fontFamily:
+                Platform.OS === "web"
+                  ? "ui-monospace, SFMono-Regular, Menlo, monospace"
+                  : "monospace",
+              lineHeight: 18,
+            }}
+          >
+            {value}
+          </Text>
+        </ScrollView>
       </View>
     </View>
   );
@@ -50,6 +54,14 @@ const styles = StyleSheet.create({
     borderColor: colors.zinc[200],
     borderRadius: 8,
     backgroundColor: colors.white,
+    // The ScrollView owns the padding (content inset scrolls with the text); the
+    // frame just clips so the scrollbar respects the rounded corners.
+    overflow: "hidden",
+  },
+  scroll: {
+    maxHeight: 240,
+  },
+  content: {
     paddingHorizontal: 10,
     paddingVertical: 8,
   },

package/src/primitives_purity.test.ts

@@ -21,18 +21,31 @@ import * as path from "node:path";
  * import `./markdown`. So it's allowed — the guards below remain for the
  * genuine context couplings.
  *
+ * The ONE allowed `ai` coupling: the `AgentRun` family renders the ai-sdk
+ * `UIMessage.parts` shape directly — that IS its contract (both chat and app
+ * agents emit it), so there is no bespoke transcript type to keep in sync.
+ * `agent_transform.ts` (the single place that folds parts into the render
+ * timeline) `import type`s from `ai` — erased at runtime, so no `ai` enters any
+ * consumer's bundle. That file alone is exempt from the `ai`-package guard; every
+ * other primitive stays ai-free, and the `@ai-sdk/*` runtime packages are never
+ * allowed anywhere.
+ *
  * The boundary is enforced by this test — without it primitives drift
  * back into the parent app's contexts over months.
  */
 
+const AI_PACKAGE_PATTERN = /from\s+["']ai["']/;
 const FORBIDDEN_PATTERNS = [
   /from\s+["']posthog-js/,
   /from\s+["']@lingui\//,
   /from\s+["']@ai-sdk\//,
-  /from\s+["']ai["']/,
+  AI_PACKAGE_PATTERN,
   /from\s+["']@lotics\/shared/,
 ];
 
+// The sole file permitted to `import type` from the `ai` package (see above).
+const AI_PACKAGE_ALLOWED = new Set(["agent_transform.ts"]);
+
 const SRC_DIR = path.resolve(__dirname);
 
 function listTopLevelSourceFiles(): string[] {
@@ -49,6 +62,7 @@ describe("packages/ui primitives — purity", () => {
     for (const file of listTopLevelSourceFiles()) {
       const src = fs.readFileSync(file, "utf-8");
       for (const pattern of FORBIDDEN_PATTERNS) {
+        if (pattern === AI_PACKAGE_PATTERN && AI_PACKAGE_ALLOWED.has(path.basename(file))) continue;
         if (pattern.test(src)) {
           violations.push(`${path.basename(file)} matches ${pattern}`);
         }