@agent-native/core 0.153.6 → 0.153.9

package/corpus/templates/slides/app/components/editor/SlideEditor.tsx

@@ -5003,15 +5003,17 @@ export default function SlideEditor({
   const objectOperationSelection = getObjectOperationSelection();
   const hasObjectSelection = objectOperationSelection !== null;
   const objectSelectionCount = objectOperationSelection?.elements.length ?? 0;
+  const canZoomOut = canvasZoom > MIN_CANVAS_ZOOM;
+  const canZoomIn =
+    canvasZoom < CANVAS_ZOOM_PRESETS[CANVAS_ZOOM_PRESETS.length - 1];
   const zoomControls = slide.excalidrawData
     ? undefined
     : {
         value: canvasZoom,
         onZoomOut: canvasZoomOut,
         onZoomIn: canvasZoomIn,
-        canZoomOut: canvasZoom > MIN_CANVAS_ZOOM,
-        canZoomIn:
-          canvasZoom < CANVAS_ZOOM_PRESETS[CANVAS_ZOOM_PRESETS.length - 1],
+        canZoomOut,
+        canZoomIn,
       };
 
   // Excalidraw slides have no selectable slide content, so the row collapses

package/dist/agent/run-store.d.ts

@@ -681,13 +681,26 @@ export declare function listRunsForThread(threadId: string, options?: {
  * Best-effort on parse: malformed ledger rows are skipped rather than thrown.
  */
 export declare function getCurrentTurnEventsForThread(threadId: string, knownTurnId?: string): Promise<AgentChatEvent[]>;
+export interface StaleRunReapResult {
+    /** Rows this pass reaped. */
+    reaped: number;
+    /**
+     * Rows whose reap threw. Separate from `reaped` because a pass where every
+     * row failed must not read as "nothing was stale" — those were the same
+     * number before, and the caller's own `null`-vs-`0` distinction is worthless
+     * while the per-row failures underneath it are coerced away.
+     */
+    failed: number;
+    /** More stale rows remain than the batch cap; the next tick continues. */
+    truncated: boolean;
+}
 /**
  * Expire any "running" rows whose heartbeat is stale — producer died.
  * Safe to call at server startup on multi-isolate deployments: only rows
  * without a fresh heartbeat get reaped, so runs owned by OTHER live
  * isolates (which keep heartbeating) are left alone.
  */
-export declare function reapAllStaleRuns(): Promise<number>;
+export declare function reapAllStaleRuns(): Promise<StaleRunReapResult>;
 /**
  * Read the daily terminal-outcome counters rolled up from pruned runs. Pair
  * with live `agent_runs` rows for a complete picture — see

package/dist/agent/run-store.js

@@ -2253,6 +2253,18 @@ export async function getCurrentTurnEventsForThread(threadId, knownTurnId) {
     }
     return events;
 }
+/**
+ * Rows one pass will reap. Each costs ~5-10 serial round trips (reconcile,
+ * transactional reap plus recovery, terminal-event append), and this sweep now
+ * runs ahead of `processRecurringJobs` on the shared durable tick — so an
+ * unbounded first pass against a backlog spends the platform wall before jobs
+ * get any. Production carried 1,216 stale rows while nothing periodic reaped
+ * them, so the first tick after that fix lands on exactly such a backlog.
+ * A truncated pass is drained by the next tick (60s durable, 20s in-process),
+ * never dropped — `truncated` is what stops a partial sweep being reported as
+ * a clean one.
+ */
+const REAP_ALL_STALE_BATCH_LIMIT = 200;
 /**
  * Expire any "running" rows whose heartbeat is stale — producer died.
  * Safe to call at server startup on multi-isolate deployments: only rows
@@ -2260,9 +2272,14 @@ export async function getCurrentTurnEventsForThread(threadId, knownTurnId) {
  * isolates (which keep heartbeating) are left alone.
  */
 export async function reapAllStaleRuns() {
+    const nothingStale = {
+        reaped: 0,
+        failed: 0,
+        truncated: false,
+    };
     await ensureRunTables();
     if (!(await hasRunningRuns()))
-        return 0;
+        return nothingStale;
     const client = getDbExec();
     const now = Date.now();
     // Background-dispatched runs use the wider window; everything else 15s. The
@@ -2274,13 +2291,23 @@ export async function reapAllStaleRuns() {
     // server startup across possibly-multiple isolates, so a sibling isolate's
     // still-alive, in-flight run must not be reaped just because THIS isolate
     // just booted and has no heartbeat history for it.
-    const stale = await client.execute({
+    // One row over the cap is how a truncated pass is detected without a second
+    // COUNT query against the same predicate.
+    const scanned = await client.execute({
         sql: `SELECT id FROM agent_runs
           WHERE status = 'running'
             AND ${livenessBasisSql()} < ${backgroundAwareStaleCutoffSql()}
-            AND ${inFlightGraceSql()}`,
+            AND ${inFlightGraceSql()}
+          ORDER BY started_at ASC
+          LIMIT ${REAP_ALL_STALE_BATCH_LIMIT + 1}`,
         args: [now, now, now],
     });
+    const truncated = scanned.rows.length > REAP_ALL_STALE_BATCH_LIMIT;
+    const stale = {
+        rows: truncated
+            ? scanned.rows.slice(0, REAP_ALL_STALE_BATCH_LIMIT)
+            : scanned.rows,
+    };
     for (const row of stale.rows) {
         const id = row.id;
         if (typeof id === "string") {
@@ -2299,13 +2326,19 @@ export async function reapAllStaleRuns() {
     // already found stale; on an idle app `hasRunningRuns` returns before any of
     // this, so the 20s fast sweep (agent-chat-plugin.ts) costs one probe.
     let reapedCount = 0;
+    let failedCount = 0;
     for (const row of stale.rows) {
         const id = row.id;
         if (typeof id !== "string")
             continue;
-        const reaped = await reapSingleStaleRun(id).catch(() => false);
-        if (reaped)
-            reapedCount += 1;
+        try {
+            if (await reapSingleStaleRun(id))
+                reapedCount += 1;
+        }
+        catch (error) {
+            failedCount += 1;
+            console.error(`[run-store] stale reap failed for run ${id}:`, error);
+        }
     }
     for (const row of stale.rows) {
         const id = row.id;
@@ -2313,7 +2346,7 @@ export async function reapAllStaleRuns() {
             await safeAppendTerminalRunEvent(id, STALE_RUN_ERROR_EVENT, "reap-all-stale");
         }
     }
-    return reapedCount;
+    return { reaped: reapedCount, failed: failedCount, truncated };
 }
 const RUN_OUTCOME_DAY_MS = 86_400_000;
 /**

package/dist/client/hooks/index.d.ts

@@ -1,5 +1,5 @@
 export { getBrowserTabId } from "../browser-tab-id.js";
-export { deleteClientAppState, readClientAppState, setClientAppState, writeClientAppState, type ClientAppStateReadOptions, type ClientAppStateWriteOptions, } from "../application-state.js";
+export { deleteClientAppState, readClientAppState, readClientAppStateMany, setClientAppState, writeClientAppState, type ClientAppStateBatch, type ClientAppStateReadOptions, type ClientAppStateWriteOptions, } from "../application-state.js";
 export { useDbSync, useFileWatcher, useScreenRefreshKey, } from "../use-db-sync.js";
 export { useChangeVersion, useChangeVersions, getChangeVersion, bumpChangeVersion, } from "../use-change-version.js";
 export { useDemoModeStatus, type DemoModeStatus, } from "../use-demo-mode-status.js";

package/dist/client/hooks/index.js

@@ -1,5 +1,5 @@
 export { getBrowserTabId } from "../browser-tab-id.js";
-export { deleteClientAppState, readClientAppState, setClientAppState, writeClientAppState, } from "../application-state.js";
+export { deleteClientAppState, readClientAppState, readClientAppStateMany, setClientAppState, writeClientAppState, } from "../application-state.js";
 export { useDbSync, useFileWatcher, useScreenRefreshKey, } from "../use-db-sync.js";
 export { useChangeVersion, useChangeVersions, getChangeVersion, bumpChangeVersion, } from "../use-change-version.js";
 export { useDemoModeStatus, } from "../use-demo-mode-status.js";

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
-    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
+    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
-    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
+    error?: undefined;
 }>>;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/server/agent-chat-plugin.js

@@ -4907,7 +4907,10 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     //
                     // Reported, never swallowed, and never fatal to the job sweep: a
                     // reap failure must not take recurring jobs down with it, and
-                    // `null` must stay distinguishable from "reaped nothing".
+                    // `null` must stay distinguishable from "reaped nothing". The
+                    // result carries `failed` and `truncated` for the same reason one
+                    // level down — a pass where every row threw, and a pass that hit
+                    // the batch cap, both used to be reportable as a clean sweep.
                     const { reapAllStaleRuns } = await import("../agent/run-store.js");
                     const staleRunsReaped = await reapAllStaleRuns().catch((error) => {
                         console.error("[agent-chat] durable stale-run reap failed:", error);

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/docs/content/client-advanced.mdx

@@ -0,0 +1,200 @@
+---
+title: "Advanced"
+description: "Lower-level app/ primitives and escape hatches: direct application-state access, background chat sends, custom suggestion chips, and the MCP App host bridge."
+---
+
+# Advanced
+
+Overview, Data & Sync, Agent Chat, and Routing cover the typical case: the hooks and helpers most pages need. This page covers the lower-level primitives and narrower escape hatches underneath them. Most apps never touch these directly. Reach for one when you're building something more custom than the default hooks support, such as a custom selection sync or an embedded MCP App. For syncing a raw `useQuery` with a hand-rolled key, see [Sync Internals](/docs/client-sync-internals) instead.
+
+## Application State {#application-state}
+
+`application_state` is the SQL-backed key/value store the agent reads to know what the UI is currently looking at, including navigation, selection, and other focused-object context (see [Context Awareness](/docs/context-awareness)). `useAgentRouteState` and `useSemanticNavigationState` (also covered in Context Awareness) already wrap these for the common navigation case. Reach for the primitives below directly when you're syncing something they don't cover, such as a custom selection, or writing from outside a component's render.
+
+### readClientAppState {#read-client-app-state}
+
+Read the current value for a key. Resolves to whatever was last written for that key, or `null` if the key has never been written.
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+Write a value for a key. Unlike `setClientAppState` below, it always writes, even if you pass `null`. Passing `undefined` throws instead, since `undefined` isn't valid JSON. Use `setClientAppState(key, undefined)` or `deleteClientAppState()` to clear a key.
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+The convenience wrapper most UI code should reach for: writes the value, or deletes the key when you pass `null`/`undefined`. Use this instead of `writeClientAppState` unless a call site genuinely needs "always write, never delete."
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+Remove a key entirely.
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+Read several keys in one request. Returns `{ values, missing }`. `values` holds an entry for every key the server has a row for, including a key that was explicitly written as `null`. `missing` lists the keys that have never been written at all. This is how "never written" stays distinguishable from "written as null."
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+Requests over 100 keys are chunked automatically. `readClientAppState()` itself is built on this: calls issued in the same tick are coalesced into one batched request behind the scenes, so calling it many times in a single render pass costs one round trip, not one per call.
+
+### Options {#application-state-options}
+
+`signal` is accepted by all five functions above, to cancel an in-flight call. `requestSource` and `keepalive` only apply to the three write functions, since they don't mean anything for a read.
+
+| Option          | Type           | Applies to                                                         | Description                                                                                  |
+| --------------- | -------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Tags the write with an id so a matching `useDbSync({ ignoreSource })` can skip refetching it |
+| `keepalive`     | `boolean?`     | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Lets the request outlive page unload. Use for cleanup writes like clearing selection         |
+| `signal`        | `AbortSignal?` | all five functions                                                 | Cancels the request                                                                          |
+
+### Failure behavior {#failure-behavior}
+
+All five functions throw on a failed request, a non-2xx response, or a body that can't be parsed. The thrown `Error` carries a `.status` property when the server responded, so a caller can branch on the HTTP status if needed. Wrap a call in `try`/`catch`, or let it propagate to an error boundary, the same as any other network call.
+
+### What TAB_ID is {#tab-id}
+
+`requestSource` is commonly set to `TAB_ID`, a plain constant every template exports from `app/lib/tab-id.ts`: a short random string that stays the same for the life of a tab and differs between tabs. Pairing `requestSource: TAB_ID` on a write with `useDbSync({ ignoreSource: TAB_ID })` on the read side is how a tab avoids refetching its own write while still reacting to everyone else. See [Context Awareness](/docs/context-awareness#jitter-prevention) for the full walkthrough.
+
+## sendToAgentChat: Background Sends {#background-send}
+
+Use `background: true` when a UI action should kick off real agent work without
+opening or focusing the sidebar. This still creates a normal chat thread/run,
+uses the agent's tools/actions/context, and keeps the work observable through
+the runs tray. It is not a raw one-shot model call.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` is intended to be paired with `newTab` so the hidden work does not
+overwrite the user's active conversation. Use the returned `tabId` if the UI
+needs to correlate follow-up status or deep-link into the run later.
+
+A few more `AgentChatMessage` options exist beyond the ones covered in [Agent Chat](/docs/client-agent-chat#agentchatmessage), mostly for embedded or downstream-integration cases:
+
+| Option                | Type        | Description                                                                |
+| --------------------- | ----------- | -------------------------------------------------------------------------- |
+| `background`          | `boolean?`  | With `newTab`, run without focusing the tab and show the run in `RunsTray` |
+| `projectSlug`         | `string?`   | Optional project slug for structured context                               |
+| `preset`              | `string?`   | Optional preset name for downstream consumers                              |
+| `referenceImagePaths` | `string[]?` | Optional reference image paths                                             |
+
+## MCP App Host Bridge {#mcp-app-host-bridge}
+
+Routes embedded as MCP Apps should be URL-first: load the current artifact from
+path/query params, render the real React route or a focused shared component,
+and use the host bridge only for host-owned behavior. `@agent-native/core/client`
+exports the helpers embedded routes call:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` reads the latest pushed host context snapshot.
+`useMcpAppHostContext()` subscribes React components to changes. The request
+helpers (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) return `false` outside an embedded MCP App frame, or
+`Promise<boolean>` inside a frame.
+
+`sendToAgentChat()` (see [Agent Chat](/docs/client-agent-chat#sendtoagentchat)) uses the same bridge for auto-submitted prompts from embedded routes. Inside an MCP App embed created with `embedApp()`, auto-submitted messages (`submit` omitted or `true`) are forwarded to the bridge, which asks the containing host to add hidden context and send the visible user turn. `context` stays model-visible without being posted as user-facing chat. `submit: false` keeps the local prefill/review behavior because MCP Apps do not define a standard draft-prefill API. Internally this is the submitted-chat path sometimes surfaced as `agentNative.submitChat`. App code should still call `sendToAgentChat()` rather than posting that event directly.
+
+The bridge itself, the `ui/*` JSON-RPC messages, the `agentNative.mcpHost.*`
+wrapper relay, transplant vs. controlled-frame rendering, host context, and
+display-mode requests, is owned by
+[External Agents](/docs/external-agents#mcp-app-bridge). See [MCP Apps](/docs/mcp-apps) for the full protocol.
+
+## Custom Suggestion Chips {#custom-suggestions}
+
+`<AgentSidebar>`'s `dynamicSuggestions` (see [Agent Chat](/docs/client-agent-chat#dynamic-suggestions)) already merges static `suggestions` with the framework's own context-aware heuristic. Pass a `getSuggestions` function inside `dynamicSuggestions` instead when an app wants deterministic, domain-specific chips computed from the same `application_state` context rather than the framework's default heuristic.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` receives the same `navigation`/`selection`/`pendingSelection` snapshot the built-in heuristic reads, typed as `unknown` since its shape is app-defined, so narrow it before reading fields. A custom implementation can react to exactly the state the default one does, just with app-specific rules instead of generic ones.
+
+## What's next
+
+- [**Overview**](/docs/client-overview) — the `app/` and `public/` directory layout these primitives live in
+- [**Data & Sync**](/docs/client-data) — the default action hooks and `useDbSync` most pages should use instead
+- [**Sync Internals**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions` and the two latency paths a refetch can take
+- [**Agent Chat**](/docs/client-agent-chat) — the default `sendToAgentChat`/`askUserQuestion` helpers most UI should use instead, and the staged agent chat context-state APIs
+- [**Entry Points**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` and SSR streaming customization
+- [**Context Awareness**](/docs/context-awareness) — the `navigation`/`selection` semantics built on `application_state`, and the `TAB_ID`/jitter-prevention walkthrough
+- [**Generative UI**](/docs/generative-ui) — richer inline chat controls beyond `askUserQuestion`
+- [**External Agents**](/docs/external-agents#mcp-app-bridge) — the full MCP App host bridge internals