@frontmcp/skills 1.8.7 → 1.9.0

package/catalog/frontmcp-deployment/references/deploy-to-node.md

@@ -41,7 +41,7 @@ This skill walks you through deploying a FrontMCP server as a standalone Node.js
 frontmcp build --target node
 ```
 
-This compiles your TypeScript source, bundles dependencies, and produces a production-ready output in `dist/`. The build output includes compiled JavaScript optimized for Node.js, a `package.json` with production dependencies only, and any static assets.
+This compiles your TypeScript source, bundles dependencies, and writes the output to `dist/node/`: a CommonJS single-file bundle at `dist/node/<name>.bundle.js` (`<name>` is the `name` in `frontmcp.config`, or the unscoped `package.json` name without a config file), a `dist/node/<name>` runner script, and any static assets. The examples below use `my-server` as `<name>`.
 
 ## Step 2: Dockerfile (Multi-Stage)
 
@@ -66,7 +66,7 @@ RUN yarn install --frozen-lockfile --production && yarn cache clean
 EXPOSE 3000
 HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
   CMD wget -qO- http://localhost:3000/healthz || exit 1
-CMD ["node", "dist/main.js"]
+CMD ["node", "dist/node/my-server.bundle.js"]
 ```
 
 The first stage installs all dependencies and builds the project. The second stage copies only the compiled output and production dependencies into a slim image.
@@ -173,7 +173,7 @@ When running without Docker, use PM2 as a process manager:
 npm install -g pm2
 
 # Start the server with cluster mode (one instance per CPU core)
-pm2 start dist/main.js --name frontmcp-server -i max
+pm2 start dist/node/my-server.bundle.js --name frontmcp-server -i max
 
 # Save the process list for auto-restart on reboot
 pm2 save
@@ -223,20 +223,20 @@ services:
 
 ## Common Patterns
 
-| Pattern                   | Correct                              | Incorrect                                        | Why                                                                 |
-| ------------------------- | ------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------- |
-| Build command             | `frontmcp build --target node`       | `tsc && node dist/main.js`                       | The FrontMCP build bundles deps and produces an optimized output    |
-| Docker base image         | `node:24-alpine` (multi-stage)       | `node:24` (single stage with dev deps)           | Multi-stage keeps the production image small and secure             |
-| Process manager           | PM2 with `-i max` cluster mode       | Running `node dist/main.js` directly via `nohup` | PM2 handles restarts, logging, and multi-core clustering            |
-| Redis hostname in Compose | Service name `redis`                 | `localhost` or `127.0.0.1`                       | Containers communicate via Docker's internal DNS, not localhost     |
-| Environment config        | `.env` file or orchestrator env vars | Hardcoded values in source code                  | Keeps secrets out of the codebase and allows per-environment config |
+| Pattern                   | Correct                              | Incorrect                               | Why                                                                 |
+| ------------------------- | ------------------------------------ | --------------------------------------- | ------------------------------------------------------------------- |
+| Build command             | `frontmcp build --target node`       | `tsc && node dist/main.js`              | The FrontMCP build bundles deps and produces an optimized output    |
+| Docker base image         | `node:24-alpine` (multi-stage)       | `node:24` (single stage with dev deps)  | Multi-stage keeps the production image small and secure             |
+| Process manager           | PM2 with `-i max` cluster mode       | Running the bundle directly via `nohup` | PM2 handles restarts, logging, and multi-core clustering            |
+| Redis hostname in Compose | Service name `redis`                 | `localhost` or `127.0.0.1`              | Containers communicate via Docker's internal DNS, not localhost     |
+| Environment config        | `.env` file or orchestrator env vars | Hardcoded values in source code         | Keeps secrets out of the codebase and allows per-environment config |
 
 ## Verification Checklist
 
 **Build**
 
 - [ ] `frontmcp build --target node` completes without errors
-- [ ] `dist/main.js` exists and is runnable with `node dist/main.js`
+- [ ] `dist/node/<name>.bundle.js` exists and is runnable with `node dist/node/<name>.bundle.js`
 
 **Docker**
 

package/catalog/frontmcp-deployment/references/mcp-client-integration.md

@@ -102,12 +102,17 @@ Wire the client at the bridge:
 
 Bridge guarantees:
 
-- Stdout is 100% JSON-RPC frames; diagnostics go to `./.frontmcp/dev.log` (override with `--log-file`).
-- Session id survives reload (pinned via `FRONTMCP_DEV_FORCE_SESSION_ID`).
-- Buffered RPCs during reload drain in FIFO once the child reports ready.
+- Stdout is 100% JSON-RPC frames; diagnostics go to `.frontmcp/dev.log` in the project root (override with `--log-file`), start-up notices (port picked, `.env` loaded) to stderr.
+- Same project setup as `frontmcp dev`: `frontmcp.config.*` (from any subfolder), `entry`, `transport.http.port` / `path`, `env` overlays and `.env`. The server gets `PORT` + `FRONTMCP_HTTP_ENTRY_PATH`; with no port chosen anywhere the bridge picks a free loopback port.
+- The server reports the port and MCP path it really serves (`__FRONTMCP_BOOTSTRAP_COMPLETE__ {"port":…,"path":…}` on stderr), so values hard-coded in `@FrontMcp({ http })` work.
+- The client stays connected across reloads: the bridge uses the `mcp-session-id` the server issues, replays the client's `initialize` handshake on the restarted server, then sends `notifications/tools/list_changed` (and resources/prompts when advertised). Server-side session state starts fresh on each reload.
+- Buffered RPCs during reload drain in FIFO once the new server is ready and initialized. A server that rejects the replayed handshake is a failed reload: it is stopped, and buffered RPCs wait for the next save or answer `dev_reload_deadline`.
 - Reload deadline + buffer overflow surface structured errors (`dev_server_unreachable` / `dev_buffer_full` / `dev_reload_deadline` — codes -32099 / -32098 / -32097) so the client spinner clears instead of hanging.
+- Closing stdin or `SIGINT` / `SIGTERM` stops the server and everything it started.
 
-Flags: `--stdio`, `--serve`, `--log-file <path>`, `--buffer-size <n>` (default 8), `--reload-deadline-ms <ms>` (default 30000), `-p <port>` (HTTP-mode loopback, default 3000).
+`--serve` runs the entry with the project's `tsx` (`node --import tsx`) so the server owns the IPC channel — keep `tsx` in devDependencies (scaffolded projects have it).
+
+Flags: `--stdio`, `--serve`, `--log-file <path>`, `--buffer-size <n>` (default 8), `--reload-deadline-ms <ms>` (default 30000), `-p <port>` (HTTP-mode loopback; default `transport.http.port`, then `PORT`, then a free port), `--auto-port`.
 
 ## Stdio Transport
 
@@ -184,9 +189,9 @@ itself before any framework initialization:
 }
 ```
 
-> Do not run the raw `--target node` bundle as `node dist/node/my-server.bundle.js --stdio`
-> — that bundle is your `@FrontMcp` server module and starts the HTTP server on
-> import. Use the runner above, or set `FRONTMCP_STDIO=1` before the bundle loads.
+> The bundle itself honors the flag too: `node dist/node/my-server.bundle.js --stdio`
+> serves stdio and binds no port (and, run directly, it serves MCP at
+> `transport.http.path` like the runner does).
 
 ## HTTP Transport
 

package/catalog/frontmcp-deployment/references/protocol-versions.md

@@ -188,11 +188,15 @@ resolves with the final result either way.
 For a remote app, negotiate per remote:
 
 ```ts
-transportOptions: {
-  protocolVersion: 'auto';
-} // 'legacy' (default) | '2026-07-28' | 'auto'
+App.remote('https://example.com/mcp', {
+  transportOptions: {
+    protocolVersion: 'auto', // 'legacy' (default) | '2026-07-28' | 'auto'
+  },
+});
 ```
 
+`'auto'` probes `server/discover` and falls back to the session transports; `'2026-07-28'` always uses the stateless client and requires a URL remote (other transports are refused at connect time).
+
 ## Deprecated in this revision
 
 Still functional; do not adopt in new servers:

package/catalog/frontmcp-development/examples/create-agent/nested-agents-with-swarm.md

@@ -2,7 +2,7 @@
 name: nested-agents-with-swarm
 reference: create-agent
 level: advanced
-description: Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `use-agent:<id>` tools. Routing is driven by the orchestrator's LLM, not a declarative handoff table.
+description: Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `invoke_<id>` tools, plus a nested sub-agent and `this.invokeAgent()`. Routing is driven by the orchestrator's LLM, not a declarative handoff table.
 tags:
   - development
   - agent
@@ -10,15 +10,17 @@ tags:
   - agents
   - swarm
 features:
-  - 'Setting `swarm: { canSeeOtherAgents: true, visibleAgents: [...] }` on the orchestrator so peers appear as `use-agent:*` tools'
+  - 'Setting `swarm: { canSeeOtherAgents: true, visibleAgents: [...] }` on the orchestrator so peers are offered to its model as `invoke_*` tools'
   - 'Setting `swarm: { isVisible: true }` (the default) on specialist peers so they can be called'
-  - Routing is driven by the orchestrator LLM choosing among `use-agent:<peer>` tools, not by a declarative handoff table
+  - Routing is driven by the orchestrator LLM choosing among `invoke_<peer>` tools, not by a declarative handoff table
+  - 'A nested sub-agent (`agents: [...]`) private to the orchestrator, called from code with `this.invokeAgent()`'
+  - '`swarm.maxCallDepth` bounding how deep agents may call each other'
   - Each agent has its own `llm` config, `tools`, and `systemInstructions` for specialization
 ---
 
 # Multi-Agent Swarm Visibility
 
-Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `use-agent:<id>` tools. Routing is driven by the orchestrator's LLM, not a declarative handoff table.
+Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `invoke_<id>` tools, plus a nested sub-agent and `this.invokeAgent()`. Routing is driven by the orchestrator's LLM, not a declarative handoff table.
 
 ## Code
 
@@ -42,6 +44,8 @@ class LookupInvoiceTool extends ToolContext {
   name: 'billing_agent',
   description: 'Handles billing and payment inquiries',
   llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  // The arguments of its invoke_billing_agent tool: an agent without an inputSchema receives {}.
+  inputSchema: { request: z.string().describe('The billing request') },
   tools: [LookupInvoiceTool],
   // isVisible defaults to true; specialists do not need swarm config to be callable.
   swarm: { isVisible: true },
@@ -51,23 +55,45 @@ class BillingAgent extends AgentContext {}
 
 ```typescript
 // src/apps/support/agents/technical.agent.ts
-import { Agent, AgentContext } from '@frontmcp/sdk';
+import { Agent, AgentContext, z } from '@frontmcp/sdk';
 
 @Agent({
   id: 'technical_agent',
   name: 'technical_agent',
   description: 'Handles technical support issues',
   llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  inputSchema: { request: z.string().describe('The technical issue') },
   systemInstructions: 'You are a technical support specialist. Diagnose issues and provide solutions.',
   swarm: { isVisible: true },
 })
 class TechnicalAgent extends AgentContext {}
 ```
 
+```typescript
+// src/apps/support/agents/sentiment.agent.ts
+import { Agent, AgentContext, z } from '@frontmcp/sdk';
+
+// Nested in the triage agent below: private to it, never offered to clients.
+@Agent({
+  id: 'sentiment_agent',
+  name: 'sentiment_agent',
+  description: 'Rates how upset a customer is',
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  inputSchema: { request: z.string() },
+  outputSchema: { urgency: z.enum(['low', 'high']) },
+  // The model's reply is parsed as the output: ask for JSON that matches outputSchema.
+  systemInstructions:
+    'Rate how urgent the request is. Reply only with JSON: {"urgency": "low"} or {"urgency": "high"}.',
+})
+export class SentimentAgent extends AgentContext {}
+```
+
 ```typescript
 // src/apps/support/agents/triage.agent.ts
 import { Agent, AgentContext, z } from '@frontmcp/sdk';
 
+import { SentimentAgent } from './sentiment.agent';
+
 @Agent({
   id: 'triage_agent',
   name: 'triage_agent',
@@ -76,16 +102,28 @@ import { Agent, AgentContext, z } from '@frontmcp/sdk';
   inputSchema: {
     request: z.string().describe('The incoming user request'),
   },
+  // Nested sub-agent: offered to this agent's model as invoke_sentiment_agent, and callable from code.
+  agents: [SentimentAgent],
   // Orchestrator: opts in to seeing peers and (optionally) restricts to a whitelist.
   swarm: {
     canSeeOtherAgents: true,
     visibleAgents: ['billing_agent', 'technical_agent'],
-    maxCallDepth: 3,
+    maxCallDepth: 3, // a deeper agent-to-agent chain fails with AGENT_CALL_DEPTH_EXCEEDED
   },
   systemInstructions:
-    'Analyze the request and delegate by calling either use-agent:billing_agent (for billing/payments) or use-agent:technical_agent (for technical issues).',
+    'Analyze the request and delegate by calling either invoke_billing_agent (for billing/payments) or invoke_technical_agent (for technical issues).',
 })
-class TriageAgent extends AgentContext {}
+class TriageAgent extends AgentContext {
+  async execute(input: { request: string }) {
+    // Code can call a nested agent, or a peer it sees, and gets its output back.
+    const sentiment = (await this.invokeAgent('sentiment_agent', { request: input.request })) as { urgency: string };
+    if (sentiment.urgency === 'high') {
+      return this.invokeAgent('technical_agent', { request: input.request });
+    }
+    // Otherwise let the model route among invoke_billing_agent / invoke_technical_agent.
+    return super.execute(input);
+  }
+}
 ```
 
 ```typescript
@@ -101,9 +139,11 @@ class SupportApp {}
 
 ## What This Demonstrates
 
-- Setting `swarm: { canSeeOtherAgents: true, visibleAgents: [...] }` on the orchestrator so peers appear as `use-agent:*` tools
+- Setting `swarm: { canSeeOtherAgents: true, visibleAgents: [...] }` on the orchestrator so peers are offered to its model as `invoke_*` tools
 - Setting `swarm: { isVisible: true }` (the default) on specialist peers so they can be called
-- Routing is driven by the orchestrator LLM choosing among `use-agent:<peer>` tools, not by a declarative handoff table
+- Routing is driven by the orchestrator LLM choosing among `invoke_<peer>` tools, not by a declarative handoff table
+- A nested sub-agent (`agents: [...]`) private to the orchestrator, called from code with `this.invokeAgent()`
+- `swarm.maxCallDepth` bounding how deep agents may call each other
 - Each agent has its own `llm` config, `tools`, and `systemInstructions` for specialization
 
 ## Related

package/catalog/frontmcp-development/examples/openapi-adapter/ref-security-and-filtering.md

@@ -8,7 +8,7 @@ features:
   - 'Secure defaults: external `$ref` resolution off, spec-URL redirects not followed, internal/private targets blocked (DNS-resolved) — on `mcp-from-openapi` >= 2.5.0'
   - 'Opting back into external refs with `allowedProtocols`, and restricting the spec URL + `$ref`s with `allowedHosts`'
   - 'Using `allowInternalIPs` for trusted internal/local targets (governs the spec URL and `$ref`s)'
-  - 'Filtering operations with `includeOperations`, `excludeOperations`, and `filterFn`'
+  - 'Filtering operations with `readOnlyOnly`, `includeTags`, `includePaths`, `excludeMethods`, `includeOperations`, `excludeOperations`, and `filterFn`'
   - 'Combining security hardening with operation filtering for a production-ready setup'
 ---
 
@@ -20,8 +20,8 @@ Demonstrates configuring $ref / spec-URL resolution security to prevent SSRF att
 
 ```typescript
 // src/server.ts
-import { FrontMcp, App } from '@frontmcp/sdk';
 import { OpenapiAdapter } from '@frontmcp/adapters';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'secure-app',
@@ -45,8 +45,10 @@ import { OpenapiAdapter } from '@frontmcp/adapters';
         },
       },
       generateOptions: {
-        // Only expose read operations to MCP clients
-        filterFn: (op) => op.method === 'get',
+        // Only expose read-only operations (readOnlyHint: true — GET/HEAD/OPTIONS/TRACE by default)
+        readOnlyOnly: true,
+        // ...and only the partner's public tag
+        includeTags: ['public'],
         // Skip deprecated endpoints
         includeDeprecated: false,
       },
@@ -88,8 +90,12 @@ import { OpenapiAdapter } from '@frontmcp/adapters';
       generateOptions: {
         // Exclude admin and dangerous operations
         excludeOperations: ['deleteAll', 'resetDatabase', 'adminPanel'],
-        // Only include billing-related paths
-        filterFn: (op) => op.path.startsWith('/billing') || op.path.startsWith('/invoices'),
+        // Never expose deletes (lower-case HTTP method names)
+        excludeMethods: ['delete'],
+        // Only include billing-related paths (globs: `*` within a segment, `**` across segments)
+        includePaths: ['/billing/**', '/invoices/**'],
+        // Anything a declarative filter can't express goes in filterFn (runs after the others)
+        filterFn: (op) => !op.summary?.toLowerCase().includes('experimental'),
       },
     }),
   ],
@@ -109,7 +115,7 @@ class MyServer {}
 - Secure defaults: external `$ref` resolution off, spec-URL redirects not followed, internal/private targets blocked (DNS-resolved) — on `mcp-from-openapi` >= 2.5.0
 - Opting back into external refs with `allowedProtocols`, and restricting the spec URL + `$ref`s with `allowedHosts`
 - Using `allowInternalIPs` for trusted internal/local targets (governs the spec URL and `$ref`s)
-- Filtering operations with `includeOperations`, `excludeOperations`, and `filterFn`
+- Filtering operations with `readOnlyOnly`, `includeTags`, `includePaths`, `excludeMethods`, `includeOperations`, `excludeOperations`, and `filterFn`
 - Combining security hardening with operation filtering for a production-ready setup
 
 ## Related

package/catalog/frontmcp-development/references/create-adapter.md

@@ -92,6 +92,8 @@ class MyApiAdapter extends DynamicAdapter<MyAdapterOptions> {
 class MyApp {}
 ```
 
+To serve the adapter's tools, resources and prompts from every app, register it on the server instead with `@FrontMcp({ adapters: [MyApiAdapter.init({ ... })] })`. Like a server-level plugin, each scope (a standalone or `splitByApp` app gets its own) builds its own adapter from the `init()` options and runs `fetch()`; a hand-written `{ provide, useValue }` record is one adapter that every scope shares. Disposing the server calls each adapter's `stopPolling()` and drops its `onUpdate()` subscription. Up to 1.8.7 `@FrontMcp({ adapters })` was silently dropped, and disposing did not stop adapter polling.
+
 ## FrontMcpAdapterResponse
 
 The `fetch()` method returns tools, resources, and prompts to register:
@@ -120,6 +122,18 @@ const adapter = MyApiAdapter.init({
 @App({ adapters: [adapter] })
 ```
 
+When the options depend on a provider, use `init({ name, inject, useFactory })`. The factory returns the adapter's **options** (or a promise of them) and the adapter is built from them, named by the `name` given to `init()`:
+
+```typescript
+MyApiAdapter.init({
+  name: 'my-api',
+  inject: () => [ApiConfig] as const,
+  useFactory: (config: ApiConfig) => ({ name: 'my-api', endpoint: config.endpoint, apiKey: config.apiKey }),
+});
+```
+
+A factory may instead return an adapter instance, used as is when its `options.name` is the `name` given to `init()`; an instance named otherwise, or anything else, fails startup with an `InvalidEntityError`.
+
 ## Nx Generator
 
 ```bash

package/catalog/frontmcp-development/references/create-agent.md

@@ -77,7 +77,8 @@ class CodeReviewerAgent extends AgentContext {
 - `execute(input: In): Promise<Out>` -- the main method; default runs the agent loop
 - `completion(prompt: AgentPrompt, options?): Promise<AgentCompletion>` -- make a single LLM call
 - `streamCompletion(prompt: AgentPrompt, options?): AsyncIterable<AgentCompletionChunk>` -- stream an LLM response
-- `executeTool(toolDef, input): Promise<unknown>` -- (protected) invoke one of the agent's inner tools programmatically
+- `executeTool(name, args): Promise<unknown>` -- (protected) run one of the tools the model is offered; every model tool call goes through it, so an override sees them all
+- `invokeAgent(agentId, input): Promise<unknown>` -- (protected) call a nested agent, or a swarm agent this agent sees, and get its output
 
 **Inherited Methods:**
 
@@ -96,7 +97,7 @@ class CodeReviewerAgent extends AgentContext {
 - `this.llmAdapter` -- the configured LLM adapter instance
 - `this.toolDefinitions` -- definitions of inner tools available to the agent
 - `this.toolExecutor` -- executor for invoking inner tools
-- `this.metadata` -- agent metadata from the decorator
+- `this.metadata` -- the options given to `@Agent`, with defaults applied (there is no `this.options`)
 - `this.scope` -- the current scope instance
 - `this.context` -- the execution context
 
@@ -308,9 +309,9 @@ class PRReviewerAgent extends AgentContext {
 }
 ```
 
-## Exported Tools
+## Exports
 
-Use `exports: { tools: [] }` to expose specific tools that the agent makes available to external callers. Unlike inner tools (which the agent uses privately), exported tools appear in the MCP tool listing for clients to invoke directly.
+`exports` shares some of the agent's own resources, prompts and providers with the scope it is registered in (the server, or its parent agent). There is no `exports.tools`: an agent's tools are private to its model, and `exports: { tools }` is refused when the agent is decorated. Register a tool clients should call in the app's `tools`.
 
 ```typescript
 @Agent({
@@ -321,15 +322,24 @@ Use `exports: { tools: [] }` to expose specific tools that the agent makes avail
     model: 'gpt-4o',
     apiKey: { env: 'OPENAI_API_KEY' },
   },
-  tools: [ExtractTool, TransformTool, LoadTool], // Agent uses these internally
-  exports: { tools: [ValidateDataTool, StatusTool] }, // These are exposed to MCP clients
+  tools: [ExtractTool, TransformTool, LoadTool], // The agent's model uses these
+  providers: [WarehouseClient],
+  resources: [PipelineStatusResource],
+  prompts: [PipelineReportPrompt],
+  exports: {
+    resources: '*', // listed in resources/list, read with resources/read
+    prompts: [PipelineReportPrompt], // listed in prompts/list, got with prompts/get
+    providers: [WarehouseClient], // the app's tools can use this.get(WarehouseClient)
+  },
 })
 class DataPipelineAgent extends AgentContext {}
 ```
 
+Each export must be one of the agent's own `resources`, `prompts` or `providers`; otherwise the server refuses to start with `AgentConfigurationError`.
+
 ## Nested Agents (Sub-Agents)
 
-Use the `agents` array to compose agents from smaller, specialized sub-agents. Each sub-agent has its own LLM config, inner tools, and system instructions.
+Use the `agents` array to compose agents from smaller, specialized sub-agents. Each sub-agent has its own LLM config, inner tools, and system instructions. The parent's model is offered each one as an `invoke_<id>` tool next to its own tools, and the parent's code can call them with `this.invokeAgent('<id>', input)`. Nested agents are private: clients are not offered them. A call to one runs through its `invoke_<id>` tool's `tools:call-tool` flow in the parent's scope, also when the parent sets `execution.useToolFlow: false`, so the nested agent's `authorities`, `rateLimit`, `concurrency`, `timeout`, plugin gates and hooks apply as for a client's call. A `rateLimit` or `concurrency` declared only on a nested agent is enforced without a `throttle` option. Under `auth.consent`, the consent given to the parent agent covers its own tools and nested agents, which the consent screen never offers.
 
 ```typescript
 @Agent({
@@ -368,7 +378,7 @@ class CodeAuditorAgent extends AgentContext {}
 
 ## Swarm Configuration
 
-Swarm mode lets agents discover and call each other at runtime. The framework registers visible peers as callable tools (`use-agent:<id>`) on the orchestrator's LLM, so the LLM itself decides when to delegate -- there is no declarative routing table.
+Swarm mode lets agents discover and call each other at runtime. The framework offers the orchestrator's LLM each peer it sees as that peer's `invoke_<id>` tool, so the LLM itself decides when to delegate -- there is no declarative routing table. The orchestrator's code can call a peer it sees with `this.invokeAgent('<id>', input)`.
 
 ### SwarmConfig Fields
 
@@ -376,10 +386,10 @@ Swarm mode lets agents discover and call each other at runtime. The framework re
 | ------------------- | ---------- | ------- | ------------------------------------------------------------------------------------ |
 | `canSeeOtherAgents` | `boolean`  | `false` | If `true`, this agent can discover and call other agents in the same scope           |
 | `visibleAgents`     | `string[]` | --      | Whitelist of agent IDs this agent is allowed to see (when `canSeeOtherAgents: true`) |
-| `isVisible`         | `boolean`  | `true`  | If `false`, this agent is hidden from peers (cannot be called as `use-agent:<id>`)   |
+| `isVisible`         | `boolean`  | `true`  | If `false`, this agent is hidden from peers (never offered or callable by them)      |
 | `maxCallDepth`      | `number`   | `3`     | Maximum nested agent-to-agent call depth (1-10)                                      |
 
-There is no `role`, `handoff`, or `condition` field -- routing is driven by the orchestrator's LLM choosing among the visible `use-agent:*` tools.
+There is no `role`, `handoff`, or `condition` field -- routing is driven by the orchestrator's LLM choosing among the visible `invoke_*` tools.
 
 ```typescript
 @Agent({
@@ -397,7 +407,7 @@ There is no `role`, `handoff`, or `condition` field -- routing is driven by the
     maxCallDepth: 3,
   },
   systemInstructions:
-    'Analyze the request and call use-agent:billing_agent or use-agent:technical_agent depending on the topic.',
+    'Analyze the request and call invoke_billing_agent or invoke_technical_agent depending on the topic.',
 })
 class TriageAgent extends AgentContext {}
 
@@ -406,6 +416,8 @@ class TriageAgent extends AgentContext {}
   name: 'billing_agent',
   description: 'Handles billing and payment inquiries',
   llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  // The arguments of its invoke_billing_agent tool: an agent without an inputSchema receives {}.
+  inputSchema: { request: z.string().describe('The billing request') },
   tools: [LookupInvoiceTool, ProcessRefundTool],
   // Specialist is visible to peers but does not see others.
   swarm: { isVisible: true },
@@ -415,39 +427,42 @@ class BillingAgent extends AgentContext {}
 
 ### How Routing Works
 
-- When the orchestrator agent runs its LLM loop, every visible peer is exposed as a tool named `use-agent:<id>`.
+- When the orchestrator agent runs its LLM loop, every peer it sees (in `visibleAgents` when set, never one with `isVisible: false`, never itself) is offered as a tool named `invoke_<id>`.
 - The orchestrator's `systemInstructions` should describe when to call each peer; the LLM decides at runtime.
 - Peers do not need any swarm config to be callable -- they only need `isVisible: true` (the default).
 - Set `canSeeOtherAgents: false` (the default) on agents that should never be able to delegate.
+- A peer call runs through the peer's `invoke_<id>` tool, so its `authorities`, `rateLimit`, `concurrency`, `timeout` and hooks apply.
+- `this.invokeAgent('<id>', input)` on an agent that exists but isn't seen throws `AgentVisibilityError` (`AGENT_VISIBILITY_DENIED`); an unknown id throws `AgentNotFoundError`.
+
+### Call Depth
+
+`maxCallDepth` counts agent-to-agent calls in one chain, however they are made (the model, `invokeAgent()`, or `this.callTool('invoke_<id>')`): an agent called by a client that calls another makes call 1. The smallest `maxCallDepth` of the agents running applies, and agents without `swarm` count with the default of 3. A deeper call fails with `AgentCallDepthExceededError` (`AGENT_CALL_DEPTH_EXCEEDED`), which stops agents that call each other from looping forever.
 
 ## Function-Style Builder
 
-For agents that do not need a class, use the `agent()` function builder.
+For agents that do not need a class, use the `agent()` function builder. The handler is the agent's `execute()`: it receives the validated input and the agent's context, and returns the agent's output. It doesn't run the LLM loop; use a class extending `AgentContext` when the model should drive.
 
 ```typescript
 import { agent, z } from '@frontmcp/sdk';
 
-const QuickSummarizer = agent({
-  name: 'quick_summarizer',
-  description: 'Summarizes text quickly',
+const QuickTruncator = agent({
+  name: 'quick_truncator',
+  description: 'Truncates text to a length',
   llm: {
     provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
   inputSchema: {
-    text: z.string().describe('Text to summarize'),
-    maxLength: z.number().default(100).describe('Max summary length'),
+    text: z.string().describe('Text to truncate'),
+    maxLength: z.number().default(100).describe('Max length'),
   },
-})((input, ctx) => {
-  // Custom logic using ctx for completion calls
-  return ctx.completion({
-    messages: [{ role: 'user', content: `Summarize in ${input.maxLength} chars:\n${input.text}` }],
-  });
-});
+})((input) => ({ text: input.text.slice(0, input.maxLength) }));
 ```
 
-Register it the same way as a class agent: `agents: [QuickSummarizer]`.
+Up to 1.8.7 the handler never ran: every call failed output validation with a list of Zod issues.
+
+Register it the same way as a class agent: `agents: [QuickTruncator]`.
 
 ## Remote and ESM Loading
 
@@ -488,7 +503,7 @@ class ReviewApp {}
 @FrontMcp({
   info: { name: 'my-server', version: '1.0.0' },
   apps: [ReviewApp],
-  agents: [QuickSummarizer], // can also register agents directly on the server
+  agents: [QuickTruncator], // can also register agents directly on the server
 })
 class MyServer {}
 ```
@@ -534,7 +549,7 @@ class ExpensiveAgent extends AgentContext {
 
 ## Agent with Providers and Plugins
 
-Agents can include their own providers and plugins for self-contained dependency management:
+Agents can include their own providers and plugins for self-contained dependency management. The agent's tools can inject its providers without the app registering them too, and its plugins' hooks run for its tools. Set `execution: { inheritPlugins: true }` to also run the plugins installed on the app and the server for the agent's tools (a plugin installed in both places runs once).
 
 ```typescript
 @Agent({
@@ -559,7 +574,7 @@ class DatabaseAgent extends AgentContext {}
 
 ## Agent with Resources and Prompts
 
-Agents can include resources and prompts that are available within the agent's scope:
+Agents can include resources and prompts scoped to the agent. The agent's model is sent tools only, so they reach clients only when exported (`exports: { resources, prompts }`, see [Exports](#exports)); the server reports any that are not exported at startup.
 
 ```typescript
 @Agent({
@@ -576,19 +591,34 @@ Agents can include resources and prompts that are available within the agent's s
   tools: [WriteFileTool, ReadFileTool],
   resources: [DocsTemplateResource],
   prompts: [TechnicalWritingPrompt],
+  exports: { resources: '*', prompts: '*' },
 })
 class DocsAgent extends AgentContext {}
 ```
 
+## Execution Options
+
+| Option                         | Default  | Effect                                                                                                                                          |
+| ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `execution.maxIterations`      | `10`     | Max tool-call rounds of the LLM loop                                                                                                            |
+| `execution.timeout`            | `120000` | Max run time in ms                                                                                                                              |
+| `execution.inheritParentTools` | `false`  | Also offer the model the tools of the scope the agent is registered in, other than agents; they run through that scope's `tools:call-tool` flow |
+| `execution.inheritPlugins`     | `false`  | Also run the app's and server's plugin hooks for the agent's own tools                                                                          |
+| `execution.useToolFlow`        | `true`   | Own tools through its `tools:call-tool` flow (hooks, limits, authorization); `false` runs them directly. Nested agents always use their flow    |
+| `execution.enableAutoProgress` | `false`  | Send progress notifications during the loop                                                                                                     |
+| `execution.enableStreaming`    | `false`  | Not supported yet: the agent replies once the run completes, and `true` is reported at startup                                                  |
+
+Through that flow the agent's own tools get the `rateLimit`, `concurrency` and `timeout` they declare (else the `throttle` defaults), as the app's tools do; a `rateLimit` or `concurrency` there is enforced without a `throttle` option. The calls an agent makes during its run (its model's tool calls, its nested and swarm agents) run inside the `throttle.globalConcurrency` slot of the call that runs the agent.
+
 ## Common Patterns
 
-| Pattern                 | Correct                                                                       | Incorrect                                                      | Why                                                                             |
-| ----------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| LLM config              | `llm: { provider: 'anthropic', model: '...', apiKey: { env: 'KEY' } }`        | `llm: { provider: 'anthropic', apiKey: 'sk-hardcoded' }`       | Environment variable references prevent leaking secrets in code                 |
-| Inner tools vs exported | `tools: [...]` for agent-private; `exports: { tools: [...] }` for MCP-visible | Putting all tools in `tools` and expecting clients to see them | Inner tools are private to the agent; only exported tools appear in MCP listing |
-| Custom execute          | Override `execute()` for multi-pass orchestration                             | Putting all logic in system instructions                       | Custom `execute()` gives structured control over completion calls and stages    |
-| Sub-agents              | Use `agents: [SubAgent]` for composition                                      | Calling another agent's `execute()` directly                   | The `agents` array enables proper lifecycle and scope isolation                 |
-| Swarm visibility        | `swarm: { canSeeOtherAgents: true, visibleAgents: ['peer'] }`                 | `swarm: { role, handoff }` (those fields do not exist)         | Routing is LLM-driven via `use-agent:*` tools; only visibility is configurable  |
+| Pattern                  | Correct                                                                             | Incorrect                                                            | Why                                                                          |
+| ------------------------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| LLM config               | `llm: { provider: 'anthropic', model: '...', apiKey: { env: 'KEY' } }`              | `llm: { provider: 'anthropic', apiKey: 'sk-hardcoded' }`             | Environment variable references prevent leaking secrets in code              |
+| Inner tools vs app tools | `tools: [...]` on the agent for its model; `tools: [...]` on the `@App` for clients | `exports: { tools: [...] }` (refused: there is no such export)       | An agent's tools are private to its model; clients see the app's tools       |
+| Custom execute           | Override `execute()` for multi-pass orchestration                                   | Putting all logic in system instructions                             | Custom `execute()` gives structured control over completion calls and stages |
+| Sub-agents               | Use `agents: [SubAgent]` and `this.invokeAgent('sub_agent', input)`                 | Calling another agent's `execute()` directly, or `tools: [SubAgent]` | The `agents` array enables proper lifecycle, gates and scope isolation       |
+| Swarm visibility         | `swarm: { canSeeOtherAgents: true, visibleAgents: ['peer'] }`                       | `swarm: { role, handoff }` (those fields do not exist)               | Routing is LLM-driven via `invoke_*` tools; only visibility is configurable  |
 
 ## Verification Checklist
 
@@ -606,26 +636,29 @@ class DocsAgent extends AgentContext {}
 - [ ] LLM adapter connects successfully to the configured provider
 - [ ] Inner tools are invoked correctly during the agent loop
 - [ ] `this.completion()` and `this.streamCompletion()` return valid responses
-- [ ] Visible peers appear as `use-agent:<id>` tools to the orchestrator agent
+- [ ] Visible peers and nested agents are offered as `invoke_<id>` tools to the orchestrator's model
 
 ## Troubleshooting
 
-| Problem                                | Cause                                                                                                                     | Solution                                                                                                                                                                         |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Agent not appearing in tool listing    | Not registered in `agents` array                                                                                          | Add agent class to `@App` or `@FrontMcp` `agents` array                                                                                                                          |
-| LLM authentication error               | API key not set or incorrect env variable                                                                                 | Verify the environment variable name in `apiKey: { env: '...' }` is set                                                                                                          |
-| Inner tools not being called           | Tools not listed in `tools` array of `@Agent`                                                                             | Add tool classes to the `tools` field in the `@Agent` decorator                                                                                                                  |
-| Agent times out                        | No timeout or rate limit configured                                                                                       | Add `timeout: { executeMs: 120_000 }` and `rateLimit` to `@Agent` options                                                                                                        |
-| Peer agent not callable                | Peer has `isVisible: false`, or orchestrator lacks `canSeeOtherAgents: true`, or peer is not in `visibleAgents` whitelist | Set `swarm.isVisible: true` on the peer and `swarm.canSeeOtherAgents: true` (and add the peer to `visibleAgents`) on the orchestrator                                            |
-| Agent call fails with `INVALID_OUTPUT` | The model's reply does not match the agent's `outputSchema` (a value outside an enum, or text that is not JSON)           | Tighten the prompt or loosen the schema; the error message names the field, for example `output does not match outputSchema at priority`. The result never carries a stack trace |
+| Problem                                                       | Cause                                                                                                                     | Solution                                                                                                                                                                         |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Agent not appearing in tool listing                           | Not registered in `agents` array                                                                                          | Add agent class to `@App` or `@FrontMcp` `agents` array                                                                                                                          |
+| LLM authentication error                                      | API key not set or incorrect env variable                                                                                 | Verify the environment variable name in `apiKey: { env: '...' }` is set                                                                                                          |
+| Inner tools not being called                                  | Tools not listed in `tools` array of `@Agent`                                                                             | Add tool classes to the `tools` field in the `@Agent` decorator                                                                                                                  |
+| Agent times out                                               | No timeout or rate limit configured                                                                                       | Add `timeout: { executeMs: 120_000 }` and `rateLimit` to `@Agent` options                                                                                                        |
+| Peer agent not callable                                       | Peer has `isVisible: false`, or orchestrator lacks `canSeeOtherAgents: true`, or peer is not in `visibleAgents` whitelist | Set `swarm.isVisible: true` on the peer and `swarm.canSeeOtherAgents: true` (and add the peer to `visibleAgents`) on the orchestrator                                            |
+| `AGENT_CALL_DEPTH_EXCEEDED`                                   | Agents call each other deeper than `swarm.maxCallDepth` (default 3) allows                                                | Stop the loop in `systemInstructions`, or raise `maxCallDepth` (max 10) on every agent in the chain                                                                              |
+| `AGENT_VISIBILITY_DENIED`                                     | `this.invokeAgent()` names an agent this agent doesn't see                                                                | Add it to `swarm.visibleAgents` (with `canSeeOtherAgents: true`), or nest it in `agents`                                                                                         |
+| Startup warning `declares resources [...] that nothing reads` | The agent's resources or prompts aren't exported; its model is sent tools only                                            | Export them (`exports: { resources, prompts }`) or remove them                                                                                                                   |
+| Agent call fails with `INVALID_OUTPUT`                        | The model's reply does not match the agent's `outputSchema` (a value outside an enum, or text that is not JSON)           | Tighten the prompt or loosen the schema; the error message names the field, for example `output does not match outputSchema at priority`. The result never carries a stack trace |
 
 ## Examples
 
-| Example                                                                            | Level        | Description                                                                                                                                                                                                     |
-| ---------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`basic-agent-with-tools`](../examples/create-agent/basic-agent-with-tools.md)     | Basic        | An autonomous agent that uses inner tools to review GitHub pull requests.                                                                                                                                       |
-| [`custom-multi-pass-agent`](../examples/create-agent/custom-multi-pass-agent.md)   | Intermediate | An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`.                                                                                                               |
-| [`nested-agents-with-swarm`](../examples/create-agent/nested-agents-with-swarm.md) | Advanced     | Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `use-agent:<id>` tools. Routing is driven by the orchestrator's LLM, not a declarative handoff table. |
+| Example                                                                            | Level        | Description                                                                                                                                                                                                                                                    |
+| ---------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-agent-with-tools`](../examples/create-agent/basic-agent-with-tools.md)     | Basic        | An autonomous agent that uses inner tools to review GitHub pull requests.                                                                                                                                                                                      |
+| [`custom-multi-pass-agent`](../examples/create-agent/custom-multi-pass-agent.md)   | Intermediate | An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`.                                                                                                                                                              |
+| [`nested-agents-with-swarm`](../examples/create-agent/nested-agents-with-swarm.md) | Advanced     | Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `invoke_<id>` tools, plus a nested sub-agent and `this.invokeAgent()`. Routing is driven by the orchestrator's LLM, not a declarative handoff table. |
 
 > See all examples in [`examples/create-agent/`](../examples/create-agent/)