create-donobu-plugin 1.2.1 → 1.7.0

package/README.md

@@ -1,99 +1,191 @@
 # create-donobu-plugin
 
-`create-donobu-plugin` is the official scaffolding CLI for Donobu Studio plugins. It generates a TypeScript workspace wired to Donobu’s plugin API, pins dependencies to whatever versions your local Studio installation already uses, and ships with helper utilities so you can focus on describing new tools instead of wiring.
+`create-donobu-plugin` is the official scaffolding CLI for Donobu Studio plugins. It generates a TypeScript project wired to Donobu's plugin API and pins dependencies to whatever versions your local Donobu installation already uses.
 
 ## How Donobu loads plugins
 
-- Donobu watches a plugins directory inside its working data folder (macOS: `~/Library/Application Support/Donobu Studio/plugins`, Windows: `%APPDATA%/Donobu Studio/plugins`, Linux: `~/.config/Donobu Studio/plugins`).
-- Each plugin ships a bundled `dist/index.mjs` that exports one async function named `loadCustomTools(dependencies)`. When Donobu starts it imports every plugin bundle and calls that function to collect tools.
-- `npm exec install-donobu-plugin` builds your project and copies the resulting `dist/` folder into `<workingDir>/plugins/<plugin-name>`, so restarting Donobu is enough to pick up changes.
+Donobu watches a plugins directory inside its working data folder:
 
-Keep those three rules in mind and your plugin will load reliably.
+| Platform | Path                                                   |
+| -------- | ------------------------------------------------------ |
+| macOS    | `~/Library/Application Support/Donobu Studio/plugins/` |
+| Windows  | `%APPDATA%/Donobu Studio/plugins/`                     |
+| Linux    | `~/.config/Donobu Studio/plugins/`                     |
+
+Each plugin ships a bundled `dist/index.mjs`. On startup Donobu imports every plugin and calls the exported functions it finds:
+
+- **`loadCustomTools(deps)`** — returns an array of `Tool` instances.
+- **`loadPersistencePlugin(deps)`** — returns `{ key, plugin }` to register a persistence backend, or `null` to skip.
+
+A single plugin may export both functions. Scoped package names (e.g., `@myorg/my-plugin`) are supported.
+
+`npm exec install-donobu-plugin` builds your project and copies `dist/` into the plugins directory. Restarting Donobu is enough to pick up changes.
 
 ## Prerequisites
 
-- Node.js 18+ and npm 8+
+- Node.js 20+ and a package manager (npm 8+, pnpm 10+, or yarn)
 - A local Donobu Studio installation (desktop or backend) so the installer has somewhere to copy the plugin bundle
-- Playwright browsers installed (Donobu will prompt you if they are missing)
 - Write access to the Donobu Studio working directory
 
-## Installation
+## Quick start
+
+### Tool plugin (default)
 
 ```bash
 npx create-donobu-plugin my-support-tools
+cd my-support-tools && npm install
+# Edit src/index.ts to add your custom tools
+npm run build
+npm exec install-donobu-plugin
+# Restart Donobu Studio
 ```
 
-Provide the plugin name as the first argument. Names may include lowercase letters, numbers, hyphens, and underscores. The CLI prints usage information if the argument is missing or invalid.
+### Persistence plugin
 
-## Quick start
+```bash
+npx create-donobu-plugin my-storage --type persistence
+cd my-storage && npm install
+# Edit src/index.ts to implement your persistence plugin
+npm run build
+npm exec install-donobu-plugin
+# Set PERSISTENCE_PRIORITY to include your plugin key, then restart Donobu
+```
 
-1. Scaffold a plugin: `npx create-donobu-plugin my-support-tools`
-2. `cd my-support-tools && npm install`
-3. Implement your tools in `src/index.ts`
-4. `npm run build`
-5. `npm exec install-donobu-plugin`
-6. Restart Donobu Studio and verify the tools appear in the UI/logs
+Plugin names may include lowercase letters, numbers, hyphens, and underscores. The CLI prints usage information if the argument is missing or invalid.
 
 ## 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 package with `"donobu-plugin": true`. `donobu` is a peer/dev dependency, never bundled. |
+| `tsconfig.json`      | ES2021 + NodeNext compiler settings that emit declarations into `dist/`.                        |
+| `esbuild.config.mjs` | Bundles TypeScript source into `dist/index.mjs`, keeping `donobu` external.                     |
+| `src/index.ts`       | Entry point. Exports `loadCustomTools(deps)` and/or `loadPersistencePlugin(deps)`.              |
+| `README.md`          | Template instructions for the team that owns the generated plugin.                              |
+
+## The deps pattern
+
+Plugins receive all runtime values through the `deps` parameter — **never use value imports from `donobu`**. Only `import type` is allowed because type imports are erased at compile time, while value imports would produce an `import ... from "donobu"` statement in the bundle that Node cannot resolve from the plugins directory.
+
+```ts
+// CORRECT — type imports are erased, runtime values come from deps
+import type { Tool, PluginDependencies } from 'donobu';
+
+export async function loadCustomTools(
+  deps: PluginDependencies,
+): Promise<Tool<any, any>[]> {
+  const logger = deps.donobu.appLogger; // runtime access via deps
+  // ...
+}
+```
+
+```ts
+// WRONG — this creates a runtime import that will fail at load time
+import { appLogger } from 'donobu';
+```
+
+### What is available on `deps`
+
+- **`deps.donobu`** — the full public SDK: `createTool`, `Tool`, `ReplayableInteraction`, `appLogger`, `MiscUtils`, `PlaywrightUtils`, schemas, exception classes, etc.
 
-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.
+Feel free to add your own npm dependencies; esbuild bundles everything except the packages listed in `external`.
 
-## Authoring tools
+## Authoring tool plugins
 
-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 tool plugin exports `loadCustomTools(deps)` and returns an array of `Tool` instances. The simplest way to create a tool is `deps.donobu.createTool()`:
 
 ```ts
-// src/index.ts
+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() },
-      };
-    },
-  });
+export async function loadCustomTools(
+  deps: PluginDependencies,
+): Promise<Tool<any, any>[]> {
+  return [
+    deps.donobu.createTool(deps, {
+      name: 'judgeWebpageTitle',
+      description: 'Judge the quality of a title to a webpage.',
+      schema: z.object({ webpageTitle: z.string() }),
+      requiresGpt: true,
+      call: async (context, parameters) => {
+        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 {
+          isSuccessful: true,
+          forLlm: resp.text,
+          metadata: null,
+        };
+      },
+    }),
+  ];
+}
+```
+
+For tools that need to extend `ReplayableInteraction` or another base class, use a factory function so the base class comes from `deps.donobu` rather than a value import:
+
+```ts
+import type { Tool, PluginDependencies } from 'donobu';
+
+function createMyTool(deps: PluginDependencies): Tool<any, any> {
+  const { ReplayableInteraction } = deps.donobu;
+
+  class MyTool extends ReplayableInteraction</* ... */> {
+    // ...
+  }
 
-  return [pingTool];
+  return new MyTool();
+}
+
+export async function loadCustomTools(deps: PluginDependencies) {
+  return [createMyTool(deps)];
 }
 ```
 
-Guidelines:
+## Authoring persistence plugins
 
-- 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.
+Persistence plugins export `loadPersistencePlugin(deps)`. The returned `key` must appear in the `PERSISTENCE_PRIORITY` environment variable for Donobu to use it.
 
-## Working with injected dependencies
+```ts
+import type {
+  EnvPersistence,
+  FlowsPersistence,
+  PersistencePlugin,
+  PluginDependencies,
+} from 'donobu';
+
+export async function loadPersistencePlugin(
+  deps: PluginDependencies,
+): Promise<{ key: string; plugin: PersistencePlugin } | null> {
+  const bucket = process.env.MY_STORAGE_BUCKET;
+  if (!bucket) return null; // skip registration if config is missing
+
+  return {
+    key: 'MY_CUSTOM',
+    plugin: {
+      async createFlowsPersistence(): Promise<FlowsPersistence | null> {
+        // Return your FlowsPersistence implementation, or null.
+        return null;
+      },
+      async createEnvPersistence(): Promise<EnvPersistence | null> {
+        // Return your EnvPersistence implementation, or null.
+        return null;
+      },
+    },
+  };
+}
+```
 
-- `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.
-- Feel free to add your own dependencies; `esbuild` bundles everything except the packages listed in `external`.
+If your persistence classes need SDK utilities like `appLogger` or `FlowNotFoundException`, accept `deps.donobu` as a constructor parameter rather than importing them directly.
 
 ## Build and install
 
@@ -102,7 +194,24 @@ 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/`, runs TypeScript (for declarations), and bundles the source with esbuild. `npm exec install-donobu-plugin` infers the plugin name from `package.json` and copies `dist/` into the Donobu plugins directory. Restart Donobu after installing so the new bundle is loaded.
+
+## esbuild considerations
+
+The generated `esbuild.config.mjs` bundles your TypeScript source and all third-party dependencies into a single `dist/index.mjs`, while keeping `donobu` external (it is injected at runtime by the plugin loader). The `mainFields: ['module', 'main']` option ensures esbuild prefers ESM entry points from third-party packages for cleaner output.
+
+If you add dependencies that include CJS modules using `require()` for Node builtins (common in Google Cloud, AWS, or gRPC libraries), the bundle may fail at runtime with `"Dynamic require of X is not supported"`. Fix this by adding a `banner` that provides a real `require()`:
+
+```js
+await build({
+  // ... your existing options ...
+  banner: {
+    js: 'import { createRequire } from "module"; const require = createRequire(import.meta.url);',
+  },
+});
+```
+
+This injects a real `require()` via Node's `createRequire`, allowing bundled CJS code to resolve Node builtins normally in the ESM context.
 
 ## Recommended development loop
 
@@ -111,10 +220,9 @@ npm exec install-donobu-plugin
 3. Restart Donobu Studio or the backend process
 4. Trigger your tool from the UI or API to verify behavior
 
-Because the default build script runs `npm install`, consider splitting the script into `build` and `bundle` variants if you need faster inner-loop iterations.
-
 ## Troubleshooting
 
 - **Plugin not appearing:** Ensure `npm exec install-donobu-plugin` ran successfully and that `dist/index.mjs` exists. Restart Donobu and watch the logs for plugin loading messages.
-- **Schema errors:** Zod throws runtime errors when inputs don’t match your schema. Log the error message to quickly see which field failed.
-- **Version mismatch:** If Donobu upgrades Playwright or its SDK, re-run the scaffold (or update the plugin’s dev dependencies) so you stay compatible.
+- **"Cannot find package 'donobu'":** Your bundle contains a runtime `import ... from "donobu"`. Ensure all `donobu` imports use `import type` and access runtime values through `deps.donobu`.
+- **"Dynamic require of X is not supported":** A bundled CJS dependency calls `require()` for a Node builtin. Add the `createRequire` banner to your esbuild config (see above).
+- **Schema errors:** Zod throws runtime errors when inputs don't match your schema. Log the error message to quickly see which field failed.

package/index.js

@@ -1,152 +1,131 @@
 #!/usr/bin/env node
 
-import { mkdir, writeFile, readFile } from 'fs/promises';
-import { join, dirname } from 'path';
-import { createRequire } from 'module';
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
 
-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');
-    // Navigate up to find package.json (donobu path might point to dist/main.js)
-    const donobuDir = dirname(donobuPath);
-    let packageJsonPath = join(donobuDir, 'package.json');
-
-    try {
-      await readFile(packageJsonPath, 'utf8');
-    } catch {
-      // If not found, try going up one more directory
-      packageJsonPath = join(dirname(donobuDir), 'package.json');
-    }
+const DONOBU_VERSION = '5.17.2';
+const VALID_PLUGIN_TYPES = ['tool', 'persistence'];
 
-    const packageJsonContent = await readFile(packageJsonPath, 'utf8');
-    const donobuPackageJson = JSON.parse(packageJsonContent);
-
-    return {
-      donobuVersion: donobuPackageJson.version,
-      playwrightVersion:
-        donobuPackageJson.devDependencies?.playwright ||
-        donobuPackageJson.dependencies?.playwright ||
-        donobuPackageJson.peerDependencies?.playwright?.replace(/^>=/, '') ||
-        '1.53.2',
-      playwrightTestVersion:
-        donobuPackageJson.devDependencies?.['@playwright/test'] ||
-        donobuPackageJson.dependencies?.['@playwright/test'] ||
-        donobuPackageJson.peerDependencies?.['@playwright/test']?.replace(
-          /^>=/,
-          ''
-        ) ||
-        '1.53.2',
-    };
-  } catch (error) {
-    console.error('Could not read the Donobu package.json file!');
-    throw error;
-  }
-}
-
-async function createPluginStructure(pluginName) {
+async function createPluginStructure(pluginName, pluginType) {
   const pluginDir = join(process.cwd(), pluginName);
-  console.log(`Creating plugin directory: ${pluginDir}`);
-  // Get current donobu and playwright versions
-  const versions = await getDonobuVersions();
-  console.log(`Using Donobu version: ${versions.donobuVersion}`);
-  console.log(`Using Playwright version: ${versions.playwrightVersion}`);
+  console.log(`Creating ${pluginType} plugin directory: ${pluginDir}`);
+  const donobuVersion = DONOBU_VERSION;
+  console.log(`Using Donobu version: ${donobuVersion}`);
   // Create directory structure
   await mkdir(pluginDir, { recursive: true });
   await mkdir(join(pluginDir, 'src'), { recursive: true });
   console.log('Creating files...');
-  await createTemplateFiles(pluginDir, pluginName, versions);
+
+  if (pluginType === 'persistence') {
+    await createPersistenceTemplateFiles(pluginDir, pluginName, donobuVersion);
+  } else {
+    await createToolTemplateFiles(pluginDir, pluginName, donobuVersion);
+  }
+
   console.log(`\nPlugin "${pluginName}" created successfully!`);
   console.log(`\nNext steps:`);
   console.log(`  cd ${pluginName}`);
   console.log(`  npm install`);
-  console.log(`  # Edit src/index.ts to add your custom tools`);
+  if (pluginType === 'persistence') {
+    console.log(`  # Edit src/index.ts to implement your persistence plugin`);
+  } else {
+    console.log(`  # Edit src/index.ts to add your custom tools`);
+  }
   console.log(`  npx install-donobu-plugin`);
 }
 
-async function createTemplateFiles(pluginDir, pluginName, versions) {
+// ---------------------------------------------------------------------------
+// Shared template helpers
+// ---------------------------------------------------------------------------
+
+function createTsConfig() {
+  return {
+    compilerOptions: {
+      target: 'ES2021',
+      lib: ['ES2021', 'DOM'],
+      module: 'NodeNext',
+      moduleResolution: 'NodeNext',
+      rootDir: './src',
+      outDir: './dist',
+      declaration: true,
+      declarationMap: true,
+      sourceMap: true,
+      esModuleInterop: true,
+      forceConsistentCasingInFileNames: true,
+      strict: true,
+      skipLibCheck: true,
+      allowUnusedLabels: false,
+      allowUnreachableCode: false,
+    },
+    include: ['src'],
+    exclude: ['node_modules', 'dist'],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tool plugin templates
+// ---------------------------------------------------------------------------
+
+async function createToolTemplateFiles(pluginDir, pluginName, donobuVersion) {
   // Create package.json
   const packageJson = {
     name: pluginName,
+    'donobu-plugin': true,
     version: '1.0.0',
     private: true,
-    type: 'module',
     description: 'Custom tools for use by Donobu.',
-    main: './dist/index.mjs',
-    types: './dist/index.d.ts',
+    main: 'dist/index.js',
+    types: 'dist/index.d.ts',
     exports: {
-      '.': './dist/index.mjs',
+      types: './dist/index.d.ts',
+      import: './dist/index.mjs',
+      require: './dist/index.js',
     },
     files: ['dist'],
     scripts: {
       clean: 'rm -rf dist',
-      build:
-        'npm run clean && npm install && tsc -p tsconfig.json && node esbuild.config.mjs',
+      build: 'npm run clean && tsc && node esbuild.config.mjs',
     },
     license: 'UNLICENSED',
-    devDependencies: {
-      donobu: `^${versions.donobuVersion}`,
-      playwright: versions.playwrightVersion,
-      '@playwright/test': versions.playwrightTestVersion,
-      typescript: '^5.8.3',
-      esbuild: '^0.25.6',
-    },
     peerDependencies: {
-      donobu: `>=${versions.donobuVersion}`,
-      playwright: `>=${versions.playwrightVersion}`,
-      '@playwright/test': `>=${versions.playwrightTestVersion}`,
+      donobu: `>=${donobuVersion}`,
     },
-    peerDependenciesMeta: {
-      playwright: {
-        optional: false,
-      },
-      '@playwright/test': {
-        optional: false,
-      },
+    devDependencies: {
+      '@types/node': '^22.19.13',
+      donobu: `^${donobuVersion}`,
+      esbuild: '^0.25.12',
+      typescript: '^5.8.3',
     },
-    dependencies: {
-      zod: '^3.25.76',
+    pnpm: {
+      onlyBuiltDependencies: ['better-sqlite3', 'esbuild'],
     },
   };
 
   await writeFile(
     join(pluginDir, 'package.json'),
-    JSON.stringify(packageJson, null, 2)
+    JSON.stringify(packageJson, null, 2),
   );
 
-  // Create tsconfig.json
-  const tsConfig = {
-    compilerOptions: {
-      target: 'ES2020',
-      module: 'NodeNext',
-      moduleResolution: 'NodeNext',
-      rootDir: './src',
-      outDir: './dist',
-      declaration: true,
-      strict: true,
-      esModuleInterop: true,
-      skipLibCheck: true,
-      forceConsistentCasingInFileNames: true,
-    },
-    include: ['src/**/*'],
-  };
-
   await writeFile(
     join(pluginDir, 'tsconfig.json'),
-    JSON.stringify(tsConfig, null, 2)
+    JSON.stringify(createTsConfig(), null, 2),
   );
 
   // Create esbuild.config.mjs
   const esbuildConfig = `import { build } from 'esbuild';
 
 await build({
-  entryPoints: ['dist/index.js'],
+  entryPoints: ['src/index.ts'],
   outfile: 'dist/index.mjs',
   bundle: true,
   format: 'esm',
   platform: 'node',
-  external: ['donobu', 'playwright'],
+
+  // 'donobu' is provided at runtime by the plugin loader via deps.donobu.
+  external: ['donobu'],
+
+  mainFields: ['module', 'main'],
+
   minify: true,
 });
 `;
@@ -154,150 +133,273 @@ 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";
+  // Create a basic README
+  const readme = `# ${pluginName}
 
-/**
- * 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);
-    }
-  }
+A custom Donobu tool plugin for browser automation.
 
-  return new AnonymousTool();
-}
+## Development
 
-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;
-}
+1. Edit \`src/index.ts\` to add your custom tools
+2. Build and install the plugin:
+   \`\`\`bash
+   npm run build
+   npm exec install-donobu-plugin
+   \`\`\`
+3. Restart Donobu to load your plugin
 `;
 
-  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, 'README.md'), readme);
 }
-`;
+
+// ---------------------------------------------------------------------------
+// Persistence plugin templates
+// ---------------------------------------------------------------------------
+
+async function createPersistenceTemplateFiles(
+  pluginDir,
+  pluginName,
+  donobuVersion,
+) {
+  // Create package.json — no playwright dependency needed
+  const packageJson = {
+    name: pluginName,
+    'donobu-plugin': true,
+    version: '1.0.0',
+    private: true,
+    description: 'Custom persistence plugin for Donobu.',
+    main: 'dist/index.js',
+    types: 'dist/index.d.ts',
+    exports: {
+      types: './dist/index.d.ts',
+      import: './dist/index.mjs',
+      require: './dist/index.js',
+    },
+    files: ['dist'],
+    scripts: {
+      clean: 'rm -rf dist',
+      build: 'npm run clean && tsc && node esbuild.config.mjs',
+    },
+    license: 'UNLICENSED',
+    peerDependencies: {
+      donobu: `>=${donobuVersion}`,
+    },
+    devDependencies: {
+      '@types/node': '^22.19.13',
+      donobu: `^${donobuVersion}`,
+      esbuild: '^0.25.12',
+      typescript: '^5.8.3',
+    },
+    pnpm: {
+      onlyBuiltDependencies: ['better-sqlite3', 'esbuild'],
+    },
+  };
 
   await writeFile(
-    join(pluginDir, 'src', 'PluginDependencies.ts'),
-    pluginDepsTs
+    join(pluginDir, 'package.json'),
+    JSON.stringify(packageJson, null, 2),
+  );
+
+  await writeFile(
+    join(pluginDir, 'tsconfig.json'),
+    JSON.stringify(createTsConfig(), null, 2),
   );
 
+  // Create esbuild.config.mjs — only externalize donobu
+  const esbuildConfig = `import { build } from 'esbuild';
+
+await build({
+  entryPoints: ['src/index.ts'],
+  outfile: 'dist/index.mjs',
+  bundle: true,
+  format: 'esm',
+  platform: 'node',
+
+  // 'donobu' is provided at runtime by the plugin loader via deps.donobu.
+  external: ['donobu'],
+
+  mainFields: ['module', 'main'],
+
+  minify: true,
+});
+`;
+
+  await writeFile(join(pluginDir, 'esbuild.config.mjs'), esbuildConfig);
+
+  // Create src/index.ts
+  const indexTs = `import type {
+  EnvPersistence,
+  FlowsPersistence,
+  PersistencePlugin,
+  PluginDependencies,
+} from 'donobu';
+
+/**
+ * Called by Donobu on startup when this plugin is installed.
+ *
+ * Return an object with a \`key\` (matching an entry in the
+ * PERSISTENCE_PRIORITY environment variable) and a \`plugin\`
+ * implementing the PersistencePlugin interface.
+ *
+ * Return \`null\` to skip registration (e.g., if required
+ * environment variables are missing).
+ */
+export async function loadPersistencePlugin(
+  deps: PluginDependencies,
+): Promise<{ key: string; plugin: PersistencePlugin } | null> {
+  // Example: skip registration if required config is not set.
+  // const bucket = process.env.MY_STORAGE_BUCKET;
+  // if (!bucket) return null;
+
+  return {
+    // This key must appear in the PERSISTENCE_PRIORITY env variable
+    // for Donobu to use this plugin. For example:
+    //   PERSISTENCE_PRIORITY=MY_CUSTOM,LOCAL,RAM
+    key: 'MY_CUSTOM',
+    plugin: {
+      async createFlowsPersistence(): Promise<FlowsPersistence | null> {
+        // Return your FlowsPersistence implementation here.
+        // Return null if the required configuration is missing.
+        return null;
+      },
+      async createEnvPersistence(): Promise<EnvPersistence | null> {
+        // Return your EnvPersistence implementation here.
+        // Return null if the required configuration is missing.
+        return null;
+      },
+    },
+  };
+}`;
+
+  await writeFile(join(pluginDir, 'src', 'index.ts'), indexTs);
+
   // Create a basic README
   const readme = `# ${pluginName}
 
-A custom Donobu plugin with tools for browser automation.
+A custom Donobu persistence plugin.
 
 ## Development
 
-1. Edit \`src/index.ts\` to add your custom tools
+1. Edit \`src/index.ts\` to implement your persistence plugin
 2. Build and install the plugin:
    \`\`\`bash
    npm run build
    npm exec install-donobu-plugin
    \`\`\`
-3. Restart Donobu to see your tools
+3. Set the \`PERSISTENCE_PRIORITY\` environment variable to include your plugin key
+4. Restart Donobu to load your plugin
 `;
 
   await writeFile(join(pluginDir, 'README.md'), readme);
 }
 
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let pluginName = null;
+  let pluginType = 'tool';
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--type' && i + 1 < args.length) {
+      pluginType = args[i + 1];
+      i++; // skip value
+    } else if (!args[i].startsWith('-')) {
+      pluginName = args[i];
+    }
+  }
+
+  return { pluginName, pluginType };
+}
+
 async function main() {
-  const pluginName = process.argv[2];
+  const { pluginName, pluginType } = parseArgs(process.argv);
 
   if (!pluginName) {
-    console.error('Usage: create-donobu-plugin <plugin-name>');
+    console.error(
+      'Usage: create-donobu-plugin <plugin-name> [--type <tool|persistence>]',
+    );
     console.error('');
-    console.error('Example:');
+    console.error('Options:');
+    console.error(
+      '  --type <type>  Plugin type: "tool" (default) or "persistence"',
+    );
+    console.error('');
+    console.error('Examples:');
     console.error('  npm create donobu-plugin my-awesome-plugin');
+    console.error('  npm create donobu-plugin my-storage --type persistence');
     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);
+  }
+
+  // Validate plugin type
+  if (!VALID_PLUGIN_TYPES.includes(pluginType)) {
+    console.error(
+      `Invalid plugin type "${pluginType}". Must be one of: ${VALID_PLUGIN_TYPES.join(', ')}`,
     );
     process.exit(1);
   }
 
   try {
-    await createPluginStructure(pluginName);
+    await createPluginStructure(pluginName, pluginType);
   } catch (error) {
     console.error('Failed to create plugin:', error.message);
     process.exit(1);

package/package.json

@@ -1,24 +1,33 @@
 {
-    "name": "create-donobu-plugin",
-    "version": "1.2.1",
-    "type": "module",
-    "description": "Create a new Donobu plugin",
-    "author": "Donobu",
-    "homepage": "https://donobu.com",
-    "main": "index.js",
-    "bin": {
-        "create-donobu-plugin": "./index.js"
-    },
-    "files": [
-        "index.js"
-    ],
-    "dependencies": {
-        "donobu": "^3.3.0"
-    },
-    "keywords": [
-        "donobu",
-        "plugin",
-        "create"
-    ],
-    "license": "UNLICENSED"
+  "name": "create-donobu-plugin",
+  "version": "1.7.0",
+  "type": "module",
+  "description": "Create a new Donobu plugin",
+  "author": "Donobu",
+  "homepage": "https://donobu.com",
+  "main": "index.js",
+  "bin": {
+    "create-donobu-plugin": "./index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.2",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "globals": "^16.0.0",
+    "prettier": "^3.8.0"
+  },
+  "keywords": [
+    "donobu",
+    "plugin",
+    "create"
+  ],
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "pnpm install --frozen-lockfile && pnpm run lint --fix && pnpm run format && pnpm run lint",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  }
 }