@lotics/app-sdk 0.51.5 → 0.52.1

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/agent_stream.d.ts

@@ -68,6 +68,24 @@ export interface AgentRunState {
     output?: unknown;
     error?: string;
 }
+/** A settled run row, as the poll endpoint returns it. */
+export interface SettledAgentRun {
+    status: string;
+    output?: unknown;
+    error_message?: string | null;
+}
+/**
+ * Fold a POLLED settled run row into the stream-accumulated state — the shared
+ * adoption step for BOTH recovery paths (a dropped stream, and a stream that
+ * ended cleanly WITHOUT a `finish` frame — an edge can close a long SSE
+ * gracefully mid-run, which looks like completion but is a truncation).
+ *
+ * The row is the source of truth for status and the STRUCTURED output. A
+ * free-text run's row `output` is its prose string — that never enters
+ * `state.output` (a structured consumer reads `output.<field>`; a stray string
+ * would crash it). The free-text answer stays in the transcript text.
+ */
+export declare function adoptSettledRun(state: AgentRunState, settled: SettledAgentRun): AgentRunState;
 export declare function initialAgentRunState(): AgentRunState;
 /** A parsed UI-message chunk — only the fields we read, all optional. */
 interface Chunk {

package/dist/src/agent_stream.js

@@ -20,6 +20,24 @@
  */
 /** The tool the backend injects to carry a typed structured result. */
 const SUBMIT_TOOL = "submit_result";
+/**
+ * Fold a POLLED settled run row into the stream-accumulated state — the shared
+ * adoption step for BOTH recovery paths (a dropped stream, and a stream that
+ * ended cleanly WITHOUT a `finish` frame — an edge can close a long SSE
+ * gracefully mid-run, which looks like completion but is a truncation).
+ *
+ * The row is the source of truth for status and the STRUCTURED output. A
+ * free-text run's row `output` is its prose string — that never enters
+ * `state.output` (a structured consumer reads `output.<field>`; a stray string
+ * would crash it). The free-text answer stays in the transcript text.
+ */
+export function adoptSettledRun(state, settled) {
+    if (settled.status === "completed") {
+        const structured = settled.output !== null && typeof settled.output === "object" ? settled.output : undefined;
+        return { ...state, status: "completed", output: structured ?? state.output };
+    }
+    return { ...state, status: "error", error: settled.error_message ?? "The run was stopped." };
+}
 export function initialAgentRunState() {
     return { status: "streaming", items: [] };
 }

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 { initialAgentRunState, reduceAgentChunk, parseSseChunks, } from "./agent_stream.js";
-import { getMockRows } from "./mock.js";
+import { rpc, rpcAgentRun, postHostNotification, subscribeHostRefetch, } from "./rpc.js";
+import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, } from "./agent_stream.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 }`
@@ -400,16 +487,33 @@ export function useAgentRun(alias) {
             },
         };
         return handle.done
-            .then(() => {
+            .then(async () => {
             if (aborted)
                 return undefined;
-            // `finish` normally settles status; guard a stream that ended without one.
-            // Keep `output` as whatever `submit_result` set (else undefined) — never
-            // coerce the free-text into it (that string would crash a structured
-            // consumer reading `output.<field>`; the answer stays in `text`).
+            // A clean stream end WITHOUT a `finish` frame is a truncation, not a
+            // completion — an edge can close a long SSE gracefully mid-run (seen
+            // in production on ~2-minute runs), swallowing the frames that carry
+            // the structured result. The run is decoupled and settles server-side
+            // regardless, so the row is the source of truth: poll it, exactly
+            // like the dropped-with-error path below. (2026-07-18: four NOXH
+            // extractions completed server-side while every client showed
+            // failure through this hole.)
             if (acc.status === "streaming") {
-                acc = { ...acc, status: "completed" };
+                const runId = runIdRef.current;
+                const settled = runId
+                    ? await pollAgentRunToSettle(runId, () => aborted || !mountedRef.current)
+                    : null;
+                if (aborted)
+                    return undefined;
+                acc = settled ? adoptSettledRun(acc, settled) : { ...acc, status: "completed" };
                 safeSetState(acc);
+                // Fleet visibility: how often edges cut agent SSE streams. One
+                // event per truncation, with whether the row rescued the result.
+                captureAppEvent("app_agent_stream_truncated", {
+                    recovered: settled != null,
+                    settled_status: settled?.status ?? null,
+                    has_output: acc.output !== undefined,
+                });
             }
             return acc.output;
         })
@@ -423,10 +527,7 @@ export function useAgentRun(alias) {
             if (runId) {
                 const settled = await pollAgentRunToSettle(runId, () => aborted || !mountedRef.current);
                 if (settled && !aborted) {
-                    acc =
-                        settled.status === "completed"
-                            ? { ...acc, status: "completed", output: settled.output ?? acc.output }
-                            : { ...acc, status: "error", error: settled.error_message ?? "The run was stopped." };
+                    acc = adoptSettledRun(acc, settled);
                     safeSetState(acc);
                     return acc.output;
                 }

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
 
@@ -121,9 +121,14 @@ Both settle the in-flight `run()` promise cleanly with `undefined` — a stop is
 
 ### Runs survive dropped connections
 
-The run's lifetime is decoupled from the stream: the server drives it to completion and persists the result even if the connection drops. The hook reads the run id from the stream's start; if the connection then fails, it **polls the persisted run to completion** (every 2.5 s, bounded at 11 minutes) and resolves with the settled result instead of surfacing a network error — so a run that settles within that 11-minute poll window survives a flaky connection. A run still going when the poll deadline passes (the hard cap is 20 min) is **not** recovered on the client: the poll gives up and the drop surfaces as an error, though the result is still persisted server-side. Only when no run id was ever received (the run never started) does the failure reject before any polling.
+The run's lifetime is decoupled from the stream: the server drives it to completion and persists the result even if the connection drops. The hook reads the run id from the stream's start and recovers through the **persisted run row** — the source of truth — in BOTH failure shapes:
 
-**Warning:** on this recovery path the hook adopts the *persisted* run's output — and a **free-text** run is persisted with its final answer text as the output. So after a connection-drop recovery, a free-text agent's `output` can carry the answer **string** (the one place the "never a stray string" rule doesn't hold), while `text` keeps only what streamed before the drop. If you consume free-text agents, guard with `typeof output === "string"` on the resolved value.
+- **The connection drops with an error** → the hook polls the persisted run to completion (every 2.5 s, bounded at 11 minutes) and resolves with the settled result instead of surfacing a network error.
+- **The stream ends cleanly WITHOUT a `finish` frame** — an edge/proxy can close a long SSE gracefully mid-run, which looks like completion but swallowed the trailing frames (including the structured result). The hook detects the missing `finish` and polls the row the same way. Each such truncation emits the `app_agent_stream_truncated` analytics event (with whether the row rescued the result), so edge-cut frequency is visible fleet-wide.
+
+A run still going when the poll deadline passes (the hard cap is 20 min) is **not** recovered on the client: the poll gives up and the drop surfaces as an error, though the result is still persisted server-side. Only when no run id was ever received (the run never started) does the failure reject before any polling.
+
+On recovery, `output` adopts the row's output **only when it is an object** (a structured result) — the "`output` is never a stray string" rule holds on every path. A **free-text** run recovered from truncation keeps only the streamed prefix in `text`; read the full settled answer via `useAgentRuns(sessionId)` if you need it.
 
 ### Sessions
 
@@ -189,6 +194,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.
@@ -200,3 +267,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.5",
+  "version": "0.52.1",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {