pastilhas
55d6eba511
the piece that makes a new notification kind a server change rather than an app store release. a push carries a code and integers; this is what the code means, synced to the device instead of compiled into it. deliberately the same shape as affordances rather than a second mechanism: a `notifications/` directory of yaml in the plugin repository, copied to capabilities/notifications/<publisher>/<appName>/ on install, removed on uninstall. publish.ts mirrors affordances/publish.ts closely enough to diff. the namespace is DERIVED from where the file lands, never from what it declares — same rule as mountPrefix. a plugin writing `officer/core:test` as a key gets `<publisher>/<plugin>:officer/core:test` and the real core entry is untouched. that is the security property of the whole scheme and it is pinned by test. version is a content hash, not a counter. a counter needs somewhere to live and is then wrong after a restore, a rollback, or two servers built from the same install; a hash needs no storage and is right in all three. so the client compares mv !== version, and both docs now say so — i had written "higher". core entries ship in code rather than on disk, because capabilities/ is installed rather than committed and `test` has to exist on a machine that has installed nothing — it is what first light is proved with. read from disk per request, not memoised: installing a plugin has to change the answer without a restart, or it presents as "the new plugin's notifications don't work", which is the hardest kind of bug to place. verified live: 401 through the platform, plugin catalogue appearing and disappearing with no restart, version returning to its prior value when the plugin is removed. 10 catalogue tests, 100% coverage of catalogue.ts.
181 lines
9.3 KiB
Markdown
181 lines
9.3 KiB
Markdown
# Plugins
|
|
|
|
`EXTRACTING-A-PLUGIN.md` is the runbook for turning a platform feature into a plugin, and
|
|
`EXTRACT-A-PLUGIN-PROMPT.md` is the way to hand that to a fresh agent. This file is for the concepts a
|
|
plugin author needs that are not procedure.
|
|
|
|
**This directory holds documentation, not plugins.** Every plugin is its own repository; `plugins/<name>/`
|
|
appears by `git clone` when somebody installs one, and is gitignored here.
|
|
|
|
---
|
|
|
|
## Affordances
|
|
|
|
**DESIGN, NOT BUILT.** Agreed 2026-08-19. There is no registry, no API and nothing to call yet. It is
|
|
written down now because the name and the boundary are the parts that are expensive to change later, and
|
|
because a plugin author who invents a different word for this will be hard to merge with afterwards.
|
|
|
|
### What one is
|
|
|
|
> **An affordance is something the surface on the other end of the conversation offers the agent —
|
|
> declared by the code that implements it, and read by the agent at runtime.**
|
|
>
|
|
> Not what the agent can do. What the client will honour.
|
|
|
|
### Why it needs to exist
|
|
|
|
The platform hosts the agent and never introduces itself. An agent gets a shell, a filesystem and a
|
|
prompt; everything about the surface it is speaking _through_ has to be smuggled in as prose somebody
|
|
maintains by hand.
|
|
|
|
The worked example is images. Officer's chat renders markdown images — `ChatImage` is wired into
|
|
`react-markdown` — but an `<img>` carries no bearer token, so it can only load what the browser can fetch
|
|
unauthenticated. A fresh agent knows none of that. It writes ``, nothing renders,
|
|
and nothing tells it why. The knowledge currently lives in a hand-written `CLAUDE.md` on one machine,
|
|
which says "use a public URL" — a workaround, one step removed from the actual constraint, with nothing
|
|
keeping the two in sync.
|
|
|
|
Three properties make prose the wrong container for this:
|
|
|
|
- **It drifts.** The file describes a workaround; the code has a reason. Neither knows about the other.
|
|
- **It is per-machine.** It lives in one repository, copied by hand.
|
|
- **A plugin cannot contribute to it.** Install a plugin that adds a surface and no agent learns it
|
|
exists — which is the case that matters here, because a plugin is exactly a new surface arriving at
|
|
runtime.
|
|
|
|
### The boundary
|
|
|
|
Three neighbours, easily confused:
|
|
|
|
| | answers |
|
|
| -------------- | ---------------------------------------------------- |
|
|
| **tool** | what the agent can _do_ — it acts, something happens |
|
|
| **permission** | what this _account_ may reach |
|
|
| **skill** | instructions the agent _follows_ |
|
|
| **affordance** | what the _client_ will render, accept or ignore |
|
|
|
|
Two tests settle most cases:
|
|
|
|
1. **Would it change if the same agent talked to a different client?** A phone app, a terminal, a
|
|
webhook, a cron run with no human at all. If yes, it is an affordance. Rendering an image is; reading
|
|
a file is not.
|
|
2. **Does the agent have to guess it today?** If the honest answer is "it writes the markdown and hopes",
|
|
that is a missing affordance.
|
|
|
|
### The rule that makes it worth having
|
|
|
|
**An affordance is declared where it is implemented.** `ChatImage` declares that images render, because
|
|
`ChatImage` is what makes them render. The moment it becomes a list maintained somewhere else, it is the
|
|
hand-written `CLAUDE.md` problem again with a better name — and this time with a build step.
|
|
|
|
Same posture as `permissions/registry.ts`, and for the same reason: one enumeration, owned by the code it
|
|
describes, which cannot quietly disagree with reality.
|
|
|
|
### The file
|
|
|
|
Markdown with YAML frontmatter, like every other item in `capabilities/`. Frontmatter is for the
|
|
PLATFORM; the body is for the agent.
|
|
|
|
```markdown
|
|
---
|
|
name: Image rendering
|
|
description: Use when you have an image to show the user in chat.
|
|
version: 1
|
|
---
|
|
|
|
`` renders as an image. **The user's device fetches the URL**, so it must be
|
|
reachable from there — a local path, `file://`, or anything behind authentication renders nothing,
|
|
and fails silently.
|
|
```
|
|
|
|
| field | |
|
|
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `name` | becomes the heading in the compiled block, so the agent can index it |
|
|
| `description` | when to reach for it. Costs the agent nothing — it is not sent |
|
|
| `version` | an INTEGER, not semver, matching `capabilities/agents/` (`agent-files.ts` parses it that way). A plugin-contributed affordance sits near two version numbers and they mean different things: this integer is the revision of _this text_, the plugin's semver is the plugin's. Do not reconcile them |
|
|
|
|
**Keep the body short.** Every affordance is loaded into every conversation, so it is charged to the
|
|
context budget of every turn. State the constraint, name the silent failures, say what to do instead.
|
|
|
|
There is deliberately no `surface` field yet. It was drafted and dropped: for the image affordance it
|
|
would mean _what the client renders_, and for the gitea one below _what tooling exists on the machine_ —
|
|
two different axes wearing one name. Everything is loaded unconditionally until that is worked out,
|
|
which is fine at two files and will not be at twenty. See `TODO.md`.
|
|
|
|
### Where they live
|
|
|
|
```
|
|
capabilities/affordances/
|
|
officer/core/ ← core, installed by the setup script
|
|
image-rendering.md
|
|
officer/gitea/ ← contributed by the gitea plugin on install
|
|
gitea.md
|
|
```
|
|
|
|
`<publisher>/<plugin>`, taken from the manifest verbatim — so a plugin published by `officerdev` lands
|
|
under `officerdev/`. `officer/core` is not a plugin: it is the platform's own, shipped by the setup
|
|
script from the capabilities repository. The two spellings mark two different things and should not be
|
|
normalised into one. A plugin ships an
|
|
`affordances/` directory in its repository; installing copies it in, uninstalling removes it — the same
|
|
shape as `assets/` and `publishAssets`.
|
|
|
|
## Notifications — the same shape, for push
|
|
|
|
A plugin can also declare what its push notifications MEAN. Same mechanism, different store:
|
|
|
|
```
|
|
capabilities/notifications/
|
|
officerdev/music/
|
|
catalogue.yaml
|
|
```
|
|
|
|
```yaml
|
|
nowPlaying:
|
|
title: 'Now playing'
|
|
route: 'officer://music/{id}'
|
|
```
|
|
|
|
That becomes the code `officerdev/music:nowPlaying`. A push carries the code and integers — never content —
|
|
and the device renders the title and follows the route. The point is that **adding a notification is a
|
|
server change and never an app build**, because the mapping is synced to the device rather than compiled
|
|
into it.
|
|
|
|
**The namespace comes from where the file lands, not from what it says.** Writing `officer/core:test` as a
|
|
key in your own catalogue produces `<you>/<yourplugin>:officer/core:test`, not the core code — the same
|
|
rule as `mountPrefix`, and pinned by test in `src/servers/notifications/catalogue.test.ts`.
|
|
|
|
An entry needs a `title`; `body`, `target`, `route` and `thread` are optional, `thread` defaults to your
|
|
namespace, and unknown keys are dropped rather than forwarded to the device. Broken YAML in one plugin's
|
|
catalogue is skipped without affecting anyone else's.
|
|
|
|
See `docs/push-notifications.md`.
|
|
|
|
### A plugin-contributed one, for reference
|
|
|
|
This is the gitea plugin's, and it shows what these are for: the agent cannot discover from the
|
|
filesystem that `tea` is authenticated, or that it should prefer `git` for the things git already does.
|
|
|
|
```markdown
|
|
---
|
|
name: Gitea
|
|
description: Use when working with git repositories, or with Gitea issues and pull requests.
|
|
version: 1
|
|
---
|
|
|
|
For anything git already does — clone, fetch, pull, push, branches, tags — use plain `git`. It talks
|
|
to the server directly.
|
|
|
|
For anything git does not — pull requests, issues, comments, releases, creating a repository — use
|
|
`tea`. It is already logged in as the current user, with that user's own permissions. Do not
|
|
configure it, and do not ask the user for a token.
|
|
```
|
|
|
|
### On the word
|
|
|
|
`capability` was taken — `CAPABILITIES` is the permission registry. `skill` was taken twice: by
|
|
`capabilities/skills/` here and by the wider AI ecosystem.
|
|
|
|
`affordance` is the exact term for what an environment offers an actor, and the precision earns the
|
|
slight awkwardness: rendering an image is not a skill the agent has, it is something the client on the
|
|
other end permits. Keeping that distinction in the name saves explaining it every time.
|