@lotics/app-sdk 0.60.1 → 0.61.0

package/AGENTS.md

@@ -17,12 +17,12 @@ signature; open the file.**
 | [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
 | [docs/data_fetching.md](./docs/data_fetching.md) | The three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, data discipline, the search-as-you-type + record-picker patterns. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, diff-before-update, locked records, `useOptimistic`, read-after-write ordering (a re-read must not overtake an in-flight write). |
-| [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + link descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the `lotics app workflow check` loop. |
-| [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs, workflow-generated files, preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
+| [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + link descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
+| [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
 | [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). **A `file` input carries its own content** — images/PDFs are perceived natively, Word/Excel/CSV/text are materialized into the run; no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`** (`run_app_query` / `run_app_workflow`); the raw record read/write tools are rejected. |
-| [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen. |
+| [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |
 | [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), `getAppBinding` (package apps' runtime `F`/`OPT`/`ROLE` resolution via the generated `.lotics/app_fields.ts`), and the publish chain for package contributors. |
 
 ## Non-negotiables (each detailed in its doc)

package/dist/src/rpc.d.ts

@@ -170,6 +170,8 @@ export declare function rpcAgentRunContinue(payload: AgentRunContinuePayload, on
  * `APP_PUBLIC_SESSION_HEADER`; both sides are pinned by tests.
  */
 export declare const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
+/** The run token header — mirrored server-side by `APP_AGENT_RUN_TOKEN_HEADER`. */
+export declare const APP_AGENT_RUN_TOKEN_HEADER = "x-app-agent-run-token";
 /**
  * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
  * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any

package/dist/src/rpc.js

@@ -250,6 +250,11 @@ export function rpcAgentRunContinue(payload, onText) {
         const headers = { "content-type": "application/json" };
         if (sessionToken)
             headers[APP_PUBLIC_SESSION_HEADER] = sessionToken;
+        // Continuing an anonymous parked run is authorized by the same per-run
+        // capability that reads it — there is no member to authorize instead.
+        const continueToken = runTokens.get(payload.run_id);
+        if (continueToken)
+            headers[APP_AGENT_RUN_TOKEN_HEADER] = continueToken;
         const res = await fetch(`${API_BASE}/v1/apps/${app_id}/agent-runs/${encodeURIComponent(payload.run_id)}/continue`, {
             method: "POST",
             headers,
@@ -297,8 +302,12 @@ function agentRunStandalone(payload, onText, onRunId) {
             throw await streamStartError(res);
         }
         const runId = res.headers.get("x-app-agent-run-id");
-        if (runId)
+        if (runId) {
+            // Anonymous runs carry their retrieval capability here; a member run does
+            // not, and `rememberRunToken` no-ops on the null.
+            rememberRunToken(runId, res.headers.get(APP_AGENT_RUN_TOKEN_HEADER));
             onRunId?.(runId);
+        }
         const reader = res.body.getReader();
         const decoder = new TextDecoder();
         try {
@@ -343,6 +352,40 @@ let sessionToken = null;
  * `APP_PUBLIC_SESSION_HEADER`; both sides are pinned by tests.
  */
 export const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
+/**
+ * Per-run retrieval credentials for ANONYMOUS agent runs, keyed by run id.
+ *
+ * A member's run is authorized by their identity, so reading it back needs
+ * nothing extra. An anonymous run on a publicly-shared app has no member to key
+ * on (`triggered_by_member_id` is null by design), so the server mints a
+ * capability token bound to that one run and returns it on the run response.
+ * Without it the recovery poll 404s and a completed answer is lost to any
+ * dropped connection — routine on mobile for a run measured in tens of seconds.
+ *
+ * Transport-level, like `sessionToken` above and for the same reason: it is a
+ * credential, not app state. Threading it through the hook would put a bearer
+ * into the app's typed surface for every app to forward by hand.
+ *
+ * Only the STANDALONE transport needs this — an embedded app always runs under
+ * a member session, so it never produces an anonymous run.
+ */
+const runTokens = new Map();
+/** Bound the map so a long-lived page cannot accumulate tokens without limit.
+ *  Insertion-ordered, so the oldest entry is the first key. */
+const MAX_TRACKED_RUN_TOKENS = 8;
+function rememberRunToken(runId, token) {
+    if (!token)
+        return;
+    runTokens.set(runId, token);
+    while (runTokens.size > MAX_TRACKED_RUN_TOKENS) {
+        const oldest = runTokens.keys().next();
+        if (oldest.done)
+            break;
+        runTokens.delete(oldest.value);
+    }
+}
+/** The run token header — mirrored server-side by `APP_AGENT_RUN_TOKEN_HEADER`. */
+export const APP_AGENT_RUN_TOKEN_HEADER = "x-app-agent-run-token";
 /**
  * The cookie the app-host Worker sets after the visitor clears the password
  * gate. Readable by design — the SDK forwards its value as the session header
@@ -473,6 +516,11 @@ async function apiCall(method, path, body, opts) {
     if (sessionToken && !opts?.skipAuth) {
         headers[APP_PUBLIC_SESSION_HEADER] = sessionToken;
     }
+    // The per-run capability for an ANONYMOUS run — the only thing that authorizes
+    // reading or cancelling it, since there is no member identity to check.
+    if (opts?.runToken) {
+        headers[APP_AGENT_RUN_TOKEN_HEADER] = opts.runToken;
+    }
     const controller = new AbortController();
     let didTimeout = false;
     const timeoutId = setTimeout(() => {
@@ -716,6 +764,7 @@ async function standaloneAgentRunGet(p) {
     const { app_id } = await boot();
     const r = (await apiCall("GET", `/v1/apps/${app_id}/agent-runs/${encodeURIComponent(p.run_id)}`, undefined, {
         appId: app_id,
+        runToken: runTokens.get(p.run_id),
     }));
     return { run: r.run };
 }
@@ -725,6 +774,7 @@ async function standaloneAgentRunCancel(p) {
     const { app_id } = await boot();
     await apiCall("POST", `/v1/apps/${app_id}/agent-runs/${encodeURIComponent(p.run_id)}/cancel`, {}, {
         appId: app_id,
+        runToken: runTokens.get(p.run_id),
     });
     return { ok: true };
 }

package/docs/ai.md

@@ -21,7 +21,7 @@ A declaration carries:
 |---|---|
 | `instructions` | System instructions — the task the agent performs per run |
 | `tool_names` | The tools the agent may call, resolved against the platform's automation tool registry. The capability boundary for everything EXCEPT workspace data — the run can use nothing else. May be empty — including for an agent that reads documents, since a [`file` input carries its own content](#file-inputs--what-the-agent-can-actually-see) |
-| `knowledge_doc_ids` | The knowledge docs the agent may read. Small docs are materialized into the run's system context; a doc too large to inline is read by staging it into a code run, which requires `code_exec` in `tool_names` |
+| `knowledge_doc_ids` | The knowledge docs the agent may read, and the whole set it can reach — a doc absent from this list is unreadable even if the agent names its id. Declare `grep_knowledge` / `read_knowledge` in `tool_names` to read them. There is no size limit and nothing is inlined, so a multi-megabyte reference corpus (a full tariff, a regulation set) is a normal declaration. Reach for `code_exec` only to COMPUTE across the corpus — counting, cross-referencing — never merely to read it |
 | `query_aliases` | The app's own named queries the agent may run via `run_app_query` — its **entire read surface** over records |
 | `workflow_aliases` | The app's own workflows the agent may invoke via `run_app_workflow` — its **entire write surface** |
 | `model_id` | Optional chat model pin. Omit (preferred) to follow the platform default chat model, resolved at run time — the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
@@ -184,6 +184,8 @@ The run's lifetime is decoupled from the stream: the server drives it to complet
 
 Both truncation shapes emit the `app_agent_stream_truncated` analytics event (`kind: "connection_error" | "clean_end"`, with whether the row rescued the result), so edge-cut frequency is visible fleet-wide.
 
+**Anonymous runs poll with a capability token, handled for you.** On a publicly-shared app a visitor has no member identity, so the server cannot authorize their poll by ownership — `triggered_by_member_id` is null by design. Instead the run response carries a per-run token (`x-app-agent-run-token`); the SDK stores it against that run id and replays it on the poll, on `cancel`, and on `answerChoice`. It is transport-level, like the password-session token — never surfaced to app code, and never issued for a member run (identity already authorizes those). Nothing to wire: an app calls `useAgentRun` the same way on both. The token is bound to ONE run, so it cannot read another visitor's, and it is why a dropped connection on a public app recovers rather than losing the answer.
+
 The poll is bounded at 22 minutes — deliberately PAST the server's 20-minute hard run cap, so a live run always settles before the client gives up. A row still `running` at the deadline means the run's process died mid-flight (e.g. a crash that skipped the server's shutdown drain); the poll surfaces an error and the server's reaper repairs the row. Only when no run id was ever received (the run never started) does the failure reject before any polling.
 
 On recovery, `output` adopts the row's output **only when it is an object** (a structured result) — the "`output` is never a stray string" rule holds on every path. A **free-text** run recovered from truncation keeps only the streamed prefix in `text`; the full settled answer is persisted server-side but is not currently client-readable (`useAgentRuns` can't reach it on any transport — see the limitation below), so treat the streamed prefix as terminal for now.

package/docs/files.md

@@ -210,8 +210,11 @@ file. It is pure and never throws.
 - **Thumbnails are optimistic.** `thumbnail_url` is emitted for every image without checking that
   the variant exists; a not-yet-generated variant 404s on fetch. `@lotics/ui`'s `FileThumbnail`
   falls back to `url` on image error — a hand-rolled `<img src={thumbnail_url}>` must do the same.
-- **Don't persist the URLs.** They expire in 24 h. Apps re-query on load, so the TTL refreshes
-  naturally; store `id`s, never `url`s.
+- **A presigned `url` is a bearer credential for the bytes.** It carries its own authorization —
+  anyone holding it fetches the file for 24 h with no session — so it must never leave the render
+  path: not into a log line, not into telemetry, not into an error report or a bug ticket. Don't
+  persist it either; apps re-query on load, so the TTL refreshes naturally. Store `id`s, never
+  `url`s.
 - **Warning:** SVG, HTML, and XHTML files are presigned with a forced-download disposition — their
   `url` downloads instead of rendering inline (stored-XSS defense). An SVG in an `<img>` will not
   display; treat these types as download-only.
@@ -278,6 +281,30 @@ if (result.status === "success" && result.files?.length) {
 - For bytes the app builds *in the browser* (a client-side .xlsx/CSV export), the counterpart is
   `downloadFile(filename, data, mimeType?)` — see [runtime](./runtime.md).
 
+### Naming what goes into a zip
+
+A workflow that bundles files (`zip_files`) names each entry itself: an item in `file_ids` is a
+file id, **or** `{ id, name }`. An entry given no name keeps whatever the uploader called the file
+(`IMG_4821.jpg`, `scan (3).pdf`) — which is exactly what the recipient opens — so pass the name the
+app already knows (document type, record key, sequence). Renaming the stored file first is not
+required, and would change what the record shows everyone else.
+
+```js
+// in a workflow body — the two forms mix freely
+const bundle = await zip_files({
+  file_ids: [{ id: inputs.signed_doc, name: "Bản ký" }, inputs.appendix],
+  filename: "ho-so",
+});
+```
+
+An entry name is a **file name, not a path**. Separators are folded away, so a document number
+survives readably (`Số 123/QĐ-BXD` arrives as `Số 123-QĐ-BXD`); a name without an extension is given
+the stored file's; two files handed the same name are suffixed `_2`, `_3`. A name that cannot be
+read as one fails the run rather than being quietly rewritten — a control character, a non-string,
+over 200 characters, punctuation alone, or the empty string a name expression yields when it found
+nothing. `null` is the one absence that is not an error (an empty record field reads as `null`): it
+means "no name", and that entry keeps the stored filename.
+
 ## Previewing — wiring to `@lotics/ui`
 
 Render any file inline — image, PDF, video, audio, Word, Excel, CSV — with `@lotics/ui`. Never

package/docs/runtime.md

@@ -288,6 +288,17 @@ It is the client-side counterpart to the server path (workflow generates a file
   the browser attributes the download to the user gesture. Build the bytes in
   the handler, then call `downloadFile` — an `await` between the click and the
   call can void the gesture and get the download blocked.
+- **One gesture buys one download.** Browsers block — or prompt over — repeated
+  programmatic downloads from a single interaction, so a loop calling
+  `downloadFile` once per file delivers the first and silently loses the rest.
+  Several files leave as **one archive**: build the bundle, hand it over in a
+  single call.
+- **Guard a URL before fetching bytes you did not build.** `fetch("")` — an
+  empty or relative string where a file URL was expected — resolves against the
+  app's own page and returns **200** with the app's HTML, which then saves under
+  the filename you intended: a plausible-looking file with the wrong contents
+  and no error anywhere. Require the URL to be present and absolute, and treat a
+  missing one as a failure, never as an empty download.
 - `mimeType` defaults to `application/octet-stream`. The blob URL is revoked on
   the next task, after the download has started.
 

package/docs/security.md

@@ -30,13 +30,21 @@ Callers never submit query ASTs or workflow definitions — the server holds the
 | `record_link` | Every submitted record id must live in the declared table |
 | `file` | Every submitted file id must live in the app's workspace — a foreign tenant's `file_id` is rejected |
 
+**Each of those bounds is a tenancy floor, not an authorization check.** It proves the value
+belongs to the app's own workspace (or to a declared group or table) — never that *this caller*
+should reach *that* row, file, or member. A `file` input is floored to the **workspace**, so a
+caller may substitute the id of any file in it, including one attached to a record they have
+never opened; a `record_link` id is floored to its declared **table**, not to the records the
+caller may see. Whenever a run acts on ids the caller supplied, intersect them server-side with
+what the target record actually holds before reading, bundling, or writing them.
+
 Workflows and agent runs additionally execute behind a **workspace tenant floor**: every table a run touches must live in the app's own workspace, so no input value can steer a run at another workspace's data even under an admin owner's authority. An **agent** run is bounded harder still: it reaches records only through the queries and workflows its declaration names (`query_aliases` / `workflow_aliases`), never a raw table — so the ceiling is what you declared for that agent, not what the owner can see. See [ai](./ai.md).
 
 What the platform does **not** constrain is the *meaning* of your params. A query param is a value hole in the template (a filter value, a search term); the server checks its type only — the group/table bindings above apply to workflow and agent-run inputs, **not** to query params — never whether the value should have been derived from the caller's identity. That's the next section.
 
 ### The devtools test
 
-Before shipping any query or workflow, ask: **could a member open the browser devtools, replay the app's RPC, and pass someone else's id?** Every declared alias is callable by every member with app access (and by *anyone*, if the app is public) with arbitrary typed values — the app's UI is not a boundary. If substituting another member's id (or another record's id) into a param would show that member's data or perform a write only they should trigger, the design has an IDOR. The fixes are always server-side:
+Before shipping any query or workflow, ask: **could a member open the browser devtools, replay the app's RPC, and pass someone else's id?** Every declared alias is callable by every member with app access (and by *anyone*, if the app is public) with arbitrary typed values — the app's UI is not a boundary. If substituting another member's id (or another record's or file's id) into a param would show that member's data or perform a write only they should trigger, the design has an IDOR. The fixes are always server-side:
 
 - Reads scoped to "the current member" → an `is_current_member` filter **in the query template**, never a client-supplied member-id param.
 - Writes attributed to the caller → `runtime.triggered_by_member_id` **in the workflow body**, never a client-supplied member input.

package/docs/workflows.md

@@ -50,6 +50,13 @@ leave `outputs` off to let the body's `return({ data })` derive it), write the b
 `check`, then `set`. Input declaration vocabulary and validation:
 [mutations](./mutations.md#declaring-workflow-inputs).
 
+**Adding an input to an alias that is already bound reverses that order.** `codegen` types a
+*registered* alias from the server's **bound** schema — the manifest declaration is only the
+fallback for an alias the server has never seen — so a newly-declared input is absent from the
+local globals and `check` rejects every read of it, however correct the body is. `set` pushes the
+manifest's `inputs` with the body and the server verifies against *those*, so the working order
+is `set` → `codegen` → `check`.
+
 An app workflow body carries **no trigger declaration** — the binding supplies the trigger
 context. A stray `on({ … })` line is rejected.
 
@@ -598,7 +605,9 @@ genuinely recursive.
 `lotics app workflow check [alias]` runs the server's **own** parse and type passes locally: the
 same subset parser, the same generated `.d.ts` and envelope, the same compiler options, one
 isolated program per alias. **Green means pushable and red means real** — do not push through a
-red check.
+red check. It is also the *only* local gate on a body: the app project's own `npm run typecheck`
+excludes `src/workflows` (bodies compile against the server's globals, not the app's DOM lib), so
+it never sees one — a fully green app typecheck says nothing about any workflow.
 
 Order matters. A subset rejection is reported *alone* and the compiler is skipped, because a body
 the parser refuses never reaches the type checker on the server anyway. Diagnostics carry
@@ -621,6 +630,22 @@ There is no separate verify endpoint: the loop is `set` → read the returned di
 round trip, not one per fix — and raw TypeScript shape errors are rewritten into field-naming,
 fix-stating messages before you see them.
 
+### Static green is not a run
+
+`check` and `set` prove parse, types, name resolution, and lint — **none of them evaluates an
+expression**. A body that saves clean can still take the wrong branch, hand a tool a filter it
+rejects, or read a path that is null on real data. The rehearsal for that is `dry_run_workflow`
+(`lotics run dry_run_workflow '<json>'`): pass the `source`, `trigger_type: "app_workflow"`,
+`table_id: null`, the input **values** as `trigger_payload`, and the declared schema as
+`app_workflow_inputs`. It walks the real step tree with the production expression evaluator and
+hands back `planned_calls` (every tool call in order, with its fully-resolved input),
+`return_value`, `validation_failures`, `evaluation_errors`, and `tool_input_errors` — inputs the
+target tool would reject, which can only surface once the values are computed. **Write tools are
+recorded, never dispatched**, and nothing is persisted. For a table-triggered body, pass
+`record_id` + `table_id` instead of `trigger_payload` and the read-only tools (`query_records`,
+`get_record`, `aggregate_records`) dispatch for real, so data-dependent gates are exercised
+against actual rows. Do this before the first live run of anything that writes.
+
 ## A worked body
 
 An app action that creates an order after checking for a duplicate, then returns the new id.

package/package.json

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