Ask for a plugin. An agent writes it into the directory olai serves, and olai compiles it and starts it without a restart, once you approve it.1
Ask for one
- Press
Cmd+K(Ctrlelsewhere) to open the command palette, and choose New plugin. Say in one sentence what it should do. - Name it.2
- Watch it arrive on its own page at
/plugins/hex-swatch.345 - Read what the agent wrote, then press Turn on. What the plugin draws appears with no reload.
Three ways to start a new plugin
All three are there before you have any plugin at all.6
| What you click | Where it is |
|---|---|
| New plugin in the command palette | Cmd + K, then search for it by name |
The + on the Plugins heading |
the sidebar, the left column of files |
| New plugin at the top of the Plugins panel | the health dot, then Plugins |
Read the plugin, then turn it on
The plugin’s page describes what it does in plain words first, and shows its source code below.7 When you approve a plugin, you approve one exact version of its code.8
The code runs with the same authority as olai itself. There is no sandbox, and your approval is the only boundary. That is why Turn on is a button in the browser, which no agent can press.
Where your approval is stored
Whether the plugin is on, which version you approved, and its own settings are kept as properties on one row in _olai/Settings.olai. That row is titled with the plugin’s name, in the file every built-in plugin uses for its own settings.910
Two plugins written out in full are in Two example plugins you can copy.
The buttons on the plugin's page, and the refusal when the code has changed
| Button | What it writes |
|---|---|
| Turn on | approved: <version> and on: yes, in one write |
Always trust changes, under ••• |
approved: always, and nothing else |
| Stop trusting changes, in its place | the version that is running |
Delete…, under ••• |
removes the folder’s files and the plugin’s settings row |
The sentence you see when you approve code that has changed since the page drew it:
"hex-swatch" has been edited since this page drew it, so approving it now would
approve source nobody has read. Look again, read what it says, and approve that.
When olai notifies you, and when it stays quiet
You ask for a plugin and then go and do something else, so three events reach you wherever you are: as a system notification, as a mark on the plugin’s row in the sidebar, and on the plugin’s page.
| Event | What has happened |
|---|---|
| Ready for you | the agent called vault-plugins_run at the version on disk, and got no fault back |
| Paused | a plugin that was running stopped, because its code changed |
| Couldn’t start | the plugin’s apply threw an error, or one of its two code files will not compile |
Nothing else notifies you. A plugin starting is not news, because you pressed the button, and one being built is not news, because you asked for it.
The settings row, and three things a plugin is not
hex-swatch on: yes
approved: 3fa9c1d2b7e45610
checked: 3fa9c1d2b7e45610
size: large
A builder property on this row is ordinary text that olai reads nothing from: the chat of plugins/hex-swatch/README.md is the builder.
- Not a lock. olai refuses any write of
approvedfrom an agent session, which stops an agent approving the plugin it just wrote. Otherwiseapprovedis an ordinary property, and one that turns up on disk is an ordinary edit to your files. - Not a report of what the browser file did. A component that throws an error while it is drawn is caught by the tab, the browser console names the plugin, and the plugin still says
running, because on the server it is. - Not a package. There is no command to install one, no version to pin and no build step: a plugin is a folder in a directory olai already serves.
The guide an agent follows to write a plugin
The folder
A plugin your directory defines is a folder under plugins/, and the folder’s name is the plugin’s name:
plugins/hex-swatch/
README.md what it does, for a person
server.ts required
browser.tsx optional
- The name has the same shape a built-in plugin’s does,
[a-z][a-z0-9-]*, and may not be a name this server already uses. A folder named anything else is not compiled, and is shown with a sentence saying so. README.mdis a# Title, a blank line, one sentence, then as much prose as the plugin deserves. The heading is the plugin’s name on screen, and the first paragraph the line under it.server.tsis required, and is a whole plugin on its own: it can teach the directory a property kind, or send a message at seven each morning.browser.tsxis optional. It is the file that draws on screen.- Anything else in the folder is ordinary content, and olai leaves it alone.
olai treats these two code files as a plugin only under plugins/, so a code checkout somebody keeps beside their notes is untouched. They stay plain text: stored like any other file, recorded in the ledger, and listed by path in the commit panel, where you commit changes.
They are not rows in the sidebar’s Reference tree, because you read them on the plugin’s page. A file’s path is an address too: /plugins/hex-swatch/server.ts opens the plugin at that file.
What each file may import
Three modules, by their bare names:
import { definePlugin, Kinds } from "@olai/plugin-api"
import { Effect } from "effect"
import { createSignal } from "solid-js"
olai resolves all three itself, against the copies inside the running binary, so what a plugin draws uses the same Solid the app does. The directory has no node_modules, so any other import is refused when olai reads the plugin, not while it runs:
olai resolves @olai/plugin-api, effect and solid-js for a plugin it mounts from
a vault, and nothing else — so "left-pad" names nothing this serve can hand
over. A vault has no node_modules.
A subpath is also refused (effect/Schema, solid-js/web), and so is an import() whose path is computed while the plugin runs. A person approves the source they read, so every module a plugin imports must be visible in it. A relative import is refused with its own sentence, because a plugin is these two files and nothing else.
Both files import the bare @olai/plugin-api, and olai gives each different services: the server file Kinds, Vault, Surfaces and Deliveries, the browser file Slots, Clocks and Wired.
Give it settings
The server file may expose a Config schema, as a built-in plugin does. Give every field a decoding default and a description annotation, then pass it as config to definePlugin; apply receives the decoded object.
import { definePlugin } from "@olai/plugin-api"
import { Effect, Schema } from "effect"
const Config = Schema.Struct({
tone: Schema.String.pipe(
Schema.withDecodingDefaultKey(Effect.succeed("blue")),
Schema.annotate({ description: "the colour to draw" })),
})
export default definePlugin({
name: "hex-swatch", needs: [], config: Config,
apply: (config) => Effect.logInfo(`tone: ${config.tone}`),
})
- Each field is a property on the plugin’s row in
_olai/Settings.olai, besideonandapproved. - Its control appears under Settings on the plugin’s page, and in the plugin’s row in the Plugins panel. A ● marks a value somebody set, and ↺ removes the property.
- Changing a setting re-applies the plugin and asks for no fresh approval, because a setting is not source code.
- A value that does not fit the schema falls back to the default, warns once, and shows the file’s text and the schema’s message under its control.
What an agent can do
| Tool | Answers |
|---|---|
vault-plugins_guide |
this guide, which ships inside the binary |
vault-plugins_inspect |
what a plugin may name: the three modules, the service keys, the slots and their keys, the folder layout, and the names in use |
vault-plugins_write |
writes one file of one plugin, and says whether that file compiles |
vault-plugins_run |
the state of one plugin right now: its state, its version, and the fault sentence if it has one |
vault-plugins_stop |
switches one plugin off for good, by writing on: no |
- Call
vault-plugins_inspectbefore you write code. Each service record says which file it belongs to, andavailabilitysays whether a server file provides it now or has declared it for the browser. - Its
takenlist holds every name this server uses, built-in plugins and folders underplugins/alike: a new plugin may use neither. vault-plugins_writecreates the folder if it is not there. It is all the vocabulary you need: no paths, no rules about which files olai claims, no guessing.vault-plugins_runanswerspendingfor a plugin nobody has approved. That is the approval boundary answering you: say so and stop.vault-plugins_stopworks on these plugins only. Naming a built-in plugin is answered as no such plugin.
Check a file before you ask for approval
Every edit changes the version, and every version costs a person a decision, so be sure the file is right before you ask for approval.
Write the file with vault-plugins_write, which says in the same reply whether it compiled, so the loop is one call rather than a write and a guess. Or compile it yourself, with the call the server makes:
import { buildHalf } from "@olai/plugin-build"
console.log(await buildHalf("browser", source)) // { ok: true, text } | { ok: false, why }
Run that from a package that depends on @olai/plugin-build; packages/server does. It catches every way a file can fail to become a module: a module olai does not provide, a relative import, a computed import(), a syntax error. Then typecheck both files with bun x tsc --noEmit.
The typecheck has one trap. Both files import the bare
@olai/plugin-api, and each gets different services, so typechecking a server file as written reportshas no exported member 'Kinds'. Point that import at@olai/plugin-api/servicesfor the check, then put it back.
Say when you are finished
vault-plugins_run is the last check, and the only one that asks about the real thing: it answers about the same plugin the person is looking at. It is also how you say the build is over.
Until that call comes in, the plugin’s page says it is still being built, and nobody is notified. A file arriving cannot mean it is finished, because this guide has you write browser.tsx last. Call it once the folder is complete, at the version on disk, and the person is told it is ready.
Call it again after every fix. Each call is about the version it was made at, and only a call with no fault in its answer ends the build. A mistake you fixed yourself notifies nobody. olai writes that version onto the plugin’s settings row, so a build finished before a restart is still finished after one.
Share a service with another plugin
A server file can offer a service to other plugins, with no change to olai’s own services. Name Offers in needs, then yield offers.own("fleet", consumer => ({ ... })). olai puts the offering plugin’s name in front of the key, so fleet-source offers fleet-source.fleet. The callback is given the asking plugin’s name, so it can return a different view per plugin.
- Both parts of the key start with a lower-case letter and hold only lower-case letters, digits or hyphens. A dot separates them.
- A plugin that wants it writes
const Fleet = serviceTag<FleetShape>("fleet-source.fleet"), putsFleetinneeds, and reads it withyield* Fleet. Making a tag names a dependency; it grants nothing. - The two plugins agree between themselves on the service’s shape. The string key checks nothing while they run.
- A plugin waits until the service has started up. Replacing a provider unloads the plugin using it and waits for its cleanup while the old service is still alive, then starts it on the new one.
- Offering a key already offered faults the offering plugin and undoes its registrations. Cordis, the registry olai runs plugins on, refuses a second provider for one key and names both.
vault-plugins_inspectlists the keys on offer now, beside olai’s own. A stopped provider’s keys leave the list, and a plugin may name a key nobody offers yet and wait for it.
A service the browser file offers
A browser file imports Offers the same way, and publishes with yield* (yield* Offers).own("palette", consumer => ({ ... })). A browser file that wants it declares serviceTag<Shape>("provider.palette") in needs and yields it in apply.
- In the browser,
Offershas onlyown, so a plugin cannot replaceSlots,Wiredor anything the app’s shell provides. These keys live in the tab, apart from server keys of the same name. - A provider publishes only once it has started up. While it is missing, the plugin waiting for it draws nothing, and when the provider withdraws, what that plugin drew is removed before the provider’s own resources are released.
- To make a browser key visible to
vault-plugins_inspect, the server file namesOffersinneedsand callsyield* (yield* Offers).browser(["palette"]). Those declarations go when the server file unloads.
What happens when it starts
The server file is compiled, evaluated and started as a fiber on the registry the built-in plugins run on. Its property kinds become available, a surface it adds reaches the wire, the list of plugins changes, and open tabs reconnect.
Then olai reads the served directory again, which is what draws the plugin on values that were already there. Without that, the plugin’s kind would be in force, but its chip would not be drawn until the next keystroke somewhere in your files.
The browser file is compiled to a chunk of JavaScript, served at /_olai/plugins/<name>-<version>.js. The tab loads it as it loads a built-in plugin’s chunk, and what the plugin draws appears with no reload. The version is in the path, so an approved edit has a different address, and no cache can return the code approved before it.
The server keeps the last chunk served for each plugin name, so a tab still fetching one while the plugin stops gets that code rather than a 404.
The plugin ends up failed if a file will not compile, exports no plugin, declares a name other than the folder’s, or if apply throws. The sentence explaining it is on the plugin’s page and its row, no other plugin is touched, and Ask the agent to fix it hands that sentence to the conversation verbatim.
Starting and stopping
The server file stays waiting while its apply starts up, and the services it offers reach other plugins only once that succeeds. If it fails, its registrations and resources are undone, and the page shows the fault.
- The switch and
vault-plugins_stopcan stop a plugin still starting up. Stopping interrupts its work, waits for background work and cleanup, and leaves it switched off. - Losing a service the plugin requires also interrupts start-up, leaves it
waiting, and names the missing key. When that service comes back, start-up runs again. - Shutting the server down closes every plugin, and a plugin’s cleanup finishes before the service it depends on releases what it was using.
- Cancellation is cooperative: synchronous JavaScript cannot be interrupted, and acquisitions and cleanups marked uninterruptible run to the end. There is no time limit on start-up.
Footnotes
-
Every page listed under Plugins describes a plugin olai was built with. The plugins on this page are yours: an agent writes them into the directory olai serves. ↩
-
olai suggests a name from the sentence you wrote, and the line under the box says where the plugin will be kept,
Kept in your vault as plugins/hex-swatch/. A name another plugin has, or one that is not lower-case letters, digits and hyphens starting with a letter, is refused while you type. ↩ -
The button opens the plugin’s own page, with the conversation building it opened in the pane beside, and the page lists each file as the agent writes it. That conversation is an ordinary one under Chats: close the pane, come back tomorrow, and an alert tells you when the agent needs you. ↩
-
Asking for a new plugin starts the chat of the plugin’s own
README.md, named after its folder: the chat forplugins/hex-swatch/README.mdishex-swatch. That chat is the builder: the page reads Being built while it works, says when the agent has finished, and carries Ask for a change…. A plugin whoseREADME.mdhas no chat offers Ask about Hex Swatch…, which starts one.The agent is told to keep the
---block at the top of thatREADME.mdexactly as it is, because those keys tie the conversation to the file, and olai refuses a write that changes them. ↩ -
A tool writing the file from outside olai is outside that fence. What the chat’s own page then says, and the one press that ties it back, are on the chat plugin’s page. ↩
-
The plugin’s page opens with the title and first line of its
README.md, then What it uses, read off the code’s own imports. The files are below that, one tab each, beside the folder they are in. Settings it declares sit under Settings, and Ask for a change… opens the builder chat in the pane beside. ↩ -
A version is a hash of the plugin’s two code files. Editing either one pauses the plugin, stops it running, and shows what changed since the version you approved. Editing the
README.mdchanges nothing, because prose is not code. Every approval carries the version the page showed you, so one made after the source changed is refused. ↩ -
You cannot use
on,approvedorcheckedas a plugin setting: aConfigdeclaring one faults the plugin, andplugins.configurerefuses to write one.checkedis the version the building conversation last finished at, and olai writes it when that call comes in. A plugin that could writecheckeditself would declare itself finished. ↩ -
A plugin folder you copy in from another directory arrives switched off and unapproved, because the code travels and your approval does not. Your answer survives a restart and a stop, because it is a line in a file:
on: no. ↩