create-donobu-plugin 1.2.0 → 1.3.0

package/README.md

@@ -36,63 +36,73 @@ Provide the plugin name as the first argument. Names may include lowercase lette
 
 ## Generated project layout
 
-| Item                        | Description                                                                                                                                                    |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `package.json`              | Private ESM package whose `main`/`types` fields point to `dist/`. Dev dependencies are aligned with the local Donobu install so you don’t chase version drift. |
-| `tsconfig.json`             | NodeNext compiler settings that emit JS + declarations into `dist/`.                                                                                           |
-| `esbuild.config.mjs`        | Bundles the compiled JS into `dist/index.mjs`, keeping Donobu and Playwright as external dependencies.                                                         |
-| `src/index.ts`              | Entry point that must export `loadCustomTools(dependencies)` and return an array of tools.                                                                     |
-| `src/createTool.ts`         | Helper around `dependencies.donobu.Tool` that reduces boilerplate when defining tools.                                                                         |
-| `src/PluginDependencies.ts` | Strongly typed view of the objects Donobu injects into your plugin (`donobu` and `playwright`).                                                                |
-| `README.md`                 | Template instructions for the team that owns the generated plugin.                                                                                             |
+| Item                 | Description                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------ |
+| `package.json`       | Private ESM package whose `main`/`types` fields point to `dist/`.                                      |
+| `tsconfig.json`      | NodeNext compiler settings that emit JS + declarations into `dist/`.                                   |
+| `esbuild.config.mjs` | Bundles the compiled JS into `dist/index.mjs`, keeping Donobu and Playwright as external dependencies. |
+| `src/index.ts`       | Entry point that must export `loadCustomTools(dependencies)` and return an array of tools.             |
+| `README.md`          | Template instructions for the team that owns the generated plugin.                                     |
 
 Because the scaffold reuses the Donobu versions already on disk, regenerating the project after a Donobu upgrade is the fastest way to stay in lockstep.
 
 ## Authoring tools
 
-Every plugin exports `loadCustomTools(dependencies)` and returns an array of `Tool` instances. You can instantiate `dependencies.donobu.Tool` directly or use the provided helper:
+Every plugin's `index.ts` exports `loadCustomTools(dependencies)` and returns an array of `Tool` instances.
 
 ```ts
-// src/index.ts
+// Note that non-type imports from 'donobu' should be extracted from the given
+// 'deps.donobu' parameter in 'loadCustomTools'.
+import type { Tool, PluginDependencies } from 'donobu';
 import { z } from 'zod/v4';
-import { createTool } from './createTool.js';
-import type { PluginDependencies } from './PluginDependencies.js';
-
-export async function loadCustomTools(deps: PluginDependencies) {
-  const pingSchema = z.object({
-    url: z.string().url(),
-  });
-
-  const pingTool = createTool(deps, {
-    name: 'pingEndpoint',
-    description: 'Fetches a URL within the Donobu-controlled browser context.',
-    requiresGpt: false,
-    schema: pingSchema,
-    async call(ctx, { url }) {
-      const page = await ctx.browserContext.newPage();
-      const response = await page.goto(url);
-      return {
-        isSuccessful: !!response,
-        forLlm: `Fetched ${url} with status ${response?.status()}`,
-        metadata: { status: response?.status() },
-      };
-    },
-  });
-
-  return [pingTool];
+
+export async function loadCustomTools(
+  deps: PluginDependencies
+): Promise<Tool<any, any>[]> {
+  // Register your custom tools here.
+  return [
+    // Here is a small example tool for reference.
+    deps.donobu.createTool(deps, {
+      // The tool name, description, and schema are shared with the Donobu agent
+      // to help it decide when, where, and how this tool will be called.
+      name: 'judgeWebpageTitle',
+      description: 'Judge the quality of a title to a webpage.',
+      schema: z.object({ webpageTitle: z.string() }),
+      // This example tool uses a GPT/LLM so we call it out here.
+      requiresGpt: true,
+      call: async (context, parameters) => {
+        // 'requiredGpt' is true, so we are guaranteed a valid gptClient handle.
+        const resp = await context.gptClient!.getMessage([
+          {
+            type: 'user',
+            items: [
+              {
+                type: 'text',
+                text: `Judge the quality of this webpage title on a scale of 1 (worst) to 10 (best) and explain why.
+                       Title: ${parameters.webpageTitle}`,
+              },
+            ],
+          },
+        ]);
+        return {
+          // Returning false or throwing an exception will signal tool call failure.
+          isSuccessful: true,
+          // This is what is shared back with the Donobu agent.
+          forLlm: resp.text,
+          // Metadata is persisted with the tool call result, but is not shared
+          // with the Donobu agent, so this can be used to store large complex data.
+          metadata: null,
+        };
+      },
+    }),
+  ];
 }
 ```
 
-Guidelines:
-
-- Define Zod schemas for every tool so inputs from humans or the LLM are validated before your code runs.
-- Use `callFromGpt` if the GPT path needs different behavior; otherwise the helper routes GPT calls through `call`.
-- Request `requiresGpt: true` only when the tool cannot run without LLM assistance.
-
 ## Working with injected dependencies
 
-- `dependencies.donobu` exposes the public SDK: the base `Tool` class, `PlaywrightUtils`, logging helpers, type definitions, etc.
-- `dependencies.playwright` points to the same Playwright build Donobu uses, so your plugin and the core runtime stay aligned.
+- `deps.donobu` exposes the public SDK: the base `Tool` class, `PlaywrightUtils`, logging helpers, type definitions, etc.
+- `deps.playwright` points to the same Playwright build Donobu uses, so your plugin and the core runtime stay aligned.
 - Feel free to add your own dependencies; `esbuild` bundles everything except the packages listed in `external`.
 
 ## Build and install
@@ -102,7 +112,7 @@ npm run build
 npm exec install-donobu-plugin
 ```
 
-`npm run build` cleans `dist/`, reinstalls dependencies (to ensure version parity), runs TypeScript, and bundles the result. `npm exec install-donobu-plugin` validates the current folder, infers the plugin name (prefers `package.json`, falls back to the git repo name or `$USER`), and copies `dist/` into the Donobu plugins directory. Restart Donobu after every install so the new bundle is loaded.
+`npm run build` cleans `dist/`, reinstalls dependencies (to ensure version parity), runs TypeScript, and bundles the result. `npm exec install-donobu-plugin` validates the current folder, infers the plugin name (prefers `package.json`, falls back to the git repo name or `$USER`), and copies `dist/` into the Donobu plugins directory. Restart Donobu after installing so the new bundle is loaded.
 
 ## Recommended development loop
 

package/index.js

@@ -1,26 +1,26 @@
 #!/usr/bin/env node
 
-import { mkdir, writeFile, readFile } from "fs/promises";
-import { join, dirname } from "path";
-import { createRequire } from "module";
+import { mkdir, writeFile, readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { createRequire } from 'module';
 
 async function getDonobuVersions() {
   try {
     // Find the donobu package.json by resolving the module path
     const require = createRequire(import.meta.url);
-    const donobuPath = require.resolve("donobu");
+    const donobuPath = require.resolve('donobu');
     // Navigate up to find package.json (donobu path might point to dist/main.js)
     const donobuDir = dirname(donobuPath);
-    let packageJsonPath = join(donobuDir, "package.json");
+    let packageJsonPath = join(donobuDir, 'package.json');
 
     try {
-      await readFile(packageJsonPath, "utf8");
+      await readFile(packageJsonPath, 'utf8');
     } catch {
       // If not found, try going up one more directory
-      packageJsonPath = join(dirname(donobuDir), "package.json");
+      packageJsonPath = join(dirname(donobuDir), 'package.json');
     }
 
-    const packageJsonContent = await readFile(packageJsonPath, "utf8");
+    const packageJsonContent = await readFile(packageJsonPath, 'utf8');
     const donobuPackageJson = JSON.parse(packageJsonContent);
 
     return {
@@ -28,19 +28,19 @@ async function getDonobuVersions() {
       playwrightVersion:
         donobuPackageJson.devDependencies?.playwright ||
         donobuPackageJson.dependencies?.playwright ||
-        donobuPackageJson.peerDependencies?.playwright?.replace(/^>=/, "") ||
-        "1.53.2",
+        donobuPackageJson.peerDependencies?.playwright?.replace(/^>=/, '') ||
+        '1.53.2',
       playwrightTestVersion:
-        donobuPackageJson.devDependencies?.["@playwright/test"] ||
-        donobuPackageJson.dependencies?.["@playwright/test"] ||
-        donobuPackageJson.peerDependencies?.["@playwright/test"]?.replace(
+        donobuPackageJson.devDependencies?.['@playwright/test'] ||
+        donobuPackageJson.dependencies?.['@playwright/test'] ||
+        donobuPackageJson.peerDependencies?.['@playwright/test']?.replace(
           /^>=/,
-          ""
+          ''
         ) ||
-        "1.53.2",
+        '1.53.2',
     };
   } catch (error) {
-    console.error("Could not read the Donobu package.json file!");
+    console.error('Could not read the Donobu package.json file!');
     throw error;
   }
 }
@@ -54,8 +54,8 @@ async function createPluginStructure(pluginName) {
   console.log(`Using Playwright version: ${versions.playwrightVersion}`);
   // Create directory structure
   await mkdir(pluginDir, { recursive: true });
-  await mkdir(join(pluginDir, "src"), { recursive: true });
-  console.log("Creating files...");
+  await mkdir(join(pluginDir, 'src'), { recursive: true });
+  console.log('Creating files...');
   await createTemplateFiles(pluginDir, pluginName, versions);
   console.log(`\nPlugin "${pluginName}" created successfully!`);
   console.log(`\nNext steps:`);
@@ -69,71 +69,71 @@ async function createTemplateFiles(pluginDir, pluginName, versions) {
   // Create package.json
   const packageJson = {
     name: pluginName,
-    version: "1.0.0",
+    version: '1.0.0',
     private: true,
-    type: "module",
-    description: "Custom tools for use by Donobu.",
-    main: "./dist/index.mjs",
-    types: "./dist/index.d.ts",
+    type: 'module',
+    description: 'Custom tools for use by Donobu.',
+    main: './dist/index.mjs',
+    types: './dist/index.d.ts',
     exports: {
-      ".": "./dist/index.mjs",
+      '.': './dist/index.mjs',
     },
-    files: ["dist"],
+    files: ['dist'],
     scripts: {
-      clean: "rm -rf dist",
+      clean: 'rm -rf dist',
       build:
-        "npm run clean && npm install && tsc -p tsconfig.json && node esbuild.config.mjs",
+        'npm run clean && npm install && tsc -p tsconfig.json && node esbuild.config.mjs',
     },
-    license: "UNLICENSED",
+    license: 'UNLICENSED',
     devDependencies: {
       donobu: `^${versions.donobuVersion}`,
       playwright: versions.playwrightVersion,
-      "@playwright/test": versions.playwrightTestVersion,
-      typescript: "^5.8.3",
-      esbuild: "^0.25.6",
+      '@playwright/test': versions.playwrightTestVersion,
+      typescript: '^5.8.3',
+      esbuild: '^0.25.6',
     },
     peerDependencies: {
       donobu: `>=${versions.donobuVersion}`,
       playwright: `>=${versions.playwrightVersion}`,
-      "@playwright/test": `>=${versions.playwrightTestVersion}`,
+      '@playwright/test': `>=${versions.playwrightTestVersion}`,
     },
     peerDependenciesMeta: {
       playwright: {
         optional: false,
       },
-      "@playwright/test": {
+      '@playwright/test': {
         optional: false,
       },
     },
     dependencies: {
-      zod: "^3.24.1",
+      zod: '^3.25.76',
     },
   };
 
   await writeFile(
-    join(pluginDir, "package.json"),
+    join(pluginDir, 'package.json'),
     JSON.stringify(packageJson, null, 2)
   );
 
   // Create tsconfig.json
   const tsConfig = {
     compilerOptions: {
-      target: "ES2020",
-      module: "NodeNext",
-      moduleResolution: "NodeNext",
-      rootDir: "./src",
-      outDir: "./dist",
+      target: 'ES2020',
+      module: 'NodeNext',
+      moduleResolution: 'NodeNext',
+      rootDir: './src',
+      outDir: './dist',
       declaration: true,
       strict: true,
       esModuleInterop: true,
       skipLibCheck: true,
       forceConsistentCasingInFileNames: true,
     },
-    include: ["src/**/*"],
+    include: ['src/**/*'],
   };
 
   await writeFile(
-    join(pluginDir, "tsconfig.json"),
+    join(pluginDir, 'tsconfig.json'),
     JSON.stringify(tsConfig, null, 2)
   );
 
@@ -151,112 +151,57 @@ await build({
 });
 `;
 
-  await writeFile(join(pluginDir, "esbuild.config.mjs"), esbuildConfig);
+  await writeFile(join(pluginDir, 'esbuild.config.mjs'), esbuildConfig);
 
   // Create src/index.ts
-  const indexTs = `import type { Tool } from "donobu";
-import { PluginDependencies } from "./PluginDependencies.js";
+  const indexTs = `// Note that non-type imports from 'donobu' should be extracted from the given
+// 'deps.donobu' parameter in 'loadCustomTools'.
+import type { Tool, PluginDependencies } from 'donobu';
+import { z } from 'zod/v4';
 
 export async function loadCustomTools(
-  dependencies: PluginDependencies
+  deps: PluginDependencies
 ): Promise<Tool<any, any>[]> {
   // Register your custom tools here.
-  return [];
-}
-`;
-
-  await writeFile(join(pluginDir, "src", "index.ts"), indexTs);
-
-  // Create src/createTool.ts
-  const createToolTs = `import { z } from "zod";
-import type { ToolCallContext, ToolCallResult, Tool } from "donobu";
-import { PluginDependencies } from "./PluginDependencies.js";
-
-/**
- * Factory function to create a Donobu Tool instance.
- */
-export function createTool<
-  CallSchema extends z.ZodObject<any>,
-  CallFromGptSchema extends z.ZodObject<any> = CallSchema,
->(
-  dependencies: PluginDependencies,
-  options: CreateToolOptions<CallSchema, CallFromGptSchema>
-): Tool<CallSchema, CallFromGptSchema> {
-  class AnonymousTool extends dependencies.donobu.Tool<
-    CallSchema,
-    CallFromGptSchema
-  > {
-    public constructor() {
-      super(
-        options.name,
-        options.description,
-        options.schema,
-        (options.gptSchema ?? options.schema) as CallFromGptSchema,
-        options.requiresGpt
-      );
-    }
-    public override async call(
-      ctx: ToolCallContext,
-      params: z.infer<CallSchema>
-    ): Promise<ToolCallResult> {
-      return options.call(ctx, params);
-    }
-    public override async callFromGpt(
-      ctx: ToolCallContext,
-      params: z.infer<CallFromGptSchema>
-    ): Promise<ToolCallResult> {
-      return options.callFromGpt
-        ? options.callFromGpt(ctx, params)
-        : this.call(ctx, params);
-    }
-  }
-
-  return new AnonymousTool();
-}
-
-export interface CreateToolOptions<
-  CallSchema extends z.ZodObject<any>,
-  CallFromGptSchema extends z.ZodObject<any> = CallSchema,
-> {
-  /**
-   * @param name This is the name for the tool that will be shared with the LLM when making requests.
-   * @param description This is the description that will be shared with the LLM when making requests.
-   * @param inputSchema This is the JSON-schema for the tool when it is invoked by a non-LLM.
-   * @param inputSchemaForGpt This is the JSON-schema that will be shared with the LLM when making
-   *                          requests during autonomous flows.
-   * @param requiresGpt Set to true if this tool requires the usage of a GPT.
-   * @param call This is the function that will be invoked when the tool is called by a non-LLM.
-   * @param callFromGpt This is the function that will be invoked when the tool is called by an LLM.
-   */
-  name: string;
-  description: string;
-  requiresGpt: boolean;
-  schema: CallSchema;
-  gptSchema?: CallFromGptSchema;
-  call(
-    ctx: ToolCallContext,
-    params: z.infer<CallSchema>
-  ): Promise<ToolCallResult> | ToolCallResult;
-  callFromGpt?(
-    ctx: ToolCallContext,
-    params: z.infer<CallFromGptSchema>
-  ): Promise<ToolCallResult> | ToolCallResult;
-}
-`;
-
-  await writeFile(join(pluginDir, "src", "createTool.ts"), createToolTs);
-
-  // Create src/PluginDependencies.ts
-  const pluginDepsTs = `export interface PluginDependencies {
-  donobu: typeof import("donobu");
-  playwright: typeof import("playwright");
-}
-`;
+  return [
+    // Here is a small example tool for reference.
+    deps.donobu.createTool(deps, {
+      // The tool name, description, and schema are shared with the Donobu agent
+      // to help it decide when, where, and how this tool will be called.
+      name: 'judgeWebpageTitle',
+      description: 'Judge the quality of a title to a webpage.',
+      schema: z.object({ webpageTitle: z.string() }),
+      // This example tool uses a GPT/LLM so we call it out here.
+      requiresGpt: true,
+      call: async (context, parameters) => {
+        // 'requiredGpt' is true, so we are guaranteed a valid gptClient handle.
+        const resp = await context.gptClient!.getMessage([
+          {
+            type: 'user',
+            items: [
+              {
+                type: 'text',
+                text: \`Judge the quality of this webpage title on a scale of 1 (worst) to 10 (best) and explain why.
+                       Title: ${parameters.webpageTitle}\`,
+              },
+            ],
+          },
+        ]);
+        return {
+          // Returning false or throwing an exception will signal tool call failure.
+          isSuccessful: true,
+          // This is what is shared back with the Donobu agent.
+          forLlm: resp.text,
+          // Metadata is persisted with the tool call result, but is not shared
+          // with the Donobu agent, so this can be used to store large complex data.
+          metadata: null,
+        };
+      },
+    }),
+  ];
+}`;
 
-  await writeFile(
-    join(pluginDir, "src", "PluginDependencies.ts"),
-    pluginDepsTs
-  );
+  await writeFile(join(pluginDir, 'src', 'index.ts'), indexTs);
 
   // Create a basic README
   const readme = `# ${pluginName}
@@ -274,24 +219,24 @@ A custom Donobu plugin with tools for browser automation.
 3. Restart Donobu to see your tools
 `;
 
-  await writeFile(join(pluginDir, "README.md"), readme);
+  await writeFile(join(pluginDir, 'README.md'), readme);
 }
 
 async function main() {
   const pluginName = process.argv[2];
 
   if (!pluginName) {
-    console.error("Usage: create-donobu-plugin <plugin-name>");
-    console.error("");
-    console.error("Example:");
-    console.error("  npm create donobu-plugin my-awesome-plugin");
+    console.error('Usage: create-donobu-plugin <plugin-name>');
+    console.error('');
+    console.error('Example:');
+    console.error('  npm create donobu-plugin my-awesome-plugin');
     process.exit(1);
   }
 
   // Validate plugin name
   if (!/^[a-z0-9-_]+$/.test(pluginName)) {
     console.error(
-      "Plugin name must contain only lowercase letters, numbers, hyphens, and underscores"
+      'Plugin name must contain only lowercase letters, numbers, hyphens, and underscores'
     );
     process.exit(1);
   }
@@ -299,7 +244,7 @@ async function main() {
   try {
     await createPluginStructure(pluginName);
   } catch (error) {
-    console.error("Failed to create plugin:", error.message);
+    console.error('Failed to create plugin:', error.message);
     process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-donobu-plugin",
-    "version": "1.2.0",
+    "version": "1.3.0",
     "type": "module",
     "description": "Create a new Donobu plugin",
     "author": "Donobu",
@@ -13,7 +13,7 @@
         "index.js"
     ],
     "dependencies": {
-        "donobu": "^3.3.0"
+        "donobu": "^3.4.0"
     },
     "keywords": [
         "donobu",