@lotics/app-sdk 0.58.4 → 0.59.0

package/AGENTS.md

@@ -21,7 +21,7 @@ signature; open the file.**
 | [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/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. |
+| [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/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/dist/src/analytics.js

@@ -4,11 +4,13 @@
  * Apps are a separate cross-origin bundle at `<slug>.lotics.app`, invisible to
  * the product's PostHog — so `mount()` boots a PostHog instance per app.
  *
- * **Why explicit events, not autocapture:** the Lotics PostHog project runs
- * with autocapture OFF (the product captures explicit events, not DOM
- * autocapture), and that project setting overrides any client `autocapture`
- * flag — so apps can't rely on autocapture. The SDK instead emits explicit
- * events for genuine user actions only: `app_opened`, `app_file_uploaded`, and
+ * **Why explicit events, not autocapture:** DOM autocapture ships `$el_text` —
+ * the visible text of whatever was clicked, i.e. the customer's own record
+ * values — and Điều 3.2 of the service contract warrants that our telemetry
+ * carries no record or document content. The flags below are what enforce
+ * that; the project-level setting is NOT a backstop, since it is server-side
+ * and fails open when the config fetch fails. The SDK emits explicit events
+ * for genuine user actions only: `app_opened`, `app_file_uploaded`, and
  * `app_comment_*`. System signals — data-read mechanics (a `useQuery` refetch)
  * and workflow/agent run outcomes — are not events: the backend already logs
  * and persists every run (`workflow_executions`, `app_agent_runs`), so a client
@@ -88,10 +90,11 @@ export async function bootstrapAnalytics() {
         // Pin the modern posthog-js init contract (the product uses the same).
         defaults: "2025-05-24",
         api_host: POSTHOG_HOST,
-        // Autocapture is disabled project-wide (the project setting overrides this
-        // flag), so app analytics is explicit events — not DOM autocapture or
-        // pageviews.
+        // App analytics is explicit events — not DOM autocapture or pageviews.
+        // Set here rather than relied on project-wide: the server-side setting
+        // fails open, and an app screen renders the customer's own records.
         autocapture: false,
+        mask_all_text: true,
         capture_pageview: false,
         capture_pageleave: false,
         // Dead-click autocapture (enabled by the defaults preset) is a UX-research

package/docs/ai.md

@@ -20,7 +20,10 @@ A declaration carries:
 | Field | Meaning |
 |---|---|
 | `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. **This is the capability boundary** — 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) |
+| `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` |
+| `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 |
 | `effort_level` | Optional reasoning depth for adaptive-thinking models. Requires an explicit `model_id` pin — effort is tuned per model |
 | `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it |
@@ -30,6 +33,10 @@ A declaration carries:
 
 **Input validation and tenant bounds.** Run inputs get the same server-side enforcement as workflow inputs: `record_link` ids must live in the declared table, `member` ids in the declared group, `file` ids in the app's workspace (see [the caller boundary](./security.md)). The run executes under the **app owner's** authority in the app's own workspace.
 
+**Record data is reached only through declared aliases.** Every tool that reads or writes record VALUES by table id is rejected in `tool_names` — there is no `query_records`, `get_record`, `create_records`, or `update_records` for an agent. The agent reads with `run_app_query(alias, params)` and writes with `run_app_workflow(alias, inputs)`, both refused for any alias outside `query_aliases` / `workflow_aliases`. This is stricter than a list of tables: a query template fixes its own tables, joins, filters AND projection, so it bounds which **rows and columns** the agent sees; writes travel the app's declared mutation path, so workflow validation and table hooks apply. It matters because a run carries the OWNER's authority while any member can invoke it — raw table access would let a caller read or write, under that authority, anything the owner can. `is_current_member` inside a declared query resolves to the **invoking** member, so a self-scoped query scopes to the person using the agent, exactly as it does in the app's UI.
+
+So an agent that reads or writes records needs a named query or workflow for each thing it touches — the same declaration the app's own UI uses. Declare only what that agent needs; a second agent in the same app can declare a narrower set.
+
 **Typing.** `lotics app pull` / `lotics app codegen` emit `.lotics/app_agents.d.ts`, which augments the SDK's `AppAgents` (alias → input shape) and `AppAgentResults` (alias → declared output shape) interfaces — `useAgentRun("recognize")` then types both `run(input)` and `output`. An alias with no codegen falls back to `Record<string, unknown>` input / `unknown` output.
 
 ---

package/docs/queries.md

@@ -583,7 +583,7 @@ the table.
 
 ## 8. Shaping: group, buckets, window, fan-out
 
-### The 20 aggregate operations
+### The 21 aggregate operations
 
 `group` and `window` share one operation vocabulary. `count` is `COUNT(*)` (no `input_column`);
 everything else requires an `input_column` whose type must be compatible — checked at deploy:
@@ -599,10 +599,38 @@ everything else requires an `input_column` whose type must be compatible — che
 | `percent_filled`, `percent_empty` | any except boolean | number | **fraction 0–1**, not 0–100; NULL for an empty group |
 | `unique`, `percent_unique` | text, number, date/datetime, select, select_member, select_record_link, files, json¹ | number | distinct **present** values; array cells compare as whole arrays |
 | `checked`, `unchecked`, `percent_checked`, `percent_unchecked` | boolean | number | `unchecked` counts false **or** empty |
+| `string_agg` | text, select | **text** | the distinct present values joined — the only operation returning values rather than a count. `group` only |
 
 ¹ opaque `json` columns support only the presence-counting six (`empty`/`filled`/`unique` and
 their `percent_*` forms).
 
+**`string_agg` — a summary column, not a dataset.** Every other operation counts or reduces to a
+number; this one joins the values, so a child set answers "which ones?" in the parent row (the
+sizes on a shipment, the tags on a ticket) without a second query.
+
+```jsonc
+{ "output": "sizes", "type": "text", "operation": "string_agg", "input_column": "size",
+  "distinct": true, "separator": ", ", "max_values": 20 }
+```
+
+- **`type` must be `text`** — declaring anything else is rejected at deploy.
+- **`distinct`** defaults to **true**: three containers sized 40HC/40HC/20DC give `20DC, 40HC`.
+  Pass `false` to keep every occurrence. Values are always sorted, so the column doesn't
+  reshuffle between reads.
+- **`max_values`** (default 20, max 100) caps the emitted values so an unbounded child set can't
+  produce a giant cell. It is a silent cap — pair it with a `unique` aggregate over the same
+  column to render an honest `+N more`.
+- **`separator`** defaults to `", "` (max 8 chars).
+- Empty values are dropped by the same emptiness contract below, so a partly-blank column
+  doesn't emit empty slots. A group with nothing present yields NULL.
+- **`group` only** — it is not in the OVER-legal set, because deduplication and window frames
+  are mutually exclusive in SQL. Setting `distinct` / `separator` / `max_values` on any other
+  operation is rejected rather than ignored.
+
+It is deliberately **not** a rollup field type: a rollup persists its value into record data and
+rewrites it on every child change, and an unbounded concatenation does not belong in a stored
+cell. Query-time only.
+
 **The one emptiness contract.** `filled`/`empty`/`unique`/`percent_*` use the same definition
 of "present" as the filter layer's `is_empty` and the `isEmpty` source: array-valued cells are
 empty at NULL / JSON `null` / `[]`; text at NULL or blank (whitespace-only); opaque json at
@@ -643,8 +671,8 @@ A `window` node carries two independent column lists — **`aggregates`** (frame
 **`aggregates` — the OVER-legal aggregate subset.** Only operations that compile to a single
 legal SQL window call are accepted: **`count`, `sum`, `avg`, `min`, `max`, `earliest`, `latest`,
 `filled`, `checked`, `unchecked`.** The rest cannot take an OVER clause (`median` is an
-ordered-set aggregate; `unique`/`percent_unique` need DISTINCT; `range`/`empty`/`date_range`/
-`percent_*` compose multiple calls) — rejected at deploy. The optional `frame` applies **only**
+ordered-set aggregate; `unique`/`percent_unique`/`string_agg` need DISTINCT;
+`range`/`empty`/`date_range`/`percent_*` compose multiple calls) — rejected at deploy. The optional `frame` applies **only**
 to these; a `frame` on a window with no `aggregates` is rejected as dead config.
 
 **`functions` — ranking / navigation.** Each is `{ "output", "fn", … }` (its own arg shape, no

package/docs/security.md

@@ -30,7 +30,7 @@ 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 |
 
-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.
+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.
 

package/package.json

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