The words a plugin uses to declare itself, in its server code and in its browser code.1
Each entry says what the word means, what it carries, and what leaving it out costs.
| Word | What it is |
|---|---|
name |
the plugin’s one word, such as kolu |
| row | its line in the list of plugins this build has |
| fiber | one mounted plugin, and whether it is running |
service, needs |
what olai hands a plugin, and what the plugin asks for |
surface, member |
the calls this plugin answers over the connection |
faces |
which callers may make which of those calls |
writes, resources, tools, charter |
the rest of what a plugin registers with its calls |
| import subpath | what another package may import from this one |
probe |
is this plugin’s tool installed on this machine? |
| kind | a word the plugin teaches the directory about property values |
| claim | the property key that kind takes for itself |
| dressing | what the plugin draws beside such a value |
| row actions | what it adds to the menu on an outline row |
| chrome | its component in the header bar at the top of the app |
| mount | its own component in the body of the page |
| mark | its logo |
Deliveries |
sending a message into a conversation with an agent |
wake |
this plugin’s wording for the control that turns that on |
| watching | being told what happened in a conversation |
| local state | one record file and one directory per plugin |
| offer | a service the plugin provides to other plugins |
| engine | a coding agent olai can run |
| slot | a named place in the page the plugin may draw in |
environment, config |
the variables and settings it reads |
| roster, licence | which plugins run, and what is allowed to draw |
The name, the registry row, and the services a plugin asks for
name
The plugin’s one word, such as "kolu".
The same word is the plugin’s id in the registry, the prefix every one of its calls answers under, the name of its fiber, the name its settings are kept under, and the address of its page, website/docs/plugins/<name>.md. Every service that keys things by plugin reads the name off the fiber, so a plugin can never register something in another plugin’s name.
row
One entry in packages/bundle/olai.yml, the file listing every plugin this build has: the plugin’s id, the module the loader mounts, and the columns that place it on the plugins panel, which is where a person switches plugins on and off. The module is named as a string and only looked up when it mounts, so whether a plugin is present is decided while olai runs. The columns are in Adding a plugin.
fiber
One mounted plugin. Whoever asks sees one of four words: running, waiting, failed and off.
service and needs
A service is something olai hands a plugin, such as the served directory or the clock. A plugin reaches one by yielding an Effect tag for it. needs is the array of those tags the plugin declares: the runtime waits until each one is there before the plugin starts, and the compiler refuses a plugin that yields a tag it did not declare.
| Tag | What it gives |
|---|---|
Vault |
the served directory, its revisions and the inbox registry |
Ops |
the write gate and the typed write verbs |
Kinds |
teach the directory a word for a kind of property value |
Surfaces |
put this plugin’s calls on the connection |
Wakes |
declare the wording of the control that turns delivery on |
Deliveries |
send a message into a conversation |
Watching |
be told what a conversation did |
SessionStart |
be asked a probe each time a conversation opens |
Agents |
offer a coding agent olai can run |
LocalState |
one record file and one directory beside the served directory |
Offers |
stand behind one of olai’s own services, or publish one of this plugin’s own |
Tools |
the tools this running olai advertises to agents |
Env |
the process environment variables, and the test stand-in this plugin was given |
Clock |
the time, as an ISO-8601 string |
Identity |
the trusted header names, and who a request is from |
Served |
the directory a transport is serving, and its write gate |
VaultViews |
register a ledger or a matcher with the store |
VaultSettings |
the directory’s settings, supplied after declarations mount |
ConfigurationWatch |
the current configuration, and its changes |
BundleModules |
the module declarations of this build, switched-off rows included |
Bundle |
this plugin’s position in the registry’s order |
A plugin’s browser code asks for browser services instead: Slots, Faces, Wired, Clocks, Bar, Links, Edits, Landings and Offers.
The calls a plugin answers: surface, faces, import subpaths and the probe
surface and member
A surface is the set of calls this plugin answers over the connection between the browser and the server, declared with defineSurface inside the plugin’s own package. A member is one of those calls: a cell, a collection, a stream or a procedure.
export const surface = defineSurface({ cells: { ci: oduMembers.cells.ci } })
The framework puts the surface under the plugin’s name, so this member is called as surface/odu/ci/get. No olai code builds that string by hand.
faces
The list of which callers may reach which members, written in the plugin’s own package against its own surface.
export const faces = { browser: { ci: "resource", service: "resource" } }
A kind of caller the plugin never lists is refused every member, so a plugin with no agent entry answers no agent calling in over MCP. The day it wants to answer them, it adds the entry, and nothing in olai’s core, the code that is not a plugin, changes.
writes, resources, tools and charter
The other fields a plugin passes to Surfaces.register. Each belongs to the plugin, and each goes away when the plugin does.
| Field | What it declares |
|---|---|
writes |
which of its procedures record who the caller was, named as its own surface spells them |
resources |
which members an agent may read as a surface:// address. A plugin whose agent calls are all actions leaves it out |
tools |
the tools this plugin gives an agent, so a plugin that is switched off advertises none |
charter |
one paragraph telling an agent what this plugin is, read off the roster whenever an agent connects |
import subpath
A path inside the plugin’s package that another package may import, such as olai-plugin-vault/contract or a plugin’s own /slots. Such a subpath carries types, service tags, descriptions and fixed data, never a running value.
probe
An Effect the plugin registers on SessionStart, which answers two questions: is your tool installed on this machine, and if it is not, what do we tell the person?
interface Probed {
server: StdioServer | null // the MCP server to hand a session
missing: { name, where, why } | null // ...or the sentence about the one it did not get
at?: string // where in this app the work is visible
}
- One call answers both questions, because asking twice would start the plugin’s background program twice for every conversation.
missing.whyis a whole sentence the plugin writes. Core shows it and writes none of it.- The probes are run again each time a conversation opens, so a plugin that unloaded contributes nothing.
- A plugin need not have a probe. Having none is the ordinary case for a machine that lacks the tool, and that already works.
- The chat plugin limits how many probes run at once, since each one may start a subprocess.
Kinds, claims and dressings
kind
A word the plugin teaches the directory about the values a property can hold. The plugin contributes the word bare, and olai stores it with the plugin’s name in front.
export const kinds = [{
kind: "run", // bare: the registry prefixes it
takes: `\`${RUN_TYPE}\` (an odu run id)`,
admits: isRunIdShaped, // does this value fit
}] as const
// kolu: terminal → kolu-terminal odu: run → odu-run
The file format itself owns seven kinds (text, date, int, path, doc, ref and node), and none of them describes a terminal. The prefix means two plugins cannot end up claiming one word, and a collision would fail that plugin’s register in any case.
claim
The property key a kind takes for itself: its own prefixed word. Whoever speaks first declares the key, and one function decides who that is.
1. the directory's row _olai/Properties.olai ← always wins
2. the plugin's claim the kind's own word ← where the row said nothing
Switching a plugin on therefore declares its key for you, with nothing written into the directory, and a row you wrote yourself always wins. Switching the plugin off takes its claims away with its kinds. What this looks like to a reader is on Properties that show what is happening now.
dressing
What a plugin draws beside a property value in an outline row, where an outline is a file of rows and a row is one line of it. A dressing draws beside the value and never instead of it, so the stored text stays searchable and editable.
| Dressing | When it draws |
|---|---|
| block | always takes a row of its own: a terminal somebody wrote down is worth a row even when nothing is happening |
| chip | only while there is something to say. A row with no odu-run value looks unchanged |
| pane | opens below the row when you click a chip |
What a plugin draws: row actions, header, page body, logo
row actions
What a plugin adds to the menu on an outline row, as a single command or as a group of them.
| Field | Means |
|---|---|
id |
the plugin’s own word for the entry, stored beside the plugin’s name |
label |
the words shown in the menu |
writes |
required: does this change the directory? Entries that only read are grouped before entries that write |
run(node) |
does the work on that row, and returns a sentence if it refuses |
confirm |
a question the menu asks before calling run |
choices |
an entry that opens a submenu of commands instead of acting itself |
A group of one draws as that single option under the entry’s label, and a group of none draws nothing. Cancelling the confirmation, or closing the menu, does not call run.
chrome
A component the plugin puts in the header bar at the top of the app, registered in app.header with a word saying where it goes.
| Word | Means |
|---|---|
lead |
a place in the bar before the health dot, drawn on phones too |
cluster |
a status line: one row of the health popover on a desktop |
A cluster entry may declare a status that updates itself, made of tone, label and detail, read from state the plugin’s own activation owns. The tones are healthy, quiet, notice and alarm, and the health dot shows the worst tone present.
mount
The plugin’s own component in the body of the page, registered in app.mount and mounted once per browser tab. It is where the plugin opens its one subscription, however many rows draw from it.
mark
The plugin’s logo: a small shape beside a message it sent into a conversation, and beside a coding agent’s name in the picker and the header. It is not a To do, Doing, Done or Cancelled mark on a row.
- It takes no arguments, because it is always drawn at the size of its line of text.
- It returns shapes only: a
<g>of paths in a0 0 16 16box, drawn incurrentColor. The app owns the<svg>around it, so a column of logos stays even. - A plugin with no logo is drawn with a general-purpose shape and its full name, never with another plugin’s shape.
Sending into a conversation: Deliveries, wake, watching
Deliveries
The service a plugin uses to send a message into a conversation with an agent. It can only send, and every message carries the name of the plugin that called it.
interface Deliveries {
scopes: () => ReadonlyArray<{ agent: string; session: string; file: string }>
deliver: (
to: { agent: string; session: string },
body: string,
options?: { coalesce?: string },
) => void
}
| Rule | Detail |
|---|---|
deliver cannot read |
a plugin learns which conversations asked for its messages, and nothing else about them |
| The message arrives the way a person’s does | it lands in a user row marked with the plugin’s name, taken from the registry, so one plugin cannot sign another’s words |
| Core decides only when it arrives | an idle agent takes it as its next turn, a busy agent gets it when the turn ends, and a conversation nobody has open keeps it until somebody opens it |
A person chooses, per conversation, which file this plugin may send about. There is no setting for the whole server and none an agent can change, and a new or cleared conversation starts with it off.
wake
The plugin’s own wording for the control that chooses that file.
readonly wake?: {
subject: string // "wake on terminal activity"
waiting: { one: string; many: string } // "fleet event waiting" / "…events waiting"
}
Everything around those words belongs to core: the picker, the separator and the number in 3 fleet events waiting. The declaration sits in the plugin’s server code, because chat.scope refuses a plugin whose server code declares no wake, checked against the plugins this running olai mounted.
watching
A service that tells the plugin what happened in a conversation: a message of its own that landed, an agent reply that finished, a turn that started or ended. What a person typed is not among those events, and there is no transcript to read. Each handler is run on its own, so a plugin that fails on one event does not bring the turn down.
State, offers, engines, slots and settings
local state
One record file per plugin and served directory, kept where olai keeps machine-local state rather than in the served directory. Core owns its path and writes saves one after another, and each save finishes with the result of its write.
LocalState.directory is a directory beside that record, for state that is a tree of files another program writes. Olai creates it readable by its owner only, marks it with the served path, refuses it if it belongs to another path, and deletes it with the records when that path stops being served. What goes inside it is the plugin’s business. It fails rather than hand back a path it could not keep private.
offer
A service of the plugin’s own, published under <plugin>.<word>.
yield* (yield* Offers).own("agenda", provision) // reached as journal.agenda
- The runtime supplies the plugin’s name; the plugin supplies only the word after the dot.
- A plugin that wants it declares
serviceTag<Shape>(key), which is both what the compiler requires of it and what it waits for, so it waits while the offering plugin is switched off. - Both parts of the name take lowercase letters, digits and hyphens and must start with a letter. Dots are refused, so one plugin cannot spell its way into another’s names.
- Two plugins offering one key at once are refused, and the message names the first one.
Offers.offerpublishes a core service instead, such asVault,Ops,AgentsorDeliveries.
Writing one is covered in Ask an agent for a plugin of your own.
engine
One ACP coding agent olai can run in a conversation, shipped as a plugin. It carries a Leg that knows how that agent talks, a probe that finds it on this machine, the channel its standing prompt travels on, plus a logo and a sentence about installing it in its browser code. One directory and one registry row each, and no surface of its own.
The chat plugin detects engines and remembers each machine’s answer until that engine unregisters. The roster lists every mounted engine in registry order, each marked standing: "here" or "not-here", and only one that is here can start.
slot
A named place in the page where a plugin draws a component, such as outline.row.chip or app.header. Which plugin owns each slot, and what each one takes, are in Slots: where a plugin draws, and who owns each one.
environment and config
A plugin declares the environment variables it reads and the settings it takes, both on definePlugin.
| Field | What it declares |
|---|---|
environment |
each variable as key, secret and says, so the plugins panel can show what a plugin reads without that list being written anywhere else |
config |
the plugin’s settings schema, with defaults on the fields. It is read inside the activation, so an invalid value fails that one plugin, with a sentence saying why |
configUpdates |
"reapply", the default, remounts the plugin when its settings change; "live" leaves it mounted and the plugin follows the change itself |
A single setting in a config schema may be marked preference, and it then appears in the preferences panel under the plugin’s heading, with the plugin’s row in the plugins panel linking to it.
roster and licence
The roster is which plugins this build has and which this running olai is running, published as core’s plugins cell. A licence is permission for one dressing to draw, answered by the server for each value it sends. Both licences are described below.
The subpaths a plugin package exposes
Three different programs load a plugin’s code, so a package exposes three subpaths of code plus one row of data.
| Subpath | Read by | Contains | May not contain |
|---|---|---|---|
./wire |
the browser, setting up the connection | name, surface, faces |
SolidJS, a client for the program the plugin talks to, a node: builtin |
./server |
the loader, at mount | name, needs, apply. May pull in that client and node: builtins |
a browser component |
./browser |
the browser | dressings, header components, the page component, the logo: SolidJS, in a chunk of its own | — |
a row in packages/bundle/olai.yml |
the loader | id and the module’s name, as data |
an import |
A browser component anywhere in the imports of a process that draws nothing kills the start-up with Cannot find module 'react/jsx-dev-runtime', which is why there are three subpaths.
Four more subpaths carry data rather than code. ./all.css adds the plugin’s stylesheet, and ./testids is its catalogue of the identifiers the browser tests look for. ./assets contributes markup for the page head and files to preload. ./policy carries fixed reservations of what the plugin may write, which hold even while the plugin is switched off.
@olai/plugin-api is not one of those subpaths. It is the interface a plugin is written against: browser components and slots at its root, server service tags at ./services. It names no plugin, which is what lets a plugin import it.
How a property value gets the component that draws it
A directory’s property declarations deliberately never travel to the browser, so the browser cannot read _olai/Properties.olai and decide anything from it. A plugin still draws a value the browser was never told about, in three steps.
- The directory declares a key to be a kind. The key may be called anything, such as
pty, and the kind is the plugin’s prefixed word,kolu-terminal. Where the directory says nothing, the plugin’s claim applies. - The server works it out once per value it is about to send.
@olai/format’smeaning.tsmaps the value to{ opens, word }: what it points at, and which running plugin’s kind claims it. Both travel with the page as tables keyedfrom·prop·value. - The browser draws it. A chip becomes a link from
opens, anddressingFor()lookswordup in the table of what plugins registered into their slots.
What travels is an answer about one value being drawn, never the declaration. A value that does not fit its kind gets no word, so switching a plugin on over a directory nobody migrated leaves the text plain, with the validator’s finding beside it.
Two permissions are settled before a dressing draws.
| Licence | Asks | Answered by |
|---|---|---|
| the page’s | is this value claimed by a kind word? | the three steps above |
| the roster’s | is this server running the plugin that owns the dressing? | the plugins cell |
For both of today’s dressings the answer names the same plugin, and they are still two questions: nothing requires a dressing to be registered by the plugin that taught the directory the word.
The roster arrives on a frame, so there is a moment when the browser does not know which plugins run. The two defaults point opposite ways, because a wrong guess costs differently.
| Before the roster lands | Assume | Why |
|---|---|---|
| drawing a dressing | on | a dressing drawn early and then removed is a flicker |
| mounting a plugin | off | a subscription to another plugin this server did not compose fails for the life of the page, naming a plugin the operator turned off |
Footnotes
-
Where the contract lives: the TypeScript types under
packages/plugin-api/src/are the contract itself, and The plugin system explains why it has this shape. ↩