donobu 5.17.2 → 5.18.0

package/README.md

@@ -11,7 +11,7 @@ Create, run, and heal AI-assisted Playwright flows with a single dependency. The
 
 ## Prerequisites
 
-- Node.js 18+ and npm 8+.
+- Node.js 18+ and a package manager (npm 8+, pnpm 10+, or yarn).
 - Playwright browsers (`npx playwright install`).
 - At least one LLM credential (OpenAI, Anthropic, Google Gemini, AWS Bedrock, or Donobu API).
 

package/dist/apis/TargetsApi.d.ts

@@ -1,5 +1,8 @@
 import type { Request, Response } from 'express';
+import type { TargetRuntimePluginRegistry } from '../targets/TargetRuntimePlugin';
 export declare class TargetsApi {
+    private readonly targetRuntimePlugins;
+    constructor(targetRuntimePlugins: TargetRuntimePluginRegistry);
     getTargets(_req: Request, res: Response): Promise<void>;
 }
 //# sourceMappingURL=TargetsApi.d.ts.map

package/dist/apis/TargetsApi.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TargetsApi = void 0;
-const TargetRuntimePlugin_1 = require("../targets/TargetRuntimePlugin");
 class TargetsApi {
+    constructor(targetRuntimePlugins) {
+        this.targetRuntimePlugins = targetRuntimePlugins;
+    }
     async getTargets(_req, res) {
-        const plugins = (0, TargetRuntimePlugin_1.getAllTargetRuntimePlugins)();
+        const plugins = this.targetRuntimePlugins.getAll();
         const targets = plugins.map((p) => ({
             type: p.type,
             ...p.describe(),

package/dist/apis/ToolsApi.d.ts

@@ -1,5 +1,6 @@
 import type { Request, Response } from 'express';
 import type { JSONSchema } from 'zod/v4/core';
+import type { ToolRegistry } from '../managers/ToolRegistry';
 export type SupportedTool = {
     name: string;
     description: string;
@@ -11,6 +12,8 @@ export type SupportedTool = {
  * This class reports the tools supported by the Donobu runtime.
  */
 export declare class ToolsApi {
+    private readonly toolRegistry;
+    constructor(toolRegistry: ToolRegistry);
     /**
      * GET endpoint handler that returns the supported tools as JSON
      */

package/dist/apis/ToolsApi.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolsApi = void 0;
 const v4_1 = require("zod/v4");
-const ToolManager_1 = require("../managers/ToolManager");
 const AcknowledgeUserInstruction_1 = require("../tools/AcknowledgeUserInstruction");
 const AssertPageTextTool_1 = require("../tools/AssertPageTextTool");
 const DetectBrokenLinksTool_1 = require("../tools/DetectBrokenLinksTool");
@@ -25,14 +24,17 @@ const SUPPRESSED_TOOLS_BY_NAME = new Set([
  * This class reports the tools supported by the Donobu runtime.
  */
 class ToolsApi {
+    constructor(toolRegistry) {
+        this.toolRegistry = toolRegistry;
+    }
     /**
      * GET endpoint handler that returns the supported tools as JSON
      */
     async getSupportedTools(req, res) {
         const targetType = req.query.target;
         const tools = targetType
-            ? await ToolManager_1.ToolManager.toolsForTarget(targetType)
-            : await ToolManager_1.ToolManager.allTools();
+            ? this.toolRegistry.toolsForTarget(targetType)
+            : this.toolRegistry.allTools();
         const response = tools
             .filter((tool) => !SUPPRESSED_TOOLS_BY_NAME.has(tool.name))
             .map((tool) => ({

package/dist/clients/GptClientFactory.d.ts

@@ -1,5 +1,6 @@
 import type { GptConfigInput } from '../models/GptConfig';
 import type { GptClient } from './GptClient';
+import { GptClientPluginRegistry } from './GptClientPlugin';
 /**
  * Interface for creating GPT clients from configuration objects.
  * This allows for dependency injection and easier testing.
@@ -18,9 +19,11 @@ export interface GptClientFactory {
  * based on configuration and validates them by performing a ping.
  *
  * Built-in types are handled directly; unknown types are delegated to
- * the GPT client plugin registry (see {@link getGptClientPlugin}).
+ * the GPT client plugin registry.
  */
 export declare class GptClientFactoryImpl implements GptClientFactory {
+    private readonly gptClientPlugins;
+    constructor(gptClientPlugins?: GptClientPluginRegistry);
     createClient(config: GptConfigInput): Promise<GptClient>;
     /**
      * Resolves the correct GptClient implementation for the given config.

package/dist/clients/GptClientFactory.js

@@ -13,9 +13,12 @@ const OpenAiGptClient_1 = require("./OpenAiGptClient");
  * based on configuration and validates them by performing a ping.
  *
  * Built-in types are handled directly; unknown types are delegated to
- * the GPT client plugin registry (see {@link getGptClientPlugin}).
+ * the GPT client plugin registry.
  */
 class GptClientFactoryImpl {
+    constructor(gptClientPlugins = new GptClientPlugin_1.GptClientPluginRegistry([])) {
+        this.gptClientPlugins = gptClientPlugins;
+    }
     async createClient(config) {
         const client = await this.resolveClient(config);
         await client.ping();
@@ -34,7 +37,7 @@ class GptClientFactoryImpl {
             return this.createBuiltInClient(builtIn.data);
         }
         // Fall back to plugin registry for plugin-provided types.
-        const plugin = (0, GptClientPlugin_1.getGptClientPlugin)(config.type);
+        const plugin = this.gptClientPlugins.get(config.type);
         if (plugin) {
             return plugin.createClient(config);
         }

package/dist/clients/GptClientPlugin.d.ts

@@ -14,14 +14,13 @@ export interface GptClientPlugin {
     createClient(config: Record<string, unknown>): Promise<GptClient>;
 }
 /**
- * Register a GPT client plugin under its declared type. The type should
- * match the `type` field on config objects so that
- * {@link GptClientFactoryImpl} can discover and use it.
+ * An immutable registry of GPT client plugins, keyed by config type.
+ * Created once at startup and threaded through the application.
  */
-export declare function registerGptClientPlugin(plugin: GptClientPlugin): void;
-/**
- * Look up a registered GPT client plugin by config type.
- * @internal Not part of the public API — used by GptClientFactoryImpl.
- */
-export declare function getGptClientPlugin(type: string): GptClientPlugin | undefined;
+export declare class GptClientPluginRegistry {
+    private readonly plugins;
+    constructor(plugins: GptClientPlugin[]);
+    /** Look up a registered GPT client plugin by config type. */
+    get(type: string): GptClientPlugin | undefined;
+}
 //# sourceMappingURL=GptClientPlugin.d.ts.map

package/dist/clients/GptClientPlugin.js

@@ -1,21 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerGptClientPlugin = registerGptClientPlugin;
-exports.getGptClientPlugin = getGptClientPlugin;
-const plugins = new Map();
+exports.GptClientPluginRegistry = void 0;
 /**
- * Register a GPT client plugin under its declared type. The type should
- * match the `type` field on config objects so that
- * {@link GptClientFactoryImpl} can discover and use it.
+ * An immutable registry of GPT client plugins, keyed by config type.
+ * Created once at startup and threaded through the application.
  */
-function registerGptClientPlugin(plugin) {
-    plugins.set(plugin.type, plugin);
-}
-/**
- * Look up a registered GPT client plugin by config type.
- * @internal Not part of the public API — used by GptClientFactoryImpl.
- */
-function getGptClientPlugin(type) {
-    return plugins.get(type);
+class GptClientPluginRegistry {
+    constructor(plugins) {
+        this.plugins = new Map(plugins.map((p) => [p.type, p]));
+    }
+    /** Look up a registered GPT client plugin by config type. */
+    get(type) {
+        return this.plugins.get(type);
+    }
 }
+exports.GptClientPluginRegistry = GptClientPluginRegistry;
 //# sourceMappingURL=GptClientPlugin.js.map

package/dist/codegen/CodeGenerator.d.ts

@@ -1,4 +1,5 @@
 import type { PageAiCacheContents } from '../lib/ai/cache/cache';
+import type { ToolRegistry } from '../managers/ToolRegistry';
 import type { BrowserStorageState } from '../models/BrowserStorageState';
 import type { CodeGenerationOptions } from '../models/CodeGenerationOptions';
 import type { FlowMetadata } from '../models/FlowMetadata';
@@ -16,9 +17,9 @@ export type FlowAnnotation = {
     description: string;
 };
 /** Creates a Node.js Microsoft Playwright script to replay the given flow. */
-export declare function getFlowAsPlaywrightScript(flowMetadata: FlowMetadata, toolCalls: ProposedToolCall[], options?: CodeGenerationOptions): Promise<string>;
+export declare function getFlowAsPlaywrightScript(flowMetadata: FlowMetadata, toolCalls: ProposedToolCall[], options: CodeGenerationOptions | undefined, toolRegistry: ToolRegistry): Promise<string>;
 /** Creates a Node.js Microsoft Playwright script to replay the given flow. */
-export declare function getFlowAsAiPlaywrightScript(flowMetadata: FlowMetadata, toolCalls: ProposedToolCall[], options: CodeGenerationOptions): Promise<string>;
+export declare function getFlowAsAiPlaywrightScript(flowMetadata: FlowMetadata, toolCalls: ProposedToolCall[], options: CodeGenerationOptions, toolRegistry: ToolRegistry): Promise<string>;
 /**
  * Generates a complete Playwright project structure.
  * Browser state dependencies are materialized as static JSON files
@@ -27,11 +28,11 @@ export declare function getFlowAsAiPlaywrightScript(flowMetadata: FlowMetadata,
 export declare function generateProject(flowsWithToolCalls: Array<{
     metadata: FlowMetadata;
     toolCalls: ProposedToolCall[];
-}>, resolvedBrowserStates: Map<string, BrowserStorageState>, gptConfig: GptConfigInput | undefined, options: CodeGenerationOptions): Promise<GeneratedProject>;
+}>, resolvedBrowserStates: Map<string, BrowserStorageState>, gptConfig: GptConfigInput | undefined, options: CodeGenerationOptions, toolRegistry: ToolRegistry): Promise<GeneratedProject>;
 export declare function buildCacheContents(flowsWithToolCalls: Array<{
     metadata: FlowMetadata;
     toolCalls: ProposedToolCall[];
-}>): PageAiCacheContents;
+}>, toolRegistry: ToolRegistry): Promise<PageAiCacheContents>;
 /**
  * Maps a proposed Donobu tool call to valid NodeJS Playwright code that uses
  * the `DonobuExtendedPage` extension.

package/dist/codegen/CodeGenerator.js

@@ -49,7 +49,6 @@ const cache_1 = require("../lib/ai/cache/cache");
 const cacheEntryBuilder_1 = require("../lib/ai/cache/cacheEntryBuilder");
 const cacheLocator_1 = require("../lib/ai/cache/cacheLocator");
 const DonobuFlowsManager_1 = require("../managers/DonobuFlowsManager");
-const ToolManager_1 = require("../managers/ToolManager");
 const GptConfig_1 = require("../models/GptConfig");
 const AnalyzePageTextTool_1 = require("../tools/AnalyzePageTextTool");
 const AssertPageTool_1 = require("../tools/AssertPageTool");
@@ -83,8 +82,38 @@ function getLocalPlaywrightVersion() {
     return pkgJson.version;
 }
 const PLAYWRIGHT_VERSION = getLocalPlaywrightVersion();
+/**
+ * Computes the `allowedTools` and `maxToolCalls` values as they will appear at
+ * runtime when the generated test code is executed by `PageAi.buildDescriptor`.
+ *
+ * The generated test code only emits an explicit `allowedTools` option when the
+ * flow uses non-default tools, and omits `maxToolCalls` when it equals the
+ * default. At runtime the omitted values fall back to `[]` and
+ * `DEFAULT_MAX_TOOL_CALLS` respectively. The cache lock file must store these
+ * same resolved values so that the cache key matches on the first run.
+ */
+function computeRuntimeCacheKeyFields(toolCalls, defaultToolNames, minimalToolNames, maxToolCalls) {
+    const toolNamesFromCalls = Array.from(new Set(toolCalls.map((tc) => tc.name)))
+        .filter((name) => !minimalToolNames.has(name))
+        .sort();
+    const usesNonDefaultTool = toolNamesFromCalls.some((name) => !defaultToolNames.has(name));
+    // Mirror the runtime defaulting in PageAi.buildDescriptor:
+    //   options?.allowedTools ?? []
+    const resolvedAllowedTools = usesNonDefaultTool && toolNamesFromCalls.length > 0
+        ? toolNamesFromCalls
+        : [];
+    // Mirror: options?.maxToolCalls ?? DEFAULT_MAX_TOOL_CALLS
+    const resolvedMaxToolCalls = maxToolCalls !== null &&
+        maxToolCalls !== DonobuFlowsManager_1.DonobuFlowsManager.DEFAULT_MAX_TOOL_CALLS
+        ? maxToolCalls
+        : DonobuFlowsManager_1.DonobuFlowsManager.DEFAULT_MAX_TOOL_CALLS;
+    return {
+        allowedTools: resolvedAllowedTools,
+        maxToolCalls: resolvedMaxToolCalls,
+    };
+}
 /** Creates a Node.js Microsoft Playwright script to replay the given flow. */
-async function getFlowAsPlaywrightScript(flowMetadata, toolCalls, options) {
+async function getFlowAsPlaywrightScript(flowMetadata, toolCalls, options = {}, toolRegistry) {
     // These tools are not supported in the generated script because they have
     // static outputs that have no side effects, so they are not actually
     // doing anything.
@@ -100,7 +129,7 @@ async function getFlowAsPlaywrightScript(flowMetadata, toolCalls, options) {
             description: env,
         };
     });
-    const allTools = await ToolManager_1.ToolManager.allTools();
+    const allTools = toolRegistry.allTools();
     const gptClientRequired = isGptClientRequired(flowMetadata, toolCalls, allTools);
     const gptSetupNote = gptClientRequired
         ? `* Note that this test uses tools that require the usage of an LLM, so be
@@ -174,7 +203,7 @@ ${resultJson}
     return prettifyCode(script);
 }
 /** Creates a Node.js Microsoft Playwright script to replay the given flow. */
-async function getFlowAsAiPlaywrightScript(flowMetadata, toolCalls, options) {
+async function getFlowAsAiPlaywrightScript(flowMetadata, toolCalls, options, toolRegistry) {
     const [firstToolCall, ...remaingToolCalls] = toolCalls;
     // If the first tool call is "GoToWebpage", then we peel it off and treat it
     // specially.
@@ -207,16 +236,10 @@ async function getFlowAsAiPlaywrightScript(flowMetadata, toolCalls, options) {
     const annotationsLiteral = annotations.length > 0
         ? JSON.stringify({ annotation: annotations }, null, 2)
         : null;
-    const defaultToolNames = new Set((await ToolManager_1.ToolManager.defaultTools()).map((tool) => tool.name));
-    const minimalTools = new Set((await ToolManager_1.ToolManager.minimalTools()).map((t) => t.name));
-    const toolNamesFromCalls = Array.from(new Set((specialCaseGoto ? remaingToolCalls : toolCalls).map((tc) => tc.name)))
-        .filter((tc) => {
-        // We can exclude minimal tools since they will automatically be included
-        // when running any flow anyway, so no need to muck up the code by specifying them.
-        return !minimalTools.has(tc);
-    })
-        .sort();
-    const usesNonDefaultTool = toolNamesFromCalls.some((toolName) => !defaultToolNames.has(toolName));
+    const defaultToolNames = new Set(toolRegistry.defaultTools().map((tool) => tool.name));
+    const minimalToolNames = new Set(toolRegistry.minimalTools().map((t) => t.name));
+    const effectiveToolCalls = specialCaseGoto ? remaingToolCalls : toolCalls;
+    const runtimeFields = computeRuntimeCacheKeyFields(effectiveToolCalls, defaultToolNames, minimalToolNames, flowMetadata.maxToolCalls);
     const donobuImports = ['test'];
     if (flowMetadata.resultJsonSchema !== null) {
         donobuImports.push('jsonSchemaToZod');
@@ -225,12 +248,11 @@ async function getFlowAsAiPlaywrightScript(flowMetadata, toolCalls, options) {
     if (flowMetadata.resultJsonSchema) {
         optionsLines.push(`schema: jsonSchemaToZod(${JSON.stringify(flowMetadata.resultJsonSchema)})`);
     }
-    if (usesNonDefaultTool && toolNamesFromCalls.length > 0) {
-        optionsLines.push(`allowedTools: ${JSON.stringify(toolNamesFromCalls)}`);
+    if (runtimeFields.allowedTools.length > 0) {
+        optionsLines.push(`allowedTools: ${JSON.stringify(runtimeFields.allowedTools)}`);
     }
-    if (flowMetadata.maxToolCalls !== null &&
-        flowMetadata.maxToolCalls !== DonobuFlowsManager_1.DonobuFlowsManager.DEFAULT_MAX_TOOL_CALLS) {
-        optionsLines.push(`maxToolCalls: ${flowMetadata.maxToolCalls}`);
+    if (runtimeFields.maxToolCalls !== DonobuFlowsManager_1.DonobuFlowsManager.DEFAULT_MAX_TOOL_CALLS) {
+        optionsLines.push(`maxToolCalls: ${runtimeFields.maxToolCalls}`);
     }
     if (flowMetadata.envVars && flowMetadata.envVars.length > 0) {
         optionsLines.push(`envVars: ${JSON.stringify(flowMetadata.envVars)}`);
@@ -271,7 +293,7 @@ ${aiInvocation}
  * Browser state dependencies are materialized as static JSON files
  * and referenced via storageState paths in the Playwright config.
  */
-async function generateProject(flowsWithToolCalls, resolvedBrowserStates, gptConfig, options) {
+async function generateProject(flowsWithToolCalls, resolvedBrowserStates, gptConfig, options, toolRegistry) {
     const flowsMetadata = flowsWithToolCalls.map((f) => f.metadata);
     const files = [];
     // Generate browser state JSON files and build a path map for the config.
@@ -292,7 +314,7 @@ async function generateProject(flowsWithToolCalls, resolvedBrowserStates, gptCon
     }
     const hasBrowserStates = browserStateEntries.length > 0;
     // Generate individual test files
-    const testFiles = await generateTestFiles(flowsWithToolCalls, options);
+    const testFiles = await generateTestFiles(flowsWithToolCalls, options, toolRegistry);
     files.push(...testFiles);
     // Generate playwright.config.ts
     files.push({
@@ -301,7 +323,7 @@ async function generateProject(flowsWithToolCalls, resolvedBrowserStates, gptCon
     });
     files.push({
         path: '.github/workflows/run-tests.yml',
-        content: await generateGitHubActionsWorkflow(flowsWithToolCalls, gptConfig, options, hasBrowserStates),
+        content: await generateGitHubActionsWorkflow(flowsWithToolCalls, gptConfig, options, hasBrowserStates, toolRegistry),
     });
     // Generate package.json if needed
     files.push({
@@ -318,17 +340,17 @@ async function generateProject(flowsWithToolCalls, resolvedBrowserStates, gptCon
         content: generateGitIgnore(),
     });
     const cacheFiles = options.playwrightScriptVariant === 'ai'
-        ? await buildCacheFiles(flowsWithToolCalls)
+        ? await buildCacheFiles(flowsWithToolCalls, toolRegistry)
         : [];
     files.push(...cacheFiles);
     return { files };
 }
-async function generateGitHubActionsWorkflow(flowsWithToolCalls, gptConfig, options, hasBrowserStates = false) {
+async function generateGitHubActionsWorkflow(flowsWithToolCalls, gptConfig, options, hasBrowserStates = false, toolRegistry) {
     const flowsMetadata = flowsWithToolCalls.map((f) => f.metadata);
     const allUniqueEnvVars = [
         ...new Set(flowsMetadata.flatMap((flow) => flow.envVars || [])),
     ];
-    const allTools = await ToolManager_1.ToolManager.allTools();
+    const allTools = toolRegistry.allTools();
     const gptClientRequired = flowsWithToolCalls.some((f) => {
         return isGptClientRequired(f.metadata, f.toolCalls, allTools);
     }) || !options.disableSelfHealingTests;
@@ -464,7 +486,9 @@ ${xvfbStep}
           fi
 ${pullRequestCreationSection}`;
 }
-function buildCacheContents(flowsWithToolCalls) {
+async function buildCacheContents(flowsWithToolCalls, toolRegistry) {
+    const defaultToolNames = new Set(toolRegistry.defaultTools().map((tool) => tool.name));
+    const minimalToolNames = new Set(toolRegistry.minimalTools().map((t) => t.name));
     const entries = flowsWithToolCalls
         // We can only create page.ai caches for flows that have an objective.
         .filter(({ metadata }) => metadata.overallObjective?.trim() && metadata.runMode === 'AUTONOMOUS')
@@ -487,9 +511,14 @@ function buildCacheContents(flowsWithToolCalls) {
             pageUrlForCache = metadata.web?.targetWebsite ?? '';
         }
         const cacheEntry = cacheEntryBuilder_1.PageAiCacheEntryBuilder.fromMetadata(pageUrlForCache, metadata, toolCallsForCache);
+        // Compute allowedTools and maxToolCalls as the runtime will see them,
+        // so the cache lock file keys match the keys built by PageAi.buildDescriptor
+        // when the generated test code is executed.
+        const runtimeFields = computeRuntimeCacheKeyFields(toolCallsForCache, defaultToolNames, minimalToolNames, metadata.maxToolCalls);
         return {
             ...cacheEntry,
-            allowedTools: [...cacheEntry.allowedTools],
+            allowedTools: runtimeFields.allowedTools,
+            maxToolCalls: runtimeFields.maxToolCalls,
             schema: cacheEntry.schema === null
                 ? null
                 : JSON.parse(JSON.stringify(cacheEntry.schema)),
@@ -499,10 +528,10 @@ function buildCacheContents(flowsWithToolCalls) {
         caches: entries,
     };
 }
-async function buildCacheFiles(flowsWithToolCalls) {
+async function buildCacheFiles(flowsWithToolCalls, toolRegistry) {
     const files = [];
     for (const flow of flowsWithToolCalls) {
-        const contents = buildCacheContents([flow]);
+        const contents = await buildCacheContents([flow], toolRegistry);
         if (contents.caches.length === 0) {
             continue;
         }
@@ -776,7 +805,7 @@ function generateProjectConfig(projectName, flow, storageStatePath) {
 /**
  * Generates test files for all flows
  */
-async function generateTestFiles(flowsWithToolCalls, options) {
+async function generateTestFiles(flowsWithToolCalls, options, toolRegistry) {
     const files = [];
     const scriptVariant = options.playwrightScriptVariant === 'classic' ? 'classic' : 'ai';
     for (const { metadata, toolCalls } of flowsWithToolCalls) {
@@ -784,8 +813,8 @@ async function generateTestFiles(flowsWithToolCalls, options) {
         const content = scriptVariant === 'classic' ||
             !metadata.overallObjective?.trim() ||
             metadata.runMode !== 'AUTONOMOUS'
-            ? await getFlowAsPlaywrightScript(metadata, toolCalls, options)
-            : await getFlowAsAiPlaywrightScript(metadata, toolCalls, options);
+            ? await getFlowAsPlaywrightScript(metadata, toolCalls, options, toolRegistry)
+            : await getFlowAsAiPlaywrightScript(metadata, toolCalls, options, toolRegistry);
         files.push({
             path: `tests/${fileName}`,
             content,

package/dist/esm/apis/TargetsApi.d.ts

@@ -1,5 +1,8 @@
 import type { Request, Response } from 'express';
+import type { TargetRuntimePluginRegistry } from '../targets/TargetRuntimePlugin';
 export declare class TargetsApi {
+    private readonly targetRuntimePlugins;
+    constructor(targetRuntimePlugins: TargetRuntimePluginRegistry);
     getTargets(_req: Request, res: Response): Promise<void>;
 }
 //# sourceMappingURL=TargetsApi.d.ts.map

package/dist/esm/apis/TargetsApi.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TargetsApi = void 0;
-const TargetRuntimePlugin_1 = require("../targets/TargetRuntimePlugin");
 class TargetsApi {
+    constructor(targetRuntimePlugins) {
+        this.targetRuntimePlugins = targetRuntimePlugins;
+    }
     async getTargets(_req, res) {
-        const plugins = (0, TargetRuntimePlugin_1.getAllTargetRuntimePlugins)();
+        const plugins = this.targetRuntimePlugins.getAll();
         const targets = plugins.map((p) => ({
             type: p.type,
             ...p.describe(),

package/dist/esm/apis/ToolsApi.d.ts

@@ -1,5 +1,6 @@
 import type { Request, Response } from 'express';
 import type { JSONSchema } from 'zod/v4/core';
+import type { ToolRegistry } from '../managers/ToolRegistry';
 export type SupportedTool = {
     name: string;
     description: string;
@@ -11,6 +12,8 @@ export type SupportedTool = {
  * This class reports the tools supported by the Donobu runtime.
  */
 export declare class ToolsApi {
+    private readonly toolRegistry;
+    constructor(toolRegistry: ToolRegistry);
     /**
      * GET endpoint handler that returns the supported tools as JSON
      */

package/dist/esm/apis/ToolsApi.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolsApi = void 0;
 const v4_1 = require("zod/v4");
-const ToolManager_1 = require("../managers/ToolManager");
 const AcknowledgeUserInstruction_1 = require("../tools/AcknowledgeUserInstruction");
 const AssertPageTextTool_1 = require("../tools/AssertPageTextTool");
 const DetectBrokenLinksTool_1 = require("../tools/DetectBrokenLinksTool");
@@ -25,14 +24,17 @@ const SUPPRESSED_TOOLS_BY_NAME = new Set([
  * This class reports the tools supported by the Donobu runtime.
  */
 class ToolsApi {
+    constructor(toolRegistry) {
+        this.toolRegistry = toolRegistry;
+    }
     /**
      * GET endpoint handler that returns the supported tools as JSON
      */
     async getSupportedTools(req, res) {
         const targetType = req.query.target;
         const tools = targetType
-            ? await ToolManager_1.ToolManager.toolsForTarget(targetType)
-            : await ToolManager_1.ToolManager.allTools();
+            ? this.toolRegistry.toolsForTarget(targetType)
+            : this.toolRegistry.allTools();
         const response = tools
             .filter((tool) => !SUPPRESSED_TOOLS_BY_NAME.has(tool.name))
             .map((tool) => ({

package/dist/esm/clients/GptClientFactory.d.ts

@@ -1,5 +1,6 @@
 import type { GptConfigInput } from '../models/GptConfig';
 import type { GptClient } from './GptClient';
+import { GptClientPluginRegistry } from './GptClientPlugin';
 /**
  * Interface for creating GPT clients from configuration objects.
  * This allows for dependency injection and easier testing.
@@ -18,9 +19,11 @@ export interface GptClientFactory {
  * based on configuration and validates them by performing a ping.
  *
  * Built-in types are handled directly; unknown types are delegated to
- * the GPT client plugin registry (see {@link getGptClientPlugin}).
+ * the GPT client plugin registry.
  */
 export declare class GptClientFactoryImpl implements GptClientFactory {
+    private readonly gptClientPlugins;
+    constructor(gptClientPlugins?: GptClientPluginRegistry);
     createClient(config: GptConfigInput): Promise<GptClient>;
     /**
      * Resolves the correct GptClient implementation for the given config.

package/dist/esm/clients/GptClientFactory.js

@@ -13,9 +13,12 @@ const OpenAiGptClient_1 = require("./OpenAiGptClient");
  * based on configuration and validates them by performing a ping.
  *
  * Built-in types are handled directly; unknown types are delegated to
- * the GPT client plugin registry (see {@link getGptClientPlugin}).
+ * the GPT client plugin registry.
  */
 class GptClientFactoryImpl {
+    constructor(gptClientPlugins = new GptClientPlugin_1.GptClientPluginRegistry([])) {
+        this.gptClientPlugins = gptClientPlugins;
+    }
     async createClient(config) {
         const client = await this.resolveClient(config);
         await client.ping();
@@ -34,7 +37,7 @@ class GptClientFactoryImpl {
             return this.createBuiltInClient(builtIn.data);
         }
         // Fall back to plugin registry for plugin-provided types.
-        const plugin = (0, GptClientPlugin_1.getGptClientPlugin)(config.type);
+        const plugin = this.gptClientPlugins.get(config.type);
         if (plugin) {
             return plugin.createClient(config);
         }

package/dist/esm/clients/GptClientPlugin.d.ts

@@ -14,14 +14,13 @@ export interface GptClientPlugin {
     createClient(config: Record<string, unknown>): Promise<GptClient>;
 }
 /**
- * Register a GPT client plugin under its declared type. The type should
- * match the `type` field on config objects so that
- * {@link GptClientFactoryImpl} can discover and use it.
+ * An immutable registry of GPT client plugins, keyed by config type.
+ * Created once at startup and threaded through the application.
  */
-export declare function registerGptClientPlugin(plugin: GptClientPlugin): void;
-/**
- * Look up a registered GPT client plugin by config type.
- * @internal Not part of the public API — used by GptClientFactoryImpl.
- */
-export declare function getGptClientPlugin(type: string): GptClientPlugin | undefined;
+export declare class GptClientPluginRegistry {
+    private readonly plugins;
+    constructor(plugins: GptClientPlugin[]);
+    /** Look up a registered GPT client plugin by config type. */
+    get(type: string): GptClientPlugin | undefined;
+}
 //# sourceMappingURL=GptClientPlugin.d.ts.map

package/dist/esm/clients/GptClientPlugin.js

@@ -1,21 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerGptClientPlugin = registerGptClientPlugin;
-exports.getGptClientPlugin = getGptClientPlugin;
-const plugins = new Map();
+exports.GptClientPluginRegistry = void 0;
 /**
- * Register a GPT client plugin under its declared type. The type should
- * match the `type` field on config objects so that
- * {@link GptClientFactoryImpl} can discover and use it.
+ * An immutable registry of GPT client plugins, keyed by config type.
+ * Created once at startup and threaded through the application.
  */
-function registerGptClientPlugin(plugin) {
-    plugins.set(plugin.type, plugin);
-}
-/**
- * Look up a registered GPT client plugin by config type.
- * @internal Not part of the public API — used by GptClientFactoryImpl.
- */
-function getGptClientPlugin(type) {
-    return plugins.get(type);
+class GptClientPluginRegistry {
+    constructor(plugins) {
+        this.plugins = new Map(plugins.map((p) => [p.type, p]));
+    }
+    /** Look up a registered GPT client plugin by config type. */
+    get(type) {
+        return this.plugins.get(type);
+    }
 }
+exports.GptClientPluginRegistry = GptClientPluginRegistry;
 //# sourceMappingURL=GptClientPlugin.js.map

package/dist/esm/codegen/CodeGenerator.d.ts

@@ -1,4 +1,5 @@
 import type { PageAiCacheContents } from '../lib/ai/cache/cache';
+import type { ToolRegistry } from '../managers/ToolRegistry';
 import type { BrowserStorageState } from '../models/BrowserStorageState';
 import type { CodeGenerationOptions } from '../models/CodeGenerationOptions';
 import type { FlowMetadata } from '../models/FlowMetadata';
@@ -16,9 +17,9 @@ export type FlowAnnotation = {
     description: string;
 };
 /** Creates a Node.js Microsoft Playwright script to replay the given flow. */
-export declare function getFlowAsPlaywrightScript(flowMetadata: FlowMetadata, toolCalls: ProposedToolCall[], options?: CodeGenerationOptions): Promise<string>;
+export declare function getFlowAsPlaywrightScript(flowMetadata: FlowMetadata, toolCalls: ProposedToolCall[], options: CodeGenerationOptions | undefined, toolRegistry: ToolRegistry): Promise<string>;
 /** Creates a Node.js Microsoft Playwright script to replay the given flow. */
-export declare function getFlowAsAiPlaywrightScript(flowMetadata: FlowMetadata, toolCalls: ProposedToolCall[], options: CodeGenerationOptions): Promise<string>;
+export declare function getFlowAsAiPlaywrightScript(flowMetadata: FlowMetadata, toolCalls: ProposedToolCall[], options: CodeGenerationOptions, toolRegistry: ToolRegistry): Promise<string>;
 /**
  * Generates a complete Playwright project structure.
  * Browser state dependencies are materialized as static JSON files
@@ -27,11 +28,11 @@ export declare function getFlowAsAiPlaywrightScript(flowMetadata: FlowMetadata,
 export declare function generateProject(flowsWithToolCalls: Array<{
     metadata: FlowMetadata;
     toolCalls: ProposedToolCall[];
-}>, resolvedBrowserStates: Map<string, BrowserStorageState>, gptConfig: GptConfigInput | undefined, options: CodeGenerationOptions): Promise<GeneratedProject>;
+}>, resolvedBrowserStates: Map<string, BrowserStorageState>, gptConfig: GptConfigInput | undefined, options: CodeGenerationOptions, toolRegistry: ToolRegistry): Promise<GeneratedProject>;
 export declare function buildCacheContents(flowsWithToolCalls: Array<{
     metadata: FlowMetadata;
     toolCalls: ProposedToolCall[];
-}>): PageAiCacheContents;
+}>, toolRegistry: ToolRegistry): Promise<PageAiCacheContents>;
 /**
  * Maps a proposed Donobu tool call to valid NodeJS Playwright code that uses
  * the `DonobuExtendedPage` extension.