@lotics/app-sdk 0.59.4 → 0.60.1

package/dist/src/hooks.js

@@ -30,10 +30,20 @@ export function useWorkflow(alias) {
 // Shared SWR config: surface a failed query immediately, keep the last good
 // rows (no retry loop that masks the error), and honor the focus/reconnect
 // opt-out.
+//
+// `revalidateIfStale: false` — SWR defaults this to `true`, and its initial
+// -revalidation decision is `isUndefined(data) || revalidateIfStale`, so every
+// re-mount of a screen that already had rows re-queried the backend. An app
+// that navigates between screens (or re-opens a drawer) paid a full query set
+// each time for data it was already showing. A cold mount still fetches
+// (`isUndefined(data)` short-circuits), focus/reconnect still refresh, and the
+// host's `refetchQueries` poke still forces a refresh after a chat turn mutates
+// records — so freshness keeps every path it had except "re-mounted".
 function swrConfig(revalidateOnFocus) {
     return {
         revalidateOnFocus,
         revalidateOnReconnect: revalidateOnFocus,
+        revalidateIfStale: false,
         shouldRetryOnError: false,
     };
 }

package/docs/ai.md

@@ -306,18 +306,60 @@ Declarative and lifecycle-bound: mounting or changing `context` pushes it; unmou
 | `slot` | ≤ 50 chars |
 | `description` | ≤ 1000 chars (truncated with `…`) |
 | `records` | ≤ 20 refs |
-| `data` | must JSON-serialize to ≤ 2000 chars, else the `data` field is **dropped** (the description is kept) |
+| `data` | must JSON-serialize to ≤ 2000 chars, else it is **replaced by an `omitted` marker** the agent reads (the description is kept) |
 | slots per app | ≤ 8 (a 9th evicts the least-recently-updated) |
 
-Keep `description` tight and human-readable — it is the line the agent reads. Put anything structured (filter/sort/form values) in `data`, and remember it is dropped whole past its size cap, so don't hide load-bearing facts there that aren't also in `description`.
+Keep `description` tight and human-readable — it is the line the agent reads. Put anything structured (filter/sort/form values) in `data`, and remember it is replaced whole past its size cap: the agent is told the state existed but not what it was, so don't hide load-bearing facts there that aren't also in `description`. It is replaced rather than silently dropped so the agent cannot mistake "too big to send" for "there was nothing".
 
 ### Security — push-only, a snapshot of what was already rendered
 
-This is a **one-way push of data the app already showed this member** — never a channel for chat to pull app-authority data back out. Two consequences hold it to that:
+This hook is a **one-way push of data the app already showed this member**. (Chat can also PULL, through the app's declared aliases — a separate channel with its own `app:use` gate, below.) Two consequences hold the push to what was rendered:
 
 - **`records` are raw `{ table_id, record_id }` refs, passed UNRESOLVED.** The app does not resolve them here; the member's own chat agent may read or act on them only where **that member's IAM already allows**. A ref to a record the member can't see stays inert.
 - **`description` and `data` enter the agent's prompt as clearly-labeled DATA, never as instructions.** Text an app renders can't hijack the agent — the host wraps it as app-supplied view state (see [security](./security.md) for the labeled-data convention).
 
+### The chat can also USE the app, not just be told about it
+
+`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.
+
+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
+`run_app_workflow`. This adds no exposure: every declared alias is already
+callable by that member against `POST /v1/apps/{id}/query` and
+`POST /v1/apps/{id}/workflows/{alias}/execute`, so the manifest already IS
+their reachable surface — the agent simply reaches it without devtools. It is
+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).
+
+**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.
+
+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
+does not belong in the manifest at all, since the member can already fire it
+from the app's own buttons.
+
+**What this means for what you push.** Keep `description` — the one line that
+says who is on screen and where they stand, which is what makes "this one"
+resolvable. Don't pack bulk rows into `data` to pre-answer questions that may
+never be asked: the agent can fetch them when needed, fresher than a snapshot,
+and a payload pushed on every message is carried by every later turn (see the
+caps above).
+
 ### Query freshness — the mutation companion
 
 When the ambient chat agent's turn ends and it mutated records, the host pushes every mounted query hook to re-read, so the screen the member is looking at reflects the agent's change without a manual refresh. That companion behavior is automatic — you write no code for it — and is documented with the query caching contract in [data_fetching](./data_fetching.md#caching-loading-states-and-errors).

package/docs/data_fetching.md

@@ -68,8 +68,13 @@ server validates system conditions by `type` and never reads `field_key` on them
   the paged hooks). Object *contents* are hashed, not references — passing a fresh inline
   `{ status: "open" }` each render is the same key; you never need to memoize params.
 - The cache **survives unmount/remount**: returning to a screen renders the cached rows instantly
-  and revalidates in the background (stale-while-revalidate). Identical concurrent reads dedupe to
-  one request.
+  and **sends no request**. Identical concurrent reads dedupe to one request.
+- **A re-mount is not a refresh event.** Freshness comes from window focus / tab return / network
+  reconnect (`revalidateOnFocus`, default on), the host's post-chat-turn refetch poke, and explicit
+  `refetch()`. Re-mounting a screen you already loaded is none of those, so it re-uses the cache.
+  A **cold** key (never loaded, or a new `(alias, params, pageSize, sort, filter)` tuple) always
+  fetches — this only affects keys that already hold rows.
+  After a write the user is watching for, call `refetch()`; never rely on navigation to refresh.
 - **`loading`** is `true` only on the *initial* load of a key — a request is in flight and there
   are no rows yet. It stays `false` during background revalidation of a key that already has rows,
   so consumers never blank loaded data to a spinner on refetch. A key *change* (new params, sort,

package/docs/queries.md

@@ -120,6 +120,15 @@ Delivery-layer enrichment (applied to the response, per request):
   only for authenticated members of the app's own org).
 - **`select` cells** — bare option-key arrays become `{ key, label }[]` (colors ride in
   `useFieldOptions`, not the cell — see [members_and_options.md](./members_and_options.md)).
+  **Enrichment needs the column's source addressing**, which a passthrough projection carries, a
+  union carries when its arms agree (or per-row, when the compiler emits it), and a **link
+  extraction** carries as of the target field it reads. The one shape that has none is a select
+  reached through a **lookup FIELD**: the column addresses the lookup, whose own type is `lookup`,
+  not `select` — so the cell stays bare `opt_*` keys AND `useFieldOptions` omits the column
+  entirely, and reading `.label` off it renders the option KEY. Carry the keys out
+  (`readSelect(cell).map((o) => o.key)`) and resolve them against an alias that projects the
+  underlying field DIRECTLY — `useFieldOptions` takes no params, so any alias whose schema
+  contains it works.
 - **`number` columns** arrive as JS numbers (Postgres `numeric` strings are coerced; a
   high-precision decimal that would lose digits stays a string). **`date`/`datetime`** columns
   arrive as canonical wall-clock strings (`YYYY-MM-DD` / `YYYY-MM-DDTHH:mm`).
@@ -350,6 +359,12 @@ target table can silently re-point (or break) the extraction — prefer field **
 target's names are volatile. Each extraction is a correlated subquery evaluated per output
 row — cheap on a filtered detail read, expensive over thousands of rows.
 
+An extracted column **is** addressed to the field it reads on the target table, so the delivery
+layer treats it like any other field-backed column: an extracted `select` enriches to
+`{key,label}` and appears in `useFieldOptions`, and an extracted date resolves relative-date
+filters in the source field's timezone. It is still never **writable** — a correlated subquery is
+not a write path, and `writable_target` rejects it.
+
 ### The expression escape hatch
 
 `{ "expression": "…" }` compiles a small jexpr subset to SQL. Column references are

package/package.json

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