@lotics/ui 13.9.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.
 
@@ -243,15 +255,23 @@ plain `useState` (controlled `status` everywhere); the family owns the mechanics
 Undo, the counter, Keep-all, apply gating). Never apply a field with no value — gate unresolved
 conflicts (`keepDisabled`, `applyDisabled`). Editing IS the review.
 
-## Ask back — `Clarify`
+## Ask back — `Clarify` / `ClarifyWizard`
 
 `Clarify` (`@lotics/ui/clarify`): when the agent is unsure, it asks a question with quick-reply
-options and PAUSES, instead of guessing wrong. Human-in-the-loop input mid-run: `question`,
-`options` (`{ label, value, description? }` — a `ChoiceList`), `onAnswer(value)` resumes the run,
-and the controlled `answer` keeps the pick switchable until committed.
-
-**Limitation:** the "Question" eyebrow above the prompt is currently hardcoded English (no label
-prop, not on the locale provider).
+options and PAUSES, instead of guessing wrong. Human-in-the-loop input mid-run: `question` (the
+prompt, rendered as-is — no eyebrow chrome), `options` (`{ label, value, description }` — every
+answer carries a REQUIRED one-line description so the human picks without re-deriving it from the
+question; a `ChoiceList`), `onAnswer(value)` resumes the run, the controlled `answer` keeps the pick
+switchable until committed. **`allowCustom`** adds an always-visible, borderless, auto-growing multiline field below the
+options — typing it IS the selection; its text becomes the value (any value not matching an option
+reads as the custom answer).
+
+`ClarifyWizard` (`@lotics/ui/clarify_wizard`): a SEQUENCE of clarify questions worked one at a time —
+Back / Next / Cancel / Submit (Next/Submit primary), the step position an eyebrow ("1 / 3") above the
+question — no progress bar. Each step is a `Clarify`; advance only once the
+current question is answered; `onSubmit` gives one `{ value, custom }` per question (aligned by index,
+`custom` true when the answer came from "Other…"), `onCancel` dismisses. All navigation chrome is
+locale-wired (the `clarify` slice). The multi-question form of the ask-back.
 
 ## Provenance — `Sources`
 

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 ·
@@ -980,11 +989,19 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `ChangeRecord` (THE item card: registers like a Change; tone wash + localized op word;
   verb level follows the decision level) · `ChangeBand` (the raw ± band) ·
   `ChangeValueInput` (the diff-at-rest editor); the `changeReview` locale slice.
-- **`clarify`** — `Clarify`: the agent asks back — a borderless block (question + a
-  `ChoiceList`), no card wrapper.
+- **`clarify`** — `Clarify` + `ClarifyOption`: the agent asks back — a borderless block
+  (the question text + a `ChoiceList`, no card wrapper; an optional muted `eyebrow` sits tight above
+  the question — e.g. a wizard's "1 / 3"). `ClarifyOption` requires
+  `{ value, label, description }` — the description is MANDATORY (every answer explains itself).
+  `allowCustom` adds an always-visible borderless multiline custom-answer field below the options.
+- **`clarify_wizard`** — `ClarifyWizard` + `ClarifyWizardQuestion`/`ClarifyWizardAnswer`: a SEQUENCE
+  of `Clarify` questions with Back/Next/Cancel/Submit + a `n / total` position indicator; advance
+  only when the current is answered, `onSubmit` returns one `{ value, custom }` per question.
+  Navigation chrome is locale-wired (the `clarify` locale slice).
 - **`choice_list`** — `ChoiceList` + `ChoiceOption`: selectable answer options as
   divider-separated rows (no bordered cards) with a per-row focus ring + hover wash; the
-  agent's quick-reply surface.
+  agent's quick-reply surface. `allowCustom` appends an always-visible borderless multiline field whose
+  text IS the value (a value not in `options` reads as the custom answer).
 - **`sources`** — `Sources` + `SourceRef`/`SourceKind` (record | document | table | web |
   knowledge): provenance chips, per-kind glyphs.
 - **`finding`** — `Finding` + `FindingComparison` + `FindingSeverity`/`FindingLabels`: one
@@ -1023,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.9.0",
+  "version": "14.0.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -89,6 +89,7 @@
     "./change_review": "./src/change_review.tsx",
     "./finding": "./src/finding.tsx",
     "./clarify": "./src/clarify.tsx",
+    "./clarify_wizard": "./src/clarify_wizard.tsx",
     "./choice_list": "./src/choice_list.tsx",
     "./sources": "./src/sources.tsx",
     "./icon": "./src/icon.tsx",
@@ -263,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}