create-donobu-plugin 1.2.1 → 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

@@ -154,110 +154,55 @@ await build({
   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 [];
-}
-`;
+  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', 'index.ts'), indexTs);
 
-  // Create src/createTool.ts
-  const createToolTs = `import { z } from "zod/v4";
-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");
-}
-`;
-
-  await writeFile(
-    join(pluginDir, 'src', 'PluginDependencies.ts'),
-    pluginDepsTs
-  );
-
   // Create a basic README
   const readme = `# ${pluginName}
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-donobu-plugin",
-    "version": "1.2.1",
+    "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",