@lotics/app-sdk 0.42.0 → 0.43.0

package/AGENTS.md

@@ -55,7 +55,10 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
   to a `DisplayFile` (snake → camel — `mime_type`→`mimeType`, `preview_url`→`url` — the app owns this
   data→UI adapter; the SDK never imports `@lotics/ui`) for
   `<FileThumbnail file={{ id, filename, mimeType, url }} uploading={f.status === "uploading"} />`;
-  `sendDisabled` gates on `uploading` and the send payload is `fileIds`. Don't hand-roll
+  `sendDisabled` gates on `uploading` and the send payload is `fileIds`. To persist several files into ONE
+  record, declare the workflow input `{ type: "file", multi: true }` — the body receives `fileIds` as
+  `ReadonlyArray<FileId>` and writes it straight to a `files` field (a single `file` input is one id → wrap `[id]`).
+  Don't hand-roll
   `createObjectURL`/upload/revoke per app. For a full add-files SCREEN (not the composer pill), map
   each `AttachedFile` to a `FileUpload` (ready → `{ status: "complete", id, file }`, else
   `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`) and feed `@lotics/ui`
@@ -71,6 +74,23 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
 - **Who's viewing** — **`useViewer()`** → the signed-in member (the *viewed* member under "View as").
   Display-only — personalize or attribute; **never** scope rows by it (use an `is_current_member`
   query filter server-side). Returns null for an anonymous public visitor.
+- **Run an AI agent** — **`useAgentRun(alias)`** → `{ run, cancel, abort, status, items, text, steps,
+  output, error }` (agent declared in `package.json#lotics.agents`, authored via `set_app_agent`).
+  `run(input, { sessionId })` streams it. TWO kinds, both first-class: a **structured** agent (declares
+  `outputs`) lands its typed result in **`output`** (the `submit_result` shape) — `undefined` if the run
+  produced none, **never a stray string** (so a present `output` is the declared shape; still validate
+  untrusted INNER fields the model authored, e.g. an array that may be missing/mistyped); a **free-text**
+  agent's answer is the transcript prose (**`text`**). Feed the live **`items`** transcript straight to
+  `@lotics/ui` `AgentRun` — `<AgentRun items={run.items} state={run.status === "streaming" ? "streaming"
+  : run.status === "error" ? "error" : "done"} labelForTool={…} />` — NO hand-assembly (`text`/`steps`
+  are backward-compat views of `items`). The transcript carries the agent's **thinking** (a distinct
+  `reasoning` segment, kept OUT of `text`) and each tool's **input / output / running→done→error state**;
+  `AgentRun` shows thinking collapsed and tool I/O in a press-to-open peek (revealed on demand, not in the
+  feed) — all for free, no extra wiring. Wire a Stop button to **`cancel()`** (stops the run server-side,
+  saves tokens; `abort()` is local-only, for unmount). `run()` THROWS on quota/network — try/catch +
+  surface. Needs an authenticated member (embedded apps only, no anonymous runs). Image/PDF `file`
+  inputs are materialized into the agent's vision — pair with `useFileUpload`. `items`/`cancel` need
+  `@lotics/app-sdk` ≥ 0.43; the reasoning + per-tool I/O reveal needs `@lotics/ui` ≥ 7.13.
 - **Device location** — **`requestGeofencedLocation(zones)`** → a structured outcome
   `{ ok:true, coords } | { ok:false, reason:"denied"|"unavailable"|"outside" }`; **`isWithinZone`**
   is the pure check. Read directly in the iframe (host delegates the permission); the gate is

package/dist/src/agent_stream.d.ts

@@ -8,10 +8,15 @@
  * 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.
  *
- * The structured result is the input of the agent's `submit_result` tool call
- * (the backend injects that tool when the agent declares `outputs`); a free-text
- * agent's result is the accumulated text. Pure + reducer-shaped so it is fully
- * unit-testable against recorded frames — no live model needed.
+ * 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.
  */
 export interface AgentRunStep {
     id: string;
@@ -19,14 +24,42 @@ export interface AgentRunStep {
     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;
 }
+/** 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);
 export interface AgentRunState {
     status: "streaming" | "completed" | "error";
-    /** The agent's streamed reasoning / answer text, accumulated. */
-    text: string;
-    /** Tool calls the agent made, in order (excludes the internal `submit_result`). */
-    steps: AgentRunStep[];
-    /** The structured result — `submit_result`'s input, or (free-text) the final text. */
+    /** 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 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
+     *  text. Coercing text here would hand a consumer reading `output.<field>` a bare
+     *  string, crashing it ("... is not iterable"). */
     output?: unknown;
     error?: string;
 }
@@ -38,6 +71,7 @@ interface Chunk {
     toolName?: string;
     toolCallId?: string;
     input?: unknown;
+    output?: unknown;
     errorText?: string;
     finishReason?: string;
 }

package/dist/src/agent_stream.js

@@ -8,45 +8,87 @@
  * 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.
  *
- * The structured result is the input of the agent's `submit_result` tool call
- * (the backend injects that tool when the agent declares `outputs`); a free-text
- * agent's result is the accumulated text. Pure + reducer-shaped so it is fully
- * unit-testable against recorded frames — no live model needed.
+ * 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.
  */
 /** The tool the backend injects to carry a typed structured result. */
 const SUBMIT_TOOL = "submit_result";
 export function initialAgentRunState() {
-    return { status: "streaming", text: "", steps: [] };
+    return { status: "streaming", items: [] };
+}
+/** 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
+ *  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 }];
+    }
+    return [...items, { type: kind, id: `${kind}-${items.length}`, text: piece }];
+}
+/** 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) {
+    if (!toolCallId)
+        return items;
+    return items.map((it) => (it.type === "step" && it.id === toolCallId ? fn(it) : it));
 }
 /** Fold one chunk into the run state. Returns a new state (immutable). */
 export function reduceAgentChunk(state, chunk) {
     switch (chunk.type) {
-        case "text-delta":
+        case "text-delta": {
+            const piece = chunk.delta ?? "";
+            return piece ? { ...state, items: appendProse(state.items, "text", piece) } : state;
+        }
         case "reasoning-delta": {
+            // Thinking is its OWN segment (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, text: state.text + piece } : state;
+            return piece ? { ...state, items: appendProse(state.items, "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.
+                // The agent emitted its structured result — not a transcript step.
                 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);
+            if (existing) {
+                return { ...state, items: updateStep(state.items, id, (s) => ({ ...s, label: s.label || name, input: chunk.input ?? s.input })) };
+            }
             return {
                 ...state,
-                steps: [
-                    ...state.steps,
-                    { id: chunk.toolCallId ?? `${name}-${state.steps.length}`, label: name, kind: "tool", status: "done" },
-                ],
+                items: [...state.items, { type: "step", id, label: name, kind: "tool", status: "running", input: chunk.input }],
             };
         }
+        case "tool-output-available":
+            return { ...state, items: updateStep(state.items, chunk.toolCallId, (s) => ({ ...s, status: "done", 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." })) };
         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": {
-            const output = state.output ?? (state.text.trim() ? state.text.trim() : undefined);
-            return { ...state, status: state.status === "error" ? "error" : "completed", output };
+            // 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 };
         }
         default:
             return state;

package/dist/src/hooks.d.ts

@@ -1,8 +1,8 @@
-import { type AgentRunStep } from "./agent_stream.js";
+import { type AgentRunStep, type AgentRunItem } 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 } from "./agent_stream.js";
+export type { AgentRunStep, AgentRunState, AgentRunItem } from "./agent_stream.js";
 /** Fields shared by every query hook's return value. */
 interface QueryStateBase {
     /**
@@ -427,25 +427,41 @@ export interface UseAgentRun<TInput, TOutput> {
      *  user-facing "Stop" button to this, not `abort`. */
     cancel: () => void;
     status: "idle" | "streaming" | "completed" | "error";
-    /** The agent's streamed reasoning / answer text, accumulating live. */
+    /** 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"} />`
+     *  — 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`. */
     text: string;
-    /** The agent's tool calls so far — bind to `@lotics/ui` `AgentRun`/`AgentProgress`. */
+    /** 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 validated structured result, once the run completes. */
+    /** 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.
+     *  So it is safe to treat a present `output` as the declared shape — but still
+     *  validate untrusted inner fields (the model authored the `submit_result` body,
+     *  so e.g. an array field may be missing/mistyped). */
     output?: TOutput;
     error?: string;
 }
 /**
  * Run a streaming agent declared in `package.json` lotics.agents and invoked by
- * alias. `run(input, { sessionId })` starts it; progress streams into `status` /
- * `text` / `steps` (feed those straight into `@lotics/ui` `AgentRun` or
- * `AgentProgress`) and the structured result lands in `output`. Read the
- * session's history with `useAgentRuns`.
+ * alias. `run(input, { sessionId })` starts it; progress streams into `status` +
+ * the ordered `items` 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 });
- * // recognize.status / recognize.steps / recognize.output
+ * // <AgentRun items={recognize.items} state={recognize.status === "streaming" ? "streaming" : "done"} />
+ * // then read recognize.output (structured) or recognize.text (free-text)
  * ```
  */
 export declare function useAgentRun<K extends keyof AppAgents & string>(alias: K): UseAgentRun<AppAgents[K], AgentOutputOf<K>>;

package/dist/src/hooks.js

@@ -406,8 +406,11 @@ export function useAgentRun(alias) {
             if (aborted)
                 return undefined;
             // `finish` normally settles status; guard a stream that ended without one.
+            // Keep `output` as whatever `submit_result` set (else undefined) — never
+            // coerce the free-text into it (that string would crash a structured
+            // consumer reading `output.<field>`; the answer stays in `text`).
             if (acc.status === "streaming") {
-                acc = { ...acc, status: "completed", output: acc.output ?? (acc.text.trim() || undefined) };
+                acc = { ...acc, status: "completed" };
                 safeSetState(acc);
             }
             captureAppEvent("app_agent_run", { alias, ok: acc.status !== "error" });
@@ -448,17 +451,26 @@ 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]);
     return {
         run,
         abort,
         cancel,
         status: state?.status ?? "idle",
-        text: state?.text ?? "",
-        steps: state?.steps ?? [],
+        items,
+        text,
+        steps,
         output: state?.output,
         error: state?.error,
     };
 }
+/** Stable empty transcript so an idle hook returns a constant `items` reference
+ *  (no new [] each render → dependents don't re-run needlessly). */
+const EMPTY_ITEMS = [];
 /**
  * Poll a single run until it leaves `running` — the resume path when a run's
  * stream connection drops mid-flight. Bounded just past the server-side max-run

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, } from "./hooks.js";
-export type { UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunRecord, AgentRunState, AgentRunStep, FieldOptions, FieldOptionsState, FieldOptionsOptions, } 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 { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {