@lotics/app-sdk 0.102.2 → 0.103.0

package/AGENTS.md

@@ -17,7 +17,7 @@ This file is the index. The **exact type** of anything is its shipped declaratio
 |---|---|
 | [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column — `useQueries` for reads known only at render, `queryAll` outside React, `exportQuery` for a file of them the server makes; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
 | [docs/queries.md](./docs/queries.md) | **The query engine reference** — AST node kinds, per-field-type operators, filters/params/pruning, free-text search, combining tables, shaping (aggregates, date buckets, windows), runtime refinement bounds, limits and the efficiency playbook. |
-| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path; `useWorkflows` for writes that are data), the `WorkflowResult` resolve-never-throw contract (`field_errors`), typed inputs, every write drawn on every read from the press — predicted from the workflow's own steps, taken back on a refusal, `pending` meanwhile — the re-read a successful write triggers over the tables its body names, diff-before-update, locked records, `useNewRecord`, read-after-write ordering (`writesSettled()`), `useRecording`. |
+| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path; `useWorkflows` for writes that are data), the `WorkflowResult` resolve-never-throw contract (`field_errors`), typed inputs, every write drawn on every read from the press — predicted from the workflow's own steps, taken back on a refusal, `pending` meanwhile — the re-read a successful write triggers over the tables its body names, diff-before-update, locked records, `useNewRecord`, read-after-write ordering (`writesSettled()`), `useRecording`, `useRecordings` over several aliases. |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY reference** — the JS subset a body may use, opaque `fld_*`/`opt_*` keys, every step form, the accepted sugar, helpers, record-write surfaces, the traps and the verify loop. |
 | [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload` and its `fidelity`, `renameFile` (a new file over the same bytes), `useAttachments`/`useAttachmentPiles`, `readFiles` and presigned URLs (a bearer credential — never logged or persisted), workflow-generated files, naming a zip's entries, the delivery bounds. |

package/dist/{chunk-ZOFKWF6V.js → chunk-CRJQYSDI.js}

@@ -444,9 +444,14 @@ async function runUploadPipeline(file, rpc2, options = {}) {
 var IDLE_RECORDING = { phase: "idle" };
 var states = /* @__PURE__ */ new Map();
 var listeners = /* @__PURE__ */ new Set();
+var version = 0;
 function emit() {
+  version += 1;
   for (const listener of listeners) listener();
 }
+function recordingsVersion() {
+  return version;
+}
 function subscribeRecordings(listener) {
   listeners.add(listener);
   return () => {
@@ -1115,6 +1120,7 @@ async function standaloneUpload(file, fidelity) {
 export {
   __export,
   DEFAULT_IMAGE_FIDELITY,
+  recordingsVersion,
   subscribeRecordings,
   recordingStateOf,
   anyRecordingLive,

package/dist/index.d.ts

@@ -11,8 +11,8 @@ export type { AttachedFile, AttachmentPiles, AttachmentPilesOptions, Attachments
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useAppContext, useViewer, useWorkspaceCurrency, useWorkspaceTimezone } from "./viewer.js";
-export { useRecording } from "./recording.js";
-export type { UseRecording } from "./recording.js";
+export { useRecording, useRecordings } from "./recording.js";
+export type { UseRecording, UseRecordings } from "./recording.js";
 export type { RecordingState, RecordingInputs } from "./recording_state.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "./geolocation.js";

package/dist/index.js

@@ -12,6 +12,7 @@ import {
   postHostNotification,
   readRecordingSnapshot,
   recordingStateOf,
+  recordingsVersion,
   replaceRecordings,
   rpc,
   rpcAgentRun,
@@ -21,7 +22,7 @@ import {
   subscribeRecordings,
   subscribeUrlParams,
   urlParam
-} from "./chunk-ZOFKWF6V.js";
+} from "./chunk-CRJQYSDI.js";
 
 // src/mount.tsx
 import { createRoot } from "react-dom/client";
@@ -23826,6 +23827,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."
@@ -24231,6 +24235,11 @@ var appQueryDeclarationSchema = zod_default.object({
     "Document templates an export of this query's rows may fill, by the name the export asks for. An export names one of these or none; a template it does not declare is refused."
   )
 });
+var appAgentWritesSchema = zod_default.object({
+  table_id: zod_default.string().min(1).describe("The table of the row written"),
+  row: zod_default.string().min(1).describe("The input naming that row: a single `record_link` input to `table_id`"),
+  fields: zod_default.record(zod_default.string().min(1), zod_default.string().min(1)).refine((fields) => Object.keys(fields).length > 0, { message: "writes.fields maps at least one output" }).describe("Output name \u2192 the field key of `table_id` it is written to")
+}).strict();
 var appAgentDeclarationSchema = zod_default.object({
   instructions: zod_default.string().min(1).describe("System instructions for the agent \u2014 the task it performs per run."),
   tool_names: zod_default.array(zod_default.string().min(1)).describe(
@@ -24262,6 +24271,9 @@ var appAgentDeclarationSchema = zod_default.object({
   ).refine(
     (outputs) => outputs === void 0 || Object.values(outputs).every((o) => appWorkflowOutputDepth(o) <= MAX_APP_WORKFLOW_OUTPUT_DEPTH),
     { message: `output schema nesting exceeds the max depth of ${MAX_APP_WORKFLOW_OUTPUT_DEPTH}` }
+  ),
+  writes: appAgentWritesSchema.optional().describe(
+    "Where the run's outputs land: each named output written to a field of the one row an input names, under the app's authority, once the result validates \u2014 locks and hooks apply as to any update. Omit for an agent whose output is only returned."
   )
 });
 var appThemeSchema = zod_default.object({
@@ -24393,6 +24405,12 @@ var agentStepSchema = stepBaseSchema.extend({
   model_tier: zod_default.enum(MODEL_TIERS).optional(),
   output: agentOutputSpecSchema
 });
+var appAgentStepSchema = stepBaseSchema.extend({
+  type: zod_default.literal("app_agent"),
+  alias: zod_default.string().min(1),
+  input: zod_default.record(zod_default.string(), toolInputValueSchema),
+  wait: zod_default.literal(false).optional()
+});
 var breakStepSchema = stepBaseSchema.extend({
   type: zod_default.literal("break")
 });
@@ -24419,6 +24437,7 @@ var workflowStepSchema = zod_default.lazy(
     returnStepSchema,
     validateStepSchema,
     agentStepSchema,
+    appAgentStepSchema,
     breakStepSchema,
     continueStepSchema,
     letDeclareStepSchema,
@@ -25041,6 +25060,7 @@ function stepChildStepArrays(step) {
     case "bind":
     case "validate":
     case "agent":
+    case "app_agent":
     case "break":
     case "continue":
     case "let_declare":
@@ -25073,6 +25093,7 @@ function changesRows(toolName) {
 }
 function rowWriteOf(step) {
   if (step.type === "agent") return step.tool_names.some(changesRows) ? { table_id: null } : void 0;
+  if (step.type === "app_agent") return { table_id: null };
   if (step.type !== "tool_call") return void 0;
   const rows = toolRows(step.tool_name);
   if (rows === null) return void 0;
@@ -27201,7 +27222,8 @@ async function run(walk, step) {
       if (write2 !== void 0) note(walk, { kind: "unknown", table_id: write2.table_id });
       return unknownAt(walk.ctx.step_outputs, step.id);
     }
-    case "agent": {
+    case "agent":
+    case "app_agent": {
       const write2 = rowWriteOf(step);
       if (write2 !== void 0) note(walk, { kind: "unknown", table_id: write2.table_id });
       return unknownAt(walk.ctx.step_outputs, step.id);
@@ -31083,33 +31105,54 @@ function useCommentCounts(args) {
 }
 
 // src/recording.ts
-import { useCallback as useCallback7, useSyncExternalStore as useSyncExternalStore3 } from "react";
+import { useCallback as useCallback7, useMemo as useMemo4, useSyncExternalStore as useSyncExternalStore3 } from "react";
 var NO_MOCKS = {};
+async function startRecording(alias, inputs) {
+  if (getMockRecordings()?.[alias]) return { started: true };
+  return rpc("recording.start", { alias, inputs });
+}
+async function stopRecording(alias) {
+  if (getMockRecordings()?.[alias]) return;
+  await rpc("recording.stop", { alias });
+}
+function busyWith(mocks, hostBusy) {
+  return hostBusy || Object.values(mocks).some((state) => state.phase === "live");
+}
 function useRecording(alias) {
   const { recordingEnabled } = useAppContext();
   const mocks = getMockRecordings() ?? NO_MOCKS;
   const mocked = mocks[alias];
   const hostState = useSyncExternalStore3(subscribeRecordings, () => recordingStateOf(alias));
   const hostBusy = useSyncExternalStore3(subscribeRecordings, anyRecordingLive);
-  const start = useCallback7(
-    async (inputs) => {
-      if (getMockRecordings()?.[alias]) return { started: true };
-      return rpc("recording.start", { alias, inputs: inputs ?? {} });
-    },
-    [alias]
-  );
-  const stop = useCallback7(async () => {
-    if (getMockRecordings()?.[alias]) return;
-    await rpc("recording.stop", { alias });
-  }, [alias]);
+  const start = useCallback7((inputs) => startRecording(alias, inputs ?? {}), [alias]);
+  const stop = useCallback7(() => stopRecording(alias), [alias]);
   return {
     available: mocked !== void 0 || recordingEnabled,
     state: mocked ?? hostState,
-    busy: hostBusy || Object.values(mocks).some((state) => state.phase === "live"),
+    busy: busyWith(mocks, hostBusy),
     start,
     stop
   };
 }
+function useRecordings(aliases) {
+  const { recordingEnabled } = useAppContext();
+  const mocks = getMockRecordings() ?? NO_MOCKS;
+  const version3 = useSyncExternalStore3(subscribeRecordings, recordingsVersion);
+  const hostBusy = useSyncExternalStore3(subscribeRecordings, anyRecordingLive);
+  const key = aliases.join("\n");
+  const states = useMemo4(
+    () => Object.fromEntries(key.split("\n").filter((alias) => alias !== "").map((alias) => [alias, mocks[alias] ?? recordingStateOf(alias)])),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [key, version3, mocks]
+  );
+  return {
+    available: recordingEnabled || aliases.some((alias) => mocks[alias] !== void 0),
+    states,
+    busy: busyWith(mocks, hostBusy),
+    start: startRecording,
+    stop: stopRecording
+  };
+}
 
 // src/geolocation.ts
 var EARTH_RADIUS_M = 6371e3;
@@ -31317,7 +31360,7 @@ function useRecents(key, options = {}) {
 }
 
 // src/use_url_state.ts
-import { useCallback as useCallback9, useEffect as useEffect6, useMemo as useMemo4, useRef as useRef5, useState as useState5 } from "react";
+import { useCallback as useCallback9, useEffect as useEffect6, useMemo as useMemo5, useRef as useRef5, useState as useState5 } from "react";
 function useUrlState(defs) {
   const defsRef = useRef5(defs);
   defsRef.current = defs;
@@ -31337,7 +31380,7 @@ function useUrlState(defs) {
       unsubscribe();
     };
   }, []);
-  const values2 = useMemo4(() => decodeAll(defsRef.current, params), [params]);
+  const values2 = useMemo5(() => decodeAll(defsRef.current, params), [params]);
   const setValues = useCallback9(
     (patch) => {
       editedRef.current = true;
@@ -31421,6 +31464,7 @@ export {
   useQuery,
   useRecents,
   useRecording,
+  useRecordings,
   useUrlState,
   useViewer,
   useWorkflow,

package/dist/recording.d.ts

@@ -44,4 +44,22 @@ export interface UseRecording<I> {
  */
 export declare function useRecording<K extends keyof AppWorkflows & string>(alias: K): UseRecording<ActInputsOf<K>>;
 export declare function useRecording(alias: string): UseRecording<Record<string, unknown>>;
+export interface UseRecordings {
+    /** As {@link UseRecording}'s: whether the host records here at all. */
+    available: boolean;
+    /** The latest recording through each alias asked, idle where none ran. */
+    states: Readonly<Record<string, RecordingState>>;
+    /** Any of this app's recordings is live, through any alias. */
+    busy: boolean;
+    start: (alias: string, inputs: Record<string, unknown>) => Promise<{
+        started: boolean;
+    }>;
+    stop: (alias: string) => Promise<void>;
+}
+/**
+ * {@link useRecording} over several aliases at once — for a screen drawing an
+ * unknown number of recording acts, which cannot call a hook per alias. One
+ * snapshot per change: the host's every-second push while live redraws once.
+ */
+export declare function useRecordings(aliases: readonly string[]): UseRecordings;
 export {};

package/dist/recording_state.d.ts

@@ -33,6 +33,7 @@ export type RecordingState = {
     inputs: RecordingInputs;
 };
 export declare const IDLE_RECORDING: RecordingState;
+export declare function recordingsVersion(): number;
 export declare function subscribeRecordings(listener: () => void): () => void;
 export declare function recordingStateOf(alias: string): RecordingState;
 export declare function anyRecordingLive(): boolean;

package/dist/router.js

@@ -1,7 +1,7 @@
 import {
   isEmbedded,
   setUrlParams
-} from "./chunk-ZOFKWF6V.js";
+} from "./chunk-CRJQYSDI.js";
 
 // src/router.tsx
 import { useEffect } from "react";

package/docs/ai.md

@@ -29,6 +29,7 @@ A declaration carries:
 | `prefix_cache_ttl` | Optional prompt-cache window for the agent's stable prefix (tools + system). **Omit it** — the default `"5m"` is right for essentially every agent. `"1h"` writes at 2x the input rate (against 1.25x) to buy only the five-minute-to-one-hour band; set it only with measured cadence showing runs land there, such as a scheduled sweep |
 | `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it. **Every field defaults to `required: true`**, exactly as `outputs` does — the two extend the same base — so an input the caller may legitimately omit needs `"required": false`, or the run is rejected before the agent sees it |
 | `outputs` | Optional typed output schema — the declaration vocabulary, including the two ways a `select` names its option set, is [mutations](./mutations.md#structured-results-return-data). Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose). **Every field defaults to `required: true`** (the same base schema as `inputs` above) — mark `"required": false` on anything the source may legitimately not carry. It matters most for `number`, which has no blank: text can answer `""`, but a required number leaves only a wrong value or a rejected submission |
+| `writes` | Optional — where the result lands: `{ table_id, row, fields }`. `row` is a single `record_link` input to `table_id`; `fields` maps each output to a field key of that table. Once a run's result validates, each output it carries is written to that row under the app's authority, with the table's locks and hooks applied; an output the result omits is left alone. A write that fails fails the run. Requires `outputs` |
 
 **Structured vs free-text is the load-bearing split.** A structured agent's result arrives in `run.output` (the server strictly validates the submitted result against the declared schema — see the `output` typing section for the exact guarantee); a free-text agent's answer is the transcript's prose (`run.text`) and its `output` stays `undefined` — never a stray string, so a consumer reading `output.<field>` can't crash on a free-text answer.
 

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
@@ -673,6 +674,11 @@ replaces the first's state):
 | `filed` | `execution_id`, `inputs` | the workflow ran and succeeded |
 | `failed` | `message`, `inputs` | transcription failed, or filing was refused or its run failed |
 
+A screen drawing a number of recording acts it only learns at run time reads them together with
+**`useRecordings(aliases)`**: `available` and `busy` as above, `states` (each alias's latest
+recording, idle where none ran), and `start(alias, inputs)` / `stop(alias)` — the same calls, by
+alias.
+
 `inputs` is what `start` was passed, so a screen with one act per row can tell which row the
 recording is about. **`busy`** is true while any recording this app started is live, through
 any alias: stand the other acts down, since the host would refuse them. A recording in another

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/workflows.md

@@ -150,6 +150,7 @@ The body is a sequence of statements, each of which maps 1:1 onto a stored step.
 | Pause for an event | `await wait_for_event({ event_type: "payment" \| "webhook", event_ref, timeout_in_minutes? });` |
 | Pause for a decision | `const a = await wait_for_approval({ approvers, prompt, timeout_in_minutes? });` |
 | LLM reasoning | `const x = await agent({ instructions, input, tools, model?, output });` |
+| Run a declared agent | `const x = await app_agent({ alias, input, wait? });` |
 | Guard | `validate({ checks: [{ fail_when, field_key?, message }, …] });` |
 | End the run | `return({ status, message, field_errors?, data? });` |
 
@@ -313,6 +314,22 @@ name" when broken:
 `model` is an optional pin — omit it to follow the platform default. The step is atomic (no wait
 or approval inside it).
 
+### `app_agent` — run one of this app's agents as one step
+
+```js
+const scored = await app_agent({ alias: "scorer", input: { deal: trigger.app_workflow.inputs.deal } });
+```
+
+`alias` names an agent this app declares; `input` is an object literal checked against its
+`inputs`. The step resolves to the agent's declared `outputs` — typed, so `scored.summary` is
+checked at save — or to its final text when it declares none, and applies the agent's `writes`.
+The run shows in the agent's history like any other. It exists only in an app's own workflows,
+and a run an agent started (through `run_app_workflow`) refuses it: an agent never starts an agent.
+
+`wait: false` starts the run and resolves at once to `{ run_id }`. The workflow goes on, and what
+it wrote stands; the agent's result — its `writes` included — lands when the run settles, and a
+run that fails fails in the agent's history, not the workflow.
+
 ### `try` / `catch`
 
 ```js

package/package.json

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