@agent-native/core 0.49.22 → 0.49.23

package/docs/content/actions.md

@@ -272,7 +272,7 @@ If your app is an [A2A](/docs/a2a-protocol) peer, other agent-native apps discov
 
 ## Exposing it over MCP {#mcp}
 
-With MCP enabled, your actions show up in the framework's MCP server at `/_agent-native/mcp`. Stdio/code developer clients can see the full connected action surface. Chat-style app hosts, including OAuth MCP Apps callers and generic authenticated remote HTTP/static-token callers, get a compact catalog containing app-facing builtins (`open_app`, `list_apps`, `ask_app`, and app-only embed helpers); action-specific MCP App resources stay out of that catalog unless an action explicitly sets `mcpApp.compactCatalog: true`. `publicAgent.expose` is still the opt-in for safe read/ingest tools outside that compact app catalog. See [MCP Protocol](/docs/mcp-protocol).
+With MCP enabled, your actions show up in the framework's MCP server at `/_agent-native/mcp`. Every caller gets a compact catalog by default — code/stdio developer clients, the local CLI proxy, and chat-style app hosts (OAuth MCP Apps callers and generic authenticated remote HTTP/static-token callers) alike — containing app-facing builtins (`open_app`, `list_apps`, `ask_app`, and app-only embed helpers) plus the template-declared app actions; action-specific MCP App resources stay out of that catalog unless an action explicitly sets `mcpApp.compactCatalog: true`. `tool-search` is always present (call it with no query for the full tool menu, or with a query for ranked matches), so any tool stays reachable on demand. The full action surface is served only on explicit opt-in (`--full-catalog` token or `AGENT_NATIVE_MCP_FULL_CATALOG=1`). `publicAgent.expose` is still the opt-in for safe read/ingest tools outside that compact app catalog. See [MCP Protocol](/docs/mcp-protocol).
 
 For UI-capable MCP hosts, an action can also declare an optional MCP Apps resource via the `mcpApp` field (and a matching `link`) so capable hosts render the result inline. The pattern mirrors the focused link we already return for external agents: the action exposes the operation, `link` points at the route with the right URL or deep-link params, and the embed helper uses that same target as the inline app. When an action's `link` and `mcpApp` should point at the same route, use `embedRoute()` to build both from one pure path builder.
 

package/docs/content/external-agents.md

@@ -214,43 +214,55 @@ When the client requests no explicit scope, the app grants all three so the conn
 
 ## Catalog tiers {#catalog-tiers}
 
-The tool catalog your agent sees depends on both the deployment context and how
-you connected.
+The MCP server serves a **compact catalog by default to every caller** —
+hosted connectors (ChatGPT, Claude), code clients (Claude Code, Cursor,
+Codex), and the local CLI/stdio proxy alike. The full action surface is served
+only on an explicit opt-in. The catalog is never inferred from the client name
+or user-agent.
+
+### Compact / connector tier (default) {#connector-tier}
+
+By default every connected agent sees a small, curated catalog: the
+template-declared allow-list of app-level actions (create/get/update plan,
+sharing, upload, navigate, automations, `tool-search`) plus the builtin
+cross-app tools (`list_apps`, `open_app`, `ask_app`, `create_embed_session`).
+Tools outside the list — `db-exec`, `db-patch`, `seed-*`, the extension suite,
+browser-session tools, agent-engine management, and context-xray tools — are
+not advertised, and calls to them are rejected with "Unknown tool" unless the
+caller has opted into the full catalog.
 
-### Connector tier (hosted multi-tenant, default) {#connector-tier}
+This keeps the context window of every connected external agent small (~20–30
+tools vs. ~105) and removes footguns that are only safe for single-tenant local
+development. The connector tier is active **whenever a template declares a
+`connectorCatalog`** — it is no longer gated behind an environment variable.
 
-On hosted multi-tenant deployments (e.g. `plan.agent-native.com`) the server
-activates a curated **connector catalog** when `AGENT_NATIVE_CONNECTOR_CATALOG=1`
-is set. External MCP clients see only the template-declared allow-list of
-app-level actions (create/get/update plan, sharing, upload, navigate, automations,
-tool-search) plus the four builtin cross-app tools (`list_apps`, `open_app`,
-`ask_app`, `create_embed_session`). Tools outside the list — `db-exec`,
-`db-patch`, `seed-*`, the extension suite, browser-session tools, agent-engine
-management, and context-xray tools — are not advertised and calls to them are
-rejected with "Unknown tool".
+`tool-search` is always available (including in the compact catalog), so a
+compacted client can still reach any tool on demand. Call it with **no query**
+to get the full menu of tool names plus one-line descriptions (cheap — no
+schemas), or with a query to get ranked matches with parameter summaries. This
+is how a compacted client discovers and loads any full-surface tool when it
+needs one.
 
-This keeps the context window of every connected external agent small (~20–30
-tools vs. ~105) and removes footguns that are only safe for single-tenant
-local development.
+### Full tier (explicit opt-in only) {#full-tier}
 
-### Full tier (local / dev, or per-token opt-up) {#full-tier}
+The complete ~105-tool action surface is served only when a caller explicitly
+opts in. There are two ways to opt in:
 
-Local and dev deployments that do not have `AGENT_NATIVE_CONNECTOR_CATALOG=1`
-always serve the full action surface. When the env flag is set, individual
-callers can still opt up by minting their token with `--full-catalog`:
+- Mint a token with `--full-catalog`, which embeds a `catalog_scope: "full"`
+  claim in the JWT:
 
-```bash
-npx @agent-native/core@latest connect https://plan.agent-native.com --client codex --full-catalog
-```
+  ```bash
+  npx @agent-native/core@latest connect https://plan.agent-native.com --client codex --full-catalog
+  ```
 
-Swap `--client codex` for another target client when needed. This embeds a `catalog_scope: "full"` claim in the minted JWT. On subsequent
-requests the MCP server bypasses the connector-catalog filter for that token
-and serves the complete action surface — identical to the local/dev experience.
+  Swap `--client codex` for another target client when needed. On subsequent
+  requests the MCP server bypasses the compact-catalog filter for that token
+  and serves the complete action surface.
 
-`AGENT_NATIVE_MCP_FULL_CATALOG=1` (process env on the server) is a
-deployment-wide override that disables the filter for all callers. Use it for
-single-tenant hosted instances that need the full surface without per-token
-opt-up.
+- Set `AGENT_NATIVE_MCP_FULL_CATALOG=1` (process env on the server) as a
+  deployment-wide override that serves the full surface to all callers. Use it
+  for single-tenant hosted instances that want the full surface without
+  per-token opt-up.
 
 ### Template declaration {#catalog-declaration}
 
@@ -283,16 +295,17 @@ included regardless of the declared list.
 
 ## What you can do once connected {#what-you-can-do}
 
-Once your agent is connected, the available MCP tool surface depends on the
-host and the deployment. Code/stdio developer clients on local deployments get
-the app's full action surface plus the `ask-agent` meta-tool that runs the full
-agent loop (the same entry point [A2A](/docs/a2a-protocol) uses). On hosted
-multi-tenant deployments the connector tier is active by default (see above).
-Chat hosts, including Claude and ChatGPT, get a compact app-facing catalog by
-default even when they authenticate through a generic bearer/static-token path:
-cross-app verbs such as `list_apps`, `open_app`, and `ask_app`, plus the
-app-only embed helper. In all cases, ask the agent to do real work and it hands
-back a link straight into the running app:
+Once your agent is connected, every caller gets the compact catalog by default
+(see [Catalog tiers](#catalog-tiers)) — code/stdio developer clients, the local
+CLI proxy, and chat hosts like Claude and ChatGPT alike. That surface is the
+template-declared app actions plus the builtin cross-app verbs (`list_apps`,
+`open_app`, `ask_app`, and the app-only embed helper). Use `ask_app` to route a
+natural-language task through an app agent (the same cross-app entry point
+[A2A](/docs/a2a-protocol) uses). `tool-search` is always present, so any tool
+outside the compact list stays reachable on demand. To get the full ~105-tool
+surface up front, opt in explicitly with `--full-catalog` or
+`AGENT_NATIVE_MCP_FULL_CATALOG=1`. In all cases, ask the agent to do real work
+and it hands back a link straight into the running app:
 
 ```
 > draft an email to John about the Q3 report
@@ -508,7 +521,7 @@ This is the unmanaged equivalent of what `connect` writes for you. See [MCP Prot
 
 ### Dev vs production tool surface {#dev-vs-prod}
 
-In plain local dev (`NODE_ENV=development` and `AGENT_MODE !== "production"`) the MCP `tools/list` deliberately exposes only the generic builtins plus actions with `publicAgent.requiresAuth === false` — the per-app ingest actions (`requiresAuth: true`) and mutating actions (no `publicAgent`) are filtered out (`filterPublicAgentActions`). Stdio/code clients that use the `agent-native` proxy identify themselves and get the full developer catalog after auth. Chat-style remote HTTP callers stay on the compact app-facing catalog by default, even when authenticated, so ChatGPT/Claude cannot dump a huge full action catalog into the conversation.
+In plain local dev (`NODE_ENV=development` and `AGENT_MODE !== "production"`) the MCP `tools/list` deliberately exposes only the generic builtins plus actions with `publicAgent.requiresAuth === false` — the per-app ingest actions (`requiresAuth: true`) and mutating actions (no `publicAgent`) are filtered out (`filterPublicAgentActions`). The compact catalog is the default for every caller after auth — stdio/code clients using the `agent-native` proxy, the local CLI, and chat-style remote HTTP callers alike — so ChatGPT/Claude (or any client) cannot dump a huge full action catalog into the conversation. The full developer catalog is served only on explicit opt-in (`--full-catalog` token or `AGENT_NATIVE_MCP_FULL_CATALOG=1`); `tool-search` keeps every tool reachable in the meantime.
 
 ### Switching first-party apps between prod and dev {#dev-switch}
 

package/docs/content/mcp-protocol.md

@@ -103,17 +103,22 @@ See [MCP Apps](/docs/mcp-apps#mcp-app-bridge) for the full embed bridge details
 
 ## Tools {#tools}
 
-Stdio/code developer clients can see all connected app actions as MCP tools
-when they explicitly request the full catalog. Chat-style app hosts, including
-OAuth callers that request `mcp:apps` and generic authenticated remote
-HTTP/static-token callers, get a compact app-host catalog by default:
-app-facing builtins (`list_apps`, `open_app`, `ask_app`, and app-only
-`create_embed_session`) plus rare actions marked `mcpApp.compactCatalog: true`.
-Their `resources/list` is compact too, normally advertising only the generic
-`open_app` embed resource. `publicAgent.expose` remains the opt-in for safe
-read/ingest tools outside that compact app catalog. This keeps ChatGPT/Claude
-app-host discovery small while preserving the full developer surface for local
-agents.
+Every caller gets a compact app-host catalog by default — chat-style app hosts
+(OAuth callers that request `mcp:apps` and generic authenticated remote
+HTTP/static-token callers), code/stdio developer clients, and the local CLI
+proxy alike: app-facing builtins (`list_apps`, `open_app`, `ask_app`, and
+app-only `create_embed_session`), the template-declared app actions, and rare
+actions marked `mcpApp.compactCatalog: true`. Their `resources/list` is compact
+too, normally advertising only the generic `open_app` embed resource. The
+catalog is never inferred from the client name or user-agent. The full action
+surface is served only on explicit opt-in — a token minted with `--full-catalog`
+(`catalog_scope: "full"`) or the deployment-wide `AGENT_NATIVE_MCP_FULL_CATALOG=1`
+override. `tool-search` is always available, including in the compact catalog:
+call it with no query for the full menu of tool names and one-line descriptions,
+or with a query for ranked matches with parameter summaries, to reach any tool
+on demand. `publicAgent.expose` remains the opt-in for safe read/ingest tools
+outside that compact app catalog. This keeps ChatGPT/Claude app-host discovery
+small while keeping every tool reachable.
 
 The mapping is direct:
 

package/docs/content/pr-visual-recap.md

@@ -36,7 +36,7 @@ explicitly at any time:
 npx @agent-native/core@latest skills add visual-plan --with-github-action
 ```
 
-This installs the `visual-plan` skill (which includes the `visual-recap` skill the action runs) and writes `.github/workflows/pr-visual-recap.yml` into your repo. The workflow calls **published CLI subcommands** through `npx @agent-native/core@latest recap <subcommand>` — including `gate`, `collect-diff`, `mcp-config`, `scan`, `build-prompt`, `shot`, `comment`, `check`, and `usage` — so nothing is copied into your repo as helper scripts. `setup` and `doctor` are the interactive helpers you run locally; `gate` is the security-gate step the workflow runs before every recap.
+This installs the `visual-plan` skill (which includes the `visual-recap` skill the action runs) and writes `.github/workflows/pr-visual-recap.yml` into your repo. The workflow calls **published CLI subcommands** through `npx @agent-native/core@latest recap <subcommand>` — including `gate`, `collect-diff`, `block-reference`, `scan`, `build-prompt`, `publish`, `shot`, `comment`, `check`, and `usage` — so nothing is copied into your repo as helper scripts. `setup` and `doctor` are the interactive helpers you run locally; `gate` is the security-gate step the workflow runs before every recap.
 
 Then run the guided setup helper:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.49.22",
+  "version": "0.49.23",
   "type": "module",
   "engines": {
     "node": ">=22"