@agent-native/core 0.93.0 → 0.94.1

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 2170
-- template files: 5316
+- core files: 2164
+- template files: 5359

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @agent-native/core
 
+## 0.94.1
+
+### Patch Changes
+
+- bb1e5c8: Prevent delayed errors from older background runs from reappearing after a newer chat response succeeds.
+
+## 0.94.0
+
+### Minor Changes
+
+- dfbbf30: Add scoped relay primitives for computer-capable devices, typed leased operations, durable approvals, replay protection, handle-only live-view events, and bounded binary-safe relay payloads.
+- dfbbf30: Add framework-wide OpenAI Realtime voice conversations with shared agent tools, actions, and navigation.
+- dfbbf30: Add owner-scoped follow-up, approval, denial, resume, and stop lifecycle controls for agent harness sessions.
+
+### Patch Changes
+
+- dfbbf30: Reduce idle hosted request volume by relaxing database sync polling between agent runs, waking event-driven application-state readers only when their values change, and avoiding duplicate action-query invalidation waves.
+- dfbbf30: Keep controlled settings pages in sync with organization hash links.
+- dfbbf30: Agent chat now uses Medium reasoning by default across supported models, migrates legacy Auto selections to Medium, avoids duplicate generic running status while reasoning streams, and renders completed reasoning directly inside the shared work summary.
+- dfbbf30: Allow explicitly marked Agent Native desktop child runs to receive their authenticated loopback computer-control MCP server without replacing user MCP configuration.
+- dfbbf30: Keep the optional server tokenizer out of browser production bundles, publish Dispatch's Operations route, simplify Dispatch's sidebar identity and chat history, and route design-task creation into structured intake.
+- dfbbf30: Honor organization and user Agent engine settings when Slack, Telegram, and other messaging integrations select their model provider and scoped API key.
+- dfbbf30: Group desktop settings navigation into clearer app, agent, workspace, and update sections.
+- dfbbf30: Add a batched application-state read helper so callers can load several exact keys with one database query.
+- dfbbf30: Export reusable composer controls for realtime voice sessions and a guarded single-tool execution helper that preserves normal validation, approval, timeout, journal, redaction, and refresh behavior.
+- dfbbf30: Make the active agent chat stop control immediately recognizable with a high-contrast circular treatment and filled stop icon.
+- dfbbf30: Stop offering Builder's unavailable Gemini 3.1 Flash-Lite preview model in agent chat and normalize existing selections back to the working default model.
+- dfbbf30: Validate converged collaborative text before persistence or broadcast so application-level guards can reject unsafe concurrent merges without exposing transient invalid state to connected clients.
+- dfbbf30: Keep Slack progress cards current during delegated agent calls, accept one scoped reply after requesting clarification, close deferred progress streams cleanly, and reserve framework integration control-plane routes from platform fallback handling.
+- dfbbf30: Enforce fail-closed computer and browser MCP policy checks in read-only Code runs.
+
 ## 0.93.0
 
 ### Minor Changes

package/corpus/core/docs/content/a2a-protocol.mdx

@@ -5,7 +5,13 @@ description: "Agent-to-agent communication via JSON-RPC: discovery, messaging, s
 
 # A2A Protocol
 
-Agent-to-agent communication over HTTP. Agents discover each other, send messages, and receive structured results.
+A2A lets agents talk to each other directly over HTTP: they discover each other's capabilities, send messages, and get back structured results — no shared database or hand-wired API needed.
+
+<Callout tone="info">
+
+**A2A vs MCP.** A2A is for **agent-to-agent** delegation — one agent-native app's agent handing work to another app's agent, which reasons over it with its own LLM loop. [MCP](/docs/mcp-protocol) is for **tool-to-agent** access — an external host like Claude or Cursor calling your app's actions directly as tools, with no extra agent reasoning in between. Use A2A when the receiving side should think; use MCP when it should just execute. See [MCP Server — MCP vs A2A](/docs/mcp-protocol#mcp-vs-a2a) for the full comparison table.
+
+</Callout>
 
 ## Overview {#overview}
 
@@ -159,7 +165,7 @@ All methods are called via `POST /_agent-native/a2a` with JSON-RPC 2.0 format:
 | `tasks/get`      | Fetch a task by ID — used to poll an async task to completion                                                         | `id`                          |
 | `tasks/cancel`   | Cancel a running task                                                                                                 | `id`                          |
 
-<Endpoint id="doc-block-a6g596" title="Primary A2A endpoint" summary="All JSON-RPC methods are POSTed here. message/send shown." method="POST" path="/_agent-native/a2a" summary="Send a message and wait for the completed task" auth="JWT bearer signed with A2A_SECRET (or legacy apiKeyEnv static token)" params={[
+<Endpoint id="doc-block-a6g596" title="Primary A2A endpoint" summary="All JSON-RPC methods are POSTed here. message/send shown." method="POST" path="/_agent-native/a2a" auth="JWT bearer signed with A2A_SECRET (or legacy apiKeyEnv static token)" params={[
   {
     "name": "Authorization",
     "in": "header",
@@ -272,9 +278,11 @@ When `message/send` is called with `async: true`, the JSON-RPC handler enqueues
 
 </Diagram>
 
-> [!IMPORTANT]
-> **Serverless Webhook & Gateway Timeouts:**
-> Hosted environment gateways (such as Netlify, Vercel, or Cloudflare Pages) impose strict execution limits (often 10 to 30 seconds) on public-facing HTTP routes. Because agent loops can take significant time to run queries, fetch context, and execute tools, you **must use `async: true`** when calling A2A endpoints or handling external webhooks. This immediately returns a `working` status to the API gateway, keeping the connection open only for a few milliseconds, while the self-fired `/process-task` POST executes the agent loop in the background. Do not block the primary HTTP request waiting for the agent loop to finish.
+<Callout tone="warning">
+
+**Serverless webhook and gateway timeouts.** Hosted environment gateways (such as Netlify, Vercel, or Cloudflare Pages) impose strict execution limits (often 10 to 30 seconds) on public-facing HTTP routes. Because agent loops can take significant time to run queries, fetch context, and execute tools, you **must use `async: true`** when calling A2A endpoints or handling external webhooks. This immediately returns a `working` status to the API gateway, keeping the connection open only for a few milliseconds, while the self-fired `/process-task` POST executes the agent loop in the background. Do not block the primary HTTP request waiting for the agent loop to finish.
+
+</Callout>
 
 Messages contain typed parts — text, structured data, and files can all travel in one message:
 
@@ -534,3 +542,11 @@ export default defineAction({
 ```
 
 The analytics agent receives the message, runs the query via its handler, and returns the result. The mail action gets the text response back. No shared database, no direct API calls — just agent-to-agent communication.
+
+## What's next {#whats-next}
+
+- [**MCP Server**](/docs/mcp-protocol#mcp-vs-a2a) — the sibling protocol for external tools calling your app directly
+- [**Dispatch**](/docs/dispatch) — the app that routes inbound messages to the right A2A peer
+- [**Messaging**](/docs/messaging) — reaching agents from Slack, email, Telegram, and WhatsApp
+- [**Agent Mentions**](/docs/agent-mentions) — `@`-mentioning a connected agent in chat, which calls A2A under the hood
+- [**Multi-App Workspaces**](/docs/multi-app-workspace) — same-origin workspace A2A with auto-signed credentials

package/corpus/core/docs/content/actions.mdx

@@ -11,7 +11,7 @@ Actions are the single source of truth for anything your app does. Define an act
 - **Typesafe React hooks** — `useActionQuery("name")` and `useActionMutation("name")` on the frontend, types inferred from the schema.
 - **Imperative client calls** — `callAction("name", params)` when a hook does not fit.
 - **Framework transport** — auto-mounted by the framework behind those hooks and available to external HTTP clients.
-- **An MCP tool** — exposed to Claude, ChatGPT custom MCP apps, Claude Desktop/Code, Cursor, Codex, and any other MCP client.
+- **An MCP tool** — exposed to Claude, ChatGPT custom MCP apps, Claude Desktop/Code, Cursor, Codex, and any other MCP host.
 - **An A2A tool** — called by other agent-native apps over A2A.
 - **A CLI command** — `pnpm action <name>` for scripting and dev loops.
 
@@ -146,23 +146,23 @@ around actions, not a required prerequisite for the action itself.
   filename="actions/reply-to-email.ts"
   language="ts"
   code={
-    'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nexport default defineAction({\n  description: "Reply to an email thread in the user\'s voice.",\n  schema: z.object({\n    emailId: z.string().describe("The id of the email to reply to."),\n    body: z.string().describe("The reply body, in markdown."),\n  }),\n  run: async ({ emailId, body }) => {\n    await db.insert(replies).values({ emailId, body });\n    return { ok: true, emailId };\n  },\n});'
+    'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\n\nexport default defineAction({\n  description: "Reply to an email thread in the user\'s voice.",\n  schema: z.object({\n    emailId: z.string().describe("The id of the email to reply to."),\n    body: z.string().describe("The reply body, in markdown."),\n  }),\n  run: async ({ emailId, body }) => {\n    const db = getDb();\n    await db.insert(schema.replies).values({ emailId, body });\n    return { ok: true, emailId };\n  },\n});'
   }
   annotations={[
     {
-      lines: "5",
+      lines: "7",
       label: "Tool surface",
       note: "`description` is what the agent reads to decide when to call this. The per-field `.describe()` calls flow into the JSON Schema too.",
     },
     {
-      lines: "6-9",
+      lines: "8-11",
       label: "Typed contract",
       note: "One schema validates input from **every** surface and is converted to JSON Schema for the model. Invalid inputs never reach `run`.",
     },
     {
-      lines: "10-13",
+      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.",
+      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).",
     },
   ]}
 />
@@ -392,23 +392,9 @@ For list and read actions, use `accessFilter` to scope the query to the current
 
 ### Human-in-the-loop approval {#needs-approval}
 
-A handful of actions are too consequential to let the agent run autonomously — sending an email, charging a card, deleting an account. For those, set `needsApproval` to pause the loop and require a human to approve the specific call before `run()` executes:
+A handful of actions are too consequential to let the agent run autonomously — sending an email, charging a card, 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.
 
-```ts
-export default defineAction({
-  description: "Send an email via Gmail.",
-  schema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
-  needsApproval: true, // pause; a human must approve this specific send
-  run: async (args) => {
-    /* ...actually send... */
-  },
-});
-```
-
-`needsApproval` also accepts a predicate `(args, ctx) => boolean | Promise<boolean>` to gate conditionally (e.g. only external recipients, only above a threshold); it **fails closed**, so a throw counts as "approval required". When the gate is truthy and unapproved, the loop stops the turn and the side effect never fires until a human approves in the chat UI.
-
-> [!WARNING]
-> Keep approvals rare. Each gated action is a hard stop in the agent loop. The default is **off**, and almost every action should leave it off. See [Human-in-the-Loop Approvals](/docs/human-approval) for the predicate API, the `approval_required` event, and the full flow.
+See [Human-in-the-Loop Approvals](/docs/human-approval) for the predicate API, the `approval_required` event, and the full end-to-end flow.
 
 ### Audit logging {#audit}
 
@@ -554,7 +540,7 @@ export default defineAction({
 });
 ```
 
-Keep `link` as the fallback for CLI and non-UI MCP clients; it is also the embed's launch target. The embed bridge — the signed embed-start session, transplant vs. controlled-frame rendering, the `ui/*` host bridge, CSP, and height clamping — is owned by [External Agents](/docs/external-agents#mcp-app-bridge).
+Keep `link` as the fallback for CLI and non-UI MCP hosts; it is also the embed's launch target. The embed bridge — the signed embed-start session, transplant vs. controlled-frame rendering, the `ui/*` host bridge, CSP, and height clamping — is owned by [External Agents](/docs/external-agents#mcp-app-bridge).
 
 ## Standard actions {#standard-actions}
 

package/corpus/core/docs/content/agent-mentions.mdx

@@ -176,11 +176,26 @@ Remote A2A agents still use JSON manifests:
 }
 ```
 
----
+## Referencing files {#referencing-files}
+
+The `@` popover is not limited to agents. You can also reference:
+
+- **Codebase files** — type `@` and search for a filename. The file contents are included in the agent's context so it can read, analyze, or modify the file.
+- **Workspace resources** — reference files defined in the Workspace tab. These can be data files, configuration, or any other structured content.
+
+Selecting a file or resource resolves it into the agent's context when the message is sent, the same way an agent mention does.
+
+Skills use a separate trigger: type `/` instead of `@` to reference a skill. Skills provide structured instructions that guide how the agent approaches a task — see [Skills Guide](/docs/skills-guide) for the full authoring format.
+
+## Sub-agent selection {#sub-agent-selection}
+
+The main agent can also use custom agents when spawning sub-agents with `agent-teams` (action: "spawn").
+
+Pass the `agent` parameter to choose a profile from `agents/*.md`. That profile's instructions are added to the delegated run, and its `model` frontmatter can override the default model for that sub-agent.
 
 ## For developers: extending mentions {#extending-mentions}
 
-Templates can register custom mention providers to add domain-specific mentionable items beyond agents and files. A mention provider implements the `MentionProvider` interface:
+Templates can register custom mention providers to add domain-specific mentionable items beyond agents and files. A mention provider implements the `MentionProvider` interface: a `label` (the section heading shown in the `@` popover) plus a `search(query, event?)` function that returns up to a handful of `MentionProviderItem` matches (`id`, `label`, `description?`, `refType`, `refId?`, `refPath?`, `metadata?`).
 
 <AnnotatedCode
   id="doc-block-159gm13"
@@ -188,28 +203,23 @@ Templates can register custom mention providers to add domain-specific mentionab
   filename="server/mentions/contacts.ts"
   language="ts"
   code={
-    'import type { MentionProvider } from "@agent-native/core/server";\n\nconst contactsProvider: MentionProvider = {\n  id: "contacts",\n  label: "Contacts",\n\n  // Search for mentionable items\n  async search(query: string) {\n    const contacts = await db.query.contacts.findMany({\n      where: like(contacts.name, `%${query}%`),\n      limit: 10,\n    });\n    return contacts.map((c) => ({\n      id: c.id,\n      label: c.name,\n      description: c.email,\n      type: "contact",\n    }));\n  },\n\n  // Resolve a mention into context for the agent\n  async resolve(id: string) {\n    const contact = await db.query.contacts.findFirst({\n      where: eq(contacts.id, id),\n    });\n    return {\n      type: "context",\n      text: `Contact: ${contact.name} (${contact.email})`,\n    };\n  },\n};'
+    'import type { MentionProvider } from "@agent-native/core/server";\nimport { like } from "drizzle-orm";\nimport { getDb, schema } from "../db/index.js";\n\nconst contactsProvider: MentionProvider = {\n  label: "Contacts",\n\n  // Runs as the user types after `@`. Return up to a handful of matches.\n  async search(query) {\n    const db = getDb();\n    const matches = await db\n      .select()\n      .from(schema.contacts)\n      .where(like(schema.contacts.name, `%${query}%`))\n      .limit(10);\n    return matches.map((c) => ({\n      id: c.id,\n      label: c.name,\n      description: c.email,\n      refType: "contact",\n      refId: c.id,\n    }));\n  },\n};'
   }
   annotations={[
     {
-      lines: "4-5",
-      label: "Identity",
-      note: "`id` namespaces the provider; `label` is the section heading shown in the `@` popover.",
+      lines: "5",
+      label: "label",
+      note: "The section heading shown in the `@` popover for this provider's matches.",
     },
     {
-      lines: "8-9",
+      lines: "8-18",
       label: "search",
-      note: "Runs as the user types after `@`. Return up to a handful of matches as `{ id, label, description, type }`.",
-    },
-    {
-      lines: "23-24",
-      label: "resolve",
-      note: 'Called when the message is sent. Turns a picked id into `{ type: "context", text }` that is injected into the agent\'s context.',
+      note: "Runs as the user types after `@`. Return matches as `MentionProviderItem`s — `id`, `label`, `description`, `refType`, `refId`.",
     },
   ]}
 />
 
-Register providers in the agent-chat plugin configuration:
+Register providers in the agent-chat plugin configuration, keyed by provider id:
 
 ```ts
 // server/plugins/agent-chat.ts
@@ -222,20 +232,12 @@ export default createAgentChatPlugin({
 });
 ```
 
-Custom mention providers appear alongside the built-in agent and file providers in the mention popover.
-
-## Referencing files {#referencing-files}
-
-The `@` popover is not limited to agents. You can also reference:
-
-- **Codebase files** — type `@` and search for a filename. The file contents are included in the agent's context so it can read, analyze, or modify the file.
-- **Workspace resources** — reference files defined in the Workspace tab. These can be data files, configuration, or any other structured content.
-- **Skills** — type `/` to reference a skill. Skills provide structured instructions that guide how the agent approaches a task.
+Custom mention providers appear alongside the built-in agent and file providers in the mention popover. When the message is sent, a picked item is added to the agent's context as a compact reference line (`[contact] Jane Doe (id: ...)`), not a fully resolved document — put enough into `label`/`description` for the agent to act, or give it an action to look up the full record by `refId`.
 
-All reference types follow the same pattern: select from the popover, and the referenced content is resolved and injected into the agent's context when the message is sent.
-
-## Sub-agent selection {#sub-agent-selection}
+## What's next {#whats-next}
 
-The main agent can also use custom agents when spawning sub-agents with `agent-teams` (action: "spawn").
-
-Pass the `agent` parameter to choose a profile from `agents/*.md`. That profile's instructions are added to the delegated run, and its `model` frontmatter can override the default model for that sub-agent.
+- [**Using Your Agent**](/docs/using-your-agent) — where mentions fit in the day-to-day loop with the agent
+- [**A2A Protocol**](/docs/a2a-protocol) — how connected-agent mentions are resolved over the wire
+- [**Agent Teams**](/docs/agent-teams) — spawn sub-agents and pass the `agent` profile parameter
+- [**Skills Guide**](/docs/skills-guide) — author the skills referenced with `/`
+- [**Workspace**](/docs/workspace#custom-agents) — the full custom-agent profile format

package/corpus/core/docs/content/agent-native-toolkit.mdx

@@ -93,12 +93,10 @@ coherent kit instead of exposing package boundaries in the app.
 
 ## Foundation Pieces {#foundation-pieces}
 
-- [UI Primitives](/docs/toolkit-ui) cover shared shadcn-style primitives under
-  `@agent-native/toolkit/ui/*`.
-- [App Adapters](/docs/toolkit-app-adapters) show how apps wrap Toolkit pieces
-  through local `@/components/*` adapters.
-- [Shell & Hooks](/docs/toolkit-shell-hooks) cover header actions, mobile hooks,
-  toasts, and small app-shell helpers.
+- [UI Primitives](/docs/toolkit-ui) covers the shared shadcn-style primitives
+  under `@agent-native/toolkit/ui/*`, the local app-adapter pattern every
+  template wraps them in, and the shared shell hooks (header actions, mobile
+  detection, toasts).
 - [Component API](/docs/components) remains the lower-level reference for the
   public React exports.
 
@@ -108,3 +106,14 @@ Use a toolkit when the behavior repeats across apps and users expect it to feel
 standard: sharing, settings, teams, comments, history, and agent progress should
 not be slightly different in every template. Keep domain-specific data,
 workflows, labels, and visual styling in the app.
+
+## What's next
+
+- [**Toolkit UI Primitives**](/docs/toolkit-ui) — the shared primitives, app
+  adapters, and shell hooks every kit builds on.
+- [**Sharing Kit**](/docs/toolkit-sharing) — a good first kit to adopt: ownable
+  resources, share dialogs, and visibility.
+- [**Creating Templates**](/docs/creating-templates) — build a template end to
+  end and see where kits fit alongside your own domain model.
+- [**Component API**](/docs/components) — the generated reference for every
+  public React export, including kit components.

package/corpus/core/docs/content/agent-surfaces.mdx

@@ -139,8 +139,7 @@ pnpm install
 
 Then define the durable operation:
 
-```ts
-// actions/summarize-week.ts
+```ts filename="actions/summarize-week.ts"
 import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
@@ -502,14 +501,11 @@ Keep the contract small: define durable operations as actions, return explicit
 widget results when chat needs rich UI, and add full screens only when users
 need to browse, compare, configure, or collaborate over persistent objects.
 
-## Related docs {#related-docs}
-
-- [Actions](/docs/actions) — define the operation once.
-- [Native Chat UI](/docs/native-chat-ui) — render typed action results in chat.
-- [Generative UI](/docs/generative-ui) — generate transient or persisted sandboxed UI inline in chat.
-- [Drop-in Agent](/docs/drop-in-agent) — mount chat, sidebar, or panel surfaces.
-- [Component API](/docs/components) — lower-level React chat/composer pieces.
-- [Embedding SDK](/docs/embedding-sdk) — add Agent-Native to an existing app.
-- [Automation-First Apps](/docs/pure-agent-apps) — no-browser apps for jobs, queues, scripts, and external agents.
-- [External Agents](/docs/external-agents) — connect MCP-compatible hosts to an app.
-- [A2A Protocol](/docs/a2a-protocol) — call agents from other agents.
+## What's next {#related-docs}
+
+- [**Actions**](/docs/actions) — define the operation once; every surface above calls the same one
+- [**Native Chat UI**](/docs/native-chat-ui) — render typed action results as tables, charts, and cards in chat
+- [**Generative UI**](/docs/generative-ui) — generate transient or persisted sandboxed UI inline in chat
+- [**Automation-First Apps**](/docs/pure-agent-apps) — the full no-browser pattern for jobs, queues, scripts, and external agents
+- [**External Agents**](/docs/external-agents) — connect MCP-compatible hosts to an app
+- [**A2A Protocol**](/docs/a2a-protocol) — call agents from other agent-native apps

package/corpus/core/docs/content/agent-teams.mdx

@@ -239,6 +239,7 @@ interface AgentTask {
   summary: string; // full summary once completed
   currentStep: string; // latest step label (updated while running)
   createdAt: number;
+  delegationDepth?: number; // 1 for a direct sub-agent, 2 for a sub-agent of that sub-agent, etc.
   // Additional fields: parentThreadId, name, updatedAt, startedAt,
   // completedAt, runId, error
 }

package/corpus/core/docs/content/authentication.mdx

@@ -15,7 +15,7 @@ Auth is configured automatically via `autoMountAuth(app)` in the auth server plu
 - **Remote MCP OAuth:** Standard OAuth 2.1 for MCP hosts such as Claude Code and ChatGPT connectors.
 - **Custom:** Bring your own auth via `getSession` callback.
 
-<Diagram id="doc-block-f8rmmq" title="Three ways in, one session" summary="Browser visitors, programmatic MCP clients, and custom providers all resolve to the same AuthSession that downstream scoping reads.">
+<Diagram id="doc-block-f8rmmq" title="Three ways in, one session" summary="Browser visitors, MCP hosts, and custom providers all resolve to the same AuthSession that downstream scoping reads.">
 
 ```html
 <div class="auth-modes">
@@ -293,8 +293,7 @@ Access tokens are signed with `A2A_SECRET` when set, otherwise `BETTER_AUTH_SECR
 
 Pass a custom `getSession` callback to use any auth provider (Clerk, Auth0, Firebase, etc.):
 
-```ts
-// server/plugins/auth.ts
+```ts filename="server/plugins/auth.ts"
 import { createAuthPlugin } from "@agent-native/core/server";
 
 export default createAuthPlugin({
@@ -443,3 +442,11 @@ The default `/_agent-native/google/auth-url` route does this automatically — o
 | `ACCESS_TOKEN`                          | Static bearer fallback for MCP/connect clients; not browser auth                                                                             |
 | `ACCESS_TOKENS`                         | Comma-separated static bearer fallbacks for MCP/connect clients; not browser auth                                                            |
 | `A2A_SECRET`                            | Shared secret for JWT-signed A2A cross-app identity verification and, when present, MCP OAuth access-token signing                           |
+
+## What's next
+
+- [**Multi-Tenancy**](/docs/multi-tenancy) — the org-management surface built on top of `session.orgId`
+- [**Security — Data Scoping**](/docs/security#data-scoping) — the `session.orgId → AGENT_ORG_ID → SQL` pipeline and access guards
+- [**Cross-App SSO**](/docs/cross-app-sso) — sharing sign-in across first-party hosted apps that each have their own auth database
+- [**Sharing**](/docs/sharing) — sharing individual resources between authenticated users and orgs
+- [**MCP Protocol**](/docs/mcp-protocol) — the MCP surface that Remote MCP OAuth authenticates into

package/corpus/core/docs/content/automation-connectors.mdx

@@ -1,55 +1,30 @@
 ---
-title: "Automation connectors"
-description: "Safely connect configured workflow systems without treating them as chat channels or generic provider APIs."
+title: "Workflow Connectors"
+description: "Invoke pre-configured external workflow systems like n8n and Zapier by a stable workflow ID, and accept their authenticated callbacks — without treating them as chat channels or generic provider APIs."
 ---
 
-# Automation connectors
+# Workflow Connectors
 
-Automation systems coordinate work. They are not messaging channels, and they are not a generic provider-data API.
+Reach for workflow connectors when you already have an automation platform — n8n, Zapier, or a similar workflow system — that should run a specific, pre-configured job on request, and hand a result back safely. An action passes a workflow ID and structured input; the workflow runs; the result (or a callback later) comes back through an authenticated, size-bounded path. Neither side ever sees a raw secret or an arbitrary URL.
 
-Agent Native's automation connector runtime has two intentionally small directions:
+This is deliberately narrower than a general-purpose HTTP client or a chat integration. Agent Native's automation connector runtime supports exactly two directions:
 
 - Invoke a **configured external workflow** from an action.
 - Receive an **authenticated callback** from a configured workflow.
 
 An app assigns each workflow a stable ID, a connector ID, input/output schemas, response behavior, credentials, timeout/retry limits, idempotency behavior, and capability flags. Agents pass the workflow ID and structured input; they never supply arbitrary target URLs or secret values.
 
-## Safety model
+<Callout tone="info">
 
-Outbound workflow definitions use a static HTTPS base URL and static path. The runtime restricts requests to the configured origin, rejects private-network targets and redirects, resolves `${keys.NAME}` server-side, bounds request and response sizes, applies a timeout, retries only transient failures, and redacts resolved values from responses and errors.
-
-Workflow callbacks authenticate with either a shared secret, an HMAC-SHA256 signature, or an app-owned provider verifier. Callbacks that start agent work must provide:
-
-1. A durable, SQL-backed idempotency claim keyed by the provider event ID.
-2. A durable queue handoff that runs in a fresh execution.
-
-The callback returns an acknowledgement quickly. Never run an agent loop inside a webhook request or rely on an in-memory deduplication map.
+**Not a messaging channel, not a generic provider API.** For "ask the agent to run a scheduled or event-triggered prompt," see [Automations](/docs/automations) — that's `web-request` calling an ad-hoc URL the agent or a user configured. For "talk to the agent from Slack/email," see [Messaging](/docs/messaging). Workflow connectors are for the third case: a pre-configured, schema-typed connection to an external workflow system your team already runs.
 
-## n8n
+</Callout>
 
-n8n is runtime-backed through configured Webhook workflows. Agent Native does **not** host or provision n8n.
-
-Configure an n8n Webhook node with an explicit URL and one of n8n's supported authentication modes (Header, Basic, or JWT), then register that static URL/origin and the matching Agent Native secret reference. n8n supports immediate responses, final-node responses, and responses via a Respond to Webhook node; model the selected behavior as asynchronous or synchronous in the workflow definition.
-
-For callbacks from n8n into Agent Native, configure an Agent Native callback URL and a shared-secret or HMAC adapter. Include a stable event ID header whenever n8n can retry delivery.
-
-See the [n8n Webhook documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/).
+## Worked example: notify Slack via n8n {#worked-example}
 
-## Zapier
+An app that wants to hand a "notify sales" job to an n8n workflow defines it once, then invokes it by ID — never by URL:
 
-Zapier is currently **blueprint-only** in the integration catalog. There is no generic Zapier workflow execution API in this runtime, and Zapier must not be presented as a chat channel or a provider-api preset.
-
-Zapier REST Hook triggers are an app-integration contract: an app implements subscribe and unsubscribe endpoints, stores Zapier's unique target URL, and delivers events to that URL. A static inbound webhook is not a public Zapier REST Hook integration.
-
-Zapier MCP is a separately configured remote MCP connection with a Zapier account and its own authorization flow. It is not interchangeable with an Agent Native workflow callback credential.
-
-See [Zapier REST Hook triggers](https://docs.zapier.com/integrations/build/hook-trigger) and [Zapier MCP](https://docs.zapier.com/mcp/home).
-
-## App setup
-
-Create a runtime and expose only the narrow action:
-
-```ts
+```ts filename="server/plugins/automation-connectors.ts"
 import {
   createAutomationRuntime,
   createInvokeAutomationWorkflowAction,
@@ -57,7 +32,35 @@ import {
 
 const automation = createAutomationRuntime({
   workflows: [
-    /* app-owned static workflow definitions */
+    {
+      id: "notify-sales-slack",
+      connectorId: "n8n",
+      name: "Notify #sales on qualified lead",
+      inputSchema: {
+        type: "object",
+        properties: {
+          leadEmail: { type: "string" },
+          company: { type: "string" },
+        },
+        required: ["leadEmail"],
+      },
+      response: { mode: "asynchronous" },
+      capabilities: {
+        invokesExternalWorkflow: true,
+        receivesCallback: false,
+        supportsIdempotency: false,
+        supportsSynchronousResponse: false,
+        supportsAsynchronousResponse: true,
+        mayCauseExternalSideEffects: true,
+      },
+      outbound: {
+        baseUrl: "https://n8n.example.com",
+        path: "/webhook/notify-sales",
+        method: "POST",
+        headers: { Authorization: "Bearer ${keys.N8N_WEBHOOK_TOKEN}" },
+        timeoutMs: 10_000,
+      },
+    },
   ],
   resolveSecret: async (ref, context) => {
     // Resolve a scoped vault/credential reference here. Never return it to UI.
@@ -75,6 +78,46 @@ const automation = createAutomationRuntime({
 export default createInvokeAutomationWorkflowAction(automation);
 ```
 
-Mount callback handlers only under `/_agent-native/automations/`; all normal app operations remain actions. Keep the callback route minimal: authenticate, claim idempotency, enqueue, and acknowledge.
+The agent calls this action with `{ workflowId: "notify-sales-slack", input: { leadEmail: "jane@acme.com" } }` — it never sees `https://n8n.example.com/webhook/notify-sales` or the bearer token. `outbound.baseUrl` + `outbound.path` are static, app-owned config; the runtime rejects any attempt to call a different origin.
+
+Mount callback handlers only under `/_agent-native/automations/`; all normal app operations remain actions. Keep the callback route minimal: authenticate, claim idempotency, enqueue, and acknowledge — never run an agent loop inside the webhook request itself.
+
+The client calls a registered action with `invokeConfiguredAutomationWorkflow()` from `@agent-native/core/client`; it does not hand-write a browser `fetch`.
+
+## Safety model {#safety-model}
+
+Outbound workflow definitions use a static HTTPS base URL and static path. The runtime restricts requests to the configured origin, rejects private-network targets and redirects, resolves `${keys.NAME}` server-side, bounds request and response sizes, applies a timeout, retries only transient failures, and redacts resolved values from responses and errors.
+
+Workflow callbacks authenticate with either a shared secret, an HMAC-SHA256 signature, or an app-owned provider verifier. Callbacks that start agent work must provide:
+
+1. A durable, SQL-backed idempotency claim keyed by the provider event ID.
+2. A durable queue handoff that runs in a fresh execution.
+
+The callback returns an acknowledgement quickly. Never run an agent loop inside a webhook request or rely on an in-memory deduplication map. This is the same queue-and-processor pattern [Messaging](/docs/messaging) uses for inbound platform webhooks — link rather than restate if you're already familiar with that page.
+
+## n8n {#n8n}
+
+n8n is runtime-backed through configured Webhook workflows. Agent Native does **not** host or provision n8n.
+
+Configure an n8n Webhook node with an explicit URL and one of n8n's supported authentication modes (Header, Basic, or JWT), then register that static URL/origin and the matching Agent Native secret reference. n8n supports immediate responses, final-node responses, and responses via a Respond to Webhook node; model the selected behavior as asynchronous or synchronous in the workflow definition.
+
+For callbacks from n8n into Agent Native, configure an Agent Native callback URL and a shared-secret or HMAC adapter. Include a stable event ID header whenever n8n can retry delivery.
+
+See the [n8n Webhook documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/).
+
+## Zapier {#zapier}
+
+Zapier is currently **blueprint-only** in the integration catalog. There is no generic Zapier workflow execution API in this runtime, and Zapier must not be presented as a chat channel or a provider-api preset.
+
+Zapier REST Hook triggers are an app-integration contract: an app implements subscribe and unsubscribe endpoints, stores Zapier's unique target URL, and delivers events to that URL. A static inbound webhook is not a public Zapier REST Hook integration.
+
+Zapier MCP is a separately configured remote MCP connection with a Zapier account and its own authorization flow. It is not interchangeable with an Agent Native workflow callback credential.
+
+See [Zapier REST Hook triggers](https://docs.zapier.com/integrations/build/hook-trigger) and [Zapier MCP](https://docs.zapier.com/mcp/home).
+
+## What's next {#whats-next}
 
-The client can call a registered action with `invokeConfiguredAutomationWorkflow()` from `@agent-native/core/client`; it does not hand-write a browser `fetch`.
+- [**Automations**](/docs/automations#web-request) — the ad-hoc `web-request` tool for one-off outbound HTTP, the lighter-weight sibling to a configured connector
+- [**Messaging**](/docs/messaging) — reaching the agent from Slack, email, Telegram, and WhatsApp, the queue-and-processor pattern this page's callbacks reuse
+- [**Actions**](/docs/actions) — `defineAction`, `needsApproval`, and the action surface `createInvokeAutomationWorkflowAction` builds on
+- [**Security**](/docs/security) — `${keys.NAME}` secret substitution and the credential-scoping model this runtime relies on

package/corpus/core/docs/content/automations.mdx

@@ -140,7 +140,9 @@ Integrations register events at module load time. The bus validates payloads aga
 
 Call `manage-automations` with `action=list-events` from the agent to see all registered events with descriptions and payload schemas for the current template.
 
-### Emitting custom events {#emitting-events}
+### Emitting custom events (for developers) {#emitting-events}
+
+The rest of this page is written for the person asking the agent to create automations. Registering a new event type is a code-level change a template developer makes so users and the agent have something to trigger on.
 
 Register an event type in a server plugin, then emit it from actions or webhook handlers:
 
@@ -185,7 +187,12 @@ Conditions are natural-language strings evaluated by Claude Haiku against the ev
 - **Empty or missing condition** = unconditional (always fires).
 - Results are memoized (SHA-256 of condition + payload) with a 5-minute TTL and 500-entry LRU cache.
 - Payload is truncated to 4000 characters before sending to Haiku.
-- On API failure, the condition evaluates to `false` (safe default — the automation is skipped).
+
+<Callout tone="info">
+
+On API failure, the condition evaluates to `false` (safe default — the automation is skipped rather than run on an unverified condition).
+
+</Callout>
 
 Examples of conditions:
 
@@ -197,6 +204,12 @@ Examples of conditions:
 
 Automations use the `web-request` tool for outbound HTTP. It supports `${keys.NAME}` placeholders in the URL, headers, and body:
 
+<Callout tone="info">
+
+**Ad-hoc HTTP vs configured workflow systems.** `web-request` calls whatever URL an ad-hoc key resolves to — good for a one-off webhook the agent or a user wires up. If you need a pre-configured, schema-typed connection to an external workflow system like n8n or Zapier — with idempotent callbacks and static allowed origins instead of arbitrary URLs — see [Workflow Connectors](/docs/automation-connectors) instead.
+
+</Callout>
+
 ```
 POST to ${keys.SLACK_WEBHOOK}
 
@@ -359,7 +372,7 @@ Confirm an automation's wiring and condition without waiting for a real provider
 Ask the plan agent: _"When someone adds a human comment on a plan, POST a
 notification to my webhook."_
 
-```yaml
+```yaml filename="jobs/notify-on-plan-comment.md"
 ---
 triggerType: event
 event: plan.commented
@@ -383,5 +396,6 @@ for the full `plan.commented` payload reference and all four plan events.
 
 - [**Recurring Jobs**](/docs/recurring-jobs) — schedule-triggered automations reuse the same scheduler
 - [**Actions**](/docs/actions) — automations can call any registered action via the agent loop
+- [**Workflow Connectors**](/docs/automation-connectors) — pre-configured n8n/Zapier-style workflow invocation, for when ad-hoc `web-request` isn't a strict enough contract
 - [**Security**](/docs/security) — input validation and secret handling
 - [**Visual Plans — Events**](/docs/template-plan#events) — plan events reference and automation recipes

package/corpus/core/docs/content/blueprint-installer.mdx

@@ -5,8 +5,12 @@ description: "agent-native add prints a curated Markdown integration recipe to s
 
 # Blueprint Installer
 
-> **Who is this for:** host authors and integrators adding a provider, channel,
-> sandbox backend, or action to a repo by piping a recipe into their coding agent.
+<Callout id="doc-block-bpin1who" tone="info">
+
+**Who is this for:** host authors and integrators adding a provider, channel,
+sandbox backend, or action to a repo by piping a recipe into their coding agent.
+
+</Callout>
 
 `agent-native add` is **not** a dumb scaffolder that writes files for you. It emits a curated Markdown _integration blueprint_ to stdout. You pipe that blueprint into your own coding agent (Claude Code, Codex, …), which applies the changes against the live repo with full context.
 
@@ -111,8 +115,11 @@ Write each blueprint as an instruction set for a coding agent with no other cont
 4. **Framework rules to honor** — actions-first, no hardcoded secrets, scope ownable data, add a changeset for publishable-package source.
 5. **Verify** — typecheck, a focused `*.spec.ts`, and an end-to-end check.
 
-> [!TIP]
-> A new curated blueprint under an existing kind needs no code — but if you create a brand-new kind directory, that kind shows up in `--list` automatically too.
+<Callout id="doc-block-bpin1tip" tone="info">
+
+A new curated blueprint under an existing kind needs no code — but if you create a brand-new kind directory, that kind shows up in `--list` automatically too.
+
+</Callout>
 
 ## What's next