Resolving plugs
How the use key of a setup entry becomes a plug, and what the loader checks.
Forms of use
| Form | Resolves to |
|---|---|
blaise:<name> | One of our plugs, through the chain below. |
./x.ts, ../x.js, /abs/x.ts | A file, relative to the config file that declares the entry. |
"@scope/pkg", pkg, "@scope/pkg/sub" | A package from node_modules, resolved from the config file directory. |
Only blaise: is special. Everything else resolves as an import() from a module next to the
config file would.
The blaise: chain
blaise:<name> is tried in order:
- A plug bundled with the runner: the export
@blaiseagent/runner/plugs/<name>, looked up in a table generated at build time, then in the package exports. Always available, at the runner's version. @blaiseagent/plugs-<name>, resolved from the config file directory. A name with a slash maps to an export of the package:blaise:k8s/podis thepodexport of@blaiseagent/plugs-k8s.- An error that names the package to add.
Nothing is installed by the runner: packages come from the project's package.json and lockfile. A
project without a package.json can still use every bundled plug and local files.
What the loader checks
Plugs are always loaded on the runner. All entries are checked, and all problems are reported together, with the entry's position. These are the messages, by problem:
Not found:
plug 3: `blaise:docker` is not bundled with the runner and `@blaiseagent/plugs-docker` is not installed; add it to the project's dependencies
The module throws when imported:
plug 2: `./x.ts` failed to load: …
The default export is not a plug:
plug 2: `./x.ts` does not default-export a plug; wrap it in definePlug()
Built for another major version of the plug API:
plug 5: `blaise:docker` was built for plug API 2.x; this runner implements 1.x
Persisted state without an id:
plug 6 (acme/db-branch) keeps persisted state and needs an `id`
A literal with: that fails the plug's schema:
plug 4 "db" (blaise:shell): invalid `with`: …Inputs that contain expressions are validated when the plug runs, after evaluation.
The plug API version
definePlug stamps each plug with the version of the plug API. The loader reads that field, which
survives bundling and duplicate copies of @blaiseagent/runner. Only the major version is compared,
and it must match exactly. Third-party plug packages declare @blaiseagent/runner as a peer
dependency.
Resumability
Plugs are resumable unless they set resumable: false. A runner whose agent pauses idle sessions
refuses to start with a plug that is not resumable, naming the plug. The check uses the agent's idle
policy at startup; every run also tells Blaise whether its chain can resume, so a policy changed
later never pauses a chain that cannot. See
make a plug resumable.