@frontmcp/skills 1.8.6 → 1.9.0

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,25 +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 |
+| 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/)
 

package/catalog/frontmcp-development/references/create-plugin-hooks.md

@@ -62,6 +62,9 @@ These are the flow names with pre-built hook decorator exports in `@frontmcp/sdk
 | `resources:read-resource`           | Resource reading          | `ResourceHook`              |
 | `resources:list-resources`          | Resource listing          | `ListResourcesHook`         |
 | `resources:list-resource-templates` | Resource template listing | `ListResourceTemplatesHook` |
+| `prompts:get-prompt`                | Prompt retrieval          | `PromptHook`                |
+| `prompts:list-prompts`              | Prompt listing            | `ListPromptsHook`           |
+| `completion:complete`               | Argument completion       | `CompletionHook`            |
 | `agents:call-agent`                 | Agent invocation          | `AgentCallHook`             |
 | `channels:send-notification`        | Channel notification send | `ChannelSendHook`           |
 | `channels:list`                     | Channel listing           | `ChannelListHook`           |
@@ -152,10 +155,13 @@ import {
   AgentCallHook, // FlowHooksOf('agents:call-agent')
   ChannelListHook, // FlowHooksOf('channels:list')
   ChannelSendHook, // FlowHooksOf('channels:send-notification')
+  CompletionHook, // FlowHooksOf('completion:complete')
   HttpHook, // FlowHooksOf('http:request')
+  ListPromptsHook, // FlowHooksOf('prompts:list-prompts')
   ListResourcesHook, // FlowHooksOf('resources:list-resources')
   ListResourceTemplatesHook, // FlowHooksOf('resources:list-resource-templates')
   ListToolsHook, // FlowHooksOf('tools:list-tools')
+  PromptHook, // FlowHooksOf('prompts:get-prompt')
   ResourceHook, // FlowHooksOf('resources:read-resource')
   ToolHook, // FlowHooksOf('tools:call-tool')
 } from '@frontmcp/sdk';
@@ -167,7 +173,7 @@ Usage:
 const { Will, Did, Around, Stage } = ToolHook;
 ```
 
-> **Note:** Other internal flows (e.g., `prompts:get-prompt`, `prompts:list-prompts`, `skills:search`, `completion:complete`, transport flows) exist at runtime and can be hooked by passing the flow name to `FlowHooksOf<'flow:name'>('flow:name')`, but they do not currently ship with a pre-built typed export. Prefer the pre-built exports above when one is available.
+> **Note:** Other flows (e.g., `skills:filter`, transport flows) can be hooked by passing the flow name to `FlowHooksOf('flow:name')`. Prefer the pre-built exports above when one is available: exporting them is also what puts a flow's types in the published package, which is why `FlowHooksOf('prompts:get-prompt')`, `'prompts:list-prompts'` and `'completion:complete'` did not typecheck in consumer projects up to 1.8.7.
 
 ## call-tool Flow Stages
 
@@ -310,7 +316,9 @@ export class MyApp {}
 
 Plugins are initialized in array order. Hook priority determines execution order within the same stage.
 
-Hooks declared on an app's providers, on its plugins (including plugins nested inside them), and on those plugins' providers run only for that app's tools, resources and prompts (`tools:call-tool`, `resources:read-resource`, `prompts:get-prompt`, `completion:complete`), including the ones its adapters and plugins provide, such as the tools an OpenAPI adapter generates. Plugins registered on the server (`@FrontMcp({ plugins })`) apply to every app. Resources and prompts the server serves outside every app, such as the SEP-2640 `skill://` resources, run every app's hooks.
+Hooks declared on an app's providers, on its plugins (including plugins nested inside them), and on those plugins' providers run only for that app's tools, resources and prompts (`tools:call-tool`, `resources:read-resource`, `prompts:get-prompt`, `completion:complete`), including the ones its adapters and plugins provide, such as the tools an OpenAPI adapter generates. Plugins and providers registered on the server (`@FrontMcp({ plugins, providers })`) apply to every app. Resources and prompts the server serves outside every app, such as the SEP-2640 `skill://` resources, run every app's hooks.
+
+A hook declared on a `CONTEXT`-scoped provider (`@Provider({ scope: ProviderScope.CONTEXT })`, a class provider) runs on the instance built for the request or session -- the same instance the request's tools get from `this.get()`. Up to 1.8.7, hooks on server-level and `CONTEXT`-scoped providers were never registered.
 
 ## Using Hooks Inside a @Tool Class
 
@@ -377,11 +385,12 @@ class ProcessOrderTool extends ToolContext {
 ### Available Stages for Tool Hooks
 
 ```
-parseInput → findTool → checkToolAuthorization → createToolCallContext
-  → validateInput → execute → validateOutput → finalize
+parseInput → ensureRemoteCapabilities → findTool → checkToolAuthorization → checkEntryAuthorities
+  → createTaskIfRequested → createToolCallContext → checkToolCredentials → acquireQuota → acquireSemaphore
+  → validateInput → execute → validateOutput → releaseSemaphore → releaseQuota → applyUI → finalize
 ```
 
-Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
+A tool-class hook runs on the tool instance, which `createToolCallContext` builds. So it can hook `Did`/`Stage` on `createToolCallContext` and any hook on a later stage. A hook on an earlier stage, `Will`/`Around` on `createToolCallContext`, or a list-flow hook (`ListToolsHook`; listing builds no instance) fails startup with `InvalidHookFlowError` -- put those on a plugin or a provider. The same holds for `@Resource` (`createResourceContext`), `@Prompt` (`createPromptContext`) and `@Agent` (`createAgentContext`) classes. `@Job` classes cannot declare hooks at all (jobs do not run through a hookable flow); hook `tools:call-tool` for the `execute_job` tool instead. Up to 1.8.7 these hooks were accepted and silently never ran.
 
 ## Common Patterns
 
@@ -415,6 +424,7 @@ Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
 | Problem                                       | Cause                                            | Solution                                                                          |
 | --------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
 | Hook never fires                              | Plugin not registered in `plugins` array         | Add plugin class to `@App` or `@FrontMcp` `plugins` array                         |
+| `InvalidHookFlowError` at startup             | Entry-class hook that could never run            | Move early-stage, list-flow and `@Job` hooks to a plugin or a provider            |
 | Hook fires for wrong flow                     | Used wrong flow name in `FlowHooksOf`            | Verify flow name matches (e.g., `'tools:call-tool'` not `'tool:call'`)            |
 | `@Around` skips the stage entirely            | `next()` not called inside the around handler    | Always `await next()` to execute the wrapped stage                                |
 | Multiple hooks execute in wrong order         | Priorities not set or conflicting                | Set explicit `priority` values; lower numbers execute first                       |

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

@@ -5,7 +5,7 @@ description: Build plugins with providers, context extensions, lifecycle hooks,
 
 # Create a FrontMCP Plugin
 
-This skill covers building custom plugins for FrontMCP and using all 6 official plugins. Plugins are modular units that extend server behavior through providers, context extensions, lifecycle hooks, and contributed tools/resources/prompts.
+This skill covers building custom plugins for FrontMCP and using all 7 official plugins. Plugins are modular units that extend server behavior through providers, context extensions, lifecycle hooks, and contributed tools/resources/prompts.
 
 ## When to Use This Skill
 
@@ -68,6 +68,7 @@ For plugins that accept runtime configuration, extend `DynamicPlugin<TOptions, T
 ```typescript
 abstract class DynamicPlugin<TOptions extends object, TInput extends object = TOptions> {
   static dynamicProviders?(options: any): readonly ProviderType[];
+  static dynamicTools?(options: any): readonly ToolType[];
   static init<TThis>(options: InitOptions<TInput>): PluginReturn<TOptions>;
   get<T>(token: Reference<T>): T;
 }
@@ -77,6 +78,7 @@ abstract class DynamicPlugin<TOptions extends object, TInput extends object = TO
 - `TInput` -- the input type users provide to `init()` (may have optional fields)
 - `init()` creates a provider entry for use in `plugins: [...]` arrays
 - `dynamicProviders()` returns providers computed from the input options
+- `dynamicTools()` returns tools computed from the input options
 
 ## Quick Start: Minimal DynamicPlugin
 
@@ -328,6 +330,23 @@ export default class MyPlugin extends DynamicPlugin<MyPluginOptions, MyPluginOpt
 
 The reverse does not work: an option-derived provider cannot inject a provider that a nested plugin exports.
 
+### Options named like plugin metadata, and option-derived tools
+
+`init(options)` spreads the options into the plugin's metadata, so an option named like a list-valued metadata key (`tools`, `resources`, `prompts`, `skills`, `adapters`, `plugins`, `exports`, `contextExtensions`, `enforcesMetadata`) used to be read as that list: `RememberPlugin.init({ tools: { enabled: true } })` crashed at startup. A non-array value under one of those keys is now an option and stays out of the metadata; an array still contributes.
+
+`providers` follows the same rule: an array adds providers to the plugin; any other value (`MyPlugin.init({ providers: { region: 'eu' } })`) is the plugin's own option and reaches the instance instead of throwing `(extraProviders ?? []) is not iterable` at module load. When the options type declares `providers`, `init()` types the key as that option.
+
+To register tools only when an option asks for it, declare `static dynamicTools(options)`, the counterpart of `dynamicProviders`. Its tools are added to those from `@Plugin({ tools })` and from an array `tools` option:
+
+```typescript
+export default class MemoryPlugin extends DynamicPlugin<MemoryOptions, MemoryOptionsInput> {
+  static override dynamicTools = (options: MemoryOptionsInput): readonly ToolType[] =>
+    options.tools?.enabled ? [RememberTool, RecallTool] : [];
+}
+```
+
+`dynamicTools`, like `dynamicProviders`, runs on the options the plugin is built with: those given to `init(options)`, or the ones an `init({ inject, useFactory })` factory returns at startup. `RememberPlugin.init({ inject, useFactory: () => ({ type: 'memory', tools: { enabled: true } }) })` therefore registers the memory tools.
+
 ### Installing the same plugin in several apps
 
 Each app that installs a plugin gets its own copy of the plugin's providers, including CONTEXT-scoped ones. Tools, resources and prompts resolve the nearest definition in their own hierarchy (plugin, then app, then server). So `this.myService` in app A uses A's options even when app B installs `MyPlugin.init()` with different options:
@@ -340,6 +359,8 @@ class BillingApp {}
 class OpsApp {}
 ```
 
+An app that does not install the plugin does not get its providers: there, `this.get(Token)` throws and `this.tryGet(Token)` returns `undefined`. Install the plugin on the server (`@FrontMcp({ plugins })`) to share it with every app. Up to 1.8.7 the providers a plugin derives from its options (`dynamicProviders(options)`, `init({ providers })`) leaked to every other app on the server.
+
 ## Step 5: Extend Metadata and Execution Context
 
 FrontMCP provides two extension mechanisms for plugins: **metadata augmentation** (add fields to decorators) and **context extensions** (add properties to `this` in tools/resources/prompts).
@@ -458,7 +479,7 @@ export { MyServiceToken } from './my-plugin.symbols';
 
 ## Official Plugins
 
-For official plugin installation, configuration, and examples, see the **official-plugins** skill. FrontMCP provides 6 official plugins: CodeCall, Remember, Approval, Cache, Feature Flags, and Dashboard. Install individually or via `@frontmcp/plugins` (meta-package).
+For official plugin installation, configuration, and examples, see the **official-plugins** skill. FrontMCP provides 7 official plugins: CodeCall, Remember, Approval, Cache, Feature Flags, Dashboard, and WebMCP. Install individually or via `@frontmcp/plugins` (meta-package).
 
 ## Recommended Folder Structure
 

package/catalog/frontmcp-development/references/create-skill-with-tools.md

@@ -82,7 +82,9 @@ The `tools` array in `@Skill` metadata supports three ways to reference tools th
 
 ### 1. Class Reference
 
-Pass the tool class directly. The framework resolves the tool name and validates it exists in the registry.
+Pass the tool class directly (or `{ tool: ToolClass, purpose?, required? }`). The framework resolves the tool name (the tool's `id` when it declares one, else its `name`) and validates it exists in the registry. The class is only a reference: register the tool in the `tools` of the `@App` or `@FrontMcp` too. A class that isn't a `@Tool` stops the server from starting with `Invalid tool class '<ClassName>'`.
+
+Up to 1.8.7 a class reference itself stopped the server from starting (the class lost its `@Tool` name while the skill's options were validated); on those versions, reference the tool by name.
 
 ```typescript
 @Skill({
@@ -170,6 +172,8 @@ class StrictWorkflowSkill extends SkillContext {}
 | `'warn'`   | Logs a warning for missing tools but continues. Use during development when tools may not all be available yet.                  |
 | `'ignore'` | Silently ignores missing tools. Use for optional tool references or cross-server skills.                                         |
 
+In `'strict'` mode the server refuses to start, with `SkillValidationError: Skill '<name>' failed tool validation: missing tools [...]`. Up to 1.8.7 it started anyway, silently.
+
 When a caller loads the skill (`skills/load`, the `skills:load` flow, `GET /skills/{id}`, `/llm_full.txt`), a referenced tool that `availableWhen.surface` doesn't offer that caller (an agent-only tool, for an MCP client) is reported as missing, without its input schema, just as `tools/list` leaves it out. The same skill loaded by an agent lists it as available.
 
 ## Instruction Sources
@@ -652,7 +656,7 @@ class AuditServer {}
 
 ## CodeCall Compatibility
 
-When the `CodeCallPlugin` is active in `codecall_only` mode, all tools registered on the server are hidden from `list_tools`. The AI client only sees the three CodeCall meta-tools (`codecall:search`, `codecall:describe`, `codecall:execute`). This means skill instructions that reference tool names directly (e.g., "Use the `build_project` tool") become misleading -- the AI cannot call those tools because they do not appear in the tool listing.
+When the `CodeCallPlugin` is active in `codecall_only` mode, all tools registered on the server are hidden from `list_tools`. The AI client only sees the three CodeCall meta-tools (`codecall:search`, `codecall:describe`, `codecall:execute`). This means skill instructions that reference tool names directly (e.g., "Use the `build_project` tool") become misleading -- the AI cannot call those tools: they do not appear in the tool listing, and a direct `tools/call` of a hidden tool is refused as for an unknown tool.
 
 ### When This Matters
 
@@ -755,6 +759,7 @@ class DeployServiceSkill extends SkillContext {}
 | -------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | Skill not appearing in `/llm.txt`            | `visibility` is set to `'mcp'`                              | Change to `'both'` or `'http'` to include HTTP discovery                               |
 | `toolValidation: 'strict'` throws at startup | A referenced tool is not registered in the scope            | Register all referenced tools in the `tools` array of `@App` or `@FrontMcp`            |
+| `Invalid tool class` at startup              | A class in `tools` isn't decorated with `@Tool`             | Reference a `@Tool` class, or the tool's name                                          |
 | `skillDir()` fails to load                   | `SKILL.md` file missing or frontmatter is invalid YAML      | Ensure the directory contains a `SKILL.md` with valid `---` delimited YAML frontmatter |
 | Instructions are empty at runtime            | `{ file: './path.md' }` path is relative to wrong directory | Use a path relative to the skill file's location, not the project root                 |
 | Parameters not visible to AI client          | `parameters` defined as a plain object instead of an array  | Use array format: `[{ name, description, type, required }]`                            |

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

@@ -53,6 +53,8 @@ Create a class extending `SkillContext` and decorate it with `@Skill`. The decor
 | `allowedTools`      | `string`                                        | No       | Space-delimited pre-approved tool names (Agent Skills spec)    |
 | `resources`         | `SkillResources`                                | No       | Bundled dirs: `{ scripts?, references?, assets? }`             |
 
+With `toolValidation: 'strict'`, the server refuses to start when a referenced tool isn't registered (`SkillValidationError`).
+
 ### Basic Example
 
 ```typescript
@@ -158,6 +160,8 @@ class ApiStandardsSkill extends SkillContext {}
 
 > **When file and URL instructions are read:** when the server starts, for every skill — the server indexes each skill for `skills/search` and checks its tools then, so a URL is fetched at every start whether or not a client reads the skill. A read that fails is logged (`Failed to load skill <name>: …`) and tried again the first time the skill is loaded; the content is kept once a read succeeds.
 
+> **Search index:** `skills/search` ranks with TF-IDF from the optional peer `vectoriadb`, loaded the first time a search runs — not at server start. Listing and loading skills (`skills/list`, `skills/load`, `skill://` resources) never need it, so a server whose skills are never searched runs without it installed, and a server started inside a Jest test needs no `--experimental-vm-modules`. The first search without the package fails with an error naming it.
+
 ## SkillContext: loadInstructions() and build()
 
 The `SkillContext` class resolves instructions regardless of the source type. When the framework serves a skill, it calls `build()` which internally calls `loadInstructions()`.

package/catalog/frontmcp-development/references/decorators-guide.md

@@ -87,7 +87,7 @@ FrontMCP uses a hierarchical decorator system. The nesting order is:
 | `pagination?`   | List operation pagination (`tools/list` endpoint)                                                                                                                            |
 | `fetch?`        | What `this.fetch()` adds upstream: `forwardCallerTokenTo` / `forwardCustomHeadersTo` origin allow-lists (default: none), `autoInjectTracingHeaders`, `requestTimeout`        |
 | `ui?`           | UI rendering config (CDN overrides for widget imports)                                                                                                                       |
-| `extApps?`      | Widget-to-host MCP Apps communication (host capabilities, session validation)                                                                                                |
+| `extApps?`      | Widget-to-host MCP Apps communication (host capabilities, session validation). `ui/callServerTool` returns the tool's data without its page; `ui/log` answers `result: {}`   |
 | `loader?`       | Default npm/ESM package loader for `App.esm()` / `App.remote()` apps                                                                                                         |
 
 > **Throttle vs per-tool guards:** Server-level `throttle` is a `GuardConfig` object with `global`, `defaultRateLimit`, `defaultConcurrency`, `defaultTimeout` sub-fields that set server-wide defaults. Tool-level `rateLimit`, `concurrency`, `timeout` fields (on `@Tool`) override these defaults per tool.
@@ -123,7 +123,7 @@ class MyServer {}
 | `tools?`         | Array of tool classes or function-built tools                                                                                      |
 | `resources?`     | Array of resource classes or function-built resources                                                                              |
 | `prompts?`       | Array of prompt classes or function-built prompts                                                                                  |
-| `agents?`        | Array of agent classes (each exposed as `use-agent:<name>` tool)                                                                   |
+| `agents?`        | Array of agent classes (each exposed as an `invoke_<id>` tool)                                                                     |
 | `skills?`        | Array of skill definitions                                                                                                         |
 | `plugins?`       | App-scoped plugins                                                                                                                 |
 | `providers?`     | App-scoped DI providers                                                                                                            |
@@ -331,10 +331,11 @@ class UserProfileResource extends ResourceContext {
 | `llm`           | LLM configuration (model, provider, temperature, etc.) |
 | `inputSchema?`  | Zod raw shape for agent input                          |
 | `outputSchema?` | Zod schema for structured output                       |
-| `tools?`        | Tools available to this agent                          |
-| `agents?`       | Sub-agents for delegation                              |
-| `exports?`      | What capabilities to expose externally                 |
-| `swarm?`        | Multi-agent swarm configuration                        |
+| `tools?`        | Tools offered to this agent's model                    |
+| `agents?`       | Nested agents, offered to its model as `invoke_<id>`   |
+| `exports?`      | `{ resources?, prompts?, providers? }` shared with app |
+| `swarm?`        | Which other agents it can call, and how deep           |
+| `execution?`    | Loop limits, `inheritParentTools`, `inheritPlugins`    |
 
 ```typescript
 import { Agent, AgentContext, z } from '@frontmcp/sdk';
@@ -348,11 +349,7 @@ import { Agent, AgentContext, z } from '@frontmcp/sdk';
   },
   tools: [WebSearchTool, SummarizeTool],
 })
-class ResearchAgent extends AgentContext {
-  async execute(input: { topic: string }) {
-    return this.run(`Research and summarize: ${input.topic}`);
-  }
-}
+class ResearchAgent extends AgentContext {} // the default execute() runs the LLM loop
 ```
 
 ---
@@ -384,6 +381,8 @@ class ResearchAgent extends AgentContext {
 | `allowedTools?`      | Space-delimited pre-approved tool names (Agent Skills spec)                    |
 | `resources?`         | Bundled dirs: `{ scripts?, references?, assets? }` (Agent Skills spec)         |
 
+`toolValidation: 'strict'` makes the server refuse to start when a referenced tool isn't registered.
+
 ```typescript
 import { Skill } from '@frontmcp/sdk';
 

package/catalog/frontmcp-development/references/official-adapters.md

@@ -5,7 +5,7 @@ description: Overview of all official FrontMCP adapters that convert external de
 
 # Official Adapters
 
-Adapters convert external definitions (OpenAPI specs, Lambda functions, etc.) into MCP tools, resources, and prompts automatically. They are registered in the `adapters` array of `@App`.
+Adapters convert external definitions (OpenAPI specs, Lambda functions, etc.) into MCP tools, resources, and prompts automatically. They are registered in the `adapters` array of `@App` (that app's entries) or of `@FrontMcp` (entries every app serves).
 
 ## When to Use This Skill