@lotics/app-sdk 0.102.0 → 0.102.2

package/AGENTS.md

@@ -25,7 +25,7 @@ This file is the index. The **exact type** of anything is its shipped declaratio
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`, `useFolderPick`. |
 | [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming parts, the agent's ask-back), `askAi`, `useAiContext`, and what the member's own chat agent can do with the app while it is open. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, why a per-input bound is a tenancy floor rather than an authorization check. |
-| [docs/runtime.md](./docs/runtime.md) | `mount()` and the errors it reports to the host (`reportAppError`), the two transports, the API address a standalone bundle reads out of its own page (`<meta name="lotics-api-base">`), `rpc()`, the mock harness (`fixture` + `?__mock=1`), `openExternal`/`openApp`/`downloadFile`, geofencing, the peer dependencies. |
+| [docs/runtime.md](./docs/runtime.md) | `mount()` and the errors it reports to the host (`reportAppError`), the two transports, the API address a standalone bundle reads out of its own page (`<meta name="lotics-api-base">`), `rpc()`, the mock harness (`fixture` + `?__mock=1` — queries, workflows and agents, a mocked agent's run played line by line), `openExternal`/`openApp`/`downloadFile`, geofencing, the peer dependencies. |
 
 ## Non-negotiables (each detailed in its doc)
 

package/dist/agent_stream.d.ts

@@ -2,7 +2,8 @@
  * Folds the AI-SDK UI-message SSE stream into the `UIMessagePart[]` shape
  * `@lotics/ui` `AgentRun` renders. `ai` is imported for types only, so no `ai`
  * runtime enters the app bundle; unknown chunk types are ignored. A structured
- * agent's `submit_result` input becomes `output`, never a part.
+ * agent's `output` is the result the server accepted (`data-run-output`, sent
+ * before `finish`); until it arrives, `submit_result`'s input — never a part.
  */
 import type { UIMessagePart, UIDataTypes, UITools } from "ai";
 /** An ai-sdk message part — the render model, tool-set-agnostic. */
@@ -12,7 +13,7 @@ export declare const INTERACTIVE_TOOLS: ReadonlySet<string>;
 export interface AgentRunState {
     status: "streaming" | "awaiting_input" | "completed" | "error";
     parts: AgentUIPart[];
-    /** `submit_result`'s input, never the free text — a consumer reading `output.<field>` would crash on a string. */
+    /** The structured result — `submit_result`'s input as it streams, the server's accepted one from `data-run-output` on; never the free text — a consumer reading `output.<field>` would crash on a string. */
     output?: unknown;
     error?: string;
 }
@@ -92,6 +93,7 @@ interface Chunk {
     output?: unknown;
     errorText?: string;
     finishReason?: string;
+    data?: unknown;
 }
 export declare function reduceAgentChunk(state: AgentRunState, chunk: Chunk): AgentRunState;
 /** Complete chunks so far and the partial frame to carry forward; `[DONE]` is dropped. */

package/dist/index.d.ts

@@ -28,6 +28,7 @@ export type { ResolvedMember } from "./members.js";
 export { readSelect } from "./select.js";
 export type { ResolvedOption } from "./select.js";
 export type { AppFixture, MockExport, MockQuery, MockQueryCall, MockWorkflow } from "./mock.js";
+export type { MockAgent, MockAgentRun } from "./mock_agent_run.js";
 export type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
 export { row, readLinks, readFiles, readLocked, readCreatedAt, readUpdatedAt, PENDING } from "./row.js";
 export type { ResolvedLink, AppFile } from "./row.js";

package/dist/index.js

@@ -59,6 +59,10 @@ function getMockWorkflow(alias) {
   if (!isMockMode()) return null;
   return registeredFixture?.workflows?.[alias] ?? null;
 }
+function getMockAgent(alias) {
+  if (!isMockMode()) return null;
+  return registeredFixture?.agents?.[alias] ?? null;
+}
 function getMockExport(alias) {
   if (!isMockMode()) return null;
   return registeredFixture?.exports?.[alias] ?? null;
@@ -91,8 +95,8 @@ function reportAppError(kind, error51) {
 function firstFrame(error51, stack) {
   const header = String(error51);
   const frames = stack.startsWith(header) ? stack.slice(header.length) : stack;
-  const frame = frames.split("\n").find((line) => line.trim() !== "");
-  return frame === void 0 ? null : withoutOrigins(frame.trim()).slice(0, MESSAGE_LIMIT);
+  const frame2 = frames.split("\n").find((line) => line.trim() !== "");
+  return frame2 === void 0 ? null : withoutOrigins(frame2.trim()).slice(0, MESSAGE_LIMIT);
 }
 function withoutOrigins(text2) {
   return text2.replace(/\b[a-z][a-z0-9+.-]*:\/\/[^/\s)]+/gi, "").replace(/[?#][^\s)]*?(?=(?::\d+){1,2}\)?(?:\s|$)|[\s)]|$)/g, "");
@@ -387,6 +391,8 @@ function reduceAgentChunk(state, chunk) {
       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, 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 "data-run-output":
+      return chunk.data !== null && typeof chunk.data === "object" ? { ...state, output: chunk.data } : state;
     case "error":
       return { ...state, status: "error", error: chunk.errorText ?? "The run failed." };
     case "abort":
@@ -415,8 +421,8 @@ function parseSseChunks(buffer) {
   const chunks = [];
   const frames = buffer.split("\n\n");
   const rest = frames.pop() ?? "";
-  for (const frame of frames) {
-    for (const line of frame.split("\n")) {
+  for (const frame2 of frames) {
+    for (const line of frame2.split("\n")) {
       const trimmed = line.startsWith("data:") ? line.slice(5).trim() : "";
       if (!trimmed || trimmed === "[DONE]") continue;
       try {
@@ -444,6 +450,39 @@ function landingOf(state) {
   }
 }
 
+// src/mock_agent_run.ts
+var BEAT_MS = 700;
+var frame = (chunk) => `data: ${JSON.stringify(chunk)}
+
+`;
+function playMockRun(run2, onText, beat = BEAT_MS) {
+  const verdict = run2.error !== void 0 ? frame({ type: "error", errorText: run2.error }) : frame({ type: "data-run-output", data: run2.output ?? {} });
+  const beats = [...(run2.steps ?? []).map((line) => frame({ type: "text-delta", delta: `${line}
+
+` })), `${verdict}${frame({ type: "finish" })}`];
+  let timer;
+  let stop = () => {
+  };
+  const done = new Promise((resolve) => {
+    stop = resolve;
+    const play = (at2) => {
+      timer = setTimeout(() => {
+        onText(beats[at2] ?? "");
+        if (at2 === beats.length - 1) resolve();
+        else play(at2 + 1);
+      }, beat);
+    };
+    play(0);
+  });
+  return {
+    done,
+    abort: () => {
+      clearTimeout(timer);
+      stop();
+    }
+  };
+}
+
 // src/store.ts
 import { useCallback as useCallback2, useEffect as useEffect2, useRef, useSyncExternalStore } from "react";
 var slots = /* @__PURE__ */ new Map();
@@ -25313,12 +25352,12 @@ async function evaluateWorkflowExpression(expr2, ctx) {
 }
 function evaluateLambda(params, body, ctx, items) {
   return async (...args) => {
-    const frame = {};
+    const frame2 = {};
     for (let i = 0; i < params.length; i++) {
-      frame[params[i]] = args[i];
+      frame2[params[i]] = args[i];
     }
     const stack = ctx.lambda_params ?? [];
-    const newStack = [...stack, frame];
+    const newStack = [...stack, frame2];
     const innerCtx = {
       ...ctx,
       lambda_params: newStack,
@@ -25401,8 +25440,8 @@ function resolveReadRoot(source, ctx) {
       const stack = ctx.lambda_params;
       if (stack !== void 0) {
         for (let i = stack.length - 1; i >= 0; i--) {
-          const frame = stack[i];
-          if (source.name in frame) return frame[source.name];
+          const frame2 = stack[i];
+          if (source.name in frame2) return frame2[source.name];
         }
       }
       throw new WorkflowEvalError(
@@ -25414,8 +25453,8 @@ function resolveReadRoot(source, ctx) {
       const stack = ctx.lexical_bindings;
       if (stack !== void 0) {
         for (let i = stack.length - 1; i >= 0; i--) {
-          const frame = stack[i];
-          if (source.name in frame) return frame[source.name];
+          const frame2 = stack[i];
+          if (source.name in frame2) return frame2[source.name];
         }
       }
       throw new WorkflowEvalError(
@@ -25453,8 +25492,8 @@ function resolveForeachFrame(ctx, name, at2) {
       at: at2
     });
   }
-  const frame = resolveNamedForeachFrame(stack, name);
-  if (frame !== void 0) return frame;
+  const frame2 = resolveNamedForeachFrame(stack, name);
+  if (frame2 !== void 0) return frame2;
   const known = stack.map((f) => f.name).filter((n) => n !== void 0);
   throw new WorkflowEvalError(
     `Read from ${at2} "${name}", but no enclosing foreach binds that name` + (known.length > 0 ? ` (in scope: ${known.join(", ")})` : ""),
@@ -27104,15 +27143,15 @@ async function predictRead(walk, step) {
   if (typeof id !== "string" || record2 === void 0) return unknownAt(walk.ctx.step_outputs, step.id);
   walk.ctx.step_outputs[step.id] = { output: modelled(step.id, { id, table_id: record2.table_id, data: knownCells(walk.input.tables, record2.table_id, record2.cells) }) };
 }
-function bindLexical(frame, name, held2) {
-  if (held2 === UNKNOWN) return unknownAt(frame, name);
-  Object.defineProperty(frame, name, { enumerable: true, configurable: true, writable: true, value: held2 });
+function bindLexical(frame2, name, held2) {
+  if (held2 === UNKNOWN) return unknownAt(frame2, name);
+  Object.defineProperty(frame2, name, { enumerable: true, configurable: true, writable: true, value: held2 });
 }
 function setLexical(walk, name, held2) {
   const stack = walk.ctx.lexical_bindings ?? [];
   for (let at2 = stack.length - 1; at2 >= 0; at2--) {
-    const frame = stack[at2];
-    if (frame !== void 0 && Object.prototype.hasOwnProperty.call(frame, name)) return bindLexical(frame, name, held2);
+    const frame2 = stack[at2];
+    if (frame2 !== void 0 && Object.prototype.hasOwnProperty.call(frame2, name)) return bindLexical(frame2, name, held2);
   }
 }
 async function block(walk, steps) {
@@ -27179,8 +27218,8 @@ async function run(walk, step) {
       return;
     }
     case "let_declare": {
-      const frame = walk.ctx.lexical_bindings?.at(-1);
-      if (frame !== void 0) bindLexical(frame, step.name, await attempt(walk, expr(step.initial)));
+      const frame2 = walk.ctx.lexical_bindings?.at(-1);
+      if (frame2 !== void 0) bindLexical(frame2, step.name, await attempt(walk, expr(step.initial)));
       return;
     }
     case "assign":
@@ -28136,10 +28175,11 @@ function useAgentRun(alias) {
       }
       handleRef.current?.abort();
       runIdRef.current = null;
+      const mock = getMockAgent(alias);
       const inflight = streamLeg(
-        (onText) => rpcAgentRun({ alias, session_id: opts.sessionId, input: input ?? {} }, onText, (runId) => {
+        (onText) => mock === null ? rpcAgentRun({ alias, session_id: opts.sessionId, input: input ?? {} }, onText, (runId) => {
           runIdRef.current = runId;
-        }),
+        }) : playMockRun(typeof mock === "function" ? mock(input ?? {}) : mock, onText),
         initialAgentRunState()
       );
       const tracked = inflight.finally(() => {

package/dist/mock.d.ts

@@ -2,11 +2,13 @@
  * Design-time fixtures, active only with BOTH `mount(<App />, { fixture })`
  * and the `?__mock=1` URL param, so demo data in a bundle never answers real
  * traffic. A mocked workflow never runs, so it writes nothing and nothing is
- * drawn ahead of it; a success re-reads every mounted read.
+ * drawn ahead of it; a success re-reads every mounted read. A mocked agent is
+ * played, never run: its lines, then its result or its error.
  * `useFileUpload` is not mocked.
  */
 import type { QueryAggregate } from "./shared_types.js";
 import type { UploadedFile, WorkflowResult } from "./hooks.js";
+import type { MockAgent } from "./mock_agent_run.js";
 import type { ExportCall, QuerySortKey } from "./queries.js";
 import type { RecordingState } from "./recording_state.js";
 /** A result, or a function of the inputs — return a slow promise to review the pending state. */
@@ -29,6 +31,8 @@ export type MockExport = (call: ExportCall & {
 export interface AppFixture {
     queries?: Record<string, MockQuery>;
     workflows?: Record<string, MockWorkflow>;
+    /** `useAgentRun(alias)` plays the run — or the one made of its input — and never parks. */
+    agents?: Record<string, MockAgent>;
     /** By the query exported. */
     exports?: Record<string, MockExport>;
     /** `useRecording(alias)` reads as available; `start`/`stop` change nothing. */
@@ -41,6 +45,8 @@ export declare function hasMockFlag(): boolean;
 export declare function getMockRows(alias: string, call: MockQueryCall): Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>> | null;
 /** Null for an unmocked alias, which executes for real. */
 export declare function getMockWorkflow(alias: string): MockWorkflow | null;
+/** Null for an unmocked alias, which runs for real. */
+export declare function getMockAgent(alias: string): MockAgent | null;
 /** Null for an unmocked alias, which the server exports. */
 export declare function getMockExport(alias: string): MockExport | null;
 export declare function getMockRecordings(): Record<string, RecordingState> | null;

package/dist/mock_agent_run.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A RUN PLAYED WITHOUT A MODEL, for design time: the lines a run writes as it works, one a beat, then how it ends — the
+ * result the server accepted, or the error it failed with — streamed as the server streams a run, so the one reducer
+ * that reads a real run reads this one.
+ */
+export interface MockAgentRun {
+    /** What the run writes as it works, a line a beat. */
+    steps?: readonly string[];
+    /** A structured agent's result, as the server hands it once it accepted it. */
+    output?: Record<string, unknown>;
+    /** The run fails with these words instead, its output never sent. */
+    error?: string;
+}
+/** A run, or one made of what the run was handed. */
+export type MockAgent = MockAgentRun | ((input: Record<string, unknown>) => MockAgentRun);
+/**
+ * Plays `run` into `onText` as `rpcAgentRun` streams a real one: a line each `beat`, then its verdict — the error, or
+ * the accepted output — with `finish`, as the server sends them. `abort` stops it where it stands.
+ */
+export declare function playMockRun(run: MockAgentRun, onText: (chunk: string) => void, beat?: number): {
+    done: Promise<void>;
+    abort: () => void;
+};

package/docs/ai.md

@@ -65,7 +65,7 @@ await recognize.run({ image_file_id: fileId }, { sessionId });
 | `answerChoice` | `(answers: {value, custom}[]) => Promise<AgentRunLanding<TOutput>>` | Answer the pending question(s) and CONTINUE the run — one entry per question, aligned by index (exactly what `ClarifyWizard`'s `onSubmit` yields). Streams the continuation into the same `parts`; resolves like `run`. Rejects when nothing is pending — and when the server refuses the answer, in which case the pending question is restored for a retry |
 | `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 |
+| `output` | `TOutput \| undefined` | The structured result the server accepted — read it once `status` is `"completed"`. `undefined` for a free-text agent |
 | `error` | `string \| undefined` | The failure message when `status` is `"error"` |
 
 ### The `parts` transcript → `@lotics/ui` `AgentRun`
@@ -78,7 +78,7 @@ await recognize.run({ image_file_id: fileId }, { sessionId });
 | `"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 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**:
+The terminal `submit_result` call is **not** rendered as a tool part (structured agents therefore have no visible final step); `output` is the result the server accepted, sent as the run finishes. 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
@@ -89,7 +89,7 @@ The terminal `submit_result` call is captured into `output`, **not** rendered as
 />
 ```
 
-`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.
+`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. To see its live, done and failed states without a run, mock the agent (`fixture.agents`, [runtime](./runtime.md)): the run is played through the same stream reader, never billed.
 
 `run.error` is always a **sentence to show a person**, never a payload — on both the ways a run can fail.
 
@@ -139,7 +139,7 @@ answer may park again.
 
 ### `output` typing and the inner-field caveat
 
-The server validates the agent's submitted result strictly (unknown keys rejected, required fields present, types checked, `select` values bound to the declared options); an invalid submission is rejected back to the agent with the validation errors, and the agent retries. A run only settles **completed** with a result that passed this — so on a completed run, `output.items.map(...)` on a declared array field is safe. What that does **not** guarantee:
+The server validates the agent's submitted result strictly (unknown keys rejected, required fields present, types checked, `select` values bound to the declared options); an invalid submission is rejected back to the agent with the validation errors, and the agent retries. A submission whose JSON arrived broken is not retried: the agent would rewrite it from memory and drop fields, so the run fails instead. A run only settles **completed** with a result that passed this — so on a completed run, `output.items.map(...)` on a declared array field is safe. What that does **not** guarantee:
 
 - a field declared `required: false` may be absent;
 - a `json`-typed output field is passthrough — anything goes inside it;
@@ -147,21 +147,21 @@ The server validates the agent's submitted result strictly (unknown keys rejecte
   timestamp, an address shape) but not for being the *right* value — a parseable date can still
   be the wrong date;
 - every **value** was authored by the model — a schema-valid string can still be semantically wrong;
-- one live-stream corner: the hook adopts `output` from the submit call's **arguments as they stream**, before the server-side validation runs. Normally the loud rejection makes the agent retry and the last (valid) submit overwrites it — but a run whose *final* submit was rejected ends the live stream with that invalid attempt still in `output` (the persisted run settles as an error). The review surface below is the backstop.
+- while the run streams, `output` holds the submit call's **arguments** as they arrive, before the server has checked them — only a `completed` run's `output` is the accepted result.
 
 Treat `output` as a trusted *shape* carrying untrusted *values*: render it into a review surface and let the user confirm before a workflow commits it. Never write model output straight to records without a review step.
 
-### Errors — one landing, and one quiet mode
+### Errors — one landing
 
 A run that cannot start (AI-credit quota exhausted, the per-member concurrency cap, an undeclared alias, input validation, a network error) and one that fails mid-run both **resolve** `{kind:"failed", error}`, with `status` `"error"`. Only `answerChoice` rejects, when the server refuses an answer.
 
 ```tsx
 const landing = await recognize.run(input, { sessionId });
 if (landing.kind === "failed") { /* surface landing.error */ }
-else if (landing.kind === "settled" && landing.output === undefined) { /* no result */ }
+else if (landing.kind === "settled") { /* review landing.output */ }
 ```
 
-A capped run's live message is a generic "The run was stopped." (the persisted run carries "Run exceeded the 20-minute limit."). Two modes are **quiet on the live stream**: a structured agent that finished without ever submitting a result, and a free-text agent that produced no text, land `settled` with no result — only the *persisted* run settles as an error. That is why the example checks `output === undefined`.
+The stream ends on the persisted run's outcome, so the landing and the run never disagree: a structured agent that finished without a valid result, one whose result arrived unreadable, and a free-text agent that produced no text all land `failed`, with the message the run carries (a capped run's "Run exceeded the 20-minute limit." included).
 
 ### `cancel` vs `abort`
 

package/docs/queries.md

@@ -234,7 +234,7 @@ supports the full §5 operator matrix **except**: `traversal` nodes, `locked`, a
 `record_id` works on any row-level derived query (rejected over a `group`, which has no row
 identity). When a `filter` directly wraps a `union` of `project(from_table)` arms and every
 condition targets bare passthrough columns, the engine pushes the predicate into each arm's
-source filter automatically (making it index-servable); otherwise it evaluates post-union.
+source filter automatically, where it runs once per record; otherwise it evaluates post-union.
 
 ### `join` — combine two row sets
 
@@ -545,9 +545,9 @@ Negation-shaped inner operators (`has_none_of`, `not_equals`, `is_none_of`,
 
 Traversals are **source-layer only** (rejected on derived columns — push them into
 `from_table.filter`). Each hop reaches the linked rows by primary key from the ids in the link
-cell. Under an OR beside column conditions a traversal runs once per row and takes the column
-conditions off their indexes with it; give it a `union` arm of its own when the other arms must
-stay index-served. Two access classes:
+cell. Under an OR beside column conditions a traversal runs once per row and takes a membership
+condition off its index with it; give it a `union` arm of its own when the other arms must keep
+theirs. Two access classes:
 
 - **Self-scoped** — inner operator `is_current_member` / `is_not_current_member`: tests only
   the viewer's own membership on the linked row, leaks nothing, and is exempt from the linked
@@ -871,7 +871,7 @@ ordering and scoping into the template or its params.
 Any other execution failure returns a generic `query execution failed` (the real error — which
 may embed SQL — is server-logged only). Bind-time and validation errors are always specific.
 
-### Index reality, in plain terms
+### What a query reads, in plain terms
 
 Records are stored partitioned by workspace, so a query reads only its own workspace's slice; a
 `from_table` narrows that slice to the table's rows, and within them:
@@ -879,39 +879,18 @@ Records are stored partitioned by workspace, so a query reads only its own works
 - **GIN-served (fast at any size):** *positive* exact-membership filters at the **source
   layer** — `select`/`select_member`/`select_record_link` `has_any_of` / `has_all_of`, and
   `is_current_member`. These compile to containment the JSONB GIN index serves.
-- **Trigram-served:** `from_table.search` (§7).
-- **B-tree-served (automatic for bound queries):** text `equals`, number and date
-  comparisons (exact and range), `from_table.sort` fields, and a one-key `sort` node over a
-  number or date field the rows pass unchanged — for fields referenced in a **bound named
-  query's template**. The platform provisions a partial expression index per referenced
-  field automatically: built online whenever `set_app_query` or `set_app_queries` binds a query, re-synced daily,
-  capped at 8 per table (fields past the cap fall back to the scan tier, with a server WARN).
-  A `{{params.…}}` value hole doesn't change this — the field key is static in the template,
-  so it still gets its index. Index-seek speed at any table size once provisioned.
-- **Table scan (linear in table size):** everything else — text `contains`, negations
-  (`has_none_of`, `is_none_of`, `not_*`), emptiness, files predicates, and predicates/sorts on
-  fields that appear **only** in the runtime `filter`/`sort` options rather than the bound
-  template. Fine on thousands of rows; on very large tables these dominate latency and are the
-  usual timeout cause.
-
-**Filter shape drives latency.** Equality/range/sort predicates in the bound template are
-index-served; lead with those or a GIN-served membership filter / `search`, and let scan-shaped
-predicates refine the already-narrowed set. Derived-layer filters run over the subquery result
-(no index), so **filter at the source layer whenever the field exists there** — the runtime
-filter is for caller-driven refinement, not for the main cut (a runtime-only field gets no
-managed index). (The engine pushes eligible filter-over-union predicates down automatically,
-but don't rely on that for other shapes.)
-
-**A sorted page reads in its sort index — declare the order it is read in.** A page sorted by one
-column that passes a number or date field unchanged (a bare `project` source with no `type`
-override, an `unpivot` passthrough, or a row column that reads the same field in every row) reads
-the table in that field's sort index and stops at the page, instead of reading every row and
-sorting. Over a `union`, each arm is paged this way on its own and the arms are merged, so a
-register over several tables or `unpivot` sides is fast at any size — don't hand-split it into
-per-table queries you merge client-side. The index exists when a bound template sorts that field
-in the same direction and blank position: give the query its default order as a top-level `sort`,
-and a page the app sorts the same way is served. A text column, a computed, literal or cast column,
-a sort on more than one key, and a cursor (`keyset`) page sort every row.
+- **Trigram-served:** `from_table.search` (§7), within the one table.
+- **Every row of the table:** everything else — text equality and `contains`, number and date
+  comparisons, sorts, negations, emptiness, files predicates. Fine on thousands of rows; the cost
+  grows with the table, and on very large tables these dominate latency and are the usual
+  timeout cause.
+
+**Filter shape drives latency.** Lead with a GIN-served membership filter or `search`, which
+narrow the table before its rows are read, and let the other conditions refine that set.
+Derived-layer filters run over the subquery result, after any `unpivot` fan-out, so **filter at
+the source layer whenever the field exists there** — the runtime filter is for caller-driven
+refinement, not for the main cut. (The engine moves eligible filter-over-union predicates into
+each arm's source automatically, but don't rely on that for other shapes.)
 
 **An aggregate arm you cannot filter costs its whole table, every execution.** A `join` whose right
 side is a `group` over entire tables, keyed on a value the LEFT side supplies at run time, has no

package/docs/runtime.md

@@ -54,6 +54,12 @@ mount(<App />, {
           ? { status: "error", message: "Row 2 has no customer." }
           : new Promise((r) => setTimeout(() => r({ status: "success" }), 1200)),
     },
+    agents: {
+      // A run's lines, then the result it lands — or a FUNCTION of the run's input.
+      recognize: { steps: ["Reading the invoice."], output: { total: 1250 } },
+      // Or how it fails.
+      triage: { error: "The run ended without a result. Run it again." },
+    },
   },
 });
 ```
@@ -62,7 +68,7 @@ Activation is a **two-step gate** — both must hold, so demo data shipping in t
 bundle never leaks into normal traffic:
 
 1. A fixture is registered via `mount({ fixture })` (`AppFixture` type:
-   `dist/mock.d.ts` — `{ queries?, workflows?, exports?, recordings? }`).
+   `dist/mock.d.ts` — `{ queries?, workflows?, agents?, exports?, recordings? }`).
 2. The page URL carries `?__mock=1` (exactly `1`). Without the flag the fixture
    is completely inert.
 
@@ -99,12 +105,17 @@ pending state. Calling `mount` again (HMR) replaces the registration last-write-
   **Reach the in-flight state with a function** that resolves on a timer: an app
   whose only AI surface is a workflow calling `agent(...)` otherwise has no
   non-billing path to its own thinking / done / error screens.
+- **A mocked agent is PLAYED, never run.** `useAgentRun(alias)` streams the
+  fixture's `steps` a line a beat, then lands its `output` — or fails with its
+  `error` — through the same stream reader a real run goes through, so the pane's
+  live, done and failed states are reviewable with no spend. It never parks on a
+  question, and there is no run to cancel on the server.
 - **A mocked recording is a canned state.** `recordings: { log_visit: { phase:
   "live", elapsed_seconds: 754, inputs: { site: "rec_1" } } }` makes
   `useRecording("log_visit")` available with that `state`; `start` and `stop`
   resolve without recording anything or moving the state.
-- **Not mocked:** uploads, `useFieldOptions`, members, comments, agent runs. In
-  mock mode those still hit the real transport.
+- **Not mocked:** uploads, `useFieldOptions`, members, comments. In mock mode
+  those still hit the real transport.
 - **Analytics is disabled** whenever `?__mock=1` is present, fixture or not — a
   screenshot/design-time load emits no events.
 - The `__mock` param-name prefix is reserved by the SDK; don't use it for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.102.0",
+  "version": "0.102.2",
   "description": "The SDK a Lotics custom-code app reads and writes through \u2014 typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {