@lotics/app-sdk 0.53.0 → 0.54.1

package/AGENTS.md

@@ -20,7 +20,7 @@ signature; open the file.**
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs, workflow-generated files, preview pairing, filter operators, the server-side delivery bounds. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
-| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming `items` → `AgentRun`), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). |
+| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen. |
 | [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), `getAppBinding` (package apps' runtime `F`/`OPT`/`ROLE` resolution via the generated `.lotics/app_fields.ts`), and the publish chain for package contributors. |
 

package/dist/src/agent_stream.d.ts

@@ -3,63 +3,28 @@
  *
  * The backend streams the AI-SDK "UI message" SSE protocol (the same wire format
  * the chat uses) — `data: <json>\n\n` frames, each a typed chunk, terminated by
- * `data: [DONE]`. The app SDK consumes it WITHOUT depending on the `ai` package
- * (the sandboxed app bundle stays lean): we read the handful of chunk types that
- * matter for a run feed and fold them into `AgentRunState`. Unknown chunk types
- * are ignored, so an AI-SDK version that adds chunk kinds never breaks the SDK.
+ * `data: [DONE]`. We fold the chunk types that matter into an ordered `parts` array
+ * — the SAME ai-sdk `UIMessagePart[]` shape `@lotics/ui`'s `AgentRun` renders, so
+ * `<AgentRun parts={run.parts} />` needs no adapter. `ai` is a TYPE-ONLY import here
+ * (tool calls are hand-built as concrete `dynamic-tool` parts); NO `ai` runtime
+ * enters the sandboxed app bundle. Unknown chunk types are ignored, so a newer
+ * AI-SDK never breaks the SDK.
  *
- * Chunks fold into an ordered `items` transcript — answer prose, thinking
- * (`reasoning`, kept a distinct segment so the UI can collapse it), and tool steps
- * (each carrying its `input`/`output`/`status` for an on-demand reveal), in stream
- * order — that feeds `@lotics/ui` `AgentRun` directly. An agent can be either kind:
- * a STRUCTURED agent (declares `outputs`) emits its result as the input of the
- * injected `submit_result` tool → `output`; a FREE-TEXT agent's result is its prose
- * → the transcript's text. `output` is NEVER the free-text (see
- * `AgentRunState.output`). Pure + reducer-shaped so it is fully unit-testable
- * against recorded frames — no live model needed.
+ * An agent can be either kind: a STRUCTURED agent (declares `outputs`) emits its
+ * result as the input of the injected `submit_result` tool → `output` (NOT a part);
+ * a FREE-TEXT agent's result is its prose → a text part. `output` is NEVER the
+ * free-text (see `AgentRunState.output`). Pure + reducer-shaped so it is fully
+ * unit-testable against recorded frames — no live model needed.
  */
-export interface AgentRunStep {
-    id: string;
-    label: string;
-    detail?: string;
-    status: "running" | "done" | "error";
-    kind?: "step" | "tool";
-    /** The tool call's input (arguments). Carried for on-demand reveal, NOT shown in
-     *  the feed — `@lotics/ui` `AgentRun` renders it in a press-to-open peek. */
-    input?: unknown;
-    /** The tool call's result, once it returns. On-demand reveal, same as `input`. */
-    output?: unknown;
-    /** The tool failure message, when `status` is `"error"`. */
-    errorText?: string;
-    /** Running count of streamed argument characters. While a tool call's arguments
-     *  are still generating, the reducer writes a live size into `detail` ("18 KB")
-     *  off this accumulator, so a long generation reads as progressing, not frozen;
-     *  both are cleared when the call settles. */
-    streamedChars?: number;
-}
-/** One entry in the ordered run transcript, in the order it streamed: the agent's
- *  answer prose (`text`), its thinking (`reasoning` — shown collapsed, revealed on
- *  demand), or a tool it ran (`step`). This is structurally the `AgentRunItem` that
- *  `@lotics/ui`'s `AgentRun` takes, so `<AgentRun items={run.items} state={…} />`
- *  needs no adapter — the SDK can't import the UI type (it must stay off the
- *  react-native-web dep tree), it mirrors the shape. */
-export type AgentRunItem = {
-    type: "text";
-    id: string;
-    text: string;
-} | {
-    type: "reasoning";
-    id: string;
-    text: string;
-} | ({
-    type: "step";
-} & AgentRunStep);
+import type { UIMessagePart, UIDataTypes, UITools } from "ai";
+/** An ai-sdk message part — the render model, tool-set-agnostic. */
+export type AgentUIPart = UIMessagePart<UIDataTypes, UITools>;
 export interface AgentRunState {
     status: "streaming" | "completed" | "error";
-    /** The ordered transcript — prose interleaved with the tool steps, as it
-     *  streamed. The single source of truth for the feed; `useAgentRun` derives the
-     *  backward-compat `text` / `steps` from it. */
-    items: AgentRunItem[];
+    /** The ordered transcript as ai-sdk `parts` — prose interleaved with the tool
+     *  calls (`dynamic-tool` parts), as it streamed. The single source of truth for
+     *  the feed; `useAgentRun` derives `text` / `steps` from it. */
+    parts: AgentUIPart[];
     /** The structured result — the `submit_result` tool's input — or `undefined`.
      *  NEVER the free-text answer: a free-text agent (or a structured one that
      *  finished without submitting) has no `output`; its answer is the transcript's

package/dist/src/agent_stream.js

@@ -3,20 +3,18 @@
  *
  * The backend streams the AI-SDK "UI message" SSE protocol (the same wire format
  * the chat uses) — `data: <json>\n\n` frames, each a typed chunk, terminated by
- * `data: [DONE]`. The app SDK consumes it WITHOUT depending on the `ai` package
- * (the sandboxed app bundle stays lean): we read the handful of chunk types that
- * matter for a run feed and fold them into `AgentRunState`. Unknown chunk types
- * are ignored, so an AI-SDK version that adds chunk kinds never breaks the SDK.
+ * `data: [DONE]`. We fold the chunk types that matter into an ordered `parts` array
+ * — the SAME ai-sdk `UIMessagePart[]` shape `@lotics/ui`'s `AgentRun` renders, so
+ * `<AgentRun parts={run.parts} />` needs no adapter. `ai` is a TYPE-ONLY import here
+ * (tool calls are hand-built as concrete `dynamic-tool` parts); NO `ai` runtime
+ * enters the sandboxed app bundle. Unknown chunk types are ignored, so a newer
+ * AI-SDK never breaks the SDK.
  *
- * Chunks fold into an ordered `items` transcript — answer prose, thinking
- * (`reasoning`, kept a distinct segment so the UI can collapse it), and tool steps
- * (each carrying its `input`/`output`/`status` for an on-demand reveal), in stream
- * order — that feeds `@lotics/ui` `AgentRun` directly. An agent can be either kind:
- * a STRUCTURED agent (declares `outputs`) emits its result as the input of the
- * injected `submit_result` tool → `output`; a FREE-TEXT agent's result is its prose
- * → the transcript's text. `output` is NEVER the free-text (see
- * `AgentRunState.output`). Pure + reducer-shaped so it is fully unit-testable
- * against recorded frames — no live model needed.
+ * An agent can be either kind: a STRUCTURED agent (declares `outputs`) emits its
+ * result as the input of the injected `submit_result` tool → `output` (NOT a part);
+ * a FREE-TEXT agent's result is its prose → a text part. `output` is NEVER the
+ * free-text (see `AgentRunState.output`). Pure + reducer-shaped so it is fully
+ * unit-testable against recorded frames — no live model needed.
  */
 /** The tool the backend injects to carry a typed structured result. */
 const SUBMIT_TOOL = "submit_result";
@@ -39,94 +37,89 @@ export function adoptSettledRun(state, settled) {
     return { ...state, status: "error", error: settled.error_message ?? "The run was stopped." };
 }
 export function initialAgentRunState() {
-    return { status: "streaming", items: [] };
+    return { status: "streaming", parts: [] };
 }
-/** A live size for a step's still-streaming arguments — B under 1 KB, else KB. */
-function formatStreamSize(chars) {
-    return chars < 1024 ? `${chars} B` : `${Math.round(chars / 1024)} KB`;
-}
-/** Grow the trailing prose segment of the given kind, or open a new one (after a
- *  tool ran, or when the kind flips text↔reasoning) — so the transcript interleaves
+/** Grow the trailing prose part of the given kind, or open a new one (after a tool
+ *  ran, or when the kind flips text↔reasoning) — so the transcript interleaves
  *  answer prose, thinking, and tools in the order they streamed. */
-function appendProse(items, kind, piece) {
-    const last = items[items.length - 1];
-    if (last?.type === kind) {
-        return [...items.slice(0, -1), { ...last, text: last.text + piece }];
+function appendProse(parts, kind, piece) {
+    const last = parts[parts.length - 1];
+    if (last && last.type === kind) {
+        return [...parts.slice(0, -1), { ...last, text: last.text + piece }];
     }
-    return [...items, { type: kind, id: `${kind}-${items.length}`, text: piece }];
+    const opened = kind === "text" ? { type: "text", text: piece, state: "streaming" } : { type: "reasoning", text: piece, state: "streaming" };
+    return [...parts, opened];
 }
-/** Apply an update to the tool step with the given call id (by identity), leaving
- *  the rest untouched. A missing id (older frame) or no match is a no-op. */
-function updateStep(items, toolCallId, fn) {
+/** Apply an update to the `dynamic-tool` part with the given call id (by identity),
+ *  leaving the rest untouched. A missing id (older frame) or no match is a no-op. */
+function updateTool(parts, toolCallId, fn) {
     if (!toolCallId)
-        return items;
-    return items.map((it) => (it.type === "step" && it.id === toolCallId ? fn(it) : it));
+        return parts;
+    return parts.map((p) => (p.type === "dynamic-tool" && p.toolCallId === toolCallId ? fn(p) : p));
 }
 /** Fold one chunk into the run state. Returns a new state (immutable). */
 export function reduceAgentChunk(state, chunk) {
     switch (chunk.type) {
         case "text-delta": {
             const piece = chunk.delta ?? "";
-            return piece ? { ...state, items: appendProse(state.items, "text", piece) } : state;
+            return piece ? { ...state, parts: appendProse(state.parts, "text", piece) } : state;
         }
         case "reasoning-delta": {
-            // Thinking is its OWN segment (not folded into the answer prose) so the UI can
+            // Thinking is its OWN part (not folded into the answer prose) so the UI can
             // keep it collapsed / revealed-on-demand rather than inline in the answer.
             const piece = chunk.delta ?? "";
-            return piece ? { ...state, items: appendProse(state.items, "reasoning", piece) } : state;
+            return piece ? { ...state, parts: appendProse(state.parts, "reasoning", piece) } : state;
         }
         case "tool-input-start":
         case "tool-input-available": {
             const name = chunk.toolName ?? "tool";
             if (name === SUBMIT_TOOL) {
-                // The agent emitted its structured result — not a transcript step.
+                // The agent emitted its structured result — routed to `output`, not a part.
                 return { ...state, output: chunk.input };
             }
-            const id = chunk.toolCallId ?? `${name}-${state.items.length}`;
-            // Upsert by call id: the step opens "running" the moment the call fires and
-            // settles when its output arrives (below), so the feed shows a live tool, not
-            // an instantly-done one. `input` rides along for the on-demand peek.
-            const existing = state.items.some((it) => it.type === "step" && it.id === id);
+            const id = chunk.toolCallId ?? `${name}-${state.parts.length}`;
+            // Upsert by call id: the tool part opens "input-available" (a running step in
+            // the feed) the moment the call fires and settles when its output arrives
+            // (below), so the feed shows a live tool, not an instantly-done one.
+            const existing = state.parts.some((p) => p.type === "dynamic-tool" && p.toolCallId === id);
             if (existing) {
-                return { ...state, items: updateStep(state.items, id, (s) => ({ ...s, label: s.label || name, input: chunk.input ?? s.input })) };
+                return { ...state, parts: updateTool(state.parts, id, (p) => ({ type: "dynamic-tool", toolName: p.toolName || name, toolCallId: id, state: "input-available", input: chunk.input ?? p.input })) };
             }
             return {
                 ...state,
-                items: [...state.items, { type: "step", id, label: name, kind: "tool", status: "running", input: chunk.input }],
-            };
-        }
-        case "tool-input-delta": {
-            // A tool's arguments streaming in — grow the step's live size so a long
-            // generation reads as progressing. `submit_result` created no step (it sets
-            // `output`), so its deltas find no matching step and this no-ops.
-            const len = (chunk.inputTextDelta ?? "").length;
-            if (!len)
-                return state;
-            return {
-                ...state,
-                items: updateStep(state.items, chunk.toolCallId, (s) => {
-                    const chars = (s.streamedChars ?? 0) + len;
-                    return { ...s, streamedChars: chars, detail: formatStreamSize(chars) };
-                }),
+                parts: [...state.parts, { type: "dynamic-tool", toolName: name, toolCallId: id, state: "input-available", input: chunk.input }],
             };
         }
+        case "tool-input-delta":
+            // A tool's arguments streaming in. The ai-parts model carries no live size, so
+            // this is a no-op — the part already reads as running.
+            return state;
         case "tool-output-available":
-            // Settled — drop the live streaming size; the row is just label + done.
-            return { ...state, items: updateStep(state.items, chunk.toolCallId, (s) => ({ ...s, status: "done", output: chunk.output, detail: undefined, streamedChars: undefined })) };
+            return { ...state, parts: updateTool(state.parts, chunk.toolCallId, (p) => ({ type: "dynamic-tool", toolName: p.toolName, toolCallId: p.toolCallId, state: "output-available", input: p.input, output: chunk.output })) };
         case "tool-output-error":
-            return { ...state, items: updateStep(state.items, chunk.toolCallId, (s) => ({ ...s, status: "error", errorText: chunk.errorText ?? "The tool failed." })) };
+            return { ...state, parts: updateTool(state.parts, chunk.toolCallId, (p) => ({ type: "dynamic-tool", toolName: p.toolName, toolCallId: p.toolCallId, state: "output-error", input: p.input, errorText: chunk.errorText ?? "The tool failed." })) };
         case "error":
             return { ...state, status: "error", error: chunk.errorText ?? "The run failed." };
         case "abort":
             return { ...state, status: state.status === "streaming" ? "error" : state.status, error: state.error ?? "The run was stopped." };
         case "finish": {
-            // Settle the status, and settle any tool still "running" (its output frame
-            // never came) to "done" so nothing spins forever. `output` is whatever
-            // `submit_result` set (else undefined) — never the accumulated text: a
-            // structured-output consumer reads `output.<field>`, so a stray free-text
-            // string there would crash it. The free-text answer is always in `text`.
-            const items = state.items.map((it) => (it.type === "step" && it.status === "running" ? { ...it, status: "done" } : it));
-            return { ...state, status: state.status === "error" ? "error" : "completed", items };
+            // Settle the status, and settle anything still streaming so nothing reads as
+            // in-progress on a completed run: a tool with no output frame → output-available
+            // (its output never came); a text/reasoning part still "streaming" → "done" (the
+            // stream's `text-end`/`reasoning-end` markers aren't tracked per-part). `output`
+            // is whatever `submit_result` set (else undefined) — NEVER the accumulated text:
+            // a structured-output consumer reads `output.<field>`, so a stray free-text
+            // string there would crash it. The free-text answer is always in a text part.
+            const parts = state.parts.map((p) => {
+                if (p.type === "dynamic-tool" && (p.state === "input-available" || p.state === "input-streaming")) {
+                    return { type: "dynamic-tool", toolName: p.toolName, toolCallId: p.toolCallId, state: "output-available", input: p.input, output: undefined };
+                }
+                if ((p.type === "text" || p.type === "reasoning") && p.state === "streaming") {
+                    return { ...p, state: "done" };
+                }
+                return p;
+            });
+            return { ...state, status: state.status === "error" ? "error" : "completed", parts };
         }
         default:
             return state;

package/dist/src/hooks.d.ts

@@ -1,9 +1,9 @@
 import { type AiContextValue } from "./rpc.js";
-import { type AgentRunStep, type AgentRunItem } from "./agent_stream.js";
+import { type AgentUIPart } from "./agent_stream.js";
 import type { AppWorkflows, AppWorkflowResults, AppQueries, AppAgents, AppAgentResults } from "./types.js";
 import type { ResolvedMember } from "./members.js";
 import type { ResolvedOption } from "./select.js";
-export type { AgentRunStep, AgentRunState, AgentRunItem } from "./agent_stream.js";
+export type { AgentRunState, AgentUIPart } from "./agent_stream.js";
 /** Fields shared by every query hook's return value. */
 interface QueryStateBase {
     /**
@@ -470,20 +470,15 @@ export interface UseAgentRun<TInput, TOutput> {
      *  user-facing "Stop" button to this, not `abort`. */
     cancel: () => void;
     status: "idle" | "streaming" | "completed" | "error";
-    /** The ordered run transcript — prose interleaved with tool steps, in stream
-     *  order. Feed straight to `@lotics/ui` `AgentRun`:
-     *  `<AgentRun items={run.items} state={run.status === "streaming" ? "streaming" : run.status === "error" ? "error" : "done"} />`
+    /** The ordered run transcript as ai-sdk `parts` — prose interleaved with tool
+     *  calls, in stream order. Feed straight to `@lotics/ui` `AgentRun`:
+     *  `<AgentRun parts={run.parts} state={run.status === "streaming" ? "streaming" : run.status === "error" ? "error" : "done"} />`
      *  — no hand-assembly. */
-    items: AgentRunItem[];
-    /** The agent's ANSWER prose (every `text` segment concatenated), accumulating
-     *  live — excludes thinking (`reasoning` is its own segment in `items`). For a
-     *  FREE-TEXT agent this IS the result; a structured agent's result is `output`.
-     *  Derived from `items`. */
+    parts: AgentUIPart[];
+    /** The agent's ANSWER prose (every `text` part concatenated), accumulating live —
+     *  excludes thinking (`reasoning` is its own part). For a FREE-TEXT agent this IS
+     *  the result; a structured agent's result is `output`. Derived from `parts`. */
     text: string;
-    /** Only the tool/step items (each with its `input`/`output`/`status`) — backward
-     *  compat with the older steps-only `AgentRun`. Prefer `items` (it keeps the
-     *  text↔reasoning↔tool ordering the feed renders). Derived from `items`. */
-    steps: AgentRunStep[];
     /** The structured result once the run completes — the agent's `submit_result`
      *  output. `undefined` when the run produced none (a free-text agent, or one that
      *  finished without submitting); a free-text answer lives in `text`, never here.
@@ -496,14 +491,14 @@ export interface UseAgentRun<TInput, TOutput> {
 /**
  * Run a streaming agent declared in `package.json` lotics.agents and invoked by
  * alias. `run(input, { sessionId })` starts it; progress streams into `status` +
- * the ordered `items` transcript (feed straight to `@lotics/ui` `AgentRun`). A
+ * the ordered `parts` transcript (feed straight to `@lotics/ui` `AgentRun`). A
  * STRUCTURED agent's result lands in `output`; a FREE-TEXT agent's answer is the
  * transcript's prose (`text`). Read the session's history with `useAgentRuns`.
  *
  * ```tsx
  * const recognize = useAgentRun("recognize");
  * await recognize.run({ image_file_id }, { sessionId });
- * // <AgentRun items={recognize.items} state={recognize.status === "streaming" ? "streaming" : "done"} />
+ * // <AgentRun parts={recognize.parts} state={recognize.status === "streaming" ? "streaming" : "done"} />
  * // then read recognize.output (structured) or recognize.text (free-text)
  * ```
  */

package/dist/src/hooks.js

@@ -586,26 +586,24 @@ export function useAgentRun(alias) {
             void rpc("agentRun.cancel", { run_id: runId }).catch(() => { });
         handleRef.current?.abort();
     }, []);
-    // `items` is the source of truth; `text` (all prose) and `steps` (tool items
-    // only) are the backward-compat views derived from it.
-    const items = state?.items ?? EMPTY_ITEMS;
-    const text = useMemo(() => items.reduce((acc, i) => (i.type === "text" ? acc + i.text : acc), ""), [items]);
-    const steps = useMemo(() => items.flatMap((i) => (i.type === "step" ? [{ id: i.id, label: i.label, detail: i.detail, status: i.status, kind: i.kind, input: i.input, output: i.output, errorText: i.errorText }] : [])), [items]);
+    // `parts` is the source of truth; `text` (all prose concatenated) is the derived
+    // answer view.
+    const parts = state?.parts ?? EMPTY_PARTS;
+    const text = useMemo(() => parts.reduce((acc, p) => (p.type === "text" ? acc + p.text : acc), ""), [parts]);
     return {
         run,
         abort,
         cancel,
         status: state?.status ?? "idle",
-        items,
+        parts,
         text,
-        steps,
         output: state?.output,
         error: state?.error,
     };
 }
-/** Stable empty transcript so an idle hook returns a constant `items` reference
+/** Stable empty transcript so an idle hook returns a constant `parts` reference
  *  (no new [] each render → dependents don't re-run needlessly). */
-const EMPTY_ITEMS = [];
+const EMPTY_PARTS = [];
 /**
  * Bounded PAST the server-side max-run cap (20 min) plus settle grace. The
  * server guarantees a LIVE run settles by its own cap timer, so a row still

package/dist/src/index.d.ts

@@ -17,7 +17,7 @@
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, } from "./hooks.js";
-export type { UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunRecord, AgentRunState, AgentRunStep, AgentRunItem, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
+export type { UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunRecord, AgentRunState, AgentUIPart, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";

package/docs/ai.md

@@ -1,6 +1,6 @@
 # AI in apps
 
-An app has two AI surfaces, and they answer different questions. **`useAgentRun(alias)`** runs an agent *declared on the app* — a streaming, tool-looping run whose result lands back **in the app** (a typed structured output, or free-text prose) for the app to review and commit through its own [workflows](./mutations.md). **`askAi(args)`** is a *handoff* — it opens the Lotics chat messenger seeded with files, records, and a prefilled prompt, and the outcome lands **in chat**, under the signed-in member's control. Beyond those two, **`useAiContext(slot, context)`** feeds the member's *ambient* chat agent — the one riding alongside the app — a snapshot of what the current screen is showing, so a question the member asks there resolves against what they're looking at. Read this doc when adding any AI-driven feature to an app; read [security](./security.md) first for the authority model agent runs execute under. Exact signatures: `dist/src/hooks.d.ts` (`useAgentRun`, `useAgentRuns`, `useAiContext`), `dist/src/agent_stream.d.ts` (`AgentRunItem`, `AgentRunStep`, `AgentRunState`), `dist/src/ask_ai.d.ts` (`AskAiArgs`).
+An app has two AI surfaces, and they answer different questions. **`useAgentRun(alias)`** runs an agent *declared on the app* — a streaming, tool-looping run whose result lands back **in the app** (a typed structured output, or free-text prose) for the app to review and commit through its own [workflows](./mutations.md). **`askAi(args)`** is a *handoff* — it opens the Lotics chat messenger seeded with files, records, and a prefilled prompt, and the outcome lands **in chat**, under the signed-in member's control. Beyond those two, **`useAiContext(slot, context)`** feeds the member's *ambient* chat agent — the one riding alongside the app — a snapshot of what the current screen is showing, so a question the member asks there resolves against what they're looking at. Read this doc when adding any AI-driven feature to an app; read [security](./security.md) first for the authority model agent runs execute under. Exact signatures: `dist/src/hooks.d.ts` (`useAgentRun`, `useAgentRuns`, `useAiContext`), `dist/src/agent_stream.d.ts` (`AgentRunState`, `AgentUIPart`), `dist/src/ask_ai.d.ts` (`AskAiArgs`).
 
 ## Choosing the surface — the fields-vs-file razor
 
@@ -41,7 +41,7 @@ import { useAgentRun } from "@lotics/app-sdk";
 
 const recognize = useAgentRun("recognize");
 await recognize.run({ image_file_id: fileId }, { sessionId });
-// live: recognize.status, recognize.items
+// live: recognize.status, recognize.parts
 // done: recognize.output (structured) or recognize.text (free-text)
 ```
 
@@ -53,33 +53,33 @@ await recognize.run({ image_file_id: fileId }, { sessionId });
 | `cancel` | `() => void` | Stop the run **server-side** (saves tokens) and locally. Wire a user-facing Stop button to this |
 | `abort` | `() => void` | Stop listening **locally only** — the run keeps executing server-side and its result is still persisted. This is the unmount path (the hook calls it automatically on unmount) |
 | `status` | `"idle" \| "streaming" \| "completed" \| "error"` | Whole-run state. `abort`/`cancel` reset it to `"idle"` (and clear the partial transcript) |
-| `items` | `AgentRunItem[]` | The ordered live transcript — answer prose, thinking, and tool steps, in stream order. The single source of truth for the feed |
-| `text` | `string` | The agent's **answer prose** (every `text` segment concatenated), accumulating live. Excludes thinking. For a free-text agent this IS the result |
-| `steps` | `AgentRunStep[]` | Only the tool/step items — a backward-compat view derived from `items`. Prefer `items` (it keeps the text↔reasoning↔tool ordering) |
+| `parts` | `AgentUIPart[]` | The ordered live transcript as **ai-sdk `UIMessage.parts`** — answer prose, thinking, and tool calls, in stream order. The single source of truth for the feed; hand it straight to `@lotics/ui` `AgentRun` |
+| `text` | `string` | The agent's **answer prose** (every `text` part concatenated), accumulating live. Excludes thinking. For a free-text agent this IS the result |
 | `output` | `TOutput \| undefined` | The structured result once the run completes. `undefined` when the run produced none |
 | `error` | `string \| undefined` | The failure message when `status` is `"error"` |
 
-### The `items` transcript → `@lotics/ui` `AgentRun`
+### The `parts` transcript → `@lotics/ui` `AgentRun`
 
-`AgentRunItem` is a discriminated union in stream order:
+`parts` is the **ai-sdk `UIMessagePart[]`** shape — the same wire model chat and app agents both emit, so there is no bespoke transcript type to keep in sync. The reducer folds the run's SSE chunks into it, in stream order:
 
-| `type` | Carries | Rendering intent |
+| Part `type` | Carries | Rendering intent |
 |---|---|---|
-| `"text"` | `id`, `text` | Answer prose, grows as it streams |
-| `"reasoning"` | `id`, `text` | The agent's thinking — a **distinct segment**, kept out of `text`, so the UI can show it collapsed / revealed on demand |
-| `"step"` | `AgentRunStep`: `id`, `label` (raw tool name), `status` (`"running" \| "done" \| "error"`), `kind`, `input`, `output`, `errorText`, `detail`, `streamedChars` | One tool call — opens `"running"` the moment it fires, settles when its result arrives. `input`/`output` ride along for an on-demand reveal, not for the feed. While a call's arguments are still generating, `detail` carries a live size ("18 KB", accumulated in `streamedChars`) so a long generation reads as progressing; both clear when the call's output arrives (a call that settles `"error"` keeps its last size) |
+| `"text"` | `text`, `state` | Answer prose, grows as it streams |
+| `"reasoning"` | `text`, `state` | The agent's thinking — a **distinct part**, kept out of `text`, so `AgentRun` shows it collapsed / revealed on demand. Only produced when the agent's declared model supports thinking (**Sonnet / Opus**, not Haiku) — a Haiku agent never emits reasoning |
+| `"dynamic-tool"` | `toolName`, `toolCallId`, `state` (ai's tool lifecycle — `input-available` → `output-available` / `output-error`), `input`, `output`, `errorText` | One tool call — opens running the moment it fires, settles when its result arrives. `input`/`output` ride along for `AgentRun`'s on-demand reveal, not for the feed row |
 
-The shape is structurally the `AgentRunItem` that `@lotics/ui`'s `AgentRun` component takes, so the pairing needs **no adapter and no hand-assembly**:
+The terminal `submit_result` call is captured into `output`, **not** rendered as a tool part (structured agents therefore have no visible final step). Source/file parts aren't emitted by app agents. `parts` is exactly what `@lotics/ui` `AgentRun` renders, so the pairing needs **no adapter and no hand-assembly**:
 
 ```tsx
 <AgentRun
-  items={run.items}
+  parts={run.parts}
   state={run.status === "streaming" ? "streaming" : run.status === "error" ? "error" : "done"}
+  error={run.error}                          // the breaking error — a terminal danger row
   labelForTool={(name) => toolLabels[name]}  // optional: localize tool labels
 />
 ```
 
-`AgentRun` renders thinking collapsed, groups consecutive tool steps, and shows each tool's input/output in a press-to-open peek — all for free. Never rebuild this feed from `text` + `steps`.
+`AgentRun` renders thinking collapsed, groups consecutive tool calls, and expands each tool's input/output in place on press — all for free. Running it in a bounded container (a dialog, a panel)? Wrap it in `@lotics/ui`'s `FollowScroll` so the container follows the stream instead of letting new content grow below the fold. **Errors surface two ways:** a per-tool failure is an `output-error` part (amber dot, reason in the expanded Error panel — the feed flows on, exactly like a run that retried and recovered); a **breaking** error that killed the run lives in `run.error` (not in `parts`) — pass it as `error` and it renders as a terminal danger row. Never rebuild this feed by hand.
 
 ### `output` typing and the inner-field caveat
 
@@ -266,7 +266,6 @@ The floors below are when each capability shipped in `@lotics/app-sdk`; an app p
 |---|---|
 | `useAgentRun` (with `abort`) + `useAgentRuns` | `@lotics/app-sdk` 0.34 |
 | `cancel()` (server-side stop) + connection-drop recovery | `@lotics/app-sdk` 0.37 |
-| `items` transcript (reasoning segments + per-tool `input`/`output`) | `@lotics/app-sdk` 0.43; rendering pairs with `@lotics/ui` ≥ 7.13 (`AgentRun` `items` prop) |
-| Live streamed-argument size on a running step (`detail`) | `@lotics/app-sdk` 0.44 |
+| `parts` transcript (ai-sdk `UIMessagePart[]` — reasoning + per-tool `input`/`output`) | `@lotics/app-sdk` 0.54; renders with `@lotics/ui` ≥ 14.0 (`AgentRun` `parts` prop) |
 | `askAi` | `@lotics/app-sdk` 0.45 |
 | `useAiContext` (ambient-chat view state + auto query refetch on chat mutation) | `@lotics/app-sdk` 0.52 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.53.0",
+  "version": "0.54.1",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -30,11 +30,15 @@
     "swr": "^2.4.1"
   },
   "peerDependencies": {
+    "ai": ">=7.0.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-router-dom": "^7.0.0"
   },
   "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
     "react-router-dom": {
       "optional": true
     }