@lotics/app-sdk 0.52.4 → 0.54.0

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/dist/src/row.d.ts

@@ -24,7 +24,9 @@ declare function bool(v: unknown): boolean;
 /**
  * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
  * calendar/gantt placement never shifts across timezones. Parses the leading
- * `YYYY-MM-DD` of the serialized string; null if absent or unparseable. (Range
+ * `YYYY[-MM[-DD]]` of the serialized string — a reduced-precision `date` value
+ * ("2026-05" / "2026") decodes to its PERIOD START (missing month/day → 1)
+ * rather than vanishing to null. Null only if absent or unparseable. (Range
  * fields are not handled here — they have no consumer yet.)
  */
 declare function date(v: unknown): Date | null;
@@ -34,8 +36,10 @@ declare function date(v: unknown): Date | null;
  * value is a timezone-less workspace wall-clock (see the serialization note
  * above), so it is read verbatim — no UTC conversion. Use this when the time
  * matters (a check-in time, an appointment); `date` keeps only the calendar day.
- * Parses `YYYY-MM-DD` with an optional `T`-or-space `HH:mm[:ss]`; a missing time
- * is midnight. Null if absent or unparseable.
+ * Parses `YYYY[-MM[-DD]]` with an optional `T`-or-space `HH:mm[:ss]`; a missing
+ * month/day is the period start (1) and a missing time is midnight — a
+ * reduced-precision value decodes rather than vanishing. Null if absent or
+ * unparseable.
  */
 declare function datetime(v: unknown): Date | null;
 /** A linked record cell entry — the target record's id + its display text. */

package/dist/src/row.js

@@ -53,12 +53,16 @@ function bool(v) {
 /**
  * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
  * calendar/gantt placement never shifts across timezones. Parses the leading
- * `YYYY-MM-DD` of the serialized string; null if absent or unparseable. (Range
+ * `YYYY[-MM[-DD]]` of the serialized string — a reduced-precision `date` value
+ * ("2026-05" / "2026") decodes to its PERIOD START (missing month/day → 1)
+ * rather than vanishing to null. Null only if absent or unparseable. (Range
  * fields are not handled here — they have no consumer yet.)
  */
 function date(v) {
-    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(text(v));
-    return m ? new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3])) : null;
+    const m = /^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?/.exec(text(v));
+    if (!m)
+        return null;
+    return new Date(Number(m[1]), (m[2] ? Number(m[2]) : 1) - 1, m[3] ? Number(m[3]) : 1);
 }
 /**
  * Date/datetime field → a LOCAL Date that KEEPS the stored wall-clock time, so
@@ -66,14 +70,16 @@ function date(v) {
  * value is a timezone-less workspace wall-clock (see the serialization note
  * above), so it is read verbatim — no UTC conversion. Use this when the time
  * matters (a check-in time, an appointment); `date` keeps only the calendar day.
- * Parses `YYYY-MM-DD` with an optional `T`-or-space `HH:mm[:ss]`; a missing time
- * is midnight. Null if absent or unparseable.
+ * Parses `YYYY[-MM[-DD]]` with an optional `T`-or-space `HH:mm[:ss]`; a missing
+ * month/day is the period start (1) and a missing time is midnight — a
+ * reduced-precision value decodes rather than vanishing. Null if absent or
+ * unparseable.
  */
 function datetime(v) {
-    const m = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2}))?/.exec(text(v));
+    const m = /^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?(?:[ T](\d{2}):(\d{2}))?/.exec(text(v));
     if (!m)
         return null;
-    return new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]), m[4] ? Number(m[4]) : 0, m[5] ? Number(m[5]) : 0);
+    return new Date(Number(m[1]), (m[2] ? Number(m[2]) : 1) - 1, m[3] ? Number(m[3]) : 1, m[4] ? Number(m[4]) : 0, m[5] ? Number(m[5]) : 0);
 }
 /** One `{ id, display }` object → ResolvedLink, or null if absent/malformed. */
 function asLink(v) {

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 4.6 / Opus 4.8**, 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. **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
 
@@ -130,7 +130,7 @@ Both truncation shapes emit the `app_agent_stream_truncated` analytics event (`k
 
 The poll is bounded at 22 minutes — deliberately PAST the server's 20-minute hard run cap, so a live run always settles before the client gives up. A row still `running` at the deadline means the run's process died mid-flight (e.g. a crash that skipped the server's shutdown drain); the poll surfaces an error and the server's reaper repairs the row. Only when no run id was ever received (the run never started) does the failure reject before any polling.
 
-On recovery, `output` adopts the row's output **only when it is an object** (a structured result) — the "`output` is never a stray string" rule holds on every path. A **free-text** run recovered from truncation keeps only the streamed prefix in `text`; read the full settled answer via `useAgentRuns(sessionId)` if you need it.
+On recovery, `output` adopts the row's output **only when it is an object** (a structured result) — the "`output` is never a stray string" rule holds on every path. A **free-text** run recovered from truncation keeps only the streamed prefix in `text`; the full settled answer is persisted server-side but is not currently client-readable (`useAgentRuns` can't reach it on any transport — see the limitation below), so treat the streamed prefix as terminal for now.
 
 ### Sessions
 
@@ -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/docs/data_fetching.md

@@ -228,7 +228,7 @@ Wire shapes per output column type:
 | `text` | `string` |
 | `number` | `number` (numeric database strings are normalized server-side; a rare decimal too precise for float64 stays a string — `row.num` parses both) |
 | `boolean` | `boolean` |
-| `date` | `"YYYY-MM-DD"` — a calendar day, no time component |
+| `date` | `"YYYY-MM-DD"` — a calendar day, no time component (a reduced-precision date field may also carry `"YYYY-MM"` or `"YYYY"`; see below) |
 | `datetime` | `"YYYY-MM-DDTHH:mm"` — workspace wall-clock, minute precision |
 | `select` | `Array<{ key, label }>` — one entry per selected option |
 | `select_member` | `Array<{ id, name, email? }>` — `email` only for authenticated viewers of the app's own org |
@@ -249,8 +249,8 @@ metadata. A grouped query collapses rows and emits none of these. Details:
 | `row.text(cell)` | any → `string` | strings pass through, finite numbers stringify, everything else → `""` |
 | `row.num(cell)` | any → `number` | numbers pass (NaN/Infinity → 0), parseable strings parse, everything else → `0` |
 | `row.bool(cell)` | any → `boolean` | `true` or the string `"true"`; everything else `false` |
-| `row.date(cell)` | date/datetime cell → `Date \| null` | the stored **calendar day** at LOCAL midnight — time stripped |
-| `row.datetime(cell)` | date/datetime cell → `Date \| null` | local `Date` **keeping the stored wall-clock** (minute precision; seconds are dropped); missing time = midnight |
+| `row.date(cell)` | date/datetime cell → `Date \| null` | the stored **calendar day** at LOCAL midnight — time stripped; a reduced-precision value decodes to its **period start** |
+| `row.datetime(cell)` | date/datetime cell → `Date \| null` | local `Date` **keeping the stored wall-clock** (minute precision; seconds are dropped); missing time = midnight; a reduced-precision value decodes to its **period start** |
 | `row.link(cell)` | link cell → `{ id, display } \| null` | the FIRST linked record |
 | `readLinks(cell)` | link cell → `{ id, display }[]` | ALL linked records (`[]` when empty) |
 | `readSelect(cell)` | select cell → `ResolvedOption[]` | all selected options as `{ key, label }` (`[]` when empty) |
@@ -262,7 +262,7 @@ All readers are pure (`unknown` in, value out), never throw, and return their em
 (`null` / `""` / `0` / `false` / `[]`) for absent or malformed input — so callers iterate and
 render without null-check pyramids.
 
-**`row.date` vs `row.datetime`.** `row.date` parses only the leading `YYYY-MM-DD` and builds a
+**`row.date` vs `row.datetime`.** `row.date` parses the leading `YYYY[-MM[-DD]]` and builds a
 LOCAL-midnight `Date` — calendar/gantt placement never shifts across viewer timezones. `row.datetime`
 keeps the stored wall-clock verbatim (no UTC conversion — the stored value is a timezone-less
 workspace wall-clock), so `getHours()` / `toLocaleTimeString()` render the time as written. A
@@ -270,6 +270,14 @@ workspace wall-clock), so `getHours()` / `toLocaleTimeString()` render the time
 and the UI prints `00:00`. When you need the time, the query must output the column as `datetime`
 (the type-override rules are in [./queries.md](./queries.md)).
 
+**Reduced-precision date values.** A `date` field may store an ISO 8601 truncated value —
+`"2026-05"` (month) or `"2026"` (year) — when a document carries only that precision. Both decoders
+resolve it to its **period start** (missing month/day → 1): `row.date("2026-05")` →
+May 1 2026 at local midnight, `row.date("2026")` → Jan 1 2026 — never `null`. For DISPLAY that
+respects the precision (show "05/2026", not "01/05/2026"), format with `@lotics/ui`'s `formatDate`
+on the raw cell string rather than the decoded `Date`. Sorting/filtering server-side already treats
+a partial as its period start.
+
 **`readSelect`.** A query **cell** carries `key` + `label` only — `color` comes from
 `useFieldOptions`, not the cell. An option deleted after the cell was written surfaces as
 `label === key` (the stale state is explicit, never hidden). Render with `@lotics/ui` `OptionBadge`

package/docs/mutations.md

@@ -128,12 +128,16 @@ A workflow body ends with `return({ status, message?, data? })`. `data` is arbit
 structured data (computed totals, row lists, status objects) the app reads back as
 `result.data`:
 
-- **Typed for free.** The alias's `outputs` schema is derived at save time from the inferred
-  TypeScript type of the body's `return({ data })` — the return *is* the declaration. Codegen
-  then types `result.data` per alias. Declare an explicit `outputs` on the alias (same
-  recursive vocabulary as inputs: scalars plus nested `object`/`array`, no member/file/
-  date_range) only to narrow beyond what's inferred; a shape the checker can't pin down
-  degrades to untyped `json`, never to a wrong schema.
+- **Typed for free — persisted at `set`.** The alias's `outputs` schema is derived at save
+  time from the inferred TypeScript type of the body's `return({ data })` — the return *is*
+  the declaration. When the manifest declared **no** `outputs`, `lotics app workflow set`
+  writes the server-derived schema into `package.json#lotics.workflows.<alias>.outputs` and
+  refreshes that alias's generated types in the same command, so `result.data` is typed
+  immediately — no hand-copy of the echoed schema, no second `lotics app codegen`. An
+  **explicitly declared** `outputs` is authoritative and never overwritten. Declare an explicit
+  `outputs` (same recursive vocabulary as inputs: scalars plus nested `object`/`array`, no
+  member/file/date_range) only to narrow beyond what's inferred; a shape the checker can't pin
+  down degrades to untyped `json`, never to a wrong schema.
 - **Validated at run.** On a success return, the returned `data` is validated against the
   schema at the app boundary — a mismatch resolves as `status: "error"` with a field-level
   message, so a declared output is a real contract. An *error* return's `data` passes through
@@ -173,7 +177,7 @@ Every declaration takes optional `description` and `required` (default **true**)
 | `date` | — | `"YYYY-MM-DD"`, or a TZ-bearing ISO datetime (projected to the workspace day) | `string` |
 | `datetime` | — | `"YYYY-MM-DDTHH:mm"` naive workspace wall-clock (what the platform DatePicker emits), or TZ-bearing ISO | `string` |
 | `email` | — | a valid email | `string` |
-| `select` | `options: [{label, value}]` (min 1), `multi?` | an option key (array when `multi`) | union of declared `value` literals; `ReadonlyArray<…>` when `multi` |
+| `select` | exactly one of `options: [{label, value}]` (min 1) **or** `field: "fld_…"`; `multi?` | an option key (array when `multi`) | union of the option `value`s (inline) or the field's current option keys (`field`); `ReadonlyArray<…>` when `multi` |
 | `record_link` | `table_id` (required), `multi?` | a record id — must exist **in the declared table** | `string` / `ReadonlyArray<string>` |
 | `member` | `group?`, `multi?` | a member id — with `group`, must belong to that group | `string` / `ReadonlyArray<string>` |
 | `file` | `multi?` | a file id from an upload — must live in the app's workspace | `string` / `ReadonlyArray<string>` |
@@ -209,12 +213,24 @@ When the alias declares `inputs`, the server validates the payload before the wo
   declared group; every `file` id must live in the app's workspace. These are real write-time
   constraints, not picker cosmetics — a hand-crafted request can't redirect the workflow.
   Rationale and the full caller-boundary model: [security](./security.md).
-- **`select` accepts any well-formed option key at runtime**, not only the deploy-declared
-  `options`. **Limitation:** the declared options are frozen into the codegen literal union,
-  so an option added to the live field after deploy is valid at runtime but fails the
-  compile-time type. Populate pickers from `useFieldOptions` (the live option set — see
-  [members_and_options](./members_and_options.md)) and widen or redeploy the declaration when
-  the type gets in the way.
+- **`select` names its option set one of two ways — declare exactly one (both or neither is a
+  set-time error).** *Inline* `options: [{label, value}]` freezes the set into the codegen
+  literal union and is **format-only at run time**: any well-formed key is accepted, and an
+  option added to the live field after deploy is valid at run time but fails the compile-time
+  type (widen or redeploy the declaration when the frozen union gets in the way).
+  *Field-referenced* `field: "fld_…"` (a select field's global key — `fld_…`, no table prefix)
+  is **drift-proof**: the union is resolved from the field's *current* options at type-gen, and
+  the submitted value is validated against the field's *current* options at run time — an option
+  added after authoring is accepted, a removed one rejected
+  (`select input "<path>" value "<v>" is not one of field "<key>"'s current options`) with no
+  redeploy. A `field` that doesn't exist or names a non-select field is rejected at bind time
+  (`lotics app workflow set` / `set_app_workflow`; `lotics app deploy` never binds workflows) with
+  `select input references field "<key>", which does not exist in this workspace` /
+  `… which is a <type> field, not a select`. Prefer `field` for any select backed by a real
+  field; keep `options` for a fixed enum the app owns or a select you plan to **package** — a
+  `field`-form select can't ride a package contract (it carries a concrete field id), so inline
+  the options before publishing. Populate pickers from `useFieldOptions` either way (the live
+  option set — see [members_and_options](./members_and_options.md)).
 
 If the alias declares **no** `inputs`, the payload passes through opaquely — no validation,
 no typing, no reference binding. Fine for a zero-input action; declare inputs for anything
@@ -254,6 +270,27 @@ if (i.title != null) {
 }
 ```
 
+When several optional inputs each map to a field, per-field guards become noise. Hand the whole
+bag to `update_records`' **`set_skip_null`** instead — same object shape as `set`, but entries
+whose value is `null`/`undefined` are dropped, so only the fields actually provided get written
+(untouched fields keep their lock / `before_update` / concurrent-edit safety — the diff-write
+discipline below, done in the body):
+
+```js
+const i = trigger.app_workflow.inputs;
+await update_records({
+  table_id: "tbl_items",
+  record_ids: [i.record_id],
+  set_skip_null: { fld_title: i.title, fld_status: i.status, fld_due: i.due }, // absent inputs drop out
+});
+```
+
+`set` still writes every key it carries — `null` in `set` **clears** the field; `null`/absent in
+`set_skip_null` **skips** it. That is the per-field "clear vs. leave unchanged" choice, so a field
+may appear in **at most one** of `set` / `set_skip_null` (naming it in both is rejected at run
+time). An all-absent `set_skip_null` with no other write surface is a no-op — no records touched,
+no `before_update` hooks.
+
 ## Refetch after a mutation
 
 Query hooks cache through SWR and know nothing about your workflows — a successful mutation
@@ -281,9 +318,9 @@ in place of an explicit refetch after a write the user is watching for.
 
 An edit form snapshots the record's values when it loads, and on save sends **only the fields
 the user actually changed** to its update workflow. Declare each updatable input
-`required: false`; an omitted input means "not written" (the body guards each write as shown
-above). "Changed" is decided at the edit surface that loaded the before-state — compare
-against the load-time snapshot, not against a re-fetch.
+`required: false`; an omitted input means "not written" (the body guards each write — or hands
+them to `set_skip_null` — as shown above). "Changed" is decided at the edit surface that loaded
+the before-state — compare against the load-time snapshot, not against a re-fetch.
 
 Why a full-form snapshot save is a bug, not a style choice — three independent mechanisms:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.52.4",
+  "version": "0.54.0",
   "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
     }