The steps to add one plugin to olai. Only the name is required, plus a file declaring the calls the plugin answers if it answers any.1
A plugin that contributes one piece of live data is a whole plugin: the odu plugin is. What each word in those files means is in The words a plugin declares itself with.
| Step | Where it lands |
|---|---|
| 1. The package | packages/plugins/<name>/package.json |
| 2. The calls it answers | src/wire.ts |
| 3. The server code | src/server.ts |
| 4. The browser code | src/browser.tsx, only if the plugin draws something |
| 5. The page | packages/plugins/<name>/docs.md, plus a symlink and an index row |
| 6. The registry row | packages/bundle/olai.yml |
| 7. If it runs a coding agent | src/leg.ts, src/install.ts, no surface |
| 8. If it ships a binary, a pin or a generated file | default.nix |
| 9. If it runs a coding agent | e2e/fake/ |
| 10. Run the import check | bun test packages/bundle |
1–4: the package, the calls it answers, and its two pieces of code
1. The package: packages/plugins/<name>/package.json
The package is called olai-plugin-<name>, with no @scope/ in front, and its directory is the plugin’s own word. @olai/* is the scope for the packages that are olai itself; a plugin is named the way a plugin written outside this repository would be. It goes in packages/plugins/ and nowhere else.
Copy another plugin’s manifest: main, types, a typecheck script, and an exports map listing the subpaths this plugin offers.
"exports": {
".": "./src/index.ts",
"./wire": "./src/wire.ts",
"./browser": "./src/browser.tsx",
"./server": "./src/server.ts",
"./testids": "./src/testids.ts",
"./all.css": "./src/browser/all.css"
}
./browseris the one to get right: it is the subpath the generator writes the browser’s dynamicimport()against, so a manifest without it generates a row the browser cannot load.- A plugin with no browser code leaves out
./browserand./all.css. You do not need empty modules for them, and the generator writes neither a chunk nor a stylesheet import. - Declare
@olai/plugin-api,effect, the client for whatever outside program you talk to,@olai/formatif you read the directory,solid-jsif you draw anything, and everything else your own source files import. Bun gives a package exactly what its manifest names. - Never declare
@olai/bundle, which imports you, nor@olai/effect-cordisandcordis, which are the plugin engine’s business. - A plugin with slow tests records how long they take in its own
test-weights.jsonat the package root, a map of repo-relative path to seconds. The harness decides how to split the tests up, and only the tests know their own timings.
2. The calls it answers: src/wire.ts
Export name, a defineSurface call declaring the calls this plugin answers, and the faces map saying who may make them. This module may not import SolidJS, a client for an outside program, or a node: builtin.
export const name = "odu"
export const surface = defineSurface({
cells: {
ci: oduMembers.cells.ci,
service: oduMembers.cells.service,
},
})
export const faces = { browser: { ci: "resource", service: "resource" } }
A plugin that runs a coding agent has no such file. What such a plugin shows in the browser already travels on the chat plugin’s own data, so it declares no calls of its own and puts its name in src/index.ts. See step 6.
3. The server code: src/server.ts
Export as default a definePlugin({ name, needs, apply }), where apply is one Effect. Yield each service you listed in needs; the compiler refuses one you did not list.
- This is where you call the client for your outside program, where
Surfaces.register(…)puts your calls on the connection, whereKinds.register(…)teaches the directory a word, and whereDeliveriessends a message into a conversation. - Register a
wake, or no control appears for you on a conversation’s strip andchat.scoperefuses your plugin’s name. That is the check working. - Register on
SessionStartif you have a tool to look for on the machine, and onAgentsif your plugin runs a coding agent. - Log with
Effect.logDebugandEffect.logWarning, which are printed at whatever level the operator asked for. - If your outside program calls you back from a timer or a socket, take
detachedonce and start Effects through it. Usering(work)where nobody needs to track the work, andring.held(work)where something of yours has to interrupt it or wait for it. - Everything you register is withdrawn for you when the plugin unloads, so write no teardown code, unless you hold something the runtime cannot see. That is an
Effect.addFinalizer, which is whatxyne-spacesdoes for the copies it keeps running.
Use
addFinalizeronly when nothing was awaited to obtain the thing it releases. A fiber parked inEffect.promiseunwinds where it stands, so anything you waited for belongs inEffect.acquireRelease, which cannot be interrupted between acquiring and registering the release.
4. The browser code: src/browser.tsx
Only if the plugin draws something. Same shape: name and surface re-exported from ./wire.ts, and a default definePlugin whose Effect registers your components into Slots. It is a chunk of its own, fetched only when the list of running plugins names yours.
- A plugin that has a page of its own registers
app.routehere. A page made of rows usesdefineAppRouteanddefineAppPage; a page of any other sort usesdefineSelfDrawnRouteanddefineSelfDrawnPage. Both pairs are inolai-plugin-navigation/routes, and Addresses, panes and the command palette describes what they draw. - The slots you may put a component in, and what each one takes, are in Slots: where a plugin draws, and who owns each one.
An
onCleanupregistered after anawaitinsideonMountruns with no owner, and Solid’s production build compiles that to nothing. So register the cleanup before the load, over an empty slot, and check afterwards that the owner has not gone away.
5–6: the page, and the row in the registry
5. The page: packages/plugins/<name>/docs.md
Write the plugin’s page there, symlink it at website/docs/plugins/<name>.md, and add a row for it to website/docs/index.md, under the group its sidebar entry belongs in. packages/tests/plugin_docs.test.ts fails if you skip either.
6. The row in packages/bundle/olai.yml
One row, because the rest is generated.
- id: odu
name: olai-plugin-odu/server
section: Connections
label: Odu
| Column | What it says |
|---|---|
id |
the plugin’s word: the key other plugins know it by, the name its settings are kept under, its fiber’s name, and the address of its page |
name |
the module the loader mounts, written as a string it looks up at mount time rather than as an import |
section |
required: the group this plugin sits in on the plugins panel, spelled as the screen spells it |
label |
the name a person reads on that row, such as Claude Code. Leave it out and the row shows the id |
disabled |
true for a plugin somebody has to turn on, such as one needing a secret this machine may not have |
profiles |
the extra profiles that include this plugin. The web profile takes the catalogue’s defaults |
switchHint |
the warning shown before somebody switches this plugin off |
quiet |
true lets its group start collapsed while every plugin in it is running with nothing to say |
Add one line to the dependencies in packages/bundle/package.json, without which the generated import() does not resolve.
The generator writes everything else from the row: the browser’s table of plugins with a dynamic import for each, the chain of stylesheets, the merged table of test identifiers, and the tables of assets and write reservations. It also writes the list of stand-in agents the tests use. just install produces all of them, and so does the Nix build in its own sandbox, so a packaged build cannot ship an out-of-date copy.
7–9: running a coding agent, a Nix part, and a scripted stand-in
7. If the plugin runs a coding agent
Such a plugin runs an ACP coding agent in a conversation, rather than talking to an outside program the way the kolu and odu plugins do. Smaller shape, same rules.
- No
./wire, no surface, nofaces:src/index.tsholds the plugin’s word and nothing else. src/leg.tsis aLegfrom@kolu/acp/engine: every assumption about how that agent talks, each written as a pure function with a unit test. Where none of them matches, the person is asked.src/server.tsregisters{ name, leg, at, prompt }onAgents: the name a person reads, the leg, a probe answeringAdapter | NotHerefor this machine, and the channel the standing prompt travels on.src/install.tsholds the sentence shown when the agent is not installed: aNotHerewhosewhyis a whole sentence, which nothing else assembles. One shared component draws it in the greyed-out picker row, on the page shown when there is no agent, and in the plugins panel row.src/browser.tsxregisters the agent’s logo indelivery.mark, and may define its ownrowcomponent, which it gives toplugins.rowunder its own name through thechat.enginesservice.- Its
testidstable is rightly empty: such a plugin draws inside elements olai’s own code owns, under olai’s identifiers, withdata-agentcarrying its word. - The order of these rows in
olai.ymlmatters: it is the order the picker draws them in and the order the install screen lists, and a conversation that names no agent is taken to be about the first row.
There is no slot for the words in the picker. The server supplies both the agent’s name and the reason it is missing, so one place is responsible for that fact.
8. If it ships a binary, a pin or a generated file: default.nix
A plugin may have a packages/plugins/<name>/default.nix, which is its Nix part, folded in by packages/bundle/default.nix. Most plugins have none, which is the ordinary case. It takes { pkgs, pins, kit, b2n ? null }: and returns an attrset whose keys are all optional, and any key not in the table below is refused by name.
| Key | Meaning |
|---|---|
hydrate |
sources copied into node_modules/<dest> after bun install |
externals |
the npm packages those sources need at the repository root |
koluSeeds and koluPins |
the kolu sources this plugin imports, and the pins that complete their dependency closure |
generated |
files written into the plugin’s own tree. The path must contain .generated. |
npmTrees |
directories just install runs npm ci in, where a test needs a real node_modules |
knobs |
the environment variables the packaged wrapper sets with --set-default |
packages |
flake outputs this plugin contributes, such as claude-agent or odu-bin |
checks |
checks that need the built tree, exposed as checks.<system>.plugin-<name>-<check> |
An ACP adapter olai ships lives in the plugin’s own acp/ directory, with its patches and the test rigs for them. Where the adapter is released on its own schedule, as Codex is, it also has a lock file and derivation of its own. The plugin’s default.nix declares it through @olai/plugin-kit’s npmAdapter, and nothing outside the plugin’s directory names any of it.
9. If the plugin runs a coding agent: e2e/fake/
The scripted stand-in the browser tests run instead of the real agent lives at packages/plugins/<name>/e2e/fake/: an index.ts describing it, typed by @olai/tests’ ./harness/fake.ts, plus the executables the harness starts. packages/tests/agent/ keeps only the part that is the same for every agent, and the harness finds the stand-ins through the generated @olai/bundle/e2e-fakes list rather than by name.
10: run the import check
bun test packages/bundle
It tells you what you got wrong, and it is specific: a subpath you imported past, a word a general package reserves, an environment variable your manifest and your module spell differently. The plugin system lists which file holds which rule.
Footnotes
-
What lands outside
packages/: two files, a symlink to the plugin’s page and a line in the docs index. No general package changes at all. ↩