@lotics/app-sdk 0.58.4 → 0.58.5

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/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.58.5",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {