@lotics/app-sdk 0.33.0 → 0.35.0

package/AGENTS.md

@@ -0,0 +1,262 @@
+# @lotics/app-sdk — the SDK reference
+
+The **data + RPC** runtime for Lotics custom-code apps: typed React hooks over an
+origin-locked postMessage bridge, plus cell decoders and the `mount()` entry point. This
+file is the SDK reference — the "reach for what" guide + the load-bearing patterns. The
+**exact signature** of any hook or reader is its source, which ships with the package: read
+`node_modules/@lotics/app-sdk/dist/src/<name>.d.ts`. **Never guess a signature — open the
+file.**
+
+- Import from the package root: `import { useQuery, useWorkflow, row } from "@lotics/app-sdk"`.
+- **Data + RPC only — no UI.** The SDK ships zero components (keeps it off the React-Native-Web
+  tree). Render with **`@lotics/ui`** (read its `node_modules/@lotics/ui/AGENTS.md`); the two
+  pair — SDK fetches/mutates, `@lotics/ui` draws.
+- **Two transports, picked automatically.** Embedded (the authenticated product host bridges
+  RPC over postMessage) vs. standalone (`<slug>.lotics.app`, public, calls the API directly).
+  App code never branches on it; the SDK does.
+- **The app holds no credentials and writes nothing directly.** Every read is a declared named
+  query; every write is a declared workflow. The model, the IAM/auth rules, and the security
+  rationale live in **`docs/apps.md`** — read it for *why*; this file is *how*.
+
+---
+
+## Reach by role — the surface
+
+Pick by intent. (→ open the `.d.ts` for the exact signature.)
+
+- **Read rows** — three hooks, one job each; don't overload one:
+  - **`useQuery(alias, params?, opts?)`** — a single fetch (`pageSize` is a cap, not pagination).
+    For a detail read or a combobox's top-N. `opts.enabled` gates the fetch (nothing loads until
+    true); `opts.sort` / `opts.filter` refine over the query's OUTPUT columns.
+  - **`useInfiniteQuery`** — append / load-more (`loadMore`, accumulating `rows`). Infinite scroll.
+  - **`usePaginatedQuery(alias, params?, { pageSize, sort, filter })`** — page-model with a
+    `total`, behind `Pagination`. Owns the page cursor; fetches the page AND a `count` keyed on
+    `(alias, params, filter)` (independent of page+sort, so paging/re-sorting never recount).
+    `(params, filter)` is the result-set identity — changing it resets to page 0 and recounts.
+- **A select field's options** — **`useFieldOptions(alias)`** → per select OUTPUT column, its FULL
+  `{ key, label, color }` list (incl. options not in any current row) + a `byKey` lookup. Populates
+  + colors pickers and stored values; tracks the table (a newly added/renamed option just renders).
+- **Mutate (the ONLY write path)** — **`useWorkflow(alias)`** → an async fn returning a typed
+  `WorkflowResult` `{ status, message?, files?, data? }`. `data` is whatever the workflow
+  `return({ data })`'d (typed automatically from the alias contract). After a known mutation,
+  call the owning query's `refetch()`.
+- **Upload a file** — **`useFileUpload()`** → `{ upload, uploading, error }`. Mints a presigned URL
+  and PUTs the bytes straight to storage; the file is inert until a workflow attaches it to a
+  `files` field. Emits `app_file_uploaded`.
+- **List members** — **`useMembers(opts?)`** → `{ members: {id,name,email,image}[], loading, error }`
+  — the candidate set for an assign/picker. Gated: the app must declare a `member`-typed input
+  (`opts.group` restricts to a declared group). Render with `@lotics/ui` `MemberSelect` / `MemberChip`.
+- **Comments on a record** — **`useComments({ record_id })`** / **`useCommentCounts({ table_id })`**.
+  Capability-gated (`"capabilities": { "comments": true }` in the manifest) AND members-only — check
+  `available` before showing a composer. Runs under the VIEWING member's authority (author = the
+  viewer), unlike queries/workflows (owner authority). Render with `@lotics/ui` `comments_thread`.
+- **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.
+- **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
+  client-side advisory — pass `coords` to a workflow to record where an action happened.
+- **Recents** — **`useRecents(key, max)`** → most-recent-first, deduped, capped, `localStorage`-backed
+  (web-only, which is why it's here, not in `@lotics/ui`). Feeds a `Combobox`'s `recentOptions`.
+- **Optimistic mutation glue** — **`useOptimistic()`** → reconcile a workflow mutation against the
+  query cache for an interactive (calendar/kanban/grid) app. See the data-bound recipe.
+- **Infra** — **`mount(opts?)`** boots the app + analytics (call once at entry; PostHog is automatic,
+  no per-app wiring). **`rpc(op, payload)`** is the raw bridge (escape hatch; prefer the hooks).
+  **`openExternal(url)`** opens a link in a new tab (scheme-validated; host-mediated in the embed).
+  **`downloadFile(name, data, mime?)`** saves browser-built bytes (a `Uint8Array | Blob | string`) —
+  call it synchronously from the click that produced them.
+
+### Decoding query cells — never hand-roll the serialization contract
+
+`useQuery` rows are `Record<string, unknown>`. Coerce each cell with a typed reader (`row.ts` /
+`select.ts` / `members.ts`); never re-implement `firstOpt`/`linkId`/`linkDisplay` — they rot.
+
+- **`row.opt/text/num/bool/date/datetime/link`** — scalar coercion. `row.date` = calendar day
+  (LOCAL midnight, time stripped); **`row.datetime`** keeps the wall-clock — use it (and project the
+  column `type:"datetime"`) when you need the time, or it prints `00:00`.
+- **`readSelect(cell)`** → `ResolvedOption[]` `{ key, label, color? }` (a cell carries key+label; the
+  `color` is populated by `useFieldOptions`, not the cell). **`readMembers(cell)`** → `{ id, name,
+  email? }[]`. **`readLinks(cell)` / `row.link`** → `{ id, display }`. **`readFiles(cell)`** →
+  `AppFile[]` with presigned `url` + `thumbnail_url` (24 h). **`readLocked(row)`** → `boolean` from the
+  `__source_locked` addressing column.
+- **`project` only what you render** and `filter` server-side: a bare `from_table` ships every column
+  — incl. `files` with storage keys — to the client (over-exposure + presign-500 at scale). A code
+  lookup is a parameterized `filter`, not load-all-then-filter-in-JS.
+
+---
+
+## Data discipline (every app, prevents whole bug classes)
+
+- **Server data is never copied into `useState`.** `useQuery` / `useWorkflow` results are the source
+  of truth — derive everything else with `useMemo`. A second copy drifts and serves stale values.
+- **Prefer derivation + callbacks over `useEffect`.** A derived value is `useMemo`; "state A changed
+  → set state B" is both set in the one triggering callback. `useEffect` is for genuine external
+  subscriptions (timers, DOM listeners, storage) — fetching is `useQuery`, not an effect.
+- **No layout shift on load or paging — the UX bar, not a nicety.** Reserve space while data loads:
+  (1) first load renders `Skeleton` placeholders that mirror the final layout, not a bare spinner;
+  (2) a page change KEEPS the previous rows (`usePaginatedQuery` does this via `keepPreviousData`) —
+  gate the skeleton on `loading && rows.length === 0`, never `loading` alone, or every "next page"
+  collapses the table; (3) a view↔edit toggle reserves the input's height so pressing Edit never
+  reflows.
+- **Diff before update.** An edit form snapshots the record at load and sends only the CHANGED fields
+  to its update workflow (declare those inputs optional; an omitted input = not written). A full-form
+  snapshot re-writes locked fields (blocked even if unchanged), fires `before_update` autofills
+  spuriously, and clobbers concurrent edits. For a locked record (`readLocked`), the save becomes one
+  `request_locked_record_change` carrying the diffed `changes` + a reason.
+- **Reuse the kit's utilities** — `@lotics/ui` ships the formatters (`formatMoney`, `formatDate`/
+  `parseDate`/`toISODate`); never hand-roll `dd/MM` or `₫`. Grep `@lotics/ui` exports before writing one.
+
+---
+
+## Search-as-you-type
+
+A search-first picker (type → ranked results → pick) is one `@lotics/ui` component + three SDK pieces;
+compose these, don't hand-roll search:
+
+- **`Combobox`** (`@lotics/ui`) owns the interaction — debounced `onSearchChange`, a popover listbox
+  with rich rows (`renderOptionContent` reading `PickerOption.data`), keyboard nav, `recentOptions`,
+  `allowCustom`. (For a known small list with no search box, `Picker`.)
+- **A parameterized `search` query** — a `from_table` with `search: "{{params.q}}"` over the maintained
+  `search_document`: **diacritics- & case-insensitive** (`"da nang"` matches `"Đà Nẵng"`), trigram-
+  indexed (scales), privacy-aware. AND-s with `filter` (search within a scope). Reserve an OR-group of
+  per-field `contains` (accent-*sensitive*, unindexed) only when you must bound exactly which fields
+  match. **Search-as-you-type uses `search`, never a `contains` OR-group** — a zero-match keystroke on
+  `contains` forces a full-table scan that hangs the picker.
+- **`useQuery(alias, params, { enabled })`** — gate on a non-empty term; an empty term matches
+  everything (`ILIKE '%%'`) and dumps the table on first paint. `enabled` makes "nothing loads until
+  you type" true.
+- **`useRecents`** — persist the picked option; pass its list as `recentOptions`.
+
+Fetch detail on select with a SECOND parameterized query (a unique-code `equals`, or a link
+`has_any_of [record_id]`) — never a bare full-table load. Filtering a record by its *own* id isn't a
+compilable AST shape; filter by a unique field value.
+
+## Browse + sort + filter (the record picker)
+
+When the user doesn't know the term — "show me everything, let me narrow it" — a modal table you can
+browse (numbered pages), search, sort, and filter:
+
+- **`TablePicker`** (`@lotics/ui`) is the data-agnostic base (a `Dialog` over `SearchInput` + filter
+  pills + `Table` + `Pagination`); it owns nothing about records — the consumer passes `columns` + one
+  page of `rows` and owns the search/sort/filter/page state. Filter pills are `ColumnFilter` +
+  `columnFilterToConditions`.
+- **A records wrapper lives in the app** (e.g. `record_picker.tsx`) — it needs BOTH `@lotics/ui` and
+  the SDK (which is UI-free), so it can't be a package. It runs a named query via `usePaginatedQuery`
+  and feeds the page into `TablePicker`. Reuse it for any table by passing a different `alias` + `columns`.
+
+The pieces that make it work:
+- **Runtime `sort`/`filter` are server-bounded to the query's OUTPUT columns** (an un-projected
+  `field_key` → 400) — the picker can't widen exposure. Build `filter` with `columnFilterToConditions`;
+  map sort `{key,order}` → `[{field_key, order}]`.
+- **The total comes from `count: true`** — a single-row COUNT over the filtered set (ignores
+  sort/limit/offset), driving "Page 1 of N".
+- **Browse needs an unbounded query** — a baked-in AST `limit` caps the *total*; drop it and let
+  `pageSize` drive.
+- **Select filter options:** prefer `useFieldOptions` for the COMPLETE set (not options derived from
+  loaded rows, which are incomplete until every page loads).
+
+## Rendering table primitives — select colors & members
+
+Two of the most common cells render the platform way with zero hand-rolling; hand the value to its
+`@lotics/ui` component — never re-derive an option→color map or a hand-built avatar (both rot):
+
+- **Select value** → `OptionBadge` (`@lotics/ui`) with its CONFIGURED color. Stored value:
+  `byKey(readSelect(cell)[0]?.key)` from `useFieldOptions`; picker option: a `useFieldOptions` option.
+  Multi wraps; a missing/unknown color degrades to neutral.
+- **Member** → `MemberChip` (avatar + name; the universal person render) and `MemberSelect` (the ready
+  picker — a `Picker` of `MemberChip`s). Feed from `useMembers`. (Avatars stay in the bounded, cached
+  roster — presigned files, never fattened onto every query cell; select color is a cheap token, so it
+  rides in `useFieldOptions`.) Full props: `@lotics/ui/AGENTS.md`.
+
+## Previewing files
+
+Render any uploaded file inline — image, PDF, video, audio, Word, Excel, CSV — with `@lotics/ui`; never
+hand-roll per-type rendering.
+
+- **`FileGalleryModal`** (full-screen viewer) delegates to **`FilePreview`** (single-file), dispatching
+  by MIME; the frontend gallery uses the same renderer.
+- File cells already carry presigned URLs — decode with **`readFiles`** → `AppFile[]`, map to
+  `DisplayFile` (`mime_type`→`mimeType`, `thumbnail_url`→`thumbnailUrl`). No round-trip, no URL
+  derivation, no server-side doc→PDF (rendering is client-side).
+- Word/Excel preview lazy-imports `@lotics/docx` + `@lotics/xlsx` (optional peer deps) — an image/PDF
+  app installs neither. `@lotics/ui` is i18n/analytics-free: pass `labels` + an `onError`.
+
+## Composable optional filters (one query, many scopes)
+
+Expose several INDEPENDENT filter axes the caller mixes freely from ONE named query — don't shard into
+a query-per-combination. Mark each scoping param `required: false`; the server **prunes every filter
+condition whose `{{params.x}}` the caller didn't pass** (then collapses empty groups), so an unset axis
+stops constraining instead of erroring (no-op for all-required queries).
+
+```jsonc
+"search": {
+  "ast": { "kind": "project", "from": { "kind": "from_table", "table_id": "tbl_items", "filter": {
+    "node_type": "group", "logic": "and", "children": [
+      { "node_type": "condition", "field_key": "status", "operator": "has_any_of", "value": ["{{params.status}}"] },
+      // keyword over two fields — the whole OR-group prunes when `keyword` is absent
+      { "node_type": "group", "logic": "or", "children": [
+        { "node_type": "condition", "field_key": "title", "operator": "contains", "value": "{{params.keyword}}" },
+        { "node_type": "condition", "field_key": "notes", "operator": "contains", "value": "{{params.keyword}}" } ] },
+      // date range — each bound is its OWN single-param condition, so an open-ended range prunes one side
+      { "node_type": "condition", "field_key": "created", "operator": "on_or_after",
+        "value": { "type": "exact", "date": "{{params.from}}", "time": null } },
+      { "node_type": "condition", "field_key": "created", "operator": "on_or_before",
+        "value": { "type": "exact", "date": "{{params.to}}", "time": null } } ] } }, "columns": [ /* … */ ] },
+  "params": {
+    "status":  { "type": "select", "options": [ /* … */ ], "required": false },
+    "keyword": { "type": "text", "required": false },
+    "from":    { "type": "date", "required": false },
+    "to":      { "type": "date", "required": false } }
+}
+```
+
+`useQuery("search", { keyword })` filters by keyword only; `{}` returns everything. **Dates:** there's no
+`date_range` param — embed a `date`/`text` param in a hand-built `DateTimePoint`
+(`{type:"exact", date:"{{params.from}}", time:null}`), one condition per bound so each prunes
+independently. Keep a scope that must always apply `required` (a missing required param 400s). Typos
+can't widen — deploy rejects a `{{params.x}}` with no declared param.
+
+---
+
+## Recipes (app actions beyond the hooks)
+
+Reverse-engineered once; full code in the `/app` skill's `references/recipes.md`.
+
+- **Generate a document → download** — the file returns in `WorkflowResult.files[]` (auto-extracted from
+  any step's `file_id`); open via `openExternal(files[0].url)`. Don't hand back a `url`/`file_id` from
+  `return()`.
+- **Export displayed data → .xlsx (client-side)** — `buildDataWorkbook({columns, rows})` (`@lotics/xlsx`)
+  → `exportWorkbook` → `downloadFile`. To export the WHOLE result (not one page), page the query
+  imperatively with `rpc("query", { alias, params, limit, offset })` to exhaustion (embedded-app only —
+  the public transport drops `sort`/`filter`).
+- **Workflow returns data → fill the UI** — `return({ data })` hands back any structured result, read as
+  a typed `result.data` (no schema needed; narrow before use — a fall-through completion returns none).
+- **Look up one record by a typed code** — a parameterized `{{params.x}}` filter + `useQuery(alias, {...})`,
+  so the client never receives other rows. Autonumber fields filter as text. (Public-app IDOR caveat:
+  `docs/apps.md`.)
+- **Interactive (read + mutate) app** — `row.*` to coerce + `useOptimistic` to reconcile; `@lotics/ui`
+  provides the drag-enabled calendar/gantt/kanban/grid.
+
+---
+
+## Authority & scoping (the one-paragraph rule — full model in `docs/apps.md`)
+
+App data ops run under the **app owner's** principal, not the viewer's — so who-is-acting and per-user
+scoping are the author's job, never inferred. **Reads:** scope "my X" with the `is_current_member`
+operator in the query TEMPLATE (the server binds the signed-in viewer / the view-as subject) — never a
+client-supplied `member_id` (that's an IDOR; per-user data must not ship in a *public* app). **Writes:**
+derive the actor server-side — read `runtime.triggered_by_member_id` in the workflow body; a client
+`member` input is spoofable. **Privileged writes** (a role/group gate) authorize the caller in the
+workflow with `current_member_in_any_group(...)`, paired with a manager-only read. `useViewer()` is
+display-only, not an authorization fact. The full IAM model, public-access bounds, and the security
+rationale: **`docs/apps.md`**.
+
+---
+
+## Keeping this file current
+
+This is the published SDK reference — agents read `node_modules/@lotics/app-sdk/AGENTS.md` when building
+apps. **Codify every new hook, reader, and load-bearing pattern here** in the same change that adds it
+(and bump the package version so it ships). Keep it tight: the catalog points at the `.d.ts` for exact
+signatures; the model/IAM/security rationale stays in `docs/apps.md` — link, don't duplicate.

package/dist/src/agent_stream.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Parse a backend app-agent run stream into the app's agent-run model.
+ *
+ * The backend streams the AI-SDK "UI message" SSE protocol (the same wire format
+ * the chat uses) — `data: <json>\n\n` frames, each a typed chunk, terminated by
+ * `data: [DONE]`. The app SDK consumes it WITHOUT depending on the `ai` package
+ * (the sandboxed app bundle stays lean): we read the handful of chunk types that
+ * matter for a run feed and fold them into `AgentRunState`. Unknown chunk types
+ * are ignored, so an AI-SDK version that adds chunk kinds never breaks the SDK.
+ *
+ * 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.
+ */
+export interface AgentRunStep {
+    id: string;
+    label: string;
+    detail?: string;
+    status: "running" | "done" | "error";
+    kind?: "step" | "tool";
+}
+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. */
+    output?: unknown;
+    error?: string;
+}
+export declare function initialAgentRunState(): AgentRunState;
+/** A parsed UI-message chunk — only the fields we read, all optional. */
+interface Chunk {
+    type?: string;
+    delta?: string;
+    toolName?: string;
+    toolCallId?: string;
+    input?: unknown;
+    errorText?: string;
+    finishReason?: string;
+}
+/** Fold one chunk into the run state. Returns a new state (immutable). */
+export declare function reduceAgentChunk(state: AgentRunState, chunk: Chunk): AgentRunState;
+/**
+ * Incremental SSE frame splitter. Feed it raw text as it arrives; it returns the
+ * complete chunks parsed so far and the leftover partial frame to carry forward.
+ * `[DONE]` is dropped (the `finish` chunk already settles the state).
+ */
+export declare function parseSseChunks(buffer: string): {
+    chunks: Chunk[];
+    rest: string;
+};
+export {};

package/dist/src/agent_stream.js

@@ -0,0 +1,78 @@
+/**
+ * Parse a backend app-agent run stream into the app's agent-run model.
+ *
+ * The backend streams the AI-SDK "UI message" SSE protocol (the same wire format
+ * the chat uses) — `data: <json>\n\n` frames, each a typed chunk, terminated by
+ * `data: [DONE]`. The app SDK consumes it WITHOUT depending on the `ai` package
+ * (the sandboxed app bundle stays lean): we read the handful of chunk types that
+ * matter for a run feed and fold them into `AgentRunState`. Unknown chunk types
+ * are ignored, so an AI-SDK version that adds chunk kinds never breaks the SDK.
+ *
+ * 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.
+ */
+/** The tool the backend injects to carry a typed structured result. */
+const SUBMIT_TOOL = "submit_result";
+export function initialAgentRunState() {
+    return { status: "streaming", text: "", steps: [] };
+}
+/** Fold one chunk into the run state. Returns a new state (immutable). */
+export function reduceAgentChunk(state, chunk) {
+    switch (chunk.type) {
+        case "text-delta":
+        case "reasoning-delta": {
+            const piece = chunk.delta ?? "";
+            return piece ? { ...state, text: state.text + piece } : state;
+        }
+        case "tool-input-available": {
+            const name = chunk.toolName ?? "tool";
+            if (name === SUBMIT_TOOL) {
+                // The agent emitted its structured result.
+                return { ...state, output: chunk.input };
+            }
+            return {
+                ...state,
+                steps: [
+                    ...state.steps,
+                    { id: chunk.toolCallId ?? `${name}-${state.steps.length}`, label: name, kind: "tool", status: "done" },
+                ],
+            };
+        }
+        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 };
+        }
+        default:
+            return state;
+    }
+}
+/**
+ * Incremental SSE frame splitter. Feed it raw text as it arrives; it returns the
+ * complete chunks parsed so far and the leftover partial frame to carry forward.
+ * `[DONE]` is dropped (the `finish` chunk already settles the state).
+ */
+export function parseSseChunks(buffer) {
+    const chunks = [];
+    const frames = buffer.split("\n\n");
+    const rest = frames.pop() ?? ""; // last element is the incomplete frame
+    for (const frame of frames) {
+        for (const line of frame.split("\n")) {
+            const trimmed = line.startsWith("data:") ? line.slice(5).trim() : "";
+            if (!trimmed || trimmed === "[DONE]")
+                continue;
+            try {
+                chunks.push(JSON.parse(trimmed));
+            }
+            catch {
+                // a non-JSON data line — skip it, never throw on the stream
+            }
+        }
+    }
+    return { chunks, rest };
+}

package/dist/src/hooks.d.ts

@@ -1,5 +1,8 @@
-import type { AppWorkflows, AppWorkflowResults, AppQueries } from "./types.js";
+import { type AgentRunStep } 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";
 /** Fields shared by every query hook's return value. */
 interface QueryStateBase {
     /**
@@ -189,6 +192,68 @@ type QueryArgs<K extends keyof AppQueries & string, O> = AppQueries[K] extends R
  */
 export declare function useQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, QueryOptions>): QueryState<Record<string, unknown>>;
 export declare function useQuery(alias: string, params?: Record<string, unknown>, opts?: QueryOptions): QueryState<Record<string, unknown>>;
+/** The resolved option set of one select column, plus an index for value
+ *  rendering. The companion to a query row, for select fields. */
+export interface FieldOptions {
+    /** The source field's display name — e.g. a picker/section label. */
+    label: string;
+    /**
+     * Every option of the field — `{ key, label, color }`. Includes options not
+     * present in any current row, so a freshly-added option appears in a picker
+     * without an app change, and a removed one drops out.
+     */
+    options: ResolvedOption[];
+    /**
+     * Resolve one option by key — for COLORING A STORED VALUE: pair with
+     * `readSelect(cell)[0]?.key`. `undefined` for an unknown key (option removed
+     * after the cell was written); render the cell's own label with a neutral
+     * badge in that case.
+     */
+    byKey: (key: string) => ResolvedOption | undefined;
+}
+/** Return value of `useFieldOptions`. */
+export interface FieldOptionsState {
+    /**
+     * Resolved option sets keyed by the query's OUTPUT column name. A select
+     * column the server couldn't resolve to a source field (a UNION output, a
+     * computed column) is simply absent — read defensively (`fields.status?`).
+     */
+    fields: Record<string, FieldOptions>;
+    loading: boolean;
+    isValidating: boolean;
+    error: string | null;
+    /** Re-fetch — after a known field-config change (rare). */
+    refetch: () => void;
+}
+/** Options for `useFieldOptions`. */
+export interface FieldOptionsOptions {
+    /** Defer the fetch until true — e.g. a picker that only needs options once an
+     *  edit drawer opens. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Resolve the full option set (key, label, color) of a named query's `select`
+ * columns — the picker companion to `useQuery`. Where a query CELL carries only
+ * the options a record actually holds (key + label, no color), this returns each
+ * select column's COMPLETE option list with colors, straight from the field
+ * config — so it populates a dropdown AND colors a stored value, and a freshly
+ * added/removed option flows through with no app change.
+ *
+ * Addressed by the same alias you query: the option sets resolve from the named
+ * query's output columns, scoped exactly like running it. A column the server
+ * can't map to a source select field (UNION output, computed column) is absent.
+ *
+ * ```tsx
+ * const { fields } = useFieldOptions("records");
+ * // populate + color a picker:
+ * <Picker options={fields.status?.options ?? []}
+ *   renderOptionContent={(o) => <OptionBadge value={o} />} />
+ * // color a stored value:
+ * <OptionBadge value={fields.status?.byKey(readSelect(r.status)[0]?.key ?? "")} />
+ * ```
+ */
+export declare function useFieldOptions<K extends keyof AppQueries & string>(alias: K, opts?: FieldOptionsOptions): FieldOptionsState;
+export declare function useFieldOptions(alias: string, opts?: FieldOptionsOptions): FieldOptionsState;
 /**
  * Like `useQuery` but append/load-more: the first render loads one page and
  * `loadMore()` appends the next, accumulating into `rows` (infinite scroll).
@@ -284,4 +349,72 @@ export interface MembersOptions {
  * ```
  */
 export declare function useMembers(opts?: MembersOptions): MembersState;
-export {};
+type AgentOutputOf<K extends string> = K extends keyof AppAgentResults ? AppAgentResults[K] : unknown;
+/** Options for one `run(...)` call — the app-owned session key it belongs to. */
+export interface AgentRunOptions {
+    /** Groups this run with prior runs in the same working session; the agent
+     *  re-reads them for context. Mint a new id to "clear context". */
+    sessionId: string;
+}
+/** The live state + controls returned by `useAgentRun`. */
+export interface UseAgentRun<TInput, TOutput> {
+    /** Start a run — streams progress into this hook's state and resolves to the
+     *  structured output (undefined for a free-text or failed run). Calling again
+     *  aborts any run still in flight. */
+    run: (input: TInput, opts: AgentRunOptions) => Promise<TOutput | undefined>;
+    abort: () => void;
+    status: "idle" | "streaming" | "completed" | "error";
+    /** The agent's streamed reasoning / answer text, accumulating live. */
+    text: string;
+    /** The agent's tool calls so far — bind to `@lotics/ui` `AgentRun`/`AgentProgress`. */
+    steps: AgentRunStep[];
+    /** The validated structured result, once the run completes. */
+    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`.
+ *
+ * ```tsx
+ * const recognize = useAgentRun("recognize");
+ * await recognize.run({ image_file_id }, { sessionId });
+ * // recognize.status / recognize.steps / recognize.output
+ * ```
+ */
+export declare function useAgentRun<K extends keyof AppAgents & string>(alias: K): UseAgentRun<AppAgents[K], AgentOutputOf<K>>;
+export declare function useAgentRun(alias: string): UseAgentRun<Record<string, unknown>, unknown>;
+/** One persisted run in a session's history (the `/agent-runs` row shape). */
+export interface AgentRunRecord {
+    id: string;
+    agent_alias: string;
+    session_id: string;
+    status: string;
+    input: Record<string, unknown> | null;
+    output: unknown;
+    error_message: string | null;
+    started_at: string;
+    completed_at: string | null;
+}
+interface AgentRunsState {
+    runs: AgentRunRecord[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => void;
+}
+/**
+ * The run history of a session, oldest-first — the persisted outputs the app
+ * renders as a session log (NOT a chat: a flat list of past runs). Refetch
+ * after a `run(...)` completes to pull in the new one.
+ *
+ * ```tsx
+ * const { runs } = useAgentRuns(sessionId);
+ * ```
+ */
+export declare function useAgentRuns(sessionId: string, opts?: {
+    enabled?: boolean;
+    revalidateOnFocus?: boolean;
+}): AgentRunsState;

package/dist/src/hooks.js

@@ -15,10 +15,11 @@
  * cache survives unmount/remount. Mutation / member hooks keep their own local
  * `useState` — they have nothing to share.
  */
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
-import { rpc } from "./rpc.js";
+import { rpc, rpcAgentRun } from "./rpc.js";
+import { initialAgentRunState, reduceAgentChunk, parseSseChunks, } from "./agent_stream.js";
 import { getMockRows } from "./mock.js";
 import { captureAppEvent } from "./analytics.js";
 export function useWorkflow(alias) {
@@ -76,6 +77,33 @@ export function useQuery(alias, params, opts) {
         refetch,
     };
 }
+export function useFieldOptions(alias, opts) {
+    const enabled = opts?.enabled ?? true;
+    // Field config is slow-changing, so no focus/reconnect revalidation — the app
+    // calls `refetch()` after a known change. A null key defers the fetch.
+    const key = enabled ? ["app-field-options", alias] : null;
+    const swr = useSWR(key, () => rpc("field_options", { alias }), swrConfig(false));
+    const fields = useMemo(() => {
+        const raw = swr.data?.fields ?? {};
+        const out = {};
+        for (const [col, def] of Object.entries(raw)) {
+            const options = def.options ?? [];
+            const index = new Map(options.map((o) => [o.key, o]));
+            out[col] = { label: def.label, options, byKey: (k) => index.get(k) };
+        }
+        return out;
+    }, [swr.data]);
+    const refetch = useCallback(() => {
+        void swr.mutate();
+    }, [swr]);
+    return {
+        fields,
+        loading: swr.isLoading,
+        isValidating: swr.isValidating,
+        error: swr.error ? swr.error.message : null,
+        refetch,
+    };
+}
 export function useInfiniteQuery(alias, params, opts) {
     const pageSize = opts?.pageSize ?? 30;
     const enabled = opts?.enabled ?? true;
@@ -262,3 +290,105 @@ export function useMembers(opts) {
     }, [group]);
     return state;
 }
+export function useAgentRun(alias) {
+    const [state, setState] = useState(null);
+    const handleRef = useRef(null);
+    // Guards setState after unmount and aborts any in-flight run on unmount, so a
+    // stream never keeps writing to a dead component (or leaks the transport).
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+            handleRef.current?.abort();
+        };
+    }, []);
+    const safeSetState = useCallback((s) => {
+        if (mountedRef.current)
+            setState(s);
+    }, []);
+    const run = useCallback((input, opts) => {
+        handleRef.current?.abort();
+        let acc = initialAgentRunState();
+        let buffer = "";
+        let aborted = false;
+        safeSetState(acc);
+        const handle = rpcAgentRun({ alias, session_id: opts.sessionId, input: input ?? {} }, (textChunk) => {
+            if (aborted)
+                return;
+            buffer += textChunk;
+            const { chunks, rest } = parseSseChunks(buffer);
+            buffer = rest;
+            if (chunks.length === 0)
+                return;
+            for (const c of chunks)
+                acc = reduceAgentChunk(acc, c);
+            safeSetState({ ...acc });
+        });
+        // Wrap abort so a stop (user or unmount) marks the run cancelled and clears
+        // the partial state back to idle — `done` resolves cleanly, never an error.
+        handleRef.current = {
+            abort: () => {
+                if (aborted)
+                    return;
+                aborted = true;
+                handle.abort();
+                safeSetState(null);
+            },
+        };
+        return handle.done
+            .then(() => {
+            if (aborted)
+                return undefined;
+            // `finish` normally settles status; guard a stream that ended without one.
+            if (acc.status === "streaming") {
+                acc = { ...acc, status: "completed", output: acc.output ?? (acc.text.trim() || undefined) };
+                safeSetState(acc);
+            }
+            captureAppEvent("app_agent_run", { alias, ok: acc.status !== "error" });
+            return acc.output;
+        })
+            .catch((err) => {
+            if (aborted)
+                return undefined;
+            acc = { ...acc, status: "error", error: err.message };
+            safeSetState(acc);
+            captureAppEvent("app_agent_run", { alias, ok: false });
+            throw err;
+        });
+    }, [alias, safeSetState]);
+    const abort = useCallback(() => handleRef.current?.abort(), []);
+    return {
+        run,
+        abort,
+        status: state?.status ?? "idle",
+        text: state?.text ?? "",
+        steps: state?.steps ?? [],
+        output: state?.output,
+        error: state?.error,
+    };
+}
+/**
+ * The run history of a session, oldest-first — the persisted outputs the app
+ * renders as a session log (NOT a chat: a flat list of past runs). Refetch
+ * after a `run(...)` completes to pull in the new one.
+ *
+ * ```tsx
+ * const { runs } = useAgentRuns(sessionId);
+ * ```
+ */
+export function useAgentRuns(sessionId, opts) {
+    const enabled = opts?.enabled ?? true;
+    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
+    const key = enabled && sessionId ? ["app-agent-runs", sessionId] : null;
+    const swr = useSWR(key, () => rpc("agentRuns", { session_id: sessionId }), swrConfig(revalidateOnFocus));
+    const refetch = useCallback(() => {
+        void swr.mutate();
+    }, [swr]);
+    return {
+        runs: swr.data?.runs ?? [],
+        loading: swr.isLoading,
+        error: swr.error?.message ?? null,
+        refetch,
+    };
+}

package/dist/src/index.d.ts

@@ -16,8 +16,8 @@
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUpload, useMembers, } from "./hooks.js";
-export type { UploadedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useMembers, useAgentRun, useAgentRuns, } from "./hooks.js";
+export type { UploadedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunRecord, AgentRunState, AgentRunStep, 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";
@@ -32,7 +32,7 @@ export type { ResolvedMember } from "./members.js";
 export { readSelect } from "./select.js";
 export type { ResolvedOption } from "./select.js";
 export type { AppFixture } from "./mock.js";
-export type { AppWorkflows, AppQueries } from "./types.js";
+export type { AppWorkflows, AppQueries, AppAgents, AppAgentResults } from "./types.js";
 export { row, readLinks, readFiles, readLocked } from "./row.js";
 export type { ResolvedLink, AppFile } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";

package/dist/src/index.js

@@ -15,7 +15,7 @@
  * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUpload, useMembers, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useMembers, useAgentRun, useAgentRuns, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";

package/dist/src/rpc.d.ts

@@ -18,7 +18,19 @@
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "workflow" | "upload" | "members" | "context" | "openExternal" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "upload" | "members" | "context" | "openExternal" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+/** Payload for starting a streaming agent run. */
+export interface AgentRunPayload {
+    alias: string;
+    session_id: string;
+    input: Record<string, unknown>;
+}
+/** Handle to a running stream — `done` settles at the end (or rejects on
+ *  error); `abort` stops it. The caller feeds each text chunk to the parser. */
+export interface AgentRunHandle {
+    done: Promise<void>;
+    abort: () => void;
+}
 /**
  * The app's identity, resolved once at startup to tag PostHog events.
  * Assembled by whichever transport is active:
@@ -46,3 +58,10 @@ export interface AppContext {
     comments_enabled: boolean;
 }
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;
+/**
+ * Start a streaming agent run. Each raw SSE text chunk is handed to `onText`
+ * (the caller parses it via `agent_stream`); `done` settles when the stream
+ * ends. Bridged: the host opens the SSE with its session and forwards chunks;
+ * standalone: the SDK reads the public endpoint's body directly.
+ */
+export declare function rpcAgentRun(payload: AgentRunPayload, onText: (chunk: string) => void): AgentRunHandle;

package/dist/src/rpc.js

@@ -24,6 +24,7 @@ export function rpc(op, payload) {
         : rpcStandalone(op, payload);
 }
 const pending = new Map();
+const streaming = new Map();
 let nextRpcId = 0;
 let listenerInstalled = false;
 function ensureListener() {
@@ -37,15 +38,31 @@ function ensureListener() {
         const msg = event.data;
         if (!msg || typeof msg.id !== "number")
             return;
+        // Single-response ops.
         const handler = pending.get(msg.id);
-        if (!handler)
+        if (handler) {
+            pending.delete(msg.id);
+            if (msg.type === "result")
+                handler.resolve(msg.data);
+            else
+                handler.reject(new Error(msg.message ?? "RPC failed"));
             return;
-        pending.delete(msg.id);
-        if (msg.type === "result") {
-            handler.resolve(msg.data);
         }
-        else {
-            handler.reject(new Error(msg.message ?? "RPC failed"));
+        // Streaming op (agentRun): chunk* → end | error.
+        const stream = streaming.get(msg.id);
+        if (!stream)
+            return;
+        if (msg.type === "stream-chunk") {
+            if (typeof msg.chunk === "string")
+                stream.onText(msg.chunk);
+        }
+        else if (msg.type === "stream-end") {
+            streaming.delete(msg.id);
+            stream.resolve();
+        }
+        else if (msg.type === "error") {
+            streaming.delete(msg.id);
+            stream.reject(new Error(msg.message ?? "Run failed"));
         }
     });
 }
@@ -57,6 +74,77 @@ function rpcBridged(op, payload, host) {
         window.parent.postMessage({ id, op, payload }, host);
     });
 }
+// ── Streaming transport (agent runs) ─────────────────────────────────────────
+/**
+ * Start a streaming agent run. Each raw SSE text chunk is handed to `onText`
+ * (the caller parses it via `agent_stream`); `done` settles when the stream
+ * ends. Bridged: the host opens the SSE with its session and forwards chunks;
+ * standalone: the SDK reads the public endpoint's body directly.
+ */
+export function rpcAgentRun(payload, onText) {
+    const hostOrigin = getHostOrigin();
+    return hostOrigin ? agentRunBridged(payload, onText, hostOrigin) : agentRunStandalone(payload, onText);
+}
+function agentRunBridged(payload, onText, host) {
+    ensureListener();
+    const id = nextRpcId++;
+    let settleDone = () => { };
+    const done = new Promise((resolve, reject) => {
+        settleDone = resolve;
+        streaming.set(id, { onText, resolve, reject });
+        window.parent.postMessage({ id, op: "agentRun", payload }, host);
+    });
+    return {
+        done,
+        abort: () => {
+            if (!streaming.has(id))
+                return;
+            streaming.delete(id);
+            window.parent.postMessage({ id, type: "abort" }, host);
+            // The caller stopped the run — resolve `done` cleanly so it never hangs
+            // (an abort is not a failure). The host tears down the SSE.
+            settleDone();
+        },
+    };
+}
+function agentRunStandalone(payload, onText) {
+    const controller = new AbortController();
+    const done = (async () => {
+        const { app_id } = await boot();
+        const headers = { "content-type": "application/json" };
+        if (sessionToken)
+            headers["authorization"] = `Bearer ${sessionToken}`;
+        const res = await fetch(`${API_BASE}/v1/apps/${app_id}/agents/${encodeURIComponent(payload.alias)}/runs`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ session_id: payload.session_id, input: payload.input }),
+            signal: controller.signal,
+        });
+        if (!res.ok || !res.body) {
+            const text = await res.text().catch(() => "");
+            throw new Error(text || `HTTP ${res.status}`);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        try {
+            for (;;) {
+                const { value, done: streamDone } = await reader.read();
+                if (streamDone)
+                    break;
+                onText(decoder.decode(value, { stream: true }));
+            }
+            const tail = decoder.decode(); // flush any bytes held across the final read
+            if (tail)
+                onText(tail);
+        }
+        catch (err) {
+            if (controller.signal.aborted)
+                return; // the caller stopped the run — clean, not an error
+            throw err;
+        }
+    })();
+    return { done, abort: () => controller.abort() };
+}
 // ── Standalone transport ────────────────────────────────────────────────────
 // Standalone apps run only at `<slug>.lotics.app` (production); dev apps are
 // always bridged by the `lotics app dev` wrapper.
@@ -213,8 +301,12 @@ function rpcStandalone(op, payload) {
     switch (op) {
         case "query":
             return standaloneQuery(payload);
+        case "field_options":
+            return standaloneFieldOptions(payload);
         case "workflow":
             return standaloneWorkflow(payload);
+        case "agentRuns":
+            return standaloneAgentRuns(payload);
         case "upload":
             return standaloneUpload(payload.file);
         case "members":
@@ -289,10 +381,27 @@ async function standaloneQuery(p) {
     const r = (await apiCall("POST", `/v1/apps/${app_id}/query`, { alias: p.alias, params: p.params, limit: p.limit, offset: p.offset }, { appId: app_id }));
     return { rows: r.rows ?? [] };
 }
+async function standaloneFieldOptions(p) {
+    const { app_id } = await boot();
+    const r = (await apiCall("POST", `/v1/apps/${app_id}/field-options`, { alias: p.alias }, { appId: app_id }));
+    return { fields: r.fields ?? {} };
+}
 async function standaloneWorkflow(p) {
     const { app_id } = await boot();
     return apiCall("POST", `/v1/apps/${app_id}/workflows/${encodeURIComponent(p.alias)}/execute`, { inputs: p.inputs }, { appId: app_id });
 }
+async function standaloneAgentRuns(p) {
+    const { app_id } = await boot();
+    const qs = new URLSearchParams({ session_id: p.session_id });
+    if (p.limit != null)
+        qs.set("limit", String(p.limit));
+    if (p.offset != null)
+        qs.set("offset", String(p.offset));
+    const r = (await apiCall("GET", `/v1/apps/${app_id}/agent-runs?${qs.toString()}`, undefined, {
+        appId: app_id,
+    }));
+    return { runs: r.runs ?? [] };
+}
 async function standaloneUpload(file) {
     if (!(file instanceof File)) {
         throw new Error("upload payload must include a File");

package/dist/src/select.d.ts

@@ -14,6 +14,14 @@ export interface ResolvedOption {
     /** Option display name. Falls back to the key when the option was deleted
      *  after the cell was written — surfaces the stale state explicitly. */
     label: string;
+    /**
+     * Named palette color token (e.g. `"blue"`, `"emerald"`). Populated by
+     * `useFieldOptions` (which reads the field config); absent on options read
+     * back from a query CELL via `readSelect` — a cell carries only key + label.
+     * Pass the resolved option straight to `@lotics/ui`'s `OptionBadge`, which
+     * degrades a missing/unknown token to a neutral badge.
+     */
+    color?: string;
 }
 /**
  * Parse a `useQuery` cell value into `ResolvedOption[]`. Returns `[]` for

package/dist/src/types.d.ts

@@ -68,3 +68,28 @@ export interface AppWorkflowResults {
  */
 export interface AppQueries {
 }
+/**
+ * App-specific AGENT augmentation point — same pattern as `AppWorkflows`, for
+ * the streaming agents declared in `package.json` lotics.agents and invoked via
+ * `useAgentRun(alias)`. Per-app codegen maps each alias to its declared input
+ * shape, so an undeclared alias is a compile-time error and the run input is
+ * typed:
+ *
+ * ```ts
+ * declare module "@lotics/app-sdk" {
+ *   interface AppAgents {
+ *     "recognize": { image_file_id: string };
+ *     "edit": { current: Record<string, unknown>; prompt: string };
+ *   }
+ * }
+ * ```
+ */
+export interface AppAgents {
+}
+/**
+ * App-specific agent-RESULT augmentation point — maps each agent alias to the
+ * type of its declared `outputs` (the structured result the run emits). Absent
+ * ⇒ `run.output` is `unknown`. Same pattern as `AppWorkflowResults`.
+ */
+export interface AppAgentResults {
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -9,7 +9,7 @@
   "types": "./dist/src/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsgo",