@agent-native/core 0.169.0 → 0.170.0

package/dist/shared/surface-visibility.js

@@ -0,0 +1,57 @@
+/**
+ * Host-declared surface visibility.
+ *
+ * An Electron `<webview>` guest never reports itself hidden: hiding the element
+ * or any ancestor leaves `document.visibilityState === "visible"` and never
+ * fires `visibilitychange`, so every visibility-based pause in this package is
+ * inert inside the desktop shell. A backgrounded app tab there keeps polling at
+ * its full foreground cadence and holds its event stream open for as long as
+ * the shell is running. The host therefore has to say so explicitly, and this
+ * flag is what background work must consult instead of the document alone.
+ */
+export const SURFACE_HIDDEN_FLAG = "__agentNativeSurfaceHidden";
+/** Dispatched on `window` whenever the host flips the flag. */
+export const SURFACE_VISIBILITY_EVENT = "agentnative:surfacevisibilitychange";
+/** Whether an embedding host has declared this surface off screen. */
+export function isHostSurfaceHidden() {
+    if (typeof window === "undefined")
+        return false;
+    return (window[SURFACE_HIDDEN_FLAG] === true);
+}
+/**
+ * Whether this surface is off screen by either signal. A host that has stashed
+ * the surface entirely is a stronger statement than a backgrounded browser tab,
+ * so callers that keep working while merely backgrounded should still stop on
+ * `isHostSurfaceHidden()`.
+ */
+export function isSurfaceHidden() {
+    if (isHostSurfaceHidden())
+        return true;
+    return (typeof document !== "undefined" && document.visibilityState === "hidden");
+}
+/** Subscribe to both visibility signals. Returns an unsubscribe function. */
+export function addSurfaceVisibilityListener(handler) {
+    if (typeof document === "undefined" || typeof window === "undefined") {
+        return () => { };
+    }
+    document.addEventListener("visibilitychange", handler);
+    window.addEventListener(SURFACE_VISIBILITY_EVENT, handler);
+    return () => {
+        document.removeEventListener("visibilitychange", handler);
+        window.removeEventListener(SURFACE_VISIBILITY_EVENT, handler);
+    };
+}
+/**
+ * Script a host embedder evaluates inside the guest to declare whether the
+ * surface it is hosting is on screen. Kept here so the flag name, the event
+ * name, and the write that sets them cannot drift apart across packages.
+ */
+export function buildSurfaceVisibilityScript(hidden) {
+    return `(() => {
+  const next = ${hidden ? "true" : "false"};
+  if (window[${JSON.stringify(SURFACE_HIDDEN_FLAG)}] === next) return next;
+  window[${JSON.stringify(SURFACE_HIDDEN_FLAG)}] = next;
+  window.dispatchEvent(new Event(${JSON.stringify(SURFACE_VISIBILITY_EVENT)}));
+  return next;
+})()`;
+}

package/dist/templates/chat/.agents/skills/secrets/SKILL.md

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

package/dist/templates/chat/app/routes.ts

@@ -1,4 +1,6 @@
 import { type RouteConfig } from "@react-router/dev/routes";
 import { flatRoutes } from "@react-router/fs-routes";
 
-export default flatRoutes() satisfies RouteConfig;
+export default flatRoutes({
+  ignoredRouteFiles: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
+}) satisfies RouteConfig;

package/dist/templates/chat/vitest.config.ts

@@ -11,4 +11,12 @@ export default defineConfig({
       "@shared": path.resolve(__dirname, "./shared"),
     },
   },
+  test: {
+    exclude: [
+      "**/node_modules/**",
+      "**/.git/**",
+      "**/dist/**",
+      "**/.react-router/**",
+    ],
+  },
 });

package/dist/templates/default/.agents/skills/secrets/SKILL.md

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

package/dist/templates/default/app/routes.ts

@@ -1,4 +1,6 @@
 import { type RouteConfig } from "@react-router/dev/routes";
 import { flatRoutes } from "@react-router/fs-routes";
 
-export default flatRoutes() satisfies RouteConfig;
+export default flatRoutes({
+  ignoredRouteFiles: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
+}) satisfies RouteConfig;

package/dist/templates/headless/.agents/skills/secrets/SKILL.md

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

package/dist/templates/workspace-core/.agents/skills/secrets/SKILL.md

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

package/dist/tracking/registry.d.ts

@@ -8,6 +8,17 @@ export interface TrackingMeta {
     anonymousId?: string;
     /** Overrides the ambient request's browser session. */
     sessionId?: string;
+    /**
+     * When the event actually happened, in epoch ms. Defaults to now.
+     *
+     * Needed by callers that buffer and flush a batch of events at the end of a
+     * unit of work — an agent run emits its trace, generation, and tool spans in
+     * one burst, and stamping all of them with the flush time collapses a
+     * multi-second waterfall into a single instant. PostHog orders an LLM trace
+     * tree by event timestamp, so without this the tree renders with a synthetic
+     * timeline.
+     */
+    occurredAt?: number;
 }
 /**
  * Who an event is attributed to. Pass an action's `ctx` straight through —

package/dist/tracking/registry.js

@@ -42,10 +42,11 @@ function resolveTrackingSource(source) {
         userId: source.userId,
         anonymousId: source.anonymousId,
         sessionId: source.sessionId ?? ambientSessionId,
+        occurredAt: source.occurredAt,
     };
 }
 export function track(name, properties, source) {
-    const { userId, anonymousId, sessionId } = resolveTrackingSource(source);
+    const { userId, anonymousId, sessionId, occurredAt } = resolveTrackingSource(source);
     const clientPlatform = getRequestContext()?.clientPlatform;
     const trackedProperties = {
         ...(properties ?? {}),
@@ -57,7 +58,9 @@ export function track(name, properties, source) {
     const event = {
         name,
         properties: trackedProperties,
-        timestamp: new Date().toISOString(),
+        // A caller-supplied `occurredAt` of 0 is not a real event time, so `||`
+        // rather than `??` is deliberate here.
+        timestamp: new Date(occurredAt || Date.now()).toISOString(),
         userId,
         anonymousId,
         sessionId,

package/dist/triggers/actions.js

@@ -301,12 +301,15 @@ async function handleRunNow(args, getCurrentUser, appId, context) {
         return "Error: an automation cannot run another automation.";
     }
     try {
+        const path = typeof args.path === "string" ? args.path.trim() : "";
+        const name = typeof args.name === "string" ? args.name : "";
         const result = await queueAutomationRunNow({
             userEmail: getCurrentUser(),
             orgId: getRequestOrgId(),
             appId,
             scope: automationScope(args.scope),
-            name: typeof args.name === "string" ? args.name : "",
+            ...(path ? { path } : { name }),
+            requestHeaders: context?.requestHeaders,
         });
         return JSON.stringify(result);
     }
@@ -340,7 +343,7 @@ export function createAutomationToolEntries(getCurrentUser, appId) {
 - **update**: Update an existing automation's settings without changing its creator (enabled, schedule, timezone, condition, body, policy, model, execution host, MCP allowlist). Required param: name. Use the same scope it was created in.
 - **delete**: Delete an automation. Always confirm with the user first. Required param: name.
 - **fire-test**: Fire a test event to validate automations. Emits a test.event.fired event. Optional param: data (JSON string).
-- **run-now**: Run one automation immediately using its real actions and side effects. This is an explicit user-authorized run and returns a durable run id; it does not change the automation's next scheduled run. Required params: name; optional scope.`,
+- **run-now**: Run one automation immediately using its real actions and side effects. This is an explicit user-authorized run and returns a durable run id; it does not change the automation's next scheduled run. Required params: name or path (not both); optional scope. Use path for automations nested under jobs/ (for example jobs/factories/<id>/factory-slack-feedback.md); those names contain a slash and cannot round-trip through name.`,
                 parameters: {
                     type: "object",
                     properties: {
@@ -351,7 +354,11 @@ export function createAutomationToolEntries(getCurrentUser, appId) {
                         },
                         name: {
                             type: "string",
-                            description: "Slug name for the automation (lowercase, hyphens). Used by define, update, delete, and run-now.",
+                            description: "Slug name for the automation (lowercase, hyphens). Used by define, update, delete, and run-now for flat automations. For nested automations, pass path to run-now instead.",
+                        },
+                        path: {
+                            type: "string",
+                            description: "Full jobs resource path (jobs/...md) for a nested automation. Use with run-now instead of name when the automation name contains a slash.",
                         },
                         scope: {
                             type: "string",

package/dist/usage/store.js

@@ -207,6 +207,17 @@ export async function ensureUsageTable() {
                 // Probe pg_indexes first (no lock) and skip the SHARE-locking CREATE
                 // INDEX when the index is already present.
                 await ensureIndexExists("idx_token_usage_owner_created", `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`);
+                // `owner_email` is written as the caller supplied it, so the metrics
+                // queries scope with `LOWER(owner_email) IN (…)`. A plain btree cannot
+                // serve a function-wrapped predicate: without this expression index the
+                // usage panel scans the whole table, which is the highest-row-count one
+                // in the system (a row per LLM call, every app and org).
+                // NOT built CONCURRENTLY. This runs at release over the pooled Neon
+                // endpoint, and a transaction-pooled connection cannot carry
+                // `CREATE INDEX CONCURRENTLY` to completion — it returns without
+                // creating the index, which then fails the verifying probe and blocks
+                // the whole release. The SHARE lock is the cost of a build that lands.
+                await ensureIndexExists("idx_token_usage_lower_owner_created", `CREATE INDEX IF NOT EXISTS idx_token_usage_lower_owner_created ON token_usage (LOWER(owner_email), created_at)`);
                 return;
             }
             // SQLite (local dev): no lock problem — keep the original behaviour.
@@ -226,10 +237,19 @@ export async function ensureUsageTable() {
             // the `Date.now()` written per run by recordUsage() overflows int4. Widen
             // it in place (no-op once done / on fresh BIGINT databases).
             await widenIntColumnsToBigInt("token_usage", ["created_at"]);
-            try {
-                await client.execute(`CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`);
+            for (const ddl of [
+                `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`,
+                `CREATE INDEX IF NOT EXISTS idx_token_usage_lower_owner_created ON token_usage (LOWER(owner_email), created_at)`,
+            ]) {
+                try {
+                    await client.execute(ddl);
+                }
+                catch {
+                    // coercion-ok: index already exists, or this dialect rejected the
+                    // duplicate. Local-dev SQLite only — the hosted path creates these
+                    // through the Postgres branch above, which probes before creating.
+                }
             }
-            catch { }
         })().catch((err) => {
             // Retry init on the next call after a failed startup.
             _initPromise = undefined;

package/dist/user-profile/actions/get-auth-methods.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { defineAction } from "../../action.js";
-import { getBetterAuth } from "../../server/better-auth-instance.js";
+import { getBetterAuthInternalAdapter } from "../../server/better-auth-instance.js";
 export default defineAction({
     description: "Get the signed-in user's available authentication methods.",
     schema: z.object({}),
@@ -11,12 +11,25 @@ export default defineAction({
         if (!ctx?.userEmail || !ctx.requestHeaders) {
             throw new Error("Not authenticated.");
         }
-        const auth = await getBetterAuth();
-        const accounts = await auth.api.listUserAccounts({
-            headers: ctx.requestHeaders,
+        // Look accounts up by the framework-resolved ctx.userEmail through
+        // Better Auth's internal adapter rather than replaying ctx.requestHeaders
+        // through auth.api.listUserAccounts: that call re-derives identity from
+        // its own cookie-based session lookup, which throws for any caller the
+        // framework authenticated without a Better Auth session cookie (an
+        // AUTH_DISABLED dev session, a BYOA identity, ...) even though
+        // ctx.userEmail is already a trustworthy resolved identity. An unresolved
+        // adapter means the auth backend couldn't be read at all and must fail
+        // loudly — only a resolved adapter finding no matching user record means
+        // there is no Better Auth credential to report.
+        const adapter = await getBetterAuthInternalAdapter();
+        if (!adapter) {
+            throw new Error("Better Auth internal adapter is unavailable.");
+        }
+        const existing = await adapter.findUserByEmail(ctx.userEmail, {
+            includeAccounts: true,
         });
         return {
-            hasPassword: accounts.some((account) => account.providerId === "credential"),
+            hasPassword: existing?.accounts.some((account) => account.providerId === "credential") ?? false,
         };
     },
 });

package/dist/vite/client.js

@@ -1457,10 +1457,17 @@ function frameworkDevDynamicForwarder() {
                             ? `text/html,${accept}`
                             : "text/html";
                     }
-                    // Embed-start uses document/iframe to select its transplant response.
-                    // Only supply the classifier hint when the browser did not provide a
-                    // destination; never overwrite the request's original intent.
-                    if (req.headers["sec-fetch-dest"] === undefined) {
+                    // Embed-start uses document/iframe to select its transplant response,
+                    // and Nitro's own dev classifier already treats document/iframe/frame
+                    // as non-asset, so those (and an already-"empty" value) pass through
+                    // untouched. Everything else — undefined, or a real browser's
+                    // destination for a fetch this route never anticipated, like
+                    // "speculationrules" for the native Speculation-Rules auto-fetch —
+                    // gets normalized to "empty" so Nitro's classifier falls back to its
+                    // extension check instead of treating the request as a static asset.
+                    const fetchDest = req.headers["sec-fetch-dest"];
+                    if (fetchDest === undefined ||
+                        !/^(document|iframe|frame|empty)$/.test(String(fetchDest))) {
                         req.headers["sec-fetch-dest"] = "empty";
                     }
                 }
@@ -1960,6 +1967,18 @@ function rolldownInputFix() {
  * The template lists the packages in its `defineConfig({ ssrStubs })` call —
  * the framework never hardcodes package names.
  */
+/**
+ * Optional peers reached only through a `React.lazy` boundary whose module body
+ * guards on `typeof window === "undefined"`. The server can never import them,
+ * so their SSR chunk is pure unpack weight in every app that ships a terminal
+ * surface. Defaulted here rather than repeated in sixteen vite configs, where
+ * it would drift.
+ */
+const ALWAYS_SSR_STUBBED = [
+    "@xterm/xterm",
+    "@xterm/addon-fit",
+    "@xterm/addon-web-links",
+];
 function ssrStubPlugin(packages) {
     if (!packages.length)
         return null;
@@ -2729,7 +2748,7 @@ function createAgentNativePlugins(options, { command, includeReactTransform, use
         // don't bloat the edge worker. Opt-in per template — the framework
         // hardcodes nothing (e.g. docs sites legitimately import `shiki` on
         // the server, so we can't blanket-stub it here).
-        ssrStubPlugin(options.ssrStubs ?? []),
+        ssrStubPlugin([...ALWAYS_SSR_STUBBED, ...(options.ssrStubs ?? [])]),
         ...userPlugins,
         appChangelogRawPlugin(),
         actionTypesPlugin(),

package/docs/content/actions-access-control.mdx

@@ -1,25 +1,26 @@
 ---
 title: "Access & Authorization"
-description: "Who can call an action: exposure flags (agentTool, toolCallable), ctx-based scoping, accessFilter/assertAccess, and the authorize guard."
+description: "Who can call an action: exposure flags (agentTool, mcpTool, toolCallable), ctx-based scoping, accessFilter/assertAccess, and the authorize guard."
 ---
 
 # Access & Authorization
 
-Five settings decide who can call an action: the agent, the frontend, an extension, an outside API caller, or nobody without a human's approval first. Most actions never need to touch any of these, since the defaults already fit normal UI-and-agent use.
+Six settings decide who can call an action: the agent, the frontend, an extension, an outside API caller, or nobody without a human's approval first. Most actions never need to touch any of these, since the defaults already fit normal UI-and-agent use.
 
 ### Exposure flags {#exposure-flags}
 
-All five flags default to the permissive value, so you only set one when you need to tighten a specific surface. The table below is a quick summary. The sections after it add the one detail each flag needs.
+All six default to the permissive value — `mcpTool` by inheriting `agentTool` — so you only set one when you need to tighten a specific surface. The table below is a quick summary. The sections after it add the one detail each flag needs.
 
 | Flag            | Default       | Restrictive value → who can still call                                      | Typical use                                                          |
 | --------------- | ------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------- |
 | `agentTool`     | `true`        | `false` → UI, HTTP, and CLI only (hidden from the model, MCP, and A2A)      | UI-only or programmatic actions that shouldn't take up a tool slot   |
+| `mcpTool`       | `agentTool`   | `false` → your own app's agent only (hidden from MCP and A2A)               | Actions that need an in-app screen or session on the other end       |
 | `toolCallable`  | `true`        | `false` → everything **except** the sandboxed extension iframe bridge (403) | Sensitive account or org changes (delete account, change membership) |
 | `publicAgent`   | off (private) | `{ expose: true }` → adds the action to **public** MCP/A2A/OpenAPI surfaces | Safe read or ingest tools that don't require authentication          |
 | `needsApproval` | `false`       | `true` → the agent **pauses**, and a human must approve the specific call   | Consequential side effects (send email, charge a card, delete)       |
 | `authorize`     | none          | a guard function → only callers it accepts, on **every** surface            | Operations restricted to a role (per-app RBAC, admin-only ops)       |
 
-These flags are independent, so setting one doesn't change the others. `agentTool` controls what the model sees, see [Hide from the model](#agent-tool) below. `toolCallable` controls only the extension iframe, see [Block extension iframes](#tool-callable) below. `publicAgent` adds an opt-in public surface, and a public web route never implies public tool exposure, see [Expose to public agents](#public-agent) below. `needsApproval` gates execution after the call is already made, see [Require human approval](#needs-approval) below. `authorize` decides whether this caller may run the action at all, on every dispatch path, before `run()` is entered, see [Restrict callers by role](#authorize) below.
+These flags are independent, with one exception: an undeclared `mcpTool` inherits `agentTool`. `agentTool` controls what the model sees, see [Hide from the model](#agent-tool) below. `mcpTool` narrows that to outside agents only, see [Hide from external agents](#mcp-tool) below. `toolCallable` controls only the extension iframe, see [Block extension iframes](#tool-callable) below. `publicAgent` adds an opt-in public surface, and a public web route never implies public tool exposure, see [Expose to public agents](#public-agent) below. `needsApproval` gates execution after the call is already made, see [Require human approval](#needs-approval) below. `authorize` decides whether this caller may run the action at all, on every dispatch path, before `run()` is entered, see [Restrict callers by role](#authorize) below.
 
 ## Hide from the model {#agent-tool}
 
@@ -39,6 +40,44 @@ export default defineAction({
 
 Use this when you add a UI-only or purely programmatic action, or when the UI stops using an action that would otherwise stay exposed to the model.
 
+## Hide from external agents {#mcp-tool}
+
+`agentTool` is all-or-nothing: an action is a tool for every agent, or for none. `mcpTool` splits that in two, so an action can stay a normal tool for your own app's agent while never reaching Claude, Cursor, or a sibling app over MCP and A2A:
+
+```ts
+export default defineAction({
+  description: "Open the record inspector beside the current selection.",
+  mcpTool: false, // needs a live screen on the other end
+  schema: z.object({ recordId: z.string() }),
+  run: async ({ recordId }) => {
+    /* ... */
+  },
+});
+```
+
+Use it for actions whose result only means something with your app's UI, an open session, or the current selection in front of the caller. `mcpTool` can only narrow `agentTool`, never widen it: an action with `agentTool: false` stays hidden everywhere. It governs the external tool surface itself, not what your own agent may do while answering an `ask_app` question — that run is your agent's, and it keeps its whole tool list.
+
+Left undeclared, `mcpTool` follows `agentTool` rather than defaulting to a flat `true`, so hiding an action from the agent hides it from outside agents too and one flag stays one decision.
+
+The opposite value has a second job. External agents are served a small, curated catalog by default rather than your whole action registry, and `mcpTool: true` is how an action declares itself part of it:
+
+```ts
+export default defineAction({
+  description: "List the databases connected to this workspace.",
+  mcpTool: true, // served to external agents, not just discoverable
+  http: { method: "GET" },
+  run: async () => {
+    /* ... */
+  },
+});
+```
+
+This is the same catalog as the plugin's `mcp: { connectorCatalog: [...] }` list, declared on the action instead of in a separate array that has to be kept in sync as actions are renamed. Both forms work, and an app can move over one action at a time. Everything left out stays discoverable through `tool-search`.
+
+Pairing the two flags the other way — `agentTool: false` with `mcpTool: true` — makes an action **MCP-only**: outside agents get it, your own app's agent never sees it. Use it for the export, sync, or handoff an outside tool needs and your own agent has no reason to call.
+
+Membership is not permission. An external caller still has to pass the OAuth scope check, the `externalAgents` policy, and — for the direct, no-model A2A path — the `publicAgent` opt-in below.
+
 ## Block extension iframes {#tool-callable}
 
 Extensions ([Alpine.js mini-apps in sandboxed iframes](/docs/extensions)) call actions through `appAction(name, params)`, running with the viewer's own permissions, secrets, and SQL scope. For sensitive operations, that's too much trust by default. Set `toolCallable: false` to make the extension bridge return a 403, while keeping the action callable from the UI, agent, CLI, MCP, and A2A:

package/docs/content/actions-defining.mdx

@@ -115,6 +115,21 @@ The framework auto-discovers every file in `actions/` and mounts it on startup.
           description:
             "Set false to hide from every agent tool list. See Access & Authorization.",
         },
+        {
+          name: "mcpTool",
+          type: "boolean",
+          optional: true,
+          default: "agentTool",
+          description:
+            "Defaults to agentTool. Set false to hide from external agents over MCP and A2A, or true to declare curated catalog membership (with agentTool: false, MCP-only). See Access & Authorization.",
+        },
+        {
+          name: "deferLoading",
+          type: "boolean",
+          optional: true,
+          description:
+            "Set false to keep the action in the agent's first tool list, true to load it on demand through tool-search. See Keep the action surface small below.",
+        },
         {
           name: "toolCallable",
           type: "boolean",
@@ -261,6 +276,7 @@ Every action the agent can see takes up a slot in the model's tool list, and a l
 - Prefer **one CRUD-style `update` action** that takes a patch of optional fields, over many per-field actions like `update-name`, `update-order`, and `update-color`. The caller only sends the fields that changed.
 - Before adding a new read action for every query or filter, consider a more general option first: the [provider API trio](/docs/template-dispatch-vault-integrations#provider-api) (`provider-api-catalog`, `provider-api-docs`, and `provider-api-request`) for provider data, or the dev `db-query` tool for app data.
 - Mark UI-only or programmatic actions [`agentTool: false`](/docs/actions-access-control#agent-tool). They stay callable from the frontend or over HTTP, without taking a slot in the model's tool list.
+- Mark the handful of actions the agent reaches for constantly `deferLoading: false`. Those are the schemas sent on the first model request; everything else loads on demand through `tool-search` when the agent needs it. As soon as one action opts out this way, every unmarked action is deferred, so mark the whole starter set at once rather than one action at a time. This is about what the first turn costs, not about access: a deferred action is callable the moment `tool-search` returns it. It is the per-action form of the plugin's `initialToolNames` array, and an app can use either.
 - Delete or hide actions the UI no longer uses, instead of leaving them exposed to the model.
 
 The repo includes an advisory helper, `node scripts/audit-template-actions.mjs [template ...]` (alias `pnpm actions:audit`). It scans a template's `actions/` folder and flags actions the UI may no longer use, along with groups of per-field actions that could be combined into one. It always exits with code 0 and never fails CI, and its heuristics are conservative, so treat its output as a suggestion, not an error.