041 — agent plugin new Starts a Plugin from the Agent's Own Example
Defines a CLI command that adds a new plugin to an existing tenant project: what it writes, where its content comes from, what it refuses, and the check it ends with. It leaves out publishing a plugin to a registry, the plugin's real backend code, and upgrading a plugin already written to a newer apiVersion.
Copying a plugin is how one deployment's backend reaches another
A plugin (036, 039) takes four edits across four files: the package in plugins/<name>/, plugins/* in pnpm-workspace.yaml, a workspace:* dependency in the project's package.json, and the package name in config/plugins.json. Each is easy to get wrong, and each one wrong surfaces only when agent config check or the server refuses to start: a missing workspace entry, a path where plugins.json wants a name, apiVersion: 1 on a read tool.
The reflexive shortcut is to copy the plugin nearest to hand and edit it. That plugin was written for a live deployment, so the copy starts with its endpoints, its field names, its log messages and sometimes its environment variable names, and the new author deletes what they notice. It is 035's argument at the size of one package: what they miss ships under the new tenant's name, and whatever reaches this repository as an example breaks C1.
Rejected: leaving it to the guide (docs/guides/writing-a-plugin.md). The guide lists the four edits correctly and is still followed by hand, once per plugin.
So the rule is:
A new plugin starts from the agent's invented example, generated by the agent that will load it, and never from a copy of another plugin.
agent plugin new writes from the agent's examples, never from the project's
agent plugin new <name> --read # a read tool (039), apiVersion 2
agent plugin new <name> --write # a write tool (036), staged after the reply- One of the two flags is required. With neither or both, with no
<name>or with any other argument, it prints its usage and exits 2. Which kind of tool a plugin adds is the author's decision, and the two differ in what the model may do with them. <name>is a package name. It must be a valid unscoped npm name in lowercase kebab case, and is prefixedagent-plugin-unless it already starts with it. The plugin'snameis the part after the prefix. Its one tool's name is that part in snake case, soagent-plugin-slot-finderdeclaresslot_finder, and two scaffolded plugins do not start out clashing.- The content is the agent's. The two templates,
read.js.tmplandwrite.js.tmpl, live insrc/plugins/templates/, ship in the published package and are read from the installed agent, never from the project or the network. Every string in them is English and invented (C1, C9): a backend that does not exist, one declared parameter of each allowed type, and a comment at each place the author's own code goes. Their words are ones no vertical owns, an offering and a slot, never a course (042 § The framework says "offering" and "buy", and the tenant supplies the rest), since every tenant starts from them whatever it sells. - Left unedited, a template fails closed. Its tool calls the invented backend at
backend.example.comwithfetch, so until the author replaces it every read reaches the model as{ available: false }and every write is logged as failed (C6). It never answers with data of its own. - The API version is the installed agent's. A read template declares
PLUGIN_API_VERSION; a write template declares the lowest version inSUPPORTED_PLUGIN_API_VERSIONS, so it also loads under an agent one release older. Neither is written by hand in a template.
The template is not a test fixture. The fixtures in test/fixtures/plugins/ report their inputs through the logger so tests can observe them, which is not what a tenant's plugin should start from.
It makes all four edits, or none
Before writing anything, it refuses, and exits 1 naming the reason, when:
<name>is not an unscoped package name in lowercase kebab case;- the current directory is not a tenant project: no
package.jsondepending onmanychat-ai-agent, or noconfig/; plugins/<name>/exists;config/plugins.jsonalready lists the name, or is malformed;- the derived tool name is not one the loader accepts (lowercase snake case, starting with a letter, at most 64 characters), as for a
<name>that starts with a digit or is too long once the prefix is removed; - the tool name is a built-in tool's, or one a listed plugin already declares, or a listed plugin already has the plugin's
name; pnpm-workspace.yamlwrites itspackagesother than as a block list, one entry per line, which the command edits as text to keep its comments and other settings.
A listed plugin that does not load is not refused here: agent config check reports it. The command reads no part of config/ but plugins.json, and needs no environment, so it is the one command besides agent upgrade that runs on a config/ the server would refuse (033 § The agent ships as one package whose surface is its CLI and its schemas).
Then it writes plugins/<name>/package.json and plugins/<name>/index.js, adds plugins/* to pnpm-workspace.yaml (creating the file when the project has none, as a create project does not), adds "<name>": "workspace:*" to dependencies, and appends the name to config/plugins.json (creating it with { "plugins": ["<name>"] }). A failure part-way removes what it wrote and restores the files it changed, so a refused or failed run leaves the project as it found it (C6). It never installs anything and never touches node_modules or the lockfile.
Rejected: writing the package and printing the other three edits. Those three are the ones that go wrong, and a printed step is followed by hand.
It ends with the check the server will run
The server resolves a plugin from node_modules, which holds the new plugin only after pnpm install. So the command checks the generated plugin in two parts:
- Now, it loads
plugins/<name>/index.jsfrom its path and runs on it the declaration checks the loader runs at startup (036 § A plugin that does not load stops the server,039's refusals). A failure here is a bug in the agent: its own template does not pass its own checks. It is undone as a failed write is, and exits 1. - After install, it prints the two commands that remain, in order:
pnpm install, thenpnpm agent config check, which loads every listed plugin as the server does.
It does not run pnpm install itself. Installing rewrites the lockfile, which pins the agent version the image must match (033 § The image is published beside the package, at the same version), and that is the author's change to make and review.
The template moves with the API
A plugin API change (036 § A plugin API change is a breaking change) changes what a template must declare. The templates are covered by the tests that load the command's output with the loader of the same commit, so a change that leaves a template behind fails the suite in the pull request that makes it, not in a tenant's first config check after an upgrade.
Verification
- A test runs
agent plugin newwith--readand with--writein a temporary tenant project built bytest/helpers/plugins.ts, links the output into itsnode_modules, and loads it withloadPlugins. It asserts both load, that the read tool is offered and returns a result that validates, that the write tool stages, and thatapiVersionequalsPLUGIN_API_VERSIONfor the read template and the lowest supported version for the write template. - A test asserts the four edits: the workspace glob, the dependency, the
plugins.jsonentry, and the createdpnpm-workspace.yamlandplugins.jsonwhen the project had neither. - A test runs each refusal of
§ It makes all four edits, or none, and a failure injected after the first write, and asserts the project's files are byte for byte what they were. - A test asserts the usage error with neither flag and with both, the
agent-plugin-prefix and snake-case tool name derived from<name>, and the refusal of a<name>whose tool name starts with a digit or runs past 64 characters. - A test asserts the published package's
filesinclude the templates, so an installed agent can read them. - The C9 check of
005 § Verification(test/integration/language.test.ts) is extended to the templates. It reads a fixed list of files, so being undersrc/does not bring them into it.
What this does not catch. Nothing stops an author copying another plugin instead of running the command; it makes the safe start the easy one, as 035 does for a whole project. Once generated, the plugin is the author's: no check sees what they write into it, and a backend URL or a customer's field name added later is theirs to keep out of anything public. The tests prove the templates load, not that a real backend fits their shape.