@agent-native/core 0.164.11 → 0.164.15

package/dist/mcp-client/config.js

@@ -96,39 +96,46 @@ export function loadMcpConfig(startDir) {
  * the explicit child gate, loopback URL, and strong per-run bearer are all
  * required. Existing user servers always win on key collisions.
  */
-function mergeDesktopChildComputerConfig(base) {
-    if (process.env.AGENT_NATIVE_DESKTOP_CHILD !== "1")
-        return base;
-    const url = process.env.AGENT_NATIVE_DESKTOP_COMPUTER_MCP_URL?.trim();
-    const token = process.env.AGENT_NATIVE_DESKTOP_COMPUTER_MCP_TOKEN?.trim();
+export function resolveDesktopChildComputerMcpServer(existingServers, environment = process.env) {
+    if (environment.AGENT_NATIVE_DESKTOP_CHILD !== "1")
+        return null;
+    const url = environment.AGENT_NATIVE_DESKTOP_COMPUTER_MCP_URL?.trim();
+    const token = environment.AGENT_NATIVE_DESKTOP_COMPUTER_MCP_TOKEN?.trim();
     if (!url || !token || !/^[A-Za-z0-9_-]{32,}$/.test(token))
-        return base;
-    try {
-        const parsed = new URL(url);
-        if (parsed.protocol !== "http:" ||
-            parsed.hostname !== "127.0.0.1" ||
-            parsed.pathname !== "/mcp" ||
-            parsed.username ||
-            parsed.password) {
-            return base;
-        }
-    }
-    catch {
-        return base;
+        return null;
+    if (!URL.canParse(url))
+        return null;
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" ||
+        parsed.hostname !== "127.0.0.1" ||
+        parsed.pathname !== "/mcp" ||
+        parsed.username ||
+        parsed.password) {
+        return null;
     }
-    const servers = { ...(base?.servers ?? {}) };
     let serverId = DESKTOP_COMPUTER_SERVER_ID;
-    for (let suffix = 2; servers[serverId]; suffix += 1) {
+    for (let suffix = 2; existingServers[serverId]; suffix += 1) {
         serverId = `${DESKTOP_COMPUTER_SERVER_ID}-${suffix}`;
     }
-    servers[serverId] = {
-        type: "http",
-        url,
-        headers: { Authorization: `Bearer ${token}` },
-        description: "Authenticated computer control for this Agent Native desktop task",
+    return {
+        id: serverId,
+        config: {
+            type: "http",
+            url,
+            headers: { Authorization: `Bearer ${token}` },
+            description: "Authenticated computer control for this Agent Native desktop task",
+        },
     };
+}
+function mergeDesktopChildComputerConfig(base) {
+    const desktopServer = resolveDesktopChildComputerMcpServer(base?.servers ?? {});
+    if (!desktopServer)
+        return base;
     return {
-        servers,
+        servers: {
+            ...(base?.servers ?? {}),
+            [desktopServer.id]: desktopServer.config,
+        },
         source: base?.source ? `${base.source}+desktop-child` : "desktop-child",
     };
 }

package/dist/notifications/routes.d.ts

@@ -11,23 +11,23 @@
  *   DELETE /_agent-native/notifications/:id         — delete
  */
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
+    error?: undefined;
     count: number;
     updated?: undefined;
     ok?: undefined;
-    error?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated: number;
     ok?: undefined;
-    error?: undefined;
 } | {
     count?: undefined;
     updated?: undefined;
     error: string;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated?: undefined;
     ok: boolean;
-    error?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -42,22 +42,22 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     avgEvalScore: number;
 } | {
     error?: undefined;
+    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-    ok?: undefined;
 } | {
     error?: undefined;
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-    ok?: undefined;
 } | {
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
-    ok?: undefined;
 } | {
     error?: undefined;
     summary?: 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/resources/handlers.d.ts

@@ -51,8 +51,8 @@ export declare function handleDeleteResource(event: any): Promise<{
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>;
 /** POST /_agent-native/resources/upload — upload a file as a resource */
 export declare function handleUploadResource(event: any): Promise<import("./store.js").Resource | {
@@ -73,10 +73,10 @@ export declare function handleUploadResource(event: any): Promise<import("./stor
     runId: string | null;
     expiresAt: number | null;
     metadata: string | null;
+    error?: undefined;
     url: string;
     provider: string;
     storageSetupRequired?: undefined;
-    error?: undefined;
 } | {
     error: string;
     storageSetupRequired: boolean;

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};

package/dist/server/auth.js

@@ -405,6 +405,8 @@ export function isLoopbackRequest(event) {
 async function readDesktopSsoSafely(event) {
     if (process.env.NODE_ENV === "production")
         return null;
+    if (getAppConfig().auth.disableDesktopSsoFallbackInDevelopment)
+        return null;
     if (!isElectronRequest(event))
         return null;
     if (!isLoopbackRequest(event))
@@ -1242,7 +1244,7 @@ export function prepareDesktopOAuthBrowserBinding(event) {
     if (!binding || !/^[A-Za-z0-9_-]{43}$/.test(binding)) {
         binding = crypto.randomBytes(32).toString("base64url");
         setCookie(event, DESKTOP_OAUTH_BROWSER_BINDING_COOKIE, binding, {
-            ...crossSiteCookieAttrs(event),
+            ...desktopOAuthBrowserBindingCookieAttrs(event),
             httpOnly: true,
             path: "/",
             maxAge: Math.floor(DESKTOP_EXCHANGE_TTL_MS / 1_000),
@@ -2810,6 +2812,18 @@ function crossSiteCookieAttrs(event) {
         ? { sameSite: "none", secure: true, partitioned: true }
         : { sameSite: "lax", secure: false };
 }
+/**
+ * The binding cookie is set before navigating to Google and read after the
+ * provider redirects back. A partitioned cookie uses the top-level site from
+ * the bootstrap request, so it is unavailable when the callback starts from
+ * Google's top-level site. Keep this host-scoped cookie unpartitioned while
+ * retaining the cross-site and transport protections required by the flow.
+ */
+function desktopOAuthBrowserBindingCookieAttrs(event) {
+    return isHttpsRequest(event)
+        ? { sameSite: "none", secure: true }
+        : { sameSite: "lax", secure: false };
+}
 function setFirstRunOnboardingCookie(event) {
     setCookie(event, FIRST_RUN_ONBOARDING_COOKIE, "1", {
         ...crossSiteCookieAttrs(event),

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/actions-access-control.mdx

@@ -83,7 +83,141 @@ Use it only for safe, read-only, or ingest-only actions, the kind you'd let a st
 
 A handful of actions are too consequential to let the agent run on its own, like sending an email, charging a card, or deleting an account. Set `needsApproval: true` (or a predicate `(args, ctx) => boolean | Promise<boolean>`) on `defineAction()`, and the loop pauses before `run()`, requiring a human to approve that specific call. The default is **off**, and almost every action should stay that way.
 
-See [Human-in-the-Loop Approvals](/docs/human-approval) for the predicate API, the `approval_required` event, and the full end-to-end flow.
+<Callout tone="warning">
+  Keep approvals rare. Every gated action is a hard stop in the agent loop. It
+  interrupts the run and demands a human round-trip. Use `needsApproval` only
+  for genuinely high-consequence, hard-to-undo, outward-facing operations. If
+  you find yourself gating reads or routine writes, you're holding it wrong. The
+  default is **off**, and almost every action should leave it off.
+</Callout>
+
+<AnnotatedCode
+  id="doc-block-13p4g9y"
+  title="Gating the one consequential action"
+  filename="actions/send-email.ts"
+  language="ts"
+  code={
+    'export default defineAction({\n  description: "Send an email via Gmail.",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting and queueing are\n  // not affected. Only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});'
+  }
+  annotations={[
+    {
+      lines: "10",
+      label: "The whole gate",
+      note: "One flag. When it is truthy and the call has not been approved, the loop stops before `run`. The model never reaches the side effect on its own.",
+    },
+    {
+      lines: "11-13",
+      label: "run() is untouched",
+      note: "The handler stays the same. Approval is enforced by the loop around it, not by anything inside `run`.",
+    },
+  ]}
+/>
+
+- **`needsApproval: true`** always requires approval.
+- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`** requires approval only when the predicate returns true. Use this to gate conditionally, for example only for external recipients or only above a dollar threshold:
+
+  ```ts
+  needsApproval: (args) => !args.to.endsWith("@your-company.com"),
+  ```
+
+  Keep the predicate pure and fast. If the predicate throws an error, the framework treats the call the same as if the predicate had returned true, so the action pauses for approval instead of running. This means a broken predicate can never silently let a high-consequence action run without a human approving it first.
+
+When `needsApproval` is omitted, behavior is byte-for-byte unchanged. There is no extra cost on the common path.
+
+This works the same way for legacy `parameters`-style actions and for schema-based actions. It also works the same way for the in-app agent, sub-agents, A2A, and MCP callers, because every agent surface routes through the same loop.
+
+### How the loop pauses {#loop}
+
+When the agent calls a gated action and this specific call has **not** already been approved, the loop does **not** execute `run()`. Instead it:
+
+1. Resolves the gate. For a predicate, the loop calls `needsApproval(input, ctx)`. If that call throws an error, the loop treats it the same as a `true` result, so the action requires approval.
+2. Emits a `tool_start` event (so the UI shows the call) followed immediately by an **`approval_required`** event, then stops the turn. The action's side effect never happens.
+
+The `approval_required` event carries everything the client needs to render an affordance:
+
+| Field         | Type     | Notes                                                               |
+| ------------- | -------- | ------------------------------------------------------------------- |
+| `tool`        | `string` | The action name the agent tried to call.                            |
+| `input`       | object   | The arguments the agent passed.                                     |
+| `approvalKey` | `string` | **Stable key** the client echoes back to approve _this exact call_. |
+| `toolCallId`  | `string` | The model-side tool-call id, when available.                        |
+
+The `approvalKey` is derived deterministically from the tool name plus its input, so the same logical call always produces the same key. The model never sees or sets it. It exists purely as a handshake between the framework and the human's Approve affordance.
+
+The paused tool returns a result telling the model the turn is paused and not to retry, so the model does not spin.
+
+### How the human approves {#approve}
+
+On `approval_required`, the chat UI renders an **Approve / Deny** affordance on the paused tool call. This is wired automatically in `AssistantChat`. You do not need to build it per template.
+
+<WireframeBlock id="doc-block-humanapprovalwf1">
+  <Screen
+    surface="popover"
+    html={
+      "<div style='display:flex;flex-direction:column;box-sizing:border-box;padding:16px;gap:12px'><div class='wf-card' style='display:flex;flex-direction:column;gap:8px'><div style='display:flex;align-items:center;gap:8px'><span class='wf-pill warn'>Needs approval</span><strong>send-email</strong></div><div style='display:flex;flex-direction:column;gap:2px'><span class='wf-muted'>to: alex@acme.com</span><span class='wf-muted'>subject: Following up on the proposal</span></div><div style='display:flex;gap:8px'><button>Deny</button><button class='primary'>Approve</button></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+- **Approve** re-issues the turn as an ordinary continuation message that carries the call's key in `approvedToolCalls: [approvalKey]`. On the re-issued turn, the gate sees the key in the approved set and lets that specific call run normally.
+- **Deny** dismisses the affordance locally. Nothing is re-issued, so the action never runs.
+
+`approvedToolCalls` is a field on the chat request (`AgentChatRequest.approvedToolCalls`). Keys that are not present in it stay paused. Approving one call never approves any other call. Because the key is content-addressed, an approval only authorizes that exact call with those exact arguments. If the model later proposes a different send, that becomes a new key and needs its own fresh approval.
+
+### End-to-end {#flow}
+
+<Diagram id="doc-block-2nor1g" title="The approval interrupt" summary={"A gated call pauses the turn before run() fires. Approval re-issues the turn carrying the call's key. Only then does the side effect happen."}>
+
+```html
+<div class="diagram-approve">
+  <div class="diagram-box" data-rough>Agent calls send-email</div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-panel warn" data-rough>
+    <strong>Gate truthy, call not yet approved</strong
+    ><small class="diagram-muted"
+      >loop emits tool_start + approval_required { tool, input, approvalKey
+      }</small
+    ><span class="diagram-pill warn">run() has not executed</span>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-box" data-rough>
+    Human clicks Approve in chat<br /><small class="diagram-muted"
+      >client re-issues the turn with approvedToolCalls: [approvalKey]</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-panel ok" data-rough>
+    <span class="diagram-pill ok"
+      >Gate sees the key &rarr; run() executes &rarr; email sends</span
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-approve {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+}
+.diagram-approve .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  align-items: center;
+  padding: 12px 16px;
+  text-align: center;
+}
+.diagram-approve .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+The Mail template's `send-email` action is the canonical use of this gate in the framework, and it is intentionally rare. It sets `needsApproval: true` so the agent can draft and queue emails freely. It can never actually send a message without a human approving that specific send.
 
 ## Restrict callers by role {#authorize}
 
@@ -220,7 +354,7 @@ A few other options. `audit: { onRead: true }` audits a sensitive read, like a s
 - [**Overview**](/docs/actions-overview) — what an action is and the hello-world walkthrough
 - [**Defining Actions**](/docs/actions-defining) — `defineAction()` anatomy, schema, and HTTP config
 - [**Run Context**](/docs/actions-run-context) — the `ctx` argument these checks read
-- [**Human-in-the-Loop Approvals**](/docs/human-approval) — the `needsApproval` gate in depth
+- [**Mail template**](/docs/template-mail) — `send-email` is the reference example for `needsApproval`
 - [**Audit Log**](/docs/audit-log) — the automatic who-changed-what trail
 - [**Security**](/docs/security) — `accessFilter`/`assertAccess` and the extension iframe trust boundary
 - [**Sharing**](/docs/sharing) — the framework sharing system these helpers back

package/docs/content/actions-agent-tools.mdx

@@ -0,0 +1,101 @@
+---
+title: "Production Agent Access"
+description: "Control which framework tools and code-execution capabilities a deployed production agent has, through frameworkTools and codeExecution."
+---
+
+# Production Agent Access
+
+## Production Agent Tools {#production-agent-tools}
+
+Production agents get the app's registered actions plus the framework's own
+tools. `frameworkTools` selects which of those framework tools this app exposes.
+Every group defaults to today's behavior, so omitting the option changes
+nothing:
+
+```ts filename="server/plugins/agent-chat.ts"
+export default createAgentChatPlugin({
+  frameworkTools: {
+    database: "read", // "write" | "read" | "off", default "read"
+    extensions: true, // default false
+    sharing: false, // this app has no share surface
+    review: false,
+  },
+});
+```
+
+```ts filename="server/plugins/core-routes.ts"
+export default createCoreRoutesPlugin({
+  extensionTools: true,
+});
+```
+
+`database` and `extensions` accept the values the old top-level flags did:
+
+- `database: "read"`. Default. Registers only `db-schema` and `db-query`.
+  Agents inspect data with SQL but must use typed app actions for writes.
+- `database: "write"` or `true`. Additionally registers `db-exec` and
+  `db-patch` for deliberate raw SQL maintenance. Writes are scoped to the
+  current user/org and schema changes are blocked.
+- `database: "off"` or `false`. Removes raw database tools from the
+  agent surface so the app's actions are the only data access path.
+- `extensions: true`. Opts the app into framework extension-management
+  actions and prompt guidance (`create-extension`, `update-extension`, etc.).
+  Set `extensionTools: true` on the core-routes plugin as well to allow
+  authenticated REST creation. Extensions are disabled by default.
+
+The remaining groups are booleans, all on by default: `sharing`, `review`,
+`history`, `featureFlags`, `localization`, `audit`, `contextXray`,
+`userProfile`, `automation`, `docs`, `resources`, `web`, `workspaceApps`,
+`chat`, and `email`. Use `frameworkTools: "minimal"` to turn every group off at
+once for a voice-first or single-purpose app, or
+`frameworkTools: { preset: "minimal", resources: true }` to keep just one. An
+explicit group key always wins over the preset.
+
+Switching a group off removes it from the **agent** surfaces only: interactive
+chat, MCP, A2A, and background runs. The matching HTTP action routes stay
+mounted, because the UI reaches them through client hooks. Disabling `sharing`
+must not 404 a share dialog that is still on screen. Weigh that parity cost
+before using it: the framework's contract is that anything the UI can do the
+agent can do, so `sharing: false` alongside a visible share button is a
+deliberate break, and only makes sense when the app has no such surface at all.
+
+Framework tools are no longer promoted into the first model request by default,
+independent of this option. They stay in the searchable registry and load
+through `tool-search`, or immediately if the app names them in
+`initialToolNames`.
+
+<Callout tone="warning">
+  The top-level `databaseTools` and `extensionTools` options are deprecated in
+  favor of `frameworkTools.database` and `frameworkTools.extensions`. They are
+  still honored, but setting a top-level flag and its `frameworkTools`
+  equivalent to conflicting values throws at plugin startup rather than booting
+  with a tool surface nobody chose.
+</Callout>
+
+## Production Code Execution {#production-code-execution}
+
+By default, production agents run without code-execution tools. They can call app actions, database tools, MCP tools, browser/session tools, and other registered framework tools, but they do not get shell or filesystem access.
+
+Node-compatible deployments can opt into production code execution through the agent chat plugin or an environment override:
+
+```ts filename="server/plugins/agent-chat.ts"
+export default createAgentChatPlugin({
+  codeExecution: { production: "sandboxed" },
+});
+```
+
+The available modes are:
+
+- `off`. The default. No code-execution tools are registered in production.
+- `sandboxed`. Registers `run-code`, an isolated Node.js JavaScript runner with a scrubbed environment, a fresh temp directory, output/time limits, and a localhost bridge to allowlisted registered tools such as `provider-api-request`, `provider-api-docs`, `provider-api-catalog`, `web-request`, and the Resources-backed workspace file bridge used by `workspaceRead` / `workspaceWrite`.
+- `trusted`. Registers `run-code` plus the full coding tool registry (`bash`, `read`, `edit`, `write`). Use this only for single-tenant or operator-controlled deployments where full shell access to the host is intentional.
+
+Set `AGENT_PROD_CODE_EXECUTION=sandboxed` or `AGENT_PROD_CODE_EXECUTION=trusted` to override the plugin option for a specific deployment without a code change. `AGENT_PROD_CODE_EXECUTION=off` forces code execution off even when the plugin option enables it.
+
+The `run-code` sandbox is process-level isolation, not an OS container. It strips app secrets from the child process environment and uses the Node permission model when available, but outbound network is not blocked by Node itself. Authenticated calls should go through the bridge helpers the tool exposes.
+
+## What's next
+
+- [**Actions: Access & Authorization**](/docs/actions-access-control) — the per-action access-control axes this page's tool-level gating complements
+- [**Updating UI in Production**](/docs/updating-ui-in-production) — what a deployed agent can and can't edit with code execution left off
+- [**Deployment: Environment Variables**](/docs/deployment-environment-variables) — `AGENT_PROD_CODE_EXECUTION` and other production env vars

package/docs/content/actions-defining.mdx

@@ -29,7 +29,7 @@ Every action starts with a call to `defineAction()`. It bundles a description fo
     {
       lines: "12-16",
       label: "One implementation",
-      note: "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this. `getDb()` and `schema` come from your app's `server/db/index.ts`. See [Database](/docs/database).",
+      note: "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this. `getDb()` and `schema` come from your app's `server/db/index.ts`. See [Database](/docs/server-database).",
     },
   ]}
 />
@@ -271,5 +271,5 @@ The repo includes an advisory helper, `node scripts/audit-template-actions.mjs [
 - [**Access & Authorization**](/docs/actions-access-control) — `agentTool`, `toolCallable`, `authorize`, and `ctx` scoping
 - [**Run Context**](/docs/actions-run-context) — the full `ctx` field table
 - [**Other Surfaces**](/docs/actions-other-surfaces) — native chat UI, CLI, A2A, MCP, and standard actions
-- [**Database**](/docs/database) — `getDb()`/`schema` used inside `run()`
+- [**Database**](/docs/server-database) — `getDb()`/`schema` used inside `run()`
 - [**Data & Sync**](/docs/client-data) — calling this action from the UI

package/docs/content/audit-log.mdx

@@ -183,7 +183,7 @@ Configure via environment:
 ## What's next
 
 - [**Actions**](/docs/actions-overview) — the `defineAction` seam where capture happens
-- [**Human-in-the-Loop Approvals**](/docs/human-approval) — gated actions, recorded as `denied`
+- [**Human-in-the-Loop Approvals**](/docs/actions-access-control#needs-approval) — gated actions, recorded as `denied`
 - [**Security & Data Scoping**](/docs/security) — the ownership model audit reads reuse
 - [**Observability**](/docs/observability) — agent-run telemetry (the other "what happened")
 - [**Toolkit piece: History Kit**](/docs/toolkit-history) — the version-history timeline and undo/redo UI built on this trail

package/docs/content/authentication.mdx

@@ -456,7 +456,7 @@ function SignInCta() {
 
 Normal app pages use one impersonal, public-cacheable SSR shell for every visitor. `AppProviders` checks the session on the client; on a private path such as `/dashboard`, it redirects an anonymous visitor to `/sign-in?return=%2Fdashboard` before mounting private app UI. After sign-in, the visitor returns to `/dashboard`. Pass `isPublicPath` for public/SEO routes, or `sessionBypass` for a surface that authenticates through another scoped mechanism such as an MCP embed token.
 
-How long that shell is cached is a deployment-wide setting — see [SSR Caching](/docs/deployment#ssr-caching) for `AGENT_NATIVE_SSR_CACHE`. Shortening or disabling the cache changes duration only; SSR still renders the anonymous branch with cookies stripped.
+How long that shell is cached is a deployment-wide setting — see [SSR Caching](/docs/ssr-caching) for `AGENT_NATIVE_SSR_CACHE`. Shortening or disabling the cache changes duration only; SSR still renders the anonymous branch with cookies stripped.
 
 ### Behind the scenes: Google OAuth
 

package/docs/content/cloudflare.mdx

@@ -0,0 +1,43 @@
+---
+title: "Cloudflare"
+description: "Deploy an agent-native app to Cloudflare Pages or Cloudflare Workers with the matching Nitro preset."
+---
+
+# Cloudflare
+
+## Cloudflare Pages {#cloudflare-pages}
+
+```ts filename="vite.config.ts"
+export default defineConfig({
+  plugins: [agentNative({ nitro: { preset: "cloudflare_pages" } })],
+});
+```
+
+## Cloudflare Workers {#cloudflare-workers}
+
+Use Nitro's native module output for a Cloudflare Worker. This keeps SSR
+enabled and emits the Worker entry point plus static assets under
+`.output/server` and `.output/public`:
+
+```ts filename="vite.config.ts"
+export default defineConfig({
+  plugins: [agentNative({ nitro: { preset: "cloudflare_module" } })],
+});
+```
+
+Build and deploy the generated Worker with Wrangler:
+
+```bash
+npx @agent-native/core@latest build
+npx wrangler deploy --config .output/server/wrangler.json
+```
+
+You can also select the preset explicitly with
+`NITRO_PRESET=cloudflare_module`. Configure a durable external SQL database
+before deploying. A Worker filesystem is not a persistent application store.
+
+## What's next
+
+- [**Deployment**](/docs/deployment) — pick a persistent database and a preset before your first production deploy
+- [**Workspace Deployment**](/docs/workspace-deployment) — Cloudflare Pages is the default preset for the unified `deploy` command
+- [**Node.js & Docker**](/docs/node-docker), [**Vercel**](/docs/vercel), [**Netlify**](/docs/netlify), and [**Other Platforms**](/docs/other-platforms) — the other Nitro presets

package/docs/content/creating-templates.mdx

@@ -238,7 +238,7 @@ export default runMigrations(
 );
 ```
 
-Use the [Database](/docs/database) and [Security](/docs/security) docs before adding schemas that hold user or org data.
+Use the [Database](/docs/server-database) and [Security](/docs/security) docs before adding schemas that hold user or org data.
 
 ## Define Operations As Actions {#actions}