manychat-ai-agent 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.21.0](https://github.com/pedronastasi/manychat-ai-agent/compare/v0.20.0...v0.21.0) (2026-10-07)
+
+
+### Features
+
+* start a plugin from the agent's own example with agent plugin new (spec 041) ([6aae801](https://github.com/pedronastasi/manychat-ai-agent/commit/6aae8019080718c497f7d031b5cd3d8efe349809))
+
+
+### Bug Fixes
+
+* write the plugin templates in words no vertical owns (spec 041, 042) ([697b961](https://github.com/pedronastasi/manychat-ai-agent/commit/697b9618171e3e8fb6be23818e4833c73db1449e))
+
+
+### Specs and Docs
+
+* name agent plugin new as 033 V4's one exception (spec 041) ([516294a](https://github.com/pedronastasi/manychat-ai-agent/commit/516294a5acc98b0690a315d52d36f7da2445b56d))
+
 ## [0.20.0](https://github.com/pedronastasi/manychat-ai-agent/compare/v0.19.1...v0.20.0) (2026-10-07)
 
 

package/dist/cli/run.js

@@ -11,7 +11,9 @@ export const COMMANDS = {
     'insights review': 'Approve, edit, reject or retire playbook insights',
     'insights activate': 'Put a playbook version live once its eval passes',
     'insights report': 'Enrolment rate by playbook version',
+    'plugin new': 'Start a plugin from the agent’s example (--read or --write)',
 };
+const PLUGIN_NEW_USAGE = 'Usage: agent plugin new <name> --read|--write';
 function usage() {
     const lines = ['Usage: agent <command>', ''];
     for (const [cmd, desc] of Object.entries(COMMANDS)) {
@@ -70,8 +72,10 @@ export async function run(argv) {
     const rest = args.slice(cmd.split(' ').length);
     const configDir = process.env.CONFIG_DIR ?? 'config';
     // `upgrade` exists to rewrite a config the installed version cannot parse
-    // yet, so it checks after migrating rather than before.
-    if (cmd !== 'upgrade' && !configIsValid(configDir))
+    // yet, so it checks after migrating rather than before. `plugin new` reads
+    // no config but `plugins.json`, and ends by printing the full check
+    // (specs/041).
+    if (cmd !== 'upgrade' && cmd !== 'plugin new' && !configIsValid(configDir))
         return 1;
     switch (cmd) {
         case 'serve': {
@@ -132,6 +136,8 @@ export async function run(argv) {
             const { runInsights } = await import("../learning/commands.js");
             return runInsights([cmd.split(' ')[1], ...rest]);
         }
+        case 'plugin new':
+            return pluginNew(rest);
         case 'tokens backfill': {
             process.argv = ['node', 'backfill', ...rest];
             await import("../backfill.js");
@@ -140,6 +146,42 @@ export async function run(argv) {
     }
     return usage();
 }
+/** `agent plugin new <name> --read|--write`, run from the project's root (specs/041). */
+async function pluginNew(args) {
+    const flags = args.filter(arg => arg.startsWith('-'));
+    const positional = args.filter(arg => !arg.startsWith('-'));
+    const kinds = flags.filter(flag => flag === '--read' || flag === '--write');
+    // Which kind of tool a plugin adds is the author's decision, never a default.
+    if (kinds.length !== 1 || flags.length !== 1 || positional.length !== 1) {
+        console.error(PLUGIN_NEW_USAGE);
+        return 2;
+    }
+    const { scaffoldPlugin, ScaffoldError } = await import("../plugins/scaffold.js");
+    let made;
+    try {
+        made = await scaffoldPlugin({
+            root: process.cwd(),
+            name: positional[0],
+            kind: kinds[0] === '--read' ? 'read' : 'write',
+        });
+    }
+    catch (error) {
+        if (error instanceof ScaffoldError) {
+            console.error(`plugin new: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    console.log([
+        `created ${made.directory}: plugin ${made.pluginName}, ${made.kind} tool ${made.toolName}`,
+        'added it to pnpm-workspace.yaml, package.json and config/plugins.json',
+        '',
+        'Next, install it and run the check the server runs at startup:',
+        '  pnpm install',
+        '  pnpm agent config check',
+    ].join('\n'));
+    return 0;
+}
 /** The outbox and nudge workers without the HTTP server (specs/033). */
 async function startWorkers(configDir) {
     const dbMod = await import("../db/client.js");

package/dist/plugins/loader.d.ts

@@ -1,11 +1,30 @@
 import { ConfigError } from '../config/loader.ts';
+import type { PluginReadTool, PluginTool } from './api.ts';
 import { Plugins } from './plugins.ts';
 /** The optional tenant file that lists the plugin packages to load (specs/036). */
 export declare const PLUGINS_FILE = "plugins.json";
+/** Names the model already knows: the six of specs/012 and the read of specs/024. */
+export declare const BUILT_IN_TOOLS: ReadonlySet<string>;
+/** A tool name the loader accepts: lowercase snake case, at most 64 characters. */
+export declare const TOOL_NAME: RegExp;
 /** A plugin that cannot be loaded. A `ConfigError`, so every command reports it as one. */
 export declare class PluginError extends ConfigError {
     constructor(message: string);
 }
+/** The directory of `name` in the first `node_modules` above `from`, as Node finds a package. */
+export declare function packageDir(name: string, from: string): string | undefined;
+/** The file a bare import of the package in `dir` loads. */
+export declare function entryOf(dir: string): string;
+type CheckedTool = PluginTool | PluginReadTool;
+/**
+ * Checks a plugin's default export. Everything that would leave the prompt
+ * promising an action nothing performs fails here, at startup (C6).
+ * `agent plugin new` runs it on what it generates (specs/041).
+ */
+export declare function checkPlugin(spec: string, value: unknown, taken: Map<string, string>): {
+    name: string;
+    tools: CheckedTool[];
+};
 /** The packages `plugins.json` lists, or none when the file is absent. */
 export declare function listedPlugins(configDir: string): string[];
 /**
@@ -18,3 +37,4 @@ export declare function listedPlugins(configDir: string): string[];
 export declare function loadPlugins(configDir: string, options?: {
     from?: string;
 }): Promise<Plugins>;
+export {};

package/dist/plugins/loader.js

@@ -19,8 +19,12 @@ import { Plugins } from "./plugins.js";
 export const PLUGINS_FILE = 'plugins.json';
 const PluginsFile = z.object({ plugins: z.array(z.string().min(1)) }).strict();
 /** Names the model already knows: the six of specs/012 and the read of specs/024. */
-const BUILT_IN = new Set([...ToolName.options, 'get_contact']);
-const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+export const BUILT_IN_TOOLS = new Set([
+    ...ToolName.options,
+    'get_contact',
+]);
+/** A tool name the loader accepts: lowercase snake case, at most 64 characters. */
+export const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
 const PLUGIN_KEYS = new Set(['name', 'apiVersion', 'tools']);
 const TOOL_KEYS = new Set(['name', 'description', 'parameters', 'perform', 'read', 'result']);
 const ENUM_KEYS = new Set(['type', 'values', 'description', 'optional']);
@@ -59,7 +63,7 @@ function unknownKeys(value, allowed) {
     return Object.keys(value).filter(key => !allowed.has(key));
 }
 /** The directory of `name` in the first `node_modules` above `from`, as Node finds a package. */
-function packageDir(name, from) {
+export function packageDir(name, from) {
     let dir = resolve(from);
     for (;;) {
         const candidate = join(dir, 'node_modules', name);
@@ -94,7 +98,8 @@ function exported(target) {
     }
     return undefined;
 }
-function entryOf(dir) {
+/** The file a bare import of the package in `dir` loads. */
+export function entryOf(dir) {
     const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
     const pkg = isObject(manifest) ? manifest : {};
     const target = exported(pkg.exports) ?? (typeof pkg.main === 'string' ? pkg.main : undefined) ?? 'index.js';
@@ -212,8 +217,9 @@ function checkTool(plugin, apiVersion, value, taken) {
         throw new PluginError(`plugin ${plugin}: tool name ${JSON.stringify(name)} must be lowercase snake case`);
     }
     const where = `plugin ${plugin}, tool ${name}`;
-    if (BUILT_IN.has(name))
+    if (BUILT_IN_TOOLS.has(name)) {
         throw new PluginError(`${where}: takes the name of a built-in tool`);
+    }
     const owner = taken.get(name);
     if (owner !== undefined)
         throw new PluginError(`${where}: plugin ${owner} already defines it`);
@@ -267,8 +273,9 @@ function checkTool(plugin, apiVersion, value, taken) {
 /**
  * Checks a plugin's default export. Everything that would leave the prompt
  * promising an action nothing performs fails here, at startup (C6).
+ * `agent plugin new` runs it on what it generates (specs/041).
  */
-function checkPlugin(spec, value, taken) {
+export function checkPlugin(spec, value, taken) {
     if (!isObject(value)) {
         throw new PluginError(`plugin ${spec}: its default export is not a plugin (use definePlugin)`);
     }

package/dist/plugins/scaffold.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `agent plugin new`: a plugin package started from the agent's own invented
+ * example, and the three edits that make the project load it (specs/041).
+ */
+export type PluginKind = 'read' | 'write';
+/** The prefix every scaffolded package name carries. */
+export declare const PLUGIN_PREFIX = "agent-plugin-";
+/**
+ * The templates, read from the installed agent and never from the project.
+ * The path holds from `src/plugins/` and from `dist/plugins/` alike, and
+ * `package.json` ships the directory (specs/041 § Verification 5).
+ */
+export declare const TEMPLATES_DIR: string;
+export declare const TEMPLATE_FILES: Record<PluginKind, string>;
+/** A refusal: the project is left as it was found, and the command exits 1. */
+export declare class ScaffoldError extends Error {
+    constructor(message: string);
+}
+export interface PluginNames {
+    /** The package name: `agent-plugin-<name>`. */
+    packageName: string;
+    /** The plugin's `name`: the part after the prefix. */
+    pluginName: string;
+    /** Its one tool's name: that part in snake case. */
+    toolName: string;
+}
+/** The names `<name>` derives, or a refusal naming why it cannot be one. */
+export declare function pluginNames(name: string): PluginNames;
+/**
+ * The project's `pnpm-workspace.yaml` with `plugins/*` among its packages, or
+ * undefined when it lists them already. Edited as text, so its comments and
+ * every other setting survive.
+ */
+export declare function withWorkspaceGlob(text: string | undefined): string | undefined;
+/** The template for `kind`, filled with the plugin's names and the installed agent's API version. */
+export declare function renderTemplate(kind: PluginKind, names: PluginNames): string;
+export interface ScaffoldResult extends PluginNames {
+    kind: PluginKind;
+    /** The plugin's directory, relative to the project. */
+    directory: string;
+}
+/**
+ * Writes `plugins/<name>/` and makes the three edits that load it, or refuses
+ * and leaves the project as it found it. Installs nothing. `write` is the
+ * file write, replaceable so a test can fail one part-way.
+ */
+export declare function scaffoldPlugin(options: {
+    root: string;
+    name: string;
+    kind: PluginKind;
+    write?: (path: string, content: string) => void;
+}): Promise<ScaffoldResult>;

package/dist/plugins/scaffold.js

@@ -0,0 +1,302 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { PLUGIN_API_VERSION, SUPPORTED_PLUGIN_API_VERSIONS } from "./api.js";
+import { BUILT_IN_TOOLS, PLUGINS_FILE, TOOL_NAME, checkPlugin, entryOf, listedPlugins, packageDir, } from "./loader.js";
+import { ConfigError } from "../config/loader.js";
+/** The prefix every scaffolded package name carries. */
+export const PLUGIN_PREFIX = 'agent-plugin-';
+/**
+ * The templates, read from the installed agent and never from the project.
+ * The path holds from `src/plugins/` and from `dist/plugins/` alike, and
+ * `package.json` ships the directory (specs/041 § Verification 5).
+ */
+export const TEMPLATES_DIR = fileURLToPath(new URL('../../src/plugins/templates/', import.meta.url));
+export const TEMPLATE_FILES = {
+    read: 'read.js.tmpl',
+    write: 'write.js.tmpl',
+};
+/** The globs `pnpm-workspace.yaml` must list for `plugins/<name>` to be a workspace package. */
+const WORKSPACE_FILE = 'pnpm-workspace.yaml';
+const WORKSPACE_GLOB = 'plugins/*';
+/** An npm package name in lowercase kebab case, unscoped. */
+const PACKAGE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_PACKAGE_NAME = 214;
+/** A refusal: the project is left as it was found, and the command exits 1. */
+export class ScaffoldError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScaffoldError';
+    }
+}
+/** The names `<name>` derives, or a refusal naming why it cannot be one. */
+export function pluginNames(name) {
+    const packageName = name.startsWith(PLUGIN_PREFIX) ? name : `${PLUGIN_PREFIX}${name}`;
+    const pluginName = packageName.slice(PLUGIN_PREFIX.length);
+    if (!PACKAGE_NAME.test(packageName) ||
+        pluginName.length === 0 ||
+        packageName.length > MAX_PACKAGE_NAME) {
+        throw new ScaffoldError(`${JSON.stringify(name)} is not a package name in lowercase kebab case, such as slot-finder`);
+    }
+    const toolName = pluginName.replaceAll('-', '_');
+    if (!TOOL_NAME.test(toolName)) {
+        throw new ScaffoldError(`${packageName} would declare the tool ${toolName}, which the loader refuses: ` +
+            'a tool name starts with a letter and is at most 64 characters');
+    }
+    return { packageName, pluginName, toolName };
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A file's text, or undefined when it does not exist. */
+function textOf(path) {
+    return existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+}
+/** The project's `package.json`, refused unless it depends on the agent. */
+function projectManifest(root) {
+    const notProject = (why) => new ScaffoldError(`${root} is not a tenant project: ${why}. Run this from the project's root`);
+    const text = textOf(join(root, 'package.json'));
+    if (text === undefined)
+        throw notProject('it has no package.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(text);
+    }
+    catch {
+        throw notProject('its package.json is not JSON');
+    }
+    if (!isObject(manifest))
+        throw notProject('its package.json is not an object');
+    const depends = [manifest.dependencies, manifest.devDependencies].some(deps => isObject(deps) && 'manychat-ai-agent' in deps);
+    if (!depends)
+        throw notProject('its package.json does not depend on manychat-ai-agent');
+    const config = join(root, 'config');
+    if (!existsSync(config) || !statSync(config).isDirectory())
+        throw notProject('it has no config/');
+    return { manifest, text };
+}
+/**
+ * The project's `pnpm-workspace.yaml` with `plugins/*` among its packages, or
+ * undefined when it lists them already. Edited as text, so its comments and
+ * every other setting survive.
+ */
+export function withWorkspaceGlob(text) {
+    if (text === undefined)
+        return `packages:\n  - ${WORKSPACE_GLOB}\n`;
+    const lines = text.split('\n');
+    const item = /^\s*-\s*(['"]?)plugins\/\*\1\s*(?:#.*)?$/;
+    if (lines.some(line => item.test(line)))
+        return undefined;
+    const header = lines.findIndex(line => /^packages:\s*(?:#.*)?$/.test(line));
+    if (header === -1) {
+        if (lines.some(line => line.startsWith('packages:'))) {
+            throw new ScaffoldError(`${WORKSPACE_FILE}: packages is not a block list, so ${WORKSPACE_GLOB} cannot be added to it; ` +
+                'write it as one, an entry per line');
+        }
+        const base = text.length === 0 || text.endsWith('\n') ? text : `${text}\n`;
+        return `${base}packages:\n  - ${WORKSPACE_GLOB}\n`;
+    }
+    const next = lines.slice(header + 1).find(line => line.trim() !== '' && !/^\s*#/.test(line));
+    const indent = next?.match(/^(\s*)-\s/)?.[1] ?? '  ';
+    lines.splice(header + 1, 0, `${indent}- ${WORKSPACE_GLOB}`);
+    return lines.join('\n');
+}
+/** The project's `package.json` with the plugin as a workspace dependency, in its own indent. */
+function withDependency(manifest, text, name) {
+    const indent = text.match(/^\{\r?\n([ \t]+)"/)?.[1] ?? '  ';
+    const deps = isObject(manifest.dependencies) ? manifest.dependencies : {};
+    const sorted = Object.fromEntries(Object.entries({ ...deps, [name]: 'workspace:*' }).sort(([left], [right]) => left.localeCompare(right)));
+    return `${JSON.stringify({ ...manifest, dependencies: sorted }, null, indent)}\n`;
+}
+/** Where a listed package's source is: its installed copy, or its workspace directory. */
+function sourceOf(root, name) {
+    const installed = packageDir(name, root);
+    if (installed)
+        return installed;
+    const plugins = join(root, 'plugins');
+    if (!existsSync(plugins))
+        return undefined;
+    for (const dir of readdirSync(plugins)) {
+        const manifest = join(plugins, dir, 'package.json');
+        if (!existsSync(manifest))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(manifest, 'utf8'));
+            if (isObject(parsed) && parsed.name === name)
+                return join(plugins, dir);
+        }
+        catch {
+            // Not this package; `config check` reports a broken one.
+        }
+    }
+    return undefined;
+}
+/**
+ * The tool and plugin names the listed plugins already declare. One that does
+ * not load is skipped: it is not this command's to refuse, and `config check`
+ * reports it.
+ */
+async function declaredNames(root, listed) {
+    const tools = new Map();
+    const plugins = new Set();
+    for (const name of listed) {
+        const dir = sourceOf(root, name);
+        if (!dir)
+            continue;
+        let plugin;
+        try {
+            plugin = (await import(__rewriteRelativeImportExtension(pathToFileURL(entryOf(dir)).href))).default;
+        }
+        catch {
+            continue;
+        }
+        if (!isObject(plugin))
+            continue;
+        if (typeof plugin.name === 'string')
+            plugins.add(plugin.name);
+        if (!Array.isArray(plugin.tools))
+            continue;
+        for (const tool of plugin.tools) {
+            if (isObject(tool) && typeof tool.name === 'string')
+                tools.set(tool.name, name);
+        }
+    }
+    return { tools, plugins };
+}
+/** The template for `kind`, filled with the plugin's names and the installed agent's API version. */
+export function renderTemplate(kind, names) {
+    // A read tool needs the newest API; a write tool loads under every
+    // supported one, so under an agent one release older too.
+    const apiVersion = kind === 'read' ? PLUGIN_API_VERSION : Math.min(...SUPPORTED_PLUGIN_API_VERSIONS);
+    const source = readFileSync(join(TEMPLATES_DIR, TEMPLATE_FILES[kind]), 'utf8')
+        .replaceAll('__PLUGIN_NAME__', names.pluginName)
+        .replaceAll('__TOOL_NAME__', names.toolName)
+        .replaceAll('__API_VERSION__', String(apiVersion));
+    const left = source.match(/__[A-Z_]+__/);
+    if (left)
+        throw new ScaffoldError(`the ${kind} template leaves ${left[0]} unfilled`);
+    return source;
+}
+function packageManifest(packageName) {
+    const manifest = {
+        name: packageName,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        exports: './index.js',
+        peerDependencies: { 'manychat-ai-agent': '*' },
+    };
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+/**
+ * The project's files as they were, so a failure part-way puts them back
+ * (specs/041 § It makes all four edits, or none).
+ */
+class Edits {
+    changed = [];
+    created;
+    write;
+    constructor(write) {
+        this.write = write;
+    }
+    mkdir(dir) {
+        this.created = mkdirSync(dir, { recursive: true });
+    }
+    file(path, content) {
+        // Recorded before the write, so a write that fails half-way is undone too.
+        this.changed.push({ path, before: textOf(path) });
+        this.write(path, content);
+    }
+    undo() {
+        for (const { path, before } of this.changed.reverse()) {
+            if (before === undefined)
+                rmSync(path, { force: true });
+            else
+                writeFileSync(path, before);
+        }
+        if (this.created)
+            rmSync(this.created, { recursive: true, force: true });
+    }
+}
+/**
+ * Writes `plugins/<name>/` and makes the three edits that load it, or refuses
+ * and leaves the project as it found it. Installs nothing. `write` is the
+ * file write, replaceable so a test can fail one part-way.
+ */
+export async function scaffoldPlugin(options) {
+    const { root, kind } = options;
+    const names = pluginNames(options.name);
+    const { packageName, pluginName, toolName } = names;
+    const { manifest, text: manifestText } = projectManifest(root);
+    const directory = join('plugins', packageName);
+    if (existsSync(join(root, directory)))
+        throw new ScaffoldError(`${directory} already exists`);
+    const configDir = join(root, 'config');
+    let listed;
+    try {
+        listed = listedPlugins(configDir);
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            throw new ScaffoldError(`config/${error.message}`);
+        throw error;
+    }
+    if (listed.includes(packageName)) {
+        throw new ScaffoldError(`config/${PLUGINS_FILE} already lists ${packageName}`);
+    }
+    const declared = await declaredNames(root, listed);
+    if (BUILT_IN_TOOLS.has(toolName)) {
+        throw new ScaffoldError(`${toolName} is a built-in tool's name; choose another <name>`);
+    }
+    const owner = declared.tools.get(toolName);
+    if (owner !== undefined) {
+        throw new ScaffoldError(`${owner} already declares the tool ${toolName}; choose another <name>`);
+    }
+    if (declared.plugins.has(pluginName)) {
+        throw new ScaffoldError(`a listed plugin is already named ${pluginName}; choose another <name>`);
+    }
+    // Everything is worked out before the first write, so a refusal writes nothing.
+    const source = renderTemplate(kind, names);
+    const workspacePath = join(root, WORKSPACE_FILE);
+    const workspace = withWorkspaceGlob(textOf(workspacePath));
+    const dependency = withDependency(manifest, manifestText, packageName);
+    const pluginsFile = `${JSON.stringify({ plugins: [...listed, packageName] }, null, 2)}\n`;
+    const edits = new Edits(options.write ?? ((path, content) => writeFileSync(path, content)));
+    const pluginDir = join(root, directory);
+    try {
+        edits.mkdir(pluginDir);
+        edits.file(join(pluginDir, 'package.json'), packageManifest(packageName));
+        edits.file(join(pluginDir, 'index.js'), source);
+        if (workspace !== undefined)
+            edits.file(workspacePath, workspace);
+        edits.file(join(root, 'package.json'), dependency);
+        edits.file(join(configDir, PLUGINS_FILE), pluginsFile);
+        await checkGenerated(packageName, join(pluginDir, 'index.js'), declared.tools);
+    }
+    catch (error) {
+        edits.undo();
+        throw error;
+    }
+    return { ...names, kind, directory };
+}
+/**
+ * Runs the loader's startup checks on the generated plugin, from its path:
+ * it is not in `node_modules` until `pnpm install` (specs/041 § It ends with
+ * the check the server will run). A failure is the agent's own bug.
+ */
+async function checkGenerated(packageName, entry, taken) {
+    try {
+        const module = (await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href)));
+        checkPlugin(packageName, module.default, new Map(taken));
+    }
+    catch (error) {
+        throw new ScaffoldError(`the generated plugin does not pass the agent's own checks, which is a bug in the agent: ` +
+            error.message);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "manychat-ai-agent",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "A provider-agnostic conversational AI agent gateway that bridges no-code chat platforms to any LLM.",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,7 @@
   "files": [
     "dist/",
     "db/migrations/",
+    "src/plugins/templates/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/src/plugins/templates/read.js.tmpl

@@ -0,0 +1,57 @@
+// A read tool, generated by `agent plugin new` from the agent's own example
+// (specs/041). Every name, value and address below is invented: replace them
+// with your own. The model calls the tool while it writes the reply, and is
+// shown only the result it declares, checked by the agent (specs/039).
+import { definePlugin, defineReadTool } from 'manychat-ai-agent';
+
+// Your backend goes here. This address does not exist, so until it is
+// replaced every call fails, and the model is told the answer is unavailable.
+const BACKEND_URL = 'https://backend.example.com';
+
+export default definePlugin({
+  name: '__PLUGIN_NAME__',
+  apiVersion: __API_VERSION__,
+  tools: [
+    defineReadTool({
+      name: '__TOOL_NAME__',
+      // The only guidance the model gets: say when to call the tool, not what
+      // it does inside.
+      description:
+        'Look up whether an offering has room and when its next slot is, when the contact asks whether they can have it or when.',
+      // One parameter of each type a read tool may take. Keep the ones your
+      // backend needs, and change their names and values to yours. The query
+      // is the one free text, and the agent removes identifiers from it.
+      parameters: {
+        offering: { type: 'enum', values: ['basic', 'premium'] },
+        quantity: { type: 'number', integer: true, min: 1, max: 12, optional: true },
+        flexible: { type: 'boolean', optional: true },
+        query: { type: 'query', maxLength: 120, optional: true },
+      },
+      // What the model is shown. A value outside these declarations makes the
+      // whole read unavailable, so declare exactly what you return.
+      result: {
+        slotsLeft: { type: 'number', integer: true, min: 0 },
+        nextSlot: { type: 'enum', values: ['this_week', 'next_week', 'later'] },
+        waitlist: { type: 'boolean' },
+        summary: { type: 'text', maxLength: 300, optional: true },
+      },
+      // Throw, or take too long, and the model is told the answer is
+      // unavailable. Pass `signal` to anything that waits.
+      async read({ params, signal }) {
+        // Your code goes here: the request your backend expects.
+        const url = new URL('/availability', BACKEND_URL);
+        for (const [key, value] of Object.entries(params)) url.searchParams.set(key, String(value));
+        const response = await fetch(url, { signal });
+        if (!response.ok) throw new Error(`backend answered ${response.status}`);
+        const found = await response.json();
+        // Return only what `result` declares.
+        return {
+          slotsLeft: found.slotsLeft,
+          nextSlot: found.nextSlot,
+          waitlist: found.waitlist,
+          ...(found.summary ? { summary: found.summary } : {}),
+        };
+      },
+    }),
+  ],
+});

package/src/plugins/templates/write.js.tmpl

@@ -0,0 +1,44 @@
+// A write tool, generated by `agent plugin new` from the agent's own example
+// (specs/041). Every name, value and address below is invented: replace them
+// with your own. The model calls the tool while it writes the reply, and
+// `perform` runs once the reply has been sent (specs/036).
+import { definePlugin, defineTool } from 'manychat-ai-agent';
+
+// Your backend goes here. This address does not exist, so until it is
+// replaced every call fails, and the agent logs the failure and moves on.
+const BACKEND_URL = 'https://backend.example.com';
+
+export default definePlugin({
+  name: '__PLUGIN_NAME__',
+  apiVersion: __API_VERSION__,
+  tools: [
+    defineTool({
+      name: '__TOOL_NAME__',
+      // The only guidance the model gets: say when to call the tool, not what
+      // it does inside.
+      description:
+        'Record a follow-up request once the contact has named an offering and asked to be contacted.',
+      // One parameter of each type a write tool may take. Keep the ones your
+      // backend needs, and change their names and values to yours.
+      parameters: {
+        offering: { type: 'enum', values: ['basic', 'premium'] },
+        quantity: { type: 'number', integer: true, min: 1, max: 4, optional: true },
+        urgent: { type: 'boolean' },
+        summary: { type: 'note', maxLength: 200, optional: true },
+      },
+      // Throw to report a failure: it is logged and recorded on the turn, and
+      // never retried. Pass `signal` to anything that waits.
+      async perform({ subscriberId, params, logger, signal }) {
+        // Your code goes here: the request your backend expects.
+        const response = await fetch(`${BACKEND_URL}/follow-ups`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ subscriberId, ...params }),
+          signal,
+        });
+        if (!response.ok) throw new Error(`backend answered ${response.status}`);
+        logger.info('follow-up recorded', { offering: params.offering });
+      },
+    }),
+  ],
+});