@frontmcp/skills 1.1.2 → 1.2.0

package/catalog/frontmcp-extensibility/references/vectoriadb.md

@@ -33,73 +33,81 @@ const db = new TFIDFVectoria({
   defaultTopK: 10,
 });
 
-// Add documents (id, text)
-db.addDocument('users-list', 'List all users with pagination and filtering');
-db.addDocument('users-create', 'Create a new user account with email and password');
-db.addDocument('orders-list', 'List orders for a customer with date range filters');
+// Add documents (id, text, metadata) — metadata is required
+db.addDocument('users-list', 'List all users with pagination and filtering', { id: 'users-list' });
+db.addDocument('users-create', 'Create a new user account with email and password', { id: 'users-create' });
+db.addDocument('orders-list', 'List orders for a customer with date range filters', { id: 'orders-list' });
 
-// Build the index (required after adding documents)
-db.buildIndex();
+// Reindex (required after adding documents)
+db.reindex();
 
-// Search
-const results = db.search('find users', 5);
+// Search — second arg is SearchOptions
+const results = db.search('find users', { topK: 5 });
 // results: [{ id: 'users-list', score: 0.82 }, { id: 'users-create', score: 0.65 }]
 ```
 
-### With Field Weights
+### Combining Multiple Text Fields
 
-Weight different fields to control scoring influence:
+`TFIDFVectoria` indexes a single text string per document. To match against multiple
+conceptual fields (e.g. name + description + tags), concatenate them into one string
+when calling `addDocument`. Store the original fields in `metadata` so they remain
+available on search results.
 
 ```typescript
-const db = new TFIDFVectoria({
-  fields: {
-    name: { weight: 3 }, // Name matches are 3x more important
-    description: { weight: 2 }, // Description matches are 2x
-    tags: { weight: 1 }, // Tags are baseline
-  },
-});
+interface ToolDoc {
+  id: string;
+  name: string;
+  description: string;
+  tags: string;
+}
 
-db.addDocument('weather-tool', {
+const db = new TFIDFVectoria<ToolDoc>();
+
+const doc = {
+  id: 'weather-tool',
   name: 'get_weather',
   description: 'Fetch current weather conditions for a city',
   tags: 'weather forecast temperature',
-});
+};
 
-db.buildIndex();
-const results = db.search('temperature forecast', 5);
+// Concatenate fields into one searchable text blob
+const text = `${doc.name} ${doc.description} ${doc.tags}`;
+db.addDocument(doc.id, text, doc);
+
+db.reindex();
+const results = db.search('temperature forecast', { topK: 5 });
+// results[0].metadata.name === 'get_weather'
 ```
 
 ### FrontMCP Provider Pattern
 
 ```typescript
-import { Provider, ProviderScope } from '@frontmcp/sdk';
 import { TFIDFVectoria } from 'vectoriadb';
 
-export const FAQSearch = Symbol('FAQSearch');
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+interface FaqDoc {
+  id: string;
+  question: string;
+  answer: string;
+  tags: string;
+}
 
-@Provider({ name: 'faq-search', provide: FAQSearch, scope: ProviderScope.GLOBAL })
+@Provider({ name: 'faq-search', scope: ProviderScope.GLOBAL })
 export class FAQSearchProvider {
-  private db = new TFIDFVectoria({
-    fields: {
-      question: { weight: 3 },
-      answer: { weight: 1 },
-      tags: { weight: 2 },
-    },
-  });
+  private db = new TFIDFVectoria<FaqDoc>();
 
-  async initialize(faqs: Array<{ id: string; question: string; answer: string; tags: string }>) {
+  async initialize(faqs: FaqDoc[]) {
     for (const faq of faqs) {
-      this.db.addDocument(faq.id, {
-        question: faq.question,
-        answer: faq.answer,
-        tags: faq.tags,
-      });
+      // Concatenate fields into a single searchable text; preserve fields in metadata
+      const text = `${faq.question} ${faq.answer} ${faq.tags}`;
+      this.db.addDocument(faq.id, text, faq);
     }
-    this.db.buildIndex();
+    this.db.reindex();
   }
 
   search(query: string, limit = 5) {
-    return this.db.search(query, limit);
+    return this.db.search(query, { topK: limit });
   }
 }
 ```
@@ -111,7 +119,7 @@ Uses transformer models for true semantic understanding. "find users" matches "l
 ### Basic Usage
 
 ```typescript
-import { VectoriaDB, DocumentMetadata } from 'vectoriadb';
+import { DocumentMetadata, VectoriaDB } from 'vectoriadb';
 
 interface ProductDoc extends DocumentMetadata {
   name: string;
@@ -179,34 +187,33 @@ const results = await db.search('wireless audio', {
 ### Persistence with Storage Adapters
 
 ```typescript
-import { VectoriaDB, FileStorageAdapter } from 'vectoriadb';
+import { FileStorageAdapter, VectoriaDB } from 'vectoriadb';
 
 const db = new VectoriaDB<MyDoc>({
   storageAdapter: new FileStorageAdapter({ cacheDir: './.cache/vectors' }),
 });
 
+// initialize() automatically loads from cache if available and valid
 await db.initialize();
+
 // After adding documents, persist to disk
 await db.saveToStorage();
-// On next startup, restores without re-embedding
-await db.loadFromStorage();
+// On next startup, calling initialize() again restores without re-embedding
 ```
 
 ### FrontMCP Provider Pattern
 
 ```typescript
-import { Provider, ProviderScope } from '@frontmcp/sdk';
-import { VectoriaDB, FileStorageAdapter } from 'vectoriadb';
-import type { DocumentMetadata } from 'vectoriadb';
+import { FileStorageAdapter, VectoriaDB, type DocumentMetadata } from 'vectoriadb';
 
-export const KnowledgeBase = Symbol('KnowledgeBase');
+import { Provider, ProviderScope } from '@frontmcp/sdk';
 
 interface Article extends DocumentMetadata {
   title: string;
   category: string;
 }
 
-@Provider({ name: 'knowledge-base', provide: KnowledgeBase, scope: ProviderScope.GLOBAL })
+@Provider({ name: 'knowledge-base', scope: ProviderScope.GLOBAL })
 export class KnowledgeBaseProvider {
   private db: VectoriaDB<Article>;
   private ready: Promise<void>;
@@ -255,11 +262,14 @@ export class KnowledgeBaseProvider {
 
 ### TFIDFVectoria Options
 
-| Option                       | Type                       | Default | Description              |
-| ---------------------------- | -------------------------- | ------- | ------------------------ |
-| `defaultSimilarityThreshold` | number                     | `0.0`   | Minimum similarity score |
-| `defaultTopK`                | number                     | `10`    | Default results limit    |
-| `fields`                     | Record<string, { weight }> | None    | Field-weighted indexing  |
+| Option                       | Type   | Default | Description              |
+| ---------------------------- | ------ | ------- | ------------------------ |
+| `defaultSimilarityThreshold` | number | `0.0`   | Minimum similarity score |
+| `defaultTopK`                | number | `10`    | Default results limit    |
+
+> `TFIDFVectoria` indexes a single text string per document. To search across multiple
+> conceptual fields, concatenate them when calling `addDocument(id, text, metadata)` and
+> keep the originals in `metadata`.
 
 ## Choosing Between Engines
 
@@ -269,26 +279,26 @@ export class KnowledgeBaseProvider {
 | **Initialization** | Synchronous, instant           | Async, first-run model download           |
 | **Search quality** | Keyword-based (exact/fuzzy)    | Semantic (understands meaning)            |
 | **Best for**       | Tool discovery, FAQ, <10K docs | Knowledge base, recommendations, any size |
-| **Reindex needed** | Yes (`buildIndex()` after add) | No (auto-indexed on add)                  |
+| **Reindex needed** | Yes (`reindex()` after add)    | No (auto-indexed on add)                  |
 | **Persistence**    | Not built-in                   | FileStorageAdapter                        |
 
 ## Verification Checklist
 
 - [ ] Correct engine chosen based on requirements (TFIDFVectoria vs VectoriaDB)
 - [ ] Provider wraps the database with proper initialization
-- [ ] `buildIndex()` called after adding documents (TFIDFVectoria only)
+- [ ] `reindex()` called after adding/removing documents (TFIDFVectoria only)
 - [ ] `await db.initialize()` called before any operations (VectoriaDB only)
-- [ ] Field weights configured based on domain relevance
-- [ ] Storage adapter configured if persistence is needed
-- [ ] Search tool injects provider via `this.get(TOKEN)`
+- [ ] For TFIDFVectoria, multi-field documents concatenated into one text string
+- [ ] Storage adapter configured if persistence is needed (VectoriaDB only)
+- [ ] Search tool injects provider via `this.get(ProviderClass)`
 
 ## Examples
 
-| Example                                                                                          | Level        | Description                                                                                                                                                    |
-| ------------------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`product-catalog-search`](../examples/vectoriadb/product-catalog-search.md)                     | Advanced     | Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog. |
-| [`semantic-search-with-persistence`](../examples/vectoriadb/semantic-search-with-persistence.md) | Intermediate | Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.          |
-| [`tfidf-keyword-search`](../examples/vectoriadb/tfidf-keyword-search.md)                         | Basic        | Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.                             |
+| Example                                                                                          | Level        | Description                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`product-catalog-search`](../examples/vectoriadb/product-catalog-search.md)                     | Advanced     | Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog.                                                                                                                                   |
+| [`semantic-search-with-persistence`](../examples/vectoriadb/semantic-search-with-persistence.md) | Intermediate | Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.                                                                                                                                            |
+| [`tfidf-keyword-search`](../examples/vectoriadb/tfidf-keyword-search.md)                         | Basic        | Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider. `TFIDFVectoria` indexes a single text string per document, so multi-field documents are concatenated into one searchable blob; the original fields are kept in `metadata` for use on search results. |
 
 > See all examples in [`examples/vectoriadb/`](../examples/vectoriadb/)
 

package/catalog/frontmcp-guides/SKILL.md

@@ -160,7 +160,7 @@ export class GetWeatherTool extends ToolContext {
 **Resource** (`create-resource`):
 
 ```typescript
-import { Resource, ResourceContext } from '@frontmcp/sdk';
+import { ReadResourceResult, Resource, ResourceContext } from '@frontmcp/sdk';
 
 @Resource({
   uri: 'weather://cities',
@@ -169,8 +169,16 @@ import { Resource, ResourceContext } from '@frontmcp/sdk';
   mimeType: 'application/json',
 })
 export class CitiesResource extends ResourceContext {
-  async read() {
-    return JSON.stringify(['London', 'Tokyo', 'New York', 'Paris', 'Sydney']);
+  async execute(uri: string): Promise<ReadResourceResult> {
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(['London', 'Tokyo', 'New York', 'Paris', 'Sydney']),
+        },
+      ],
+    };
   }
 }
 ```
@@ -225,27 +233,32 @@ export default class TaskManagerServer {}
 **Provider for shared storage** (`create-provider`):
 
 ```typescript
-import type { Token } from '@frontmcp/di';
-import { Provider } from '@frontmcp/sdk';
-
-export interface TaskStore {
-  create(task: Task): Promise<Task>;
-  list(userId: string): Promise<Task[]>;
-  update(id: string, data: Partial<Task>): Promise<Task>;
-  delete(id: string): Promise<void>;
-}
-
-export const TASK_STORE: Token<TaskStore> = Symbol('TaskStore');
+import { Provider, ProviderScope } from '@frontmcp/sdk';
 
-@Provider({ token: TASK_STORE })
-export class RedisTaskStoreProvider implements TaskStore {
-  // Redis-backed implementation
+@Provider({ name: 'task-store', scope: ProviderScope.GLOBAL })
+export class TaskStoreProvider {
+  async create(task: Task): Promise<Task> {
+    /* Redis-backed implementation */
+  }
+  async list(userId: string): Promise<Task[]> {
+    /* ... */
+  }
+  async update(id: string, data: Partial<Task>): Promise<Task> {
+    /* ... */
+  }
+  async delete(id: string): Promise<void> {
+    /* ... */
+  }
 }
 ```
 
+> Use the class itself as the DI token (`this.get(TaskStoreProvider)`). For factory-built singletons (e.g. when you need async setup before the class is constructed), use `AsyncProvider({ provide, name, scope, useFactory })` instead.
+
 **Tool with DI** (`create-tool` + `create-provider`):
 
 ```typescript
+import { Tool, ToolContext, UnauthorizedError, z } from '@frontmcp/sdk';
+
 @Tool({
   name: 'create_task',
   description: 'Create a new task',
@@ -257,8 +270,10 @@ export class RedisTaskStoreProvider implements TaskStore {
 })
 export class CreateTaskTool extends ToolContext {
   async execute(input: { title: string; priority: string }) {
-    const store = this.get(TASK_STORE);
-    return store.create({ title: input.title, priority: input.priority, status: 'pending' });
+    const store = this.get(TaskStoreProvider);
+    const userId = this.auth?.user.sub;
+    if (!userId) this.fail(new UnauthorizedError('Authentication required'));
+    return store.create({ title: input.title, priority: input.priority, status: 'pending', userId });
   }
 }
 ```
@@ -325,21 +340,20 @@ export default class KnowledgeBaseServer {}
   },
   llm: {
     provider: 'anthropic',
-    model: 'claude-sonnet-4-5',
+    model: 'claude-sonnet-4-6',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
     maxTokens: 4096,
   }, // provider and model are client-configurable
+  execution: { maxIterations: 5 },
+  systemInstructions:
+    'Search for relevant documents using search_docs, synthesize findings, and produce a structured summary with source attribution.',
   tools: [SearchDocsTool, IngestDocumentTool],
 })
-export class ResearcherAgent extends AgentContext {
-  async execute(input: { topic: string; depth: string }) {
-    return this.run(
-      `Research "${input.topic}" at ${input.depth} depth. Search for relevant documents, synthesize findings, and provide a structured summary.`,
-    );
-  }
-}
+export class ResearcherAgent extends AgentContext {}
 ```
 
+> The framework drives the LLM tool-use loop via the `agents:call-agent` flow — you don't override `execute()`. Configure iteration limits and other runtime knobs through the `@Agent({ execution: { maxIterations } })` block.
+>
 > **Full working code:** See `references/example-knowledge-base.md`
 
 ---
@@ -413,8 +427,51 @@ export class ResearcherAgent extends AgentContext {
 | Tests pass but coverage below 95%        | Missing error path or branch tests                     | Run `jest --coverage` and add tests for uncovered lines      |
 | Provider state leaking between requests  | Using module-level state instead of DI                 | Move state into a `@Provider` scoped per request             |
 
+## Examples
+
+Each reference has matching examples under [`examples/<reference>/`](./examples/):
+
+### `example-knowledge-base`
+
+| Example                                                                                           | Level        | Description                                                                                                                                   |
+| ------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`agent-and-plugin`](./examples/example-knowledge-base/agent-and-plugin.md)                       | Advanced     | Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.    |
+| [`multi-app-composition`](./examples/example-knowledge-base/multi-app-composition.md)             | Basic        | Shows how to compose multiple apps (Ingestion, Search, Research) into a single server with shared providers, plugins, and agent registration. |
+| [`vector-search-and-resources`](./examples/example-knowledge-base/vector-search-and-resources.md) | Intermediate | Shows a semantic search tool with embedding generation and a resource template for retrieving documents by ID using URI parameters.           |
+
+### `example-task-manager`
+
+| Example                                                                                 | Level        | Description                                                                                                                                    |
+| --------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`auth-and-crud-tools`](./examples/example-task-manager/auth-and-crud-tools.md)         | Basic        | Shows how to create CRUD tools with authentication, using `this.context.session` for user isolation and `this.get()` for dependency injection. |
+| [`authenticated-e2e-tests`](./examples/example-task-manager/authenticated-e2e-tests.md) | Advanced     | Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.              |
+| [`redis-provider-with-di`](./examples/example-task-manager/redis-provider-with-di.md)   | Intermediate | Shows how to create a Redis-backed provider with a DI token, lifecycle hooks (`onInit`/`onDestroy`), and how tools inject it.                  |
+
+### `example-weather-api`
+
+| Example                                                                                    | Level        | Description                                                                                                                            |
+| ------------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [`server-and-app-setup`](./examples/example-weather-api/server-and-app-setup.md)           | Basic        | Shows the server entry point, app registration, and static resource for a beginner FrontMCP weather API server.                        |
+| [`unit-and-e2e-tests`](./examples/example-weather-api/unit-and-e2e-tests.md)               | Intermediate | Shows how to write unit tests for tools by mocking context methods, and E2E tests using `McpTestClient` and `TestServer`.              |
+| [`weather-tool-with-schemas`](./examples/example-weather-api/weather-tool-with-schemas.md) | Basic        | Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`. |
+
+## Accessing This Skill
+
+Skills are distributed as plain SKILL.md files plus a sibling `references/`
+and `examples/` tree, so consumers can pick whichever access mode fits:
+
+| Mode               | How it works                                                                                                                                                                                                                                                                                                                                    |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Filesystem**     | Read `libs/skills/catalog/frontmcp-guides/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point.                                                                                                                                                                             |
+| **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-guides`, `frontmcp skills read frontmcp-guides:references/<file>.md`, `frontmcp skills install frontmcp-guides` — no server required.                                                                                                                                                    |
+| **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-guides/SKILL.md`, `skill://frontmcp-guides/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. |
+
+The catalog itself is **not** an MCP server. The `skill://` URIs only resolve
+when a server has been configured to host this skill.
+
 ## Reference
 
 - [Your First Tool](https://docs.agentfront.dev/frontmcp/guides/your-first-tool)
 - Domain routers: `frontmcp-development`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-config`
 - Core skills: `setup-project`, `create-tool`, `create-resource`, `create-provider`, `create-agent`, `configure-auth`, `setup-testing`
+- Mandatory boundaries: import MCP protocol types and `McpError` from `@frontmcp/protocol` (never directly from `@modelcontextprotocol/sdk`); use `@frontmcp/utils` for crypto and file-system operations.

package/catalog/frontmcp-guides/examples/example-knowledge-base/agent-and-plugin.md

@@ -2,20 +2,26 @@
 name: agent-and-plugin
 reference: example-knowledge-base
 level: advanced
-description: 'Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.'
-tags: [guides, knowledge-base, knowledge, base, agent, plugin]
+description: Shows an autonomous research agent with inner tools and a real `ToolHook`-based plugin that hooks into the `tools:call-tool` flow for audit logging.
+tags:
+  - guides
+  - knowledge-base
+  - knowledge
+  - base
+  - agent
+  - plugin
 features:
-  - 'Agent with `@Agent` decorator, LLM config, inner tools, and system instructions'
-  - 'Using `this.run(prompt, { maxIterations })` to execute the LLM tool-use loop'
-  - "Configurable behavior via input schema (`depth: 'shallow' | 'deep'`)"
-  - 'Plugin hooks: `onToolExecuteBefore`, `onToolExecuteAfter`, `onToolExecuteError`'
-  - 'Using `ctx.state.set/get()` for flow state instead of mutating `rawInput`'
-  - 'Non-blocking audit logging (`.catch()` prevents audit failures from breaking tools)'
+  - Agent with `@Agent` decorator, LLM config, inner tools, and system instructions
+  - 'Configuring the inner-loop limit via `@Agent({ execution: { maxIterations } })` (framework drives iteration; no `this.run(...)`)'
+  - 'Plugin built on real `ToolHook` decorators: `@ToolHook.Will/Did/Around("execute")`'
+  - Using `flowCtx.state.set/get()` for hook-local state
+  - Using `flowCtx.state.required.toolContext` to read tool metadata and authInfo inside hooks
+  - Non-blocking audit logging (`.catch()` prevents audit failures from breaking tools)
 ---
 
 # Knowledge Base: Research Agent and Audit Log Plugin
 
-Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.
+Shows an autonomous research agent with inner tools and a real `ToolHook`-based plugin that hooks into the `tools:call-tool` flow for audit logging.
 
 ## Code
 
@@ -47,45 +53,38 @@ import { SearchDocsTool } from '../../search/tools/search-docs.tool';
   },
   llm: {
     provider: 'anthropic',
-    model: 'claude-sonnet-4-20250514',
+    model: 'claude-sonnet-4-6',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
     maxTokens: 4096,
   },
-  // Inner tools: the agent can call these during its execution
+  // Cap the inner tool-use loop. The framework — not your code — drives iteration.
+  execution: { maxIterations: 5 },
+  // Inner tools: the agent can call these during its execution.
   tools: [SearchDocsTool, IngestDocumentTool],
   systemInstructions: `You are a research assistant with access to a knowledge base.
 Your job is to:
 1. Search the knowledge base for relevant documents using the search_docs tool.
 2. Analyze the results and identify key themes.
-3. If depth is "deep", perform multiple searches with refined queries.
+3. When depth is "deep", perform multiple searches with refined queries; for "shallow", a single search is enough.
 4. Synthesize findings into a structured summary with source attribution.
-Always cite which documents support your findings.`,
+Always cite which documents support your findings, and return JSON matching the output schema.`,
 })
-export class ResearcherAgent extends AgentContext {
-  async execute(input: { topic: string; depth: 'shallow' | 'deep' }) {
-    const maxIterations = input.depth === 'deep' ? 5 : 2;
-    const prompt = [
-      `Research the following topic: "${input.topic}"`,
-      `Depth: ${input.depth} (max ${maxIterations} search iterations)`,
-      'Search the knowledge base, analyze results, and produce a structured summary.',
-      'Return your findings as JSON matching the output schema.',
-    ].join('\n');
-
-    // this.run() executes the LLM loop with inner tools
-    return this.run(prompt, { maxIterations });
-  }
-}
+export class ResearcherAgent extends AgentContext {}
 ```
 
 ```typescript
 // src/plugins/audit-log.plugin.ts
-import { Plugin, type PluginHookContext } from '@frontmcp/sdk';
+import { DynamicPlugin, FlowCtxOf, Plugin, ToolHook } from '@frontmcp/sdk';
+
+export interface AuditLogPluginOptions {
+  endpoint?: string;
+}
 
 @Plugin({
-  name: 'AuditLog',
+  name: 'audit-log',
   description: 'Logs all tool invocations for audit compliance',
 })
-export class AuditLogPlugin {
+export default class AuditLogPlugin extends DynamicPlugin<AuditLogPluginOptions> {
   private readonly logs: Array<{
     timestamp: string;
     tool: string;
@@ -94,52 +93,63 @@ export class AuditLogPlugin {
     success: boolean;
   }> = [];
 
-  async onToolExecuteBefore(ctx: PluginHookContext): Promise<void> {
-    // Store start time in flow state (not in rawInput)
-    ctx.state.set('audit:startTime', Date.now());
+  constructor(protected options: AuditLogPluginOptions = {}) {
+    super();
   }
 
-  async onToolExecuteAfter(ctx: PluginHookContext): Promise<void> {
-    const startTime = ctx.state.get('audit:startTime') as number;
-    const duration = Date.now() - startTime;
+  // Will('execute') runs immediately before the tool's execute() — record start time on the flow state.
+  @ToolHook.Will('execute', { priority: 100 })
+  async onWillExecute(flowCtx: FlowCtxOf<'tools:call-tool'>): Promise<void> {
+    flowCtx.state.set('audit:startTime', Date.now());
+  }
+
+  // Did('execute') runs after a successful execute() — compute duration and log success.
+  @ToolHook.Did('execute', { priority: 100 })
+  async onDidExecute(flowCtx: FlowCtxOf<'tools:call-tool'>): Promise<void> {
+    const startTime = flowCtx.state.get('audit:startTime') as number | undefined;
+    const ctx = flowCtx.state.required.toolContext;
 
     const entry = {
       timestamp: new Date().toISOString(),
-      tool: ctx.toolName,
-      userId: ctx.session?.userId,
-      duration,
+      tool: ctx.metadata.name,
+      userId: (ctx.authInfo as any)?.user?.sub as string | undefined,
+      duration: startTime ? Date.now() - startTime : 0,
       success: true,
     };
     this.logs.push(entry);
 
-    // In production, send to an external logging service
-    if (process.env.AUDIT_LOG_ENDPOINT) {
-      await ctx
-        .fetch(process.env.AUDIT_LOG_ENDPOINT, {
+    if (this.options.endpoint) {
+      // Audit logging should never block tool execution — fire-and-forget.
+      void ctx
+        .fetch(this.options.endpoint, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(entry),
         })
-        .catch(() => {
-          // Audit logging should not block tool execution
-        });
+        .catch(() => undefined);
     }
   }
 
-  async onToolExecuteError(ctx: PluginHookContext): Promise<void> {
-    const startTime = ctx.state.get('audit:startTime') as number;
-    const duration = Date.now() - startTime;
-
-    this.logs.push({
-      timestamp: new Date().toISOString(),
-      tool: ctx.toolName,
-      userId: ctx.session?.userId,
-      duration,
-      success: false,
-    });
+  // Around('execute') wraps the call so we can capture errors as well.
+  @ToolHook.Around('execute', { priority: 100 })
+  async aroundExecute(flowCtx: FlowCtxOf<'tools:call-tool'>, next: () => Promise<unknown>): Promise<unknown> {
+    try {
+      return await next();
+    } catch (err) {
+      const startTime = flowCtx.state.get('audit:startTime') as number | undefined;
+      const ctx = flowCtx.state.required.toolContext;
+      this.logs.push({
+        timestamp: new Date().toISOString(),
+        tool: ctx.metadata.name,
+        userId: (ctx.authInfo as any)?.user?.sub as string | undefined,
+        duration: startTime ? Date.now() - startTime : 0,
+        success: false,
+      });
+      throw err;
+    }
   }
 
-  getLogs(): typeof this.logs {
+  getLogs(): ReadonlyArray<(typeof this.logs)[number]> {
     return [...this.logs];
   }
 }
@@ -148,10 +158,10 @@ export class AuditLogPlugin {
 ## What This Demonstrates
 
 - Agent with `@Agent` decorator, LLM config, inner tools, and system instructions
-- Using `this.run(prompt, { maxIterations })` to execute the LLM tool-use loop
-- Configurable behavior via input schema (`depth: 'shallow' | 'deep'`)
-- Plugin hooks: `onToolExecuteBefore`, `onToolExecuteAfter`, `onToolExecuteError`
-- Using `ctx.state.set/get()` for flow state instead of mutating `rawInput`
+- Configuring the inner-loop limit via `@Agent({ execution: { maxIterations } })` (framework drives iteration; no `this.run(...)`)
+- Plugin built on real `ToolHook` decorators: `@ToolHook.Will/Did/Around("execute")`
+- Using `flowCtx.state.set/get()` for hook-local state
+- Using `flowCtx.state.required.toolContext` to read tool metadata and authInfo inside hooks
 - Non-blocking audit logging (`.catch()` prevents audit failures from breaking tools)
 
 ## Related