opencode-webui 2.4.0 → 3.0.1

package/webui-extensions/README.md

@@ -6,8 +6,8 @@ that matches the job (framing rule below), never two for the same job.
 
 ```
 my-extension/
-  manifest.json    id, name, version, description, disabled (optional bool)
-  index.tsx        browser stratum: register() against the registry
+  manifest.json    id, name, version, description; optional disabled, settings, requires, capabilities
+  index.tsx        browser stratum: register() and/or activate(ctx)
   dom.ts           DOM stratum: post-render DOM changes (the free layer)
   server.ts        proxy stratum: routes / middleware / event tap / pollers
   engine/          optional opencode plugin payload (tools, system-prompt hints)
@@ -16,7 +16,16 @@ my-extension/
 ```jsonc
 // manifest.json
 { "id": "my-extension", "name": "My extension", "version": "1.0.0",
-  "description": "What it does" /* "disabled": true — paused */ }
+  "description": "What it does" /* "disabled": true — paused */,
+  // Declared settings (roadmap 5): core renders these in Settings › Extensions.
+  "settings": [
+    { "key": "enabled", "type": "boolean", "title": "Enabled", "default": true },
+    { "key": "threshold", "type": "number", "title": "Threshold", "default": 5, "min": 1, "max": 20 },
+    { "key": "mode", "type": "enum", "title": "Mode", "options": ["fast", "thorough"], "default": "fast" }
+  ],
+  // Checkable references (roadmap 8): an unmet one is a visible warning.
+  "requires": { "api": 1, "targets": ["message.timestamp"], "slots": ["composer.above"] },
+  "capabilities": ["notify"] }
 ```
 
 **Gating — one state, owned by the folder itself:** presence = installed;
@@ -28,6 +37,16 @@ pausing: the former keeps the entry loaded but quiet, the latter
 (`disabled: true`) is never bundled or imported and its id unregisters —
 use a settings toggle for "off for now", the manifest for "unplug".
 
+**Settings › Extensions** renders one card per installed extension (its
+`name`/`description` from `manifest.json`) with an on/off switch, plus any
+`settings` collection the extension contributes, inline in that card. The
+switch is just a UI for the folder flag above: it calls
+`POST /api/webui/extensions/<id>/state { disabled }`, which edits the winning
+folder's `manifest.json`. A **shipped** id is never edited in place (an app
+update would clobber the flag) — disabling it writes a user-level shadow
+folder with the same id, removed again on re-enable (shipped browser bundles
+are glob-owned, so re-enabling reloads the page to re-register them).
+
 **Precedence (same id = same swap point, higher wins):**
 
 1. `~/.config/opencode/webui-extensions/<name>/` — user
@@ -43,7 +62,11 @@ extension code is not sandboxed (same model as host plugins).
 > browser loader + manifest SSE, proxy-stratum mounts, `dom.ts` loader wiring
 > + `data-oc-*` stamping, core self-registration, and the `ui-extensions/` →
 > `webui-extensions/` rename are landed (`docs/extension-system-spec.md` §11).
-> The contract below is what that work converged on — write to it.
+> The **roadmap seams are landed too** (`docs/extension-roadmap.md` items 1–9,
+> `EXT_API_VERSION` 2): prop-transforming wraps, the activation context +
+> disposal, scheduler access, the event bus, the curated store facade,
+> declared settings, thin slots, manifest `requires` diagnostics, and peer
+> composition. The contract below is what that work converged on — write to it.
 
 ## Choosing a stratum (framing rule)
 
@@ -65,7 +88,7 @@ semantics are the whole point: `wrap` = default, `replace` = ownership.
 
 | Kind | Job | Staleness |
 | --- | --- | --- |
-| `wrap` | Flow-through tweak of any registered target: `render(props, next)` — transform props/output, delegate to live core by default | **Stale-proof by construction.** Core updates always render *through* it. The default path for edits. |
+| `wrap` | Flow-through tweak of any registered target: `render(props, next)` — transform output, and/or call `next(overrides)` to merge changed/extra props into the rest of the chain, delegating to live core by default | **Stale-proof by construction.** Core updates always render *through* it. The default path for edits. |
 | `replace` | Take ownership of one registered target: `render(props, core)` wins outright at its priority; return `null` to fall through to the next candidate / core | **Frozen snapshot.** You opt out of core updates for that target — the marked escape hatch. Still receives `core` so you *can* compose. |
 | `contribute` | Add an item to a named collection (`collection` + `item`, `order` sorts, lower first) | Data, not code — core owns the list, you own your row. |
 | `hook` | Interception at instrumented boundaries: `{ event, handler(ctx, next) }` — `event` is an open string | New seams are new event names, never a registry change. |
@@ -90,7 +113,7 @@ with rich props, so wraps and value-overrides stay surgical.
 | `conversation.header` | full `HeaderProps` |
 | `conversation.empty` | — |
 | `composer` | full `ComposerProps` |
-| `composer.contextReadout` | `parts: string[]` |
+| `composer.contextReadout` | `parts: string[]`, `sessionID` |
 | `composer.sendActions` | `sessionID`, `appendDraft(text)` — space-joins onto the draft + refocuses; prefer over writing drafts directly |
 | `message.timestamp` | `time: number` (consults the `format.timestamp` service) |
 | `message.tokens` | `tokens` |
@@ -115,14 +138,176 @@ must never touch streaming output can rely on the distinction structurally.
 - **Runtime code uses the bridge only.** External (user/project-dir) bundles
   are built standalone: `import type` from `src/` is erased at build and
   safe, but any *runtime* `src/` import breaks the copy outside the repo.
-  Use `window.__opencodeUI` (`register`, `react`, `api`, `store`, `prefs`,
-  `notify`, `services`, `dom`, `kv`) — shipped code consumes the identical
+  Use `window.__opencodeUI` (`register`, `react`, `api`, `store` [the curated
+  facade], `events`, `settings`, `collections`, `bus`, `prefs`, `notify`,
+  `services`, `dom`, `kv`; raw modules as `advanced.*`) — shipped code consumes the identical
   surface via `getExtensionApi()`.
 - **The `@/` alias works in shipped extensions only.** Same repo, same
   tsconfig (`@/*` → `./src/*`, e.g. a shipped extension imports
   `@/components/ui/dialog`) — external copies must still use the bridge,
   never `@/` or relative `src/` paths.
 
+### Activation (lifecycle) — the shape to write
+
+`index.tsx` may export an activation entry instead of registering at module
+scope:
+
+```tsx
+export const id = "my-extension";
+
+export function activate(ctx) {
+  ctx.register({ kind: "wrap", id: "my-wrap", target: "message.timestamp", render: … });
+  const stop = someObserver(); // timer, listener, subscription…
+  ctx.onDispose(stop);          // or: return stop
+}
+```
+
+- `ctx.register(entry)` — the same five kinds; the id is remembered so
+  teardown prunes exactly this extension's entries.
+- `ctx.poll({ name, minInterval, intervals?, whenHidden?, run })` — recurring
+  work on the shared scheduler (tier-aware, jittered; the app's only timer
+  owner). Returns an idempotent stop; stopped automatically on dispose.
+- `ctx.after(ms, fn)` — one-shot delay; returns an idempotent cancel; cleared
+  automatically on dispose.
+- `ctx.on(name, handler)` — subscribe to the event bus (raw engine type or
+  derived lifecycle name; `"*"` = all). Returns an unsubscribe; removed
+  automatically on dispose. See **Events (observe)** below.
+- `ctx.subscribe(selector, listener)` — derived store read: fires immediately,
+  then only when the selected value changes (shallow-equal). Auto-removed on
+  dispose. See **Store (read + act)** below.
+- `ctx.store` — the curated store facade (selectors + actions); the same
+  object as the bridge's `store`.
+- `ctx.settings` — resolved declared settings (`get`/`set`/`reset`/`subscribe`);
+  subscriptions disposed with the extension. See **Declared settings +
+  requirements**. No manifest schema → empty handle (use `kv` for ad-hoc data).
+- `ctx.collections` — read other extensions' contributions (`get(collection)`)
+  and every live collection id (`list()`). See **Peer composition**.
+- `ctx.bus` — extension-to-extension events: `publish(channel, payload)`
+  (tagged with this id) and `subscribe(channel, fn)` (disposed with the
+  extension). See **Peer composition**.
+- `ctx.onDispose(fn)` / returning a teardown fn — runs on hot-swap,
+  `disabled: true`, and delete (LIFO, crash-isolated). This is the one place
+  non-React cleanup belongs — no `window.__*Installed` guards.
+- `ctx.log(...)` — prefixed with the extension id.
+- `ctx.services.getService` / `getServiceProviders` — named-logic lookups.
+
+Module-scope `register({…})` still works (the loaders fall back to the
+registry id-delta), but it is the shape being deprecated: nothing outside the
+module can dispose what the module did, so `disabled`/delete/hot-swap can't
+tear down listeners or timers it started. New extensions write `activate`.
+The DOM stratum already has this contract (`mount` returns a cleanup fn).
+
+### Events (observe)
+
+`ctx.on(name, handler)` (or the bridge's `events.subscribe`) observes what
+happened without diffing store snapshots. Two families share one channel:
+
+- **Raw engine events** — every event the store reduces, under its engine
+  `type` (`session.tool.success`, `session.text.delta`, `permission.asked`,
+  `session.idle`, …). Payload is the event's `data`.
+- **Derived lifecycle events** — core computes these so you don't infer them:
+  `run.started` `{sessionID}` · `run.ended` `{sessionID,reason}` ·
+  `tool.called` `{sessionID,assistantMessageID,id,name,input?}` ·
+  `tool.completed` `{sessionID,assistantMessageID,id,name?,ok}` ·
+  `message.appended` `{sessionID,messageID,type}`.
+
+```tsx
+ctx.on("tool.completed", (e) => {
+  const { name, ok } = e.payload;
+  usage[name] = (usage[name] ?? 0) + (ok ? 1 : 0);
+});
+ctx.on("run.ended", () => notify({ title: "Run finished" }));
+```
+
+Delivery is frame-batched (16ms) so a token burst is one dispatch per frame.
+`"*"` receives everything (diagnostics/analytics — it is per-event, so filter).
+Listeners are crash-isolated; the subscription is disposed with the
+extension. The bus is notification-only: it never mutates state and
+extensions cannot publish.
+
+### Store (read + act)
+
+`ctx.store` (bridge: `store`) is the curated, **supported** store surface —
+selectors and actions, never the raw module (which stays reachable, and
+explicitly unsupported, as `advanced.store`):
+
+- **observe:** `subscribe(listener)`, `select(selector, listener)`,
+  `useStore(selector)` (React), `getState()` (full snapshot)
+- **read:** `currentSessionID()`, `sessions()`, `sessionDetail(id)`,
+  `messages(id)`, `liveAssistants(id)`, `isRunning(id)`, `isQueued(id)`,
+  `pendingRequests()`, `isDraftSession(id)`, `sessionHref(id)`
+- **act:** `sendPrompt`, `sendPromptTo(id, text, {delivery?})`,
+  `selectSession`, `navigateFocused`, `newSession`, `materializeDraft`,
+  `replyPermission`, `replyForm`, `replyQuestion`, `rejectQuestion`,
+  `interrupt`, `switchAgent`, `switchModel`, `renameSession`,
+  `compactSession`, `undoSession`, `redoSession`, `activateSkill`
+
+```tsx
+// ctx.subscribe auto-disposes; ctx.store.select is the manual form.
+ctx.subscribe((s) => s.currentSessionID, (id) => badge.textContent = id ?? "");
+```
+
+Core keeps adding internal state/actions — those do **not** become API. A new
+extension need means a deliberate addition to the facade (version bump), not
+reaching into `advanced.store`.
+
+### Declared settings + requirements (manifest)
+
+Two optional `manifest.json` blocks turn a fragile extension into a checkable
+one.
+
+**`settings`** — declare options once; core renders them in the extension's
+Settings card and persists per id (defaults applied, invalid/legacy values
+dropped). The extension just reads resolved values via `ctx.settings` (or the
+bridge's `settings.forExt(id)`):
+
+```tsx
+export function activate(ctx) {
+  const apply = () => (opts = ctx.settings.get());
+  apply();
+  ctx.settings.subscribe(apply); // auto-disposed
+}
+```
+
+Schema subset per field: `{ key, type, title, description?, default? }` where
+`type` is `boolean | number (min/max/step) | string (placeholder) | enum
+(options: string[])`. That covers the common toggle/threshold/format option
+with no bespoke settings component or storage.
+
+**`requires`** — declare the references you depend on
+(`api` version, `targets`, `slots`, `services`). Core checks them every
+manifest sync; an unmet one becomes a visible warning in your Settings card
+(`⚠ unmet target "…"`) plus a console warning, instead of a silently blank
+spot. `capabilities` is free-form declared metadata.
+
+Static shape problems (bad `settings`/`requires`) are reported the same way —
+never swallowed.
+
+### Peer composition
+
+Extensions cooperate through two read-only surfaces — neither imports the
+other:
+
+- **Collections** — read what any extension contributed:
+  `ctx.collections.get("palette")` (or the bridge's `collections.get`), plus
+  `ctx.collections.list()` for every live collection id. Contributing is the
+  existing `contribute` kind; consuming another's items is just reading.
+- **The peer bus** — extension-to-extension events:
+  `ctx.bus.subscribe(channel, fn)` and `ctx.bus.publish(channel, payload)`
+  (the event carries `from: <publisher id>`). Channels are free-form strings;
+  delivery is synchronous and low-frequency (coordination, not streams).
+  Subscriptions are disposed with the extension.
+
+```tsx
+// provider
+ctx.register({ kind: "contribute", id: "my-metric", collection: "metrics", item: { label: "TPS" } });
+// consumer — same-page, no import
+ctx.bus.subscribe("metrics.changed", ({ from }) => refresh(ctx.collections.get("metrics")));
+ctx.bus.publish("metrics.changed", {});
+```
+
+`service` still covers one-to-one provide/consume; this covers many-to-many.
+
 ```tsx
 // index.tsx — wrap the timestamp, own nothing else
 import { register } from "../../src/extensions/registry";
@@ -145,6 +330,20 @@ register({
 });
 ```
 
+```tsx
+// index.tsx — a wrap that FEEDS the target changed props, not just output.
+// `next(overrides)` shallow-merges overrides into every remaining wrap and
+// the leaf (core default / winning replace). With no argument, behavior is
+// exactly as before. Overrides never change the wrap's own `props`.
+register({
+  kind: "wrap",
+  id: "my-append-action",
+  target: "composer.sendActions",
+  render: (props, next) =>
+    next({ extraActions: [...(props.extraActions as unknown[]), <MyButton />] }),
+});
+```
+
 ```tsx
 // index.tsx — replace with fall-through: own one case, defer the rest
 register({
@@ -167,7 +366,8 @@ UI-only, local `run(args, { sessionID })`; engine commands come from
 (item `{ title, description?, render }`, routed at `/ext/{id}`),
 `settings` (item `{ title, description?, render }`, section in
 Settings › Extensions), `contextMenu.message`, `contextMenu.session`,
-`contextMenu.file` (item `{ label, run, order? }`).
+`contextMenu.file` (item `{ label, run, order? }`), and the `slot:<id>`
+placement collections (see Slots below).
 
 ```tsx
 register({
@@ -178,6 +378,30 @@ register({
 });
 ```
 
+### Slots (placement)
+
+A **slot** is a named insertion point in core chrome — placement, not
+identity. Targets render a unit's component chain (something with an id you
+tweak); slots render whatever anyone contributed to a place. Same `contribute`
+kind, collection `slot:<slotID>`:
+
+```tsx
+register({
+  kind: "contribute",
+  id: "my-compose-badge",
+  collection: "slot:composer.above",
+  item: { render: ({ sessionID }) => <span>draft for {sessionID}</span> },
+});
+```
+
+Known slot ids (the versioned registry, `src/extensions/slots.tsx`):
+`conversation.header.actions`, `conversation.empty`, `composer.above`,
+`composer.actions`, `sidebar.header.actions`. Contributing to an unknown
+`slot:<id>` renders nowhere — declare it in `requires.slots` to get a warning
+instead. Items sort by `order` (lower first); each is crash-isolated; the
+stamp site carries `data-oc-slot="<id>"` for the DOM stratum. Renaming/moving
+a slot id is a contract bump + migration note.
+
 ### Hook catalog
 
 Open event strings — fired from the api client wrapper (every endpoint),
@@ -246,6 +470,7 @@ extensions break silently on every redesign.
 | `data-oc-queue-strip` | QueueStrip (steer/queue rows) |
 | `data-oc-subagent-strip` | SubagentStrip |
 | `data-oc-runs-panel` | RunsPanel |
+| `data-oc-slot` | Slot wrapper (`slot:<id>` — one per known slot id) |
 
 ```ts
 // dom.ts — badge next to the send button, cleaned up on hot-swap
@@ -358,24 +583,36 @@ One folder becomes pixels through four files — follow them in order:
 3. **Manifest + SSE + bundling (proxy).** `server/index.ts` merges folder
    entries with engine-plugin UI halves, serves
    `GET /api/webui/extensions` (`{ id, url?v=mtime, domUrl?v=mtime,
-   source, origin }`), pushes a `{ type: "webui.extensions", version }`
+   source, origin, name?, description?, disabled?, settings?, requires?,
+   capabilities? }`), pushes a `{ type: "webui.extensions", version }`
    event per manifest change on `GET /api/webui/extensions/events`, and
    bundles each entry standalone with `Bun.build` (`bundleUIEntry` —
    react external, build logs printed loudly, never silent).
 4. **Import + register (page).** `src/lib/runtimeExtensions.ts` fetches
    the manifest, dynamic-imports each new `?v=` bundle (re-import on
-   mtime move → registry same-id-swap → live repaint), mounts `domUrl`
-   via the DOM kit, and unregisters ids that vanish or flip
-   `disabled: true`. Shipped browser bundles are skipped here (the glob
+   mtime move → dispose the old instance → registry same-id-swap → live
+   repaint), runs the module's `activate(ctx)` entry when present, mounts
+   `domUrl` via the DOM kit, and disposes + unregisters ids that vanish or
+   flip `disabled: true`. Shipped browser bundles are skipped here (the glob
    owns them — importing twice would run side effects twice) but shipped
-   `domUrl` still mounts and `disabled` still pauses them.
+   `domUrl` still mounts and `disabled` still pauses them. Each sync also
+   parses the declared contract: the settings schema is registered for
+   `ctx.settings`, and unmet `requires` / malformed shapes become visible
+   diagnostics (see **Declared settings + requirements**).
 
 ## What extensions can use (browser stratum)
 
 Everything the app can — shipped extensions are the same build:
 
-- `useStore` / store actions from `src/store.ts`
+- the curated store facade (`store` / `ctx.store`), or `useStore` directly in
+  shipped components
+- declared settings (`ctx.settings` / `settings.forExt(id)`) — core renders and
+  persists the manifest schema
+- other extensions' contributions and the peer bus
+  (`ctx.collections` / `ctx.bus`)
 - `api` from `src/api/client.ts` (every endpoint fires `api.pre/post/error`)
+- the event bus (`ctx.on` / `events.subscribe`) — raw engine events + derived
+  lifecycle events, frame-batched
 - `getService` / services from `src/extensions/registry.tsx`
 - UI primitives from `src/components/ui/` (shadcn) — always build on these
   so extensions look native
@@ -383,8 +620,9 @@ Everything the app can — shipped extensions are the same build:
 - Toaster via the extension API surface (`notify`)
 
 External (user/project-dir) extensions use the one extension API surface
-(`register`, `react`, `api`, `store`, `prefs`, `notify`, `services`, `dom`
-kit, `kv`) — used identically by our shipped ones.
+(`register`, `react`, `api`, `store` facade, `events`, `settings`,
+`collections`, `bus`, `prefs`, `notify`, `services`, `dom` kit, `kv`,
+`advanced.*` raw modules) — used identically by our shipped ones.
 
 ## Hot reload guarantees