@lotics/app-sdk 0.77.0 → 0.77.2

package/AGENTS.md

@@ -22,7 +22,7 @@ signature; open the file.**
 | [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., a leg's `AgentRunLanding` (`settled`/`parked`/`failed`/`aborted` — never a bare `undefined`) |
+| [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. A leg resolves an `AgentRunLanding` (`settled`/`parked`/`failed`/`aborted` — never a bare `undefined`). Also **what the member's own chat agent can do with your app while it is open** — the alias catalog it reads (your app `description` heads it as `about:`, and an input's `description` is the only place a default is visible), and how to shape a mutating alias for it. |
 | [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. |
 

package/docs/ai.md

@@ -346,7 +346,7 @@ This hook is a **one-way push of data the app already showed this member**. (Cha
 
 `useAiContext` is a PUSH — a snapshot of what one screen rendered. It cannot
 answer a question about a record that is not on screen, and it is capped, so it
-was never the whole story.
+is not the whole story.
 
 While a member has an app open, their chat agent can also **call that app's own
 declared aliases** — named queries via `run_app_query`, workflows via
@@ -358,26 +358,62 @@ gated per turn on `app:use` for the app in the member's workspace, and runs
 under the app's OWNER authority with `is_current_member` bound to the MEMBER
 (exactly as the app's own UI does).
 
-The agent is handed a **catalog** of those aliases — each one's params and its
-`description` (a query's own, [declared in the manifest](./queries.md); a
-workflow's, off its workflow row) — so it picks the right one instead of
-guessing an alias and learning the list from a refusal. Your descriptions are
-what it reads, on this surface and inside your own agents' runs. They enter the
-prompt as a capability listing, never as instructions.
-
-**Writes carry a second gate that reads do not: `run_app_workflow` asks the
-member to approve every call from chat.** A wrong read is fixed by asking
-again; a wrong write is not. The alias list bounds what an agent *could* reach;
-the approval is what stops the wrong one. Approval applies to the chat surface
-only — an app agent's run is already an explicit act with no human in the loop
-to answer.
-
-The prompt names the action and lists the inputs the agent chose, so **your
-input names are what the member reads before authorizing the write**. Name them
-for that reader (`ma_khach_hang`, `so_tien`), and keep the decisive ones
-top-level — a value nested inside an opaque payload shows as JSON, and long
-values are truncated. Context ids the member never chose (`app_id`,
-`workspace_id`, `organization_id`) are filtered out.
+The agent is handed a **catalog** of those aliases — each one's `description`
+(a query's own, [declared in the manifest](./queries.md); a workflow's, off its
+workflow row) and its **complete input contract** — so it picks the right one
+and calls it correctly instead of guessing and learning from a refusal. Every
+alias you declare appears, however large the manifest, and every input appears
+with it:
+
+```
+workflows (run_app_workflow):
+- updateOrder(reference?: text, shipped_on?: date, owner?: member,
+    status?: select(In progress=opt_a1b2c3|Complete=opt_d4e5f6),
+    attachments?: file[], customer_id?: record_link(Customers)) — …
+```
+
+`?` marks an input the caller may omit, `[]` one that takes a list, a
+`select` spells out every legal value as `label=value` — **the agent sends the
+value** — and a `record_link` names the table an id must come from. This is the
+only place any of it is legible: both tools take an opaque
+inputs object, and a select's legal values are your DECLARATION's — usually an
+inline set that matches no table field — so an agent reading option values off
+the underlying table would send ones your write rejects.
+
+The app's own `description` heads that listing as `about:`, on both surfaces. It
+is the only channel that reaches the agent on **every** turn without the member
+saying anything, so a standing process belongs there: the recurring job the app
+exists for, which alias does it, and what the agent must leave alone.
+
+Three things follow for you as an author. **Your descriptions are what it
+reads**, on this surface and inside your own agents' runs — they enter the
+prompt as a capability listing, never as instructions. **A `select` input's
+options are part of the contract the agent sees**, so prefer the
+`field: "fld_…"` form when the values come from a real field: it resolves to
+that field's CURRENT options at both render and validation time. And **an
+input's `description` is the only place a DEFAULT is visible** — the catalog
+renders a name, a type, a `?` and your prose, never the body. An optional input
+whose default goes unstated is one the agent asks the member about instead of
+omitting; write what omitting it means ("left blank = today").
+
+**Put anything irreversible behind a
+[`wait_for_approval`](./workflows.md#wait_for_approval--the-one-wait-worth-binding):**
+an email, a shipment, a published post, a write over a value with no version to
+restore. The body's own gate is the only human checkpoint on this path — it
+names the act in the language of the business and reaches the approvers the
+workflow declares.
+
+**Shape a mutating alias around ONE call per job.** An alias that takes a single
+record turns a fifteen-record job into fifteen executions and no single answer to
+report, and a partial failure leaves it half done with nothing that says so. Take
+an array input instead — one call, one outcome. A narrow write is right for a
+screen's button, where the member picked the record by opening it; here nobody
+picked anything.
+
+**Report what it did NOT do.** The member's account of the write is assembled
+from what the workflow returned and nothing else, so a batch that matched nine of
+eleven and returns only success tells them all eleven were done. Return the
+misses in `data`.
 
 Nothing about your app changes to get this — declare a workflow as you already
 do, and it becomes reachable. If a workflow should NOT be agent-reachable, it

package/docs/workflows.md

@@ -540,6 +540,30 @@ the **diff**: `changes["fld_link"]?.next_value` / `?.prev_value` are plain id ar
 has nowhere to attach a fetch, so it cannot descend either), and they feed `set:` directly.
 Everywhere else, write `[x.id]`.
 
+### A write that will be re-run
+
+The tables above answer *what the caller sent*. A workflow an agent can reach
+needs the other axis too — **what the record already holds** — because the same
+call arrives twice: a recurring report a week later, a retry, one batch
+overlapping the last. On that second pass an unconditional `set` reports success
+and silently replaces what was there.
+
+Decide per field, and expect the two directions of one operation to be
+**asymmetric**. A field recording *when* something happened is written only while
+it is still empty, while its undo clears unconditionally:
+
+```js
+if (i.undo) {
+  await update_records({ table_id: "tbl_x", record_ids: [row.id], set: { fld_submitted_on: null } });
+} else if (isNull(row["fld_submitted_on"])) {
+  await update_records({ table_id: "tbl_x", record_ids: [row.id], set: { fld_submitted_on: i.on } });
+}
+```
+
+There is no version to restore a cell from, so prove it before anyone can call
+it: `lotics app workflow run <alias>` the same input twice, and confirm the
+second run changed nothing.
+
 ### Authorizing the caller
 
 A workflow runs under the **app owner's** authority, so its own principal tells you nothing about

package/package.json

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