@lotics/app-sdk 0.51.3 → 0.52.0

package/AGENTS.md

@@ -20,7 +20,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. |
 | [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 `items` → `AgentRun`) and `askAi` — plus the fields-vs-file razor for choosing between them. |
+| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming `items` → `AgentRun`), `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). |
 | [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/hooks.d.ts

@@ -1,3 +1,4 @@
+import { type AiContextValue } from "./rpc.js";
 import { type AgentRunStep, type AgentRunItem } from "./agent_stream.js";
 import type { AppWorkflows, AppWorkflowResults, AppQueries, AppAgents, AppAgentResults } from "./types.js";
 import type { ResolvedMember } from "./members.js";
@@ -372,6 +373,41 @@ interface AttachmentsState {
  * ```
  */
 export declare function useAttachments(): AttachmentsState;
+/**
+ * Publish a slice of the CURRENT SCREEN's view state to the app's ambient chat
+ * agent, so a member chatting alongside the app gets an agent that knows what
+ * they are looking at — which list is filtered to what, which record is open,
+ * what is typed into a form. Declarative and lifecycle-bound: mounting or
+ * changing `context` pushes it to the host; unmounting, renaming the `slot`, or
+ * passing `null` clears it. Independent components may publish different `slot`s
+ * concurrently (a list screen + an open detail drawer); the newest value per
+ * slot wins.
+ *
+ * **Push-only, and a SNAPSHOT of what the app already RENDERED to this member** —
+ * never a channel for chat to pull app-authority data. `records` are passed as
+ * raw `{ table_id, record_id }` refs (unresolved); the member's own chat agent
+ * acts on them only where that member's IAM already allows. The host feeds
+ * `description`/`data` into the agent's prompt as clearly-labeled DATA, never as
+ * instructions.
+ *
+ * Host-enforced caps (exceeding them truncates/drops — never an error): `slot`
+ * ≤ 50 chars; `description` ≤ 1000 chars (truncated with "…"); `records` ≤ 20;
+ * `data` must JSON-serialize to ≤ 2000 chars or the `data` field is dropped (the
+ * description is kept); ≤ 8 slots per app (a 9th evicts the least-recently
+ * updated).
+ *
+ * ```tsx
+ * useAiContext("orders_list", {
+ *   description: `Viewing ${rows.length} orders filtered to status=open, sorted by due date.`,
+ *   records: rows.map((r) => ({ table_id: r.__source_table_id, record_id: r.__source_record_id })),
+ *   data: { filter: "status=open", sort: "due_date desc" },
+ * });
+ * ```
+ *
+ * No-ops with no embedding host (standalone `<slug>.lotics.app` — there is no
+ * chat surface to inform) and in mock mode. Since 0.52.
+ */
+export declare function useAiContext(slot: string, context: AiContextValue | null): void;
 interface MembersState {
     /** Members of the app's organization, for assign / member-picker UIs. */
     members: ResolvedMember[];

package/dist/src/hooks.js

@@ -18,9 +18,9 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
-import { rpc, rpcAgentRun } from "./rpc.js";
+import { rpc, rpcAgentRun, postHostNotification, subscribeHostRefetch, } from "./rpc.js";
 import { initialAgentRunState, reduceAgentChunk, parseSseChunks, } from "./agent_stream.js";
-import { getMockRows } from "./mock.js";
+import { getMockRows, hasMockFlag } from "./mock.js";
 import { captureAppEvent } from "./analytics.js";
 export function useWorkflow(alias) {
     return useCallback((inputs) => rpc("workflow", { alias, inputs: inputs ?? {} }), [alias]);
@@ -35,6 +35,19 @@ function swrConfig(revalidateOnFocus) {
         shouldRetryOnError: false,
     };
 }
+/**
+ * Re-run `refetch` when the host pushes `refetchQueries` — after an ambient
+ * app-chat agent turn mutated records, every mounted query hook refreshes the
+ * data it rendered. Inert in mock mode (no host, no listener) and for a mocked
+ * alias (its rows come from the fixture). Shared by all three query hooks.
+ */
+function useHostRefetch(refetch, mockRows) {
+    useEffect(() => {
+        if (hasMockFlag() || mockRows)
+            return;
+        return subscribeHostRefetch(refetch);
+    }, [refetch, mockRows]);
+}
 export function useQuery(alias, params, opts) {
     const pageSize = opts?.pageSize;
     const enabled = opts?.enabled ?? true;
@@ -59,6 +72,7 @@ export function useQuery(alias, params, opts) {
     const refetch = useCallback(() => {
         void swr.mutate();
     }, [swr]);
+    useHostRefetch(refetch, mockRows);
     return {
         rows: mockRows ?? swr.data?.rows ?? [],
         loading: mockRows ? false : swr.isLoading,
@@ -139,6 +153,7 @@ export function useInfiniteQuery(alias, params, opts) {
     const refetch = useCallback(() => {
         void swr.mutate();
     }, [swr]);
+    useHostRefetch(refetch, mockRows);
     const loadMore = useCallback(() => {
         if (!hasMore || loadingMore)
             return;
@@ -196,6 +211,7 @@ export function usePaginatedQuery(alias, params, opts) {
         void rowsSwr.mutate();
         void countSwr.mutate();
     }, [rowsSwr, countSwr]);
+    useHostRefetch(refetch, mockRows);
     return {
         rows,
         total,
@@ -302,6 +318,77 @@ export function useAttachments() {
     const fileIds = files.flatMap((f) => (f.status === "ready" && f.file_id ? [f.file_id] : []));
     return { files, add, remove, clear, uploading, fileIds };
 }
+/**
+ * JSON-serialize the view-state snapshot — used for BOTH change-detection (a
+ * fresh inline object each render must NOT re-post) and the wire payload. The
+ * `data` field is app-supplied `unknown`; if it can't be JSON-serialized we drop
+ * it and keep description + records, mirroring the host's own `data` cap (which
+ * JSON-encodes `data` and drops it past the size limit) — a non-serializable
+ * value must never crash the app's render.
+ */
+function serializeAiContext(context) {
+    try {
+        return JSON.stringify(context);
+    }
+    catch {
+        return JSON.stringify({ description: context.description, records: context.records });
+    }
+}
+/**
+ * Publish a slice of the CURRENT SCREEN's view state to the app's ambient chat
+ * agent, so a member chatting alongside the app gets an agent that knows what
+ * they are looking at — which list is filtered to what, which record is open,
+ * what is typed into a form. Declarative and lifecycle-bound: mounting or
+ * changing `context` pushes it to the host; unmounting, renaming the `slot`, or
+ * passing `null` clears it. Independent components may publish different `slot`s
+ * concurrently (a list screen + an open detail drawer); the newest value per
+ * slot wins.
+ *
+ * **Push-only, and a SNAPSHOT of what the app already RENDERED to this member** —
+ * never a channel for chat to pull app-authority data. `records` are passed as
+ * raw `{ table_id, record_id }` refs (unresolved); the member's own chat agent
+ * acts on them only where that member's IAM already allows. The host feeds
+ * `description`/`data` into the agent's prompt as clearly-labeled DATA, never as
+ * instructions.
+ *
+ * Host-enforced caps (exceeding them truncates/drops — never an error): `slot`
+ * ≤ 50 chars; `description` ≤ 1000 chars (truncated with "…"); `records` ≤ 20;
+ * `data` must JSON-serialize to ≤ 2000 chars or the `data` field is dropped (the
+ * description is kept); ≤ 8 slots per app (a 9th evicts the least-recently
+ * updated).
+ *
+ * ```tsx
+ * useAiContext("orders_list", {
+ *   description: `Viewing ${rows.length} orders filtered to status=open, sorted by due date.`,
+ *   records: rows.map((r) => ({ table_id: r.__source_table_id, record_id: r.__source_record_id })),
+ *   data: { filter: "status=open", sort: "due_date desc" },
+ * });
+ * ```
+ *
+ * No-ops with no embedding host (standalone `<slug>.lotics.app` — there is no
+ * chat surface to inform) and in mock mode. Since 0.52.
+ */
+export function useAiContext(slot, context) {
+    // Serialize once for both the change key and the payload. The effect re-posts
+    // only when the serialized value (or slot) actually changes, so a fresh inline
+    // object each render never spams the host. Payloads are small (host-capped),
+    // so the JSON round-trip is cheap.
+    const serialized = context === null ? null : serializeAiContext(context);
+    // Post the current value on mount and whenever it changes.
+    useEffect(() => {
+        if (hasMockFlag())
+            return;
+        const payload = serialized === null ? null : JSON.parse(serialized);
+        postHostNotification({ type: "aiContext", slot, context: payload });
+    }, [slot, serialized]);
+    // Clear the slot on unmount or slot rename ONLY — a value-only change is
+    // overwritten by the post above, with no intermediate clear.
+    useEffect(() => {
+        if (hasMockFlag())
+            return;
+        return () => postHostNotification({ type: "aiContext", slot, context: null });
+    }, [slot]);
+}
 /**
  * List the members of the app's organization — the candidate set for an
  * "assign to a member" picker. Each member is `{ id, name, email, image }`

package/dist/src/index.d.ts

@@ -16,7 +16,7 @@
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, } from "./hooks.js";
 export type { UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunRecord, AgentRunState, AgentRunStep, AgentRunItem, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
@@ -26,7 +26,7 @@ export type { AppConfigValue } from "./rpc.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "./geolocation.js";
 export { rpc, isEmbedded, getAppBinding } from "./rpc.js";
-export type { RpcOp, AppBinding } from "./rpc.js";
+export type { RpcOp, AppBinding, AiContextValue, AiContextRecordRef } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { askAi, type AskAiArgs } from "./ask_ai.js";
 export { downloadFile } from "./download.js";

package/dist/src/index.js

@@ -15,7 +15,7 @@
  * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export { useViewer } from "./viewer.js";
 export { useConfig } from "./config.js";

package/dist/src/rpc.d.ts

@@ -54,6 +54,37 @@ export interface AgentRunHandle {
  * mirror, like `AppContext` itself).
  */
 export type AppConfigValue = string | number | boolean;
+/** A raw reference to one record — table + record id, passed through UNRESOLVED.
+ *  The member's own chat agent may act on it only where that member's IAM already
+ *  allows; the app never resolves it into data here. */
+export interface AiContextRecordRef {
+    table_id: string;
+    record_id: string;
+}
+/**
+ * A snapshot of what the app RENDERED to this member on the current screen —
+ * published to the ambient app chat agent via `useAiContext` so the member's
+ * agent knows what they are looking at. Push-only: this is data the app already
+ * showed, never a channel for chat to pull app-authority data back out.
+ */
+export interface AiContextValue {
+    /** Human-readable summary of the view — enters the agent prompt as labeled
+     *  DATA (never instructions). Host-capped to 1000 chars. */
+    description: string;
+    /** Records the screen is showing, as raw `{ table_id, record_id }` refs
+     *  (unresolved). Host-capped to 20. */
+    records?: AiContextRecordRef[];
+    /** Optional structured detail (filters, sort, form values). Host JSON-encodes
+     *  it and DROPS the field past its size cap, keeping the description. */
+    data?: unknown;
+}
+/** A fire-and-forget notification the app pushes UP to its embedding host — no
+ *  id, no reply, distinct from the request/reply `rpc()` bridge. */
+export type HostNotification = {
+    type: "aiContext";
+    slot: string;
+    context: AiContextValue | null;
+};
 export interface AppContext {
     app_id: string;
     app_name: string;
@@ -95,6 +126,20 @@ export declare function peekUrlParams(): UrlParams;
 /** Subscribe to external query changes — browser back/forward and edited URLs.
  *  Embedded: the host's `url-state` broadcast; standalone: `popstate`. */
 export declare function subscribeUrlParams(cb: (params: UrlParams) => void): () => void;
+/**
+ * Push a fire-and-forget notification to the embedding host — no id, no reply.
+ * Only the embedded host can receive it (it owns the chat surface), so this
+ * no-ops standalone (`<slug>.lotics.app` has no host to inform) and never
+ * throws. Distinct from `rpc()`: this is one-way, app → host.
+ */
+export declare function postHostNotification(message: HostNotification): void;
+/**
+ * Subscribe to the host's `refetchQueries` push. Returns an unsubscribe fn.
+ * Wired by every mounted query hook so an ambient-chat record mutation refreshes
+ * exactly the data currently on screen. No host ever posts it standalone, so the
+ * subscription is inert there.
+ */
+export declare function subscribeHostRefetch(cb: () => void): () => void;
 /**
  * Start a streaming agent run. Each raw SSE text chunk is handed to `onText`
  * (the caller parses it via `agent_stream`); `done` settles when the stream

package/dist/src/rpc.js

@@ -78,11 +78,40 @@ export function subscribeUrlParams(cb) {
     window.addEventListener("popstate", handler);
     return () => window.removeEventListener("popstate", handler);
 }
+// ── Host notifications (app → host, fire-and-forget) ─────────────────────────
+/**
+ * Push a fire-and-forget notification to the embedding host — no id, no reply.
+ * Only the embedded host can receive it (it owns the chat surface), so this
+ * no-ops standalone (`<slug>.lotics.app` has no host to inform) and never
+ * throws. Distinct from `rpc()`: this is one-way, app → host.
+ */
+export function postHostNotification(message) {
+    const hostOrigin = getHostOrigin();
+    if (!hostOrigin)
+        return;
+    window.parent.postMessage(message, hostOrigin);
+}
+/**
+ * Subscribe to the host's `refetchQueries` push. Returns an unsubscribe fn.
+ * Wired by every mounted query hook so an ambient-chat record mutation refreshes
+ * exactly the data currently on screen. No host ever posts it standalone, so the
+ * subscription is inert there.
+ */
+export function subscribeHostRefetch(cb) {
+    ensureListener();
+    refetchSubscribers.add(cb);
+    return () => {
+        refetchSubscribers.delete(cb);
+    };
+}
 const pending = new Map();
 const streaming = new Map();
 /** `useUrlState` subscribers — notified when the host broadcasts new params
  *  after browser back/forward. */
 const urlStateSubscribers = new Set();
+/** Query hooks subscribed to the host's `refetchQueries` push — the host sends
+ *  it after an ambient app-chat agent turn mutated records. */
+const refetchSubscribers = new Set();
 let nextRpcId = 0;
 let listenerInstalled = false;
 function ensureListener() {
@@ -103,6 +132,15 @@ function ensureListener() {
                 cb(msg.params);
             return;
         }
+        // Broadcast (no id): the host tells the app its rendered data may be stale
+        // after an ambient app-chat agent turn mutated records — every mounted query
+        // hook re-reads through its own declared queries. Push-only freshness; the
+        // host never reads app data through this path.
+        if (msg.type === "refetchQueries") {
+            for (const cb of refetchSubscribers)
+                cb();
+            return;
+        }
         if (typeof msg.id !== "number")
             return;
         // Single-response ops.

package/docs/ai.md

@@ -1,6 +1,6 @@
 # AI in apps
 
-An app has two AI surfaces, and they answer different questions. **`useAgentRun(alias)`** runs an agent *declared on the app* — a streaming, tool-looping run whose result lands back **in the app** (a typed structured output, or free-text prose) for the app to review and commit through its own [workflows](./mutations.md). **`askAi(args)`** is a *handoff* — it opens the Lotics chat messenger seeded with files, records, and a prefilled prompt, and the outcome lands **in chat**, under the signed-in member's control. Read this doc when adding any AI-driven feature to an app; read [security](./security.md) first for the authority model agent runs execute under. Exact signatures: `dist/src/hooks.d.ts` (`useAgentRun`, `useAgentRuns`), `dist/src/agent_stream.d.ts` (`AgentRunItem`, `AgentRunStep`, `AgentRunState`), `dist/src/ask_ai.d.ts` (`AskAiArgs`).
+An app has two AI surfaces, and they answer different questions. **`useAgentRun(alias)`** runs an agent *declared on the app* — a streaming, tool-looping run whose result lands back **in the app** (a typed structured output, or free-text prose) for the app to review and commit through its own [workflows](./mutations.md). **`askAi(args)`** is a *handoff* — it opens the Lotics chat messenger seeded with files, records, and a prefilled prompt, and the outcome lands **in chat**, under the signed-in member's control. Beyond those two, **`useAiContext(slot, context)`** feeds the member's *ambient* chat agent — the one riding alongside the app — a snapshot of what the current screen is showing, so a question the member asks there resolves against what they're looking at. Read this doc when adding any AI-driven feature to an app; read [security](./security.md) first for the authority model agent runs execute under. Exact signatures: `dist/src/hooks.d.ts` (`useAgentRun`, `useAgentRuns`, `useAiContext`), `dist/src/agent_stream.d.ts` (`AgentRunItem`, `AgentRunStep`, `AgentRunState`), `dist/src/ask_ai.d.ts` (`AskAiArgs`).
 
 ## Choosing the surface — the fields-vs-file razor
 
@@ -127,10 +127,11 @@ The run's lifetime is decoupled from the stream: the server drives it to complet
 
 ### Sessions
 
-`run()` requires `{ sessionId }` — an **app-minted opaque key** grouping runs into a working session. Each run replays the session's prior **completed** runs (their inputs and outputs, including re-materialized image/PDF inputs) as conversation context, so a follow-up like "make it a bit less" resolves against the previous result. Two rules keep this sane:
+`run()` requires `{ sessionId }` — an **app-minted opaque key** grouping runs into a working session. Each run replays the session's prior **completed** runs (their inputs and outputs, including re-materialized image/PDF inputs) as conversation context, so a follow-up like "make it a bit less" resolves against the previous result. Three rules keep this sane:
 
 - **The app owns the state.** Always pass the authoritative current state in `input` — the session context is memory, not the source of truth.
 - **Mint a new `sessionId` to clear context.** There is no reset call; a fresh key is a fresh session.
+- **One-shot agents get a fresh `sessionId` per run.** Session context only pays for conversational follow-ups. If every run is self-contained (the app passes the complete input each time — e.g. a document-extraction agent), reusing a key replays dead context into every request — every replayed run still bills its input tokens, so a one-shot agent on a shared key pays for history it never uses. Append a per-run nonce to the key instead. (Media itself replays as a provider file reference — uploaded once, referenced by id — so a long session no longer grows toward the provider's request-size cap; the cost of dead context is tokens, not payload.)
 
 Sessions are scoped to the authenticated member who ran them: two members using the same `sessionId` string share nothing, and a member can never read or extend another member's thread.
 
@@ -188,6 +189,68 @@ At least one of the four is required — an empty call rejects. The bridge carri
 
 ---
 
+## `useAiContext(slot, context)` — tell the ambient chat what the member is looking at
+
+A member using an app inside Lotics has an **ambient chat agent** riding alongside the app (distinct from `askAi`, which opens a fresh seeded chat, and from `useAgentRun`, which runs an agent the app declares). `useAiContext` publishes a snapshot of the **current screen's view state** into that ambient chat, so when the member turns to it and asks "why is this one overdue?" or "summarize what I'm seeing", the agent already knows which list is filtered to what, which record is open, and what's typed into a form — without the member re-describing it.
+
+```tsx
+import { useAiContext } from "@lotics/app-sdk";
+
+// A list screen publishes what it rendered:
+useAiContext("orders_list", {
+  description: `Viewing ${rows.length} orders filtered to status=open, sorted by due date.`,
+  records: rows.map((r) => ({ table_id: r.__source_table_id, record_id: r.__source_record_id })),
+  data: { filter: "status=open", sort: "due_date desc" },
+});
+
+// A detail drawer publishes its own slot; clears it when nothing is selected:
+useAiContext(
+  "order_detail",
+  selected
+    ? { description: `Order ${selected.code}, status ${selected.status}`, records: [{ table_id: "tbl_orders", record_id: selected.id }] }
+    : null,
+);
+```
+
+### When to use it
+
+- **List / register screens** — the filtered, sorted set the member is scanning: a one-line `description` of the filter + count, and the visible rows as `records`.
+- **Detail / record views** — which record is open, its key fields; pass the one record ref.
+- **Form / composer state** — what the member has entered so far (`data`), so a mid-task question resolves against the draft.
+
+Publish the **rendered** view, not the whole table. A screen that shows page 2 of an open-orders filter publishes those rows — that is exactly what "what I'm looking at" means.
+
+### Lifecycle and slots
+
+Declarative and lifecycle-bound: mounting or changing `context` pushes it; unmounting, renaming the `slot`, or passing `null` clears it. Independent components hold **different slots** at once (a list screen + an open drawer), and the newest value per slot wins. Re-posting is change-gated — passing a fresh inline object each render does **not** spam the host; only a real value change re-publishes.
+
+### The caps (host-enforced — exceeding them truncates or drops, never errors)
+
+| Field | Cap |
+|---|---|
+| `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) |
+| 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`.
+
+### 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:
+
+- **`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).
+
+### 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).
+
+**No-ops** with no embedding host (standalone `<slug>.lotics.app` — there's no chat surface to inform) and in mock mode.
+
+---
+
 ## Version floors
 
 The floors below are when each capability shipped in `@lotics/app-sdk`; an app pinned older silently lacks them.
@@ -199,3 +262,4 @@ The floors below are when each capability shipped in `@lotics/app-sdk`; an app p
 | `items` transcript (reasoning segments + per-tool `input`/`output`) | `@lotics/app-sdk` 0.43; rendering pairs with `@lotics/ui` ≥ 7.13 (`AgentRun` `items` prop) |
 | Live streamed-argument size on a running step (`detail`) | `@lotics/app-sdk` 0.44 |
 | `askAi` | `@lotics/app-sdk` 0.45 |
+| `useAiContext` (ambient-chat view state + auto query refetch on chat mutation) | `@lotics/app-sdk` 0.52 |

package/docs/data_fetching.md

@@ -83,6 +83,12 @@ server validates system conditions by `type` and never reads `field_key` on them
 - **`refetch()`** re-runs the query. Call it after a known mutation point — a successful
   `useWorkflow` call — to pull the latest state (see [./mutations.md](./mutations.md)).
   `usePaginatedQuery.refetch()` refreshes both the page and the count.
+- **Ambient-chat mutations refetch automatically.** When the member's ambient chat agent (see
+  [./ai.md](./ai.md#useaicontextslot-context--tell-the-ambient-chat-what-the-member-is-looking-at))
+  finishes a turn that mutated records, the host pushes **every mounted query hook** to re-read —
+  so the screen reflects the change with no `refetch()` call and no reload. It refreshes exactly the
+  queries currently on screen (mounted hooks only); it never reaches into app data, it only tells
+  the app its rendered rows may be stale. Inert standalone and in mock mode.
 - A design-time fixture registered via `mount(<App />, { fixture })` plus the `?__mock=1` URL flag
   short-circuits all three hooks (rows come from the fixture, no request, `loading` stays `false`)
   — see [./runtime.md](./runtime.md).

package/package.json

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