@lotics/app-sdk 0.102.1 → 0.102.3

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();
@@ -23787,6 +23826,9 @@ var queryAggregateColumnSchema = zod_default.object({
   input_column: zod_default.string().optional().describe(
     "Input column to aggregate. Required for non-count operations; ignored for count."
   ),
+  filter: tableRecordFiltersSchema.optional().describe(
+    "Aggregates only the input rows that match (SQL `FILTER`). Conditions name input columns and take `{{params.x}}`; aggregates with different filters in one node read the input once."
+  ),
   separator: zod_default.string().max(8).optional().describe('string_agg only. Joins the values. Defaults to ", ".'),
   distinct: zod_default.boolean().optional().describe(
     "string_agg only. Collapses repeats \u2014 a group of containers sized 40HC/40HC/20DC aggregates to '20DC, 40HC'. Defaults to true, which is almost always what a summary column wants."
@@ -25313,12 +25355,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 +25443,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 +25456,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 +25495,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 +27146,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 +27221,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 +28178,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/mutations.md

@@ -531,8 +531,9 @@ every read before the request answers:
 - **Totals.** A `total`, a count per value (`total: { by }`), a group asked with `aggregate` or
   declared by the query, and a parent's count or sum rollup move by exactly what the written row adds
   or takes away; a group the last row leaves is gone, and a count per value gains the value a row
-  first holds. A mean, an extreme, a distinct count, a group by day, a group none of the read's rows
-  counted in yet, a read whose rows a search or a cap decides, or a row the app never read is left
+  first holds. A mean, an extreme, a distinct count, a group by day, an aggregate with its own
+  `filter`, a group none of the read's rows counted in yet, a read whose rows a search or a cap
+  decides, or a row the app never read is left
   as the server said it until a read asked after the write answers.
 - **A refusal takes it back**, and `result` says why, as always. A success keeps it until a read
   asked after the write settled answers — the stored value then replaces the prediction, whatever

package/docs/queries.md

@@ -277,7 +277,7 @@ came from.
 
 Full semantics in §8. `by` may be empty (a single-row aggregate); `aggregates` needs ≥ 1 entry.
 Aggregate operation × input-column type is validated at bind. Grouping collapses rows —
-addressing is dropped.
+addressing is dropped. An aggregate's `filter` limits it to the rows that match (§8).
 
 ### `window` — aggregate without collapsing
 
@@ -679,6 +679,25 @@ everything else requires an `input_column` whose type must be compatible — che
 ¹ opaque `json` columns support only the presence-counting six (`empty`/`filled`/`unique` and
 their `percent_*` forms).
 
+**`filter` — aggregate a subset.** Any aggregate, in `group` or `window`, takes a `filter` over its
+input columns — the same tree as a `filter` node, `{{params.x}}` included, with a condition on an
+omitted optional param dropped. The aggregate reads only the rows it matches (SQL `FILTER`), and
+the rest of the node is unaffected, so several figures over one table cost one read of it:
+
+```jsonc
+{ "kind": "group", "from": { "kind": "from_table", "table_id": "…" }, "by": [],
+  "aggregates": [
+    { "output": "open", "type": "number", "operation": "count",
+      "filter": { "node_type": "condition", "field_key": "closed_at", "operator": "is_empty" } },
+    { "output": "closed_today", "type": "number", "operation": "count",
+      "filter": { "node_type": "condition", "field_key": "closed_at", "operator": "on",
+                  "value": { "type": "period", "period": "day", "boundary": "start", "offset": 0 } } } ] }
+```
+
+A relative date resolves in its field's timezone while the column still names one field — over a
+`from_table`, or a `project` of one. Over a `union` of different tables it names none; count per
+table, then combine.
+
 **`string_agg` — a summary column, not a dataset.** Every other operation counts or reduces to a
 number; this one joins the values, so a child set answers "which ones?" in the parent row (the
 sizes on a shipment, the tags on a ticket) without a second query.

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.1",
+  "version": "0.102.3",
   "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": {