@frontmcp/skills 1.8.6 → 1.9.0

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

@@ -123,6 +123,10 @@ npx wrangler kv:namespace create FRONTMCP_KV
 
 Copy the returned `id` into your `wrangler.toml`.
 
+Cloudflare storage: `redis: { provider: 'vercel-kv' }` (the HTTP-based Upstash/Vercel KV client) is accepted by `--target cloudflare`; only TCP `redis` and `sqlite` configs are rejected at build time, since Workers cannot open raw sockets or load native modules.
+
+To use it for sessions, install `@vercel/kv` in the project (the build bundles it into the worker), set `KV_REST_API_URL` / `KV_REST_API_TOKEN` as `[vars]` or secrets, and set `compatibility_date` to `2024-11-11` or later: the Upstash client sends `cache: 'no-store'` on every request, which Workers reject before that date (`The 'cache' field on 'RequestInitializerDict' is not implemented`). The build accepts the provider when it can read it, either from the evaluated config or written literally as `redis: { provider: 'vercel-kv' }` in `@FrontMcp({...})`; a `redis` whose provider it can read neither way is refused, and the error says so.
+
 ## Step 4: Configure the Server
 
 ```typescript
@@ -149,7 +153,7 @@ For session storage, use Upstash Redis (HTTP) via `redis: { provider: 'vercel-kv
 
 ### Secrets, vars and `process.env`
 
-Worker bindings arrive as an argument to `fetch`, not as environment variables. The generated entry copies every **string** binding into `process.env` on the first request (existing values are never overwritten), so ordinary `process.env.MY_API_KEY` reads behave the same on Workers as under `frontmcp dev`. Non-string bindings (KV, D1, R2, Durable Objects) stay on `env`, which the entry forwards to the handler along with `ctx`.
+Worker bindings arrive as an argument to `fetch`, not as environment variables. The generated entry copies every **string** binding into `process.env` on the first request (existing values are never overwritten), so ordinary `process.env.MY_API_KEY` reads behave the same on Workers as under `frontmcp dev`. Non-string bindings (KV, D1, R2, Durable Objects) stay on `env`, which the entry forwards to the handler along with `ctx`. Inside a tool, resource, prompt, agent or job, read them with `this.workerEnv` (e.g. `this.workerEnv?.MY_KV as KVNamespace | undefined`) — it is the request's Worker `env` (string bindings included), read-only, and `undefined` where the request carries no `env` (Node/Express, stdio, `create()`/`connect()` direct servers); a job run by `execute_job` reads the `env` of the request that ran it. The `process.env` copy is the generated entry's doing: the SDK never writes `process.env`, so a hand-written entry around `createWebFetchHandler` / `getServerlessHandlerAsync()` does not get it. `NODE_ENV = "production"` set in `wrangler.toml` `[vars]` is read live by the runtime context, so production mode takes effect even though the value reaches `process.env` only on the first request. Wrangler inlines the literal `process.env.NODE_ENV` at build time (`"development"` under `wrangler dev`, `"production"` under `wrangler deploy`, unless the shell sets `NODE_ENV`); FrontMCP reads the `[vars]` value past that, so `this.runtimeContext.env` / `this.isEnv('production')` follow `[vars]` under `wrangler dev` too. A `process.env.NODE_ENV` in your own tool code is still wrangler's constant — read `this.runtimeContext.env`, or run `NODE_ENV=production npx wrangler dev`.
 
 A value read at module-eval time — inside the `@FrontMcp({...})` argument itself — is still `undefined`, because the copy happens on the first request. Read configuration inside `execute()` / `read()`, or rely on `nodejs_compat_populate_process_env` (emitted by default), which populates `process.env` before your module evaluates.
 

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

@@ -36,13 +36,13 @@ This skill walks you through deploying a FrontMCP server to AWS Lambda with API
 - SAM CLI installed: `brew install aws-sam-cli` (macOS) or see AWS docs
 - Node.js 24 or later
 - A FrontMCP project ready to build
-- **Peer dependency:** `@codegenie/serverless-express` installed in your project. The Lambda adapter externalizes it at bundle time and validates its presence at build time:
+- **Peer dependency:** `@codegenie/serverless-express` installed in your project. The Lambda adapter validates its presence at build time and bundles it into `handler.cjs`, so `dist/lambda/` deploys on its own (`CodeUri: dist/lambda/`, no `node_modules` or Layer needed):
 
   ```bash
   npm install @codegenie/serverless-express
   ```
 
-  If it isn't installed, `frontmcp build --target lambda` fails with a clear error before producing artifacts.
+  If it isn't installed, `frontmcp build --target lambda` fails with a clear error before producing artifacts. `frontmcp create --target lambda` adds it to `dependencies` for you.
 
 ## Step 1: Build for Lambda
 
@@ -318,14 +318,15 @@ Lambda cold starts occur when a new execution environment is initialized. Strate
 
 ## Troubleshooting
 
-| Problem                              | Cause                                                           | Solution                                                                                                  |
-| ------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| Timeout errors                       | Function timeout too low or waiting on unreachable resource     | Increase `Timeout` in the SAM template; verify network connectivity to dependencies                       |
-| 502 Bad Gateway                      | Handler path mismatch, missing env vars, or unhandled exception | Check CloudWatch Logs; confirm `Handler: handler.handler` and `CodeUri: dist/lambda/`                     |
-| `Cannot find module @codegenie/...`  | Peer dep not installed locally or in Layer                      | `npm install @codegenie/serverless-express` (the build's `validate` hook checks for it)                   |
-| Cold starts too slow                 | Low memory, x86 architecture, or large bundle                   | Increase memory to 512+ MB, use `arm64`, or enable provisioned concurrency                                |
-| Redis connection refused from Lambda | Lambda not in the same VPC as ElastiCache                       | Place the Lambda in the ElastiCache VPC with appropriate security group rules                             |
-| `sam deploy` fails with IAM error    | Insufficient permissions for CloudFormation stack creation      | Ensure the deploying IAM user/role has `cloudformation:*`, `lambda:*`, `apigateway:*`, and `iam:PassRole` |
+| Problem                              | Cause                                                                                | Solution                                                                                                       |
+| ------------------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| Timeout errors                       | Function timeout too low or waiting on unreachable resource                          | Increase `Timeout` in the SAM template; verify network connectivity to dependencies                            |
+| 502 Bad Gateway                      | Handler path mismatch, missing env vars, or unhandled exception                      | Check CloudWatch Logs; confirm `Handler: handler.handler` and `CodeUri: dist/lambda/`                          |
+| `Cannot find module @codegenie/...`  | Peer dep not installed locally or in Layer                                           | `npm install @codegenie/serverless-express` (the build's `validate` hook checks for it)                        |
+| Cold starts too slow                 | Low memory, x86 architecture, or large bundle                                        | Increase memory to 512+ MB, use `arm64`, or enable provisioned concurrency                                     |
+| Redis connection refused from Lambda | Lambda not in the same VPC as ElastiCache                                            | Place the Lambda in the ElastiCache VPC with appropriate security group rules                                  |
+| 500 `server_misconfigured`           | A required secret is missing (`SESSION_SECRET_REQUIRED`, `JWT_SECRET_REQUIRED`, ...) | The response body names the `code` and the remedy; set the variable in the function's environment and redeploy |
+| `sam deploy` fails with IAM error    | Insufficient permissions for CloudFormation stack creation                           | Ensure the deploying IAM user/role has `cloudformation:*`, `lambda:*`, `apigateway:*`, and `iam:PassRole`      |
 
 ## Examples
 

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/deploy-to-vercel.md

@@ -90,6 +90,8 @@ export default MyServer;
 
 Provision the KV store in the Vercel dashboard under **Storage > Create Database > KV (Redis)**, then link it to your project. Vercel automatically injects the required environment variables.
 
+> **Tasks and elicitation on Vercel KV:** Vercel KV has no pub/sub, so background tasks and elicitation cannot use it. The server still starts — tasks are skipped with a `[tasks]` startup warning unless `tasks: { enabled: true }` is set (which keeps `TaskStoreNotSupportedError`), and elicitation throws `ElicitationNotSupportedError` only when its store actually resolves to Vercel KV. Give tasks their own backend with `tasks: { redis }` or `tasks: { sqlite }` (an explicit backend ignores the ambient `KV_REST_API_URL`).
+
 ## Step 3: Environment Variables
 
 Vercel KV variables are injected automatically when the store is linked. For manual setup or additional configuration, set them in the Vercel dashboard (**Settings > Environment Variables**) or via the CLI:
@@ -178,6 +180,11 @@ Serverless functions are stateless between invocations. All persistent state mus
 | Routing               | `.vercel/output/config.json` (auto)                      | Hand-written `rewrites` to `/api/frontmcp` | The adapter writes `routes: [{ src: '/(.*)', dest: '/index' }]` for you |
 | Environment variables | Link KV store in dashboard (auto-injected)               | Hardcode `KV_REST_API_URL` in source       | Linked stores inject vars automatically and rotate tokens safely        |
 
+### Bundle-time behavior of serverless builds
+
+- `process.env.NODE_ENV` stays a runtime lookup in the Vercel and Lambda bundles. It is not inlined as `"production"` at build time, so a deployment's own `NODE_ENV` (and the production-only checks that read it) behave the same as on a Node server.
+- Optional packages the server may or may not use (`@frontmcp/storage-sqlite`, `@frontmcp/observability`, `@vercel/kv`, `@opentelemetry/sdk-trace-base`) are bundled when installed and left as a lazy `require()` when they are not, so a missing optional package no longer fails the build with "Module not found". `better-sqlite3` (a native addon) is always left external.
+
 ## Verification Checklist
 
 **Build**
@@ -205,13 +212,14 @@ Serverless functions are stateless between invocations. All persistent state mus
 
 ## Troubleshooting
 
-| Problem              | Cause                                   | Solution                                                                                       |
-| -------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| Function timeout     | Operation exceeds plan's max duration   | Check plan limits (Hobby: 10s, Pro: 60s); upgrade plan or refactor the slow tool               |
-| KV connection errors | KV store not linked or env vars missing | Re-link the KV store in the Vercel dashboard; verify `KV_REST_API_URL` and `KV_REST_API_TOKEN` |
-| 404 on every route   | Build did not produce `.vercel/output/` | Ensure `frontmcp build --target vercel` ran before `vercel` deploys                            |
-| Bundle too large     | Unnecessary dependencies included       | Review dependencies and remove unused packages to reduce bundle size                           |
-| Cold starts too slow | Heavy decorator initialization          | Lazy-load providers; defer heavy work until first tool call                                    |
+| Problem                    | Cause                                                                                | Solution                                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| Function timeout           | Operation exceeds plan's max duration                                                | Check plan limits (Hobby: 10s, Pro: 60s); upgrade plan or refactor the slow tool                            |
+| KV connection errors       | KV store not linked or env vars missing                                              | Re-link the KV store in the Vercel dashboard; verify `KV_REST_API_URL` and `KV_REST_API_TOKEN`              |
+| 404 on every route         | Build did not produce `.vercel/output/`                                              | Ensure `frontmcp build --target vercel` ran before `vercel` deploys                                         |
+| Bundle too large           | Unnecessary dependencies included                                                    | Review dependencies and remove unused packages to reduce bundle size                                        |
+| Cold starts too slow       | Heavy decorator initialization                                                       | Lazy-load providers; defer heavy work until first tool call                                                 |
+| 500 `server_misconfigured` | A required secret is missing (`SESSION_SECRET_REQUIRED`, `JWT_SECRET_REQUIRED`, ...) | The response body names the `code` and the remedy; set the variable in Vercel Project Settings and redeploy |
 
 ## Examples
 

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