opencode-webui 2.0.0 → 2.1.0

package/server/index.ts

@@ -20,7 +20,7 @@
 
 import { Service } from "@opencode-ai/client/service";
 import type { Server } from "bun";
-import { existsSync, mkdirSync, readFileSync, statSync, watch } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, watch, appendFileSync } from "node:fs";
 import { appendFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
@@ -54,6 +54,7 @@ import {
   runExtRequestMiddleware,
   startExtModules,
 } from "./ext/registry";
+import { resolveEngineOverride } from "./ext/engine";
 
 // `sandbox` argv — one command, every runtime: `bun run sandbox` (repo, the
 // script adds Vite), `bunx opencode-webui sandbox`, `./opencode-webui sandbox`
@@ -116,6 +117,18 @@ async function writeDebug(lines: unknown[]) {
 let endpoint: Awaited<ReturnType<typeof Service.ensure>> | null = null;
 
 async function serviceEndpoint() {
+  // Explicit env wins: WEBUI_ENGINE_URL aims the proxy at a chosen engine.
+  // An override URL also SKIPS Service.ensure() — no spawn from a stale
+  // service.json pid (the rogue-serve incident), no version-kill of the
+  // chosen engine. Same resolution as ctx.engine (see server/ext/engine.ts).
+  const override = resolveEngineOverride();
+  if (override) {
+    if (!endpoint || endpoint.url !== override.url) {
+      endpoint = override;
+      console.log(`[webui] connected to opencode service at ${override.url} (WEBUI_ENGINE_URL)`);
+    }
+    return endpoint;
+  }
   if (!endpoint) {
     endpoint = await Service.ensure();
     console.log(`[webui] connected to opencode service at ${endpoint.url}`);
@@ -123,6 +136,40 @@ async function serviceEndpoint() {
   return endpoint;
 }
 
+// ---------------------------------------------------------------------------
+// Proxy crash-reason persistence (G-T8).
+//
+// One sandbox death left no cause. Fatal reasons are appended to CRASH_LOG
+// (never thrown from there — the crash path must not crash) and the last
+// entry is surfaced on the next boot, so an agent can see why the proxy died
+// without having watched it die. Semantics are unchanged: uncaught exceptions
+// still exit(1) (the Node default), rejections keep the runtime's behavior —
+// only observability is added.
+// ---------------------------------------------------------------------------
+
+const CRASH_LOG =
+  process.env.WEBUI_CRASH_LOG ??
+  join(process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"), "opencode-webui", "proxy-crash.log");
+
+function persistCrashReason(kind: "uncaughtException" | "unhandledRejection", reason: unknown): void {
+  const detail = reason instanceof Error ? (reason.stack ?? reason.message) : String(reason);
+  try {
+    mkdirSync(dirname(CRASH_LOG), { recursive: true, mode: 0o700 });
+    appendFileSync(CRASH_LOG, `${new Date().toISOString()} ${kind}: ${detail}\n`, "utf8");
+  } catch {
+    /* crash path — never throw */
+  }
+  console.error(`[webui] ${kind} (recorded in ${CRASH_LOG}):`, detail.split("\n")[0]);
+}
+
+process.on("uncaughtException", (err) => {
+  persistCrashReason("uncaughtException", err);
+  process.exit(1);
+});
+process.on("unhandledRejection", (reason) => {
+  persistCrashReason("unhandledRejection", reason);
+});
+
 // ---------------------------------------------------------------------------
 // Live-event recorder (catch-up for late-joining browsers).
 //
@@ -385,6 +432,12 @@ async function bundleUIEntry(entry: string): Promise<string> {
   const artifact =
     built.outputs.find((o) => o.kind === "entry-point" && o.path.endsWith(".js")) ??
     built.outputs.find((o) => o.path.endsWith(".js"));
+  for (const log of built.logs) {
+    // Build warnings/errors are the ONLY server-side signal for a broken
+    // extension — a failing bundle must never be silent (the page just sees
+    // a missing entry). Bun.build failures throw below; warnings print here.
+    console.warn(`[webui] extension bundle build (${entry}): ${log.message}`);
+  }
   if (!artifact) throw new Error(`bun.build produced no js artifact for ${entry}`);
   const js = await artifact.text();
   bundleCache.set(entry, { mtimeMs, js });
@@ -1009,3 +1062,19 @@ console.log(
 void startEventRecorder();
 startExtensionWatcher();
 void startExtModules();
+
+// Crash-log boot note: if a previous proxy died fatally, its reason is the
+// last line of CRASH_LOG — surface it so the next boot (or an agent reading
+// the log) sees why without having watched it die.
+try {
+  if (existsSync(CRASH_LOG)) {
+    const lines = readFileSync(CRASH_LOG, "utf8").trim().split("\n").filter((l) => l.length > 0);
+    // Entries are multi-line (stacks) — the "last" entry is the last line
+    // starting a new timestamped record, not the log's physical last line.
+    const heads = lines.filter((l) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(l));
+    const last = heads[heads.length - 1] ?? lines[lines.length - 1];
+    if (last) console.log(`[webui] previous proxy crash (${heads.length} entr(ies) in ${CRASH_LOG}) — last: ${last.slice(0, 300)}`);
+  }
+} catch {
+  /* observability only — never block boot */
+}

package/skills/webui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: webui
-description: opencode-webui — the browser frontend for the OpenCode engine. Load when the user mentions the webui/web frontend, asks about webui extensions, or wants to report a webui bug (/report does it).
+description: opencode-webui — the browser frontend for the OpenCode engine. Load when the user mentions the webui/web frontend, asks about webui extensions, wants to BUILD, ADD, CHANGE, DEBUG, or TEST a webui extension, or wants to report a webui bug (/report does it).
 ---
 
 # OpenCode webui (opencode-webui)
@@ -11,7 +11,7 @@ service credentials. One port for UI + `/api/*`: http://localhost:4097
 (`WEBUI_PROXY_PORT`).
 
 - **Repo**: https://github.com/AbdelftahZowail/opencode-webui
-- **This skill's version**: 2.0.0 (matches the `v2.0.0` git tag —
+- **This skill's version**: 2.1.0 (matches the `v2.1.0` git tag —
   the file links below are pinned to it, so they always describe the code
   this skill was generated with)
 - **A running instance exposes its version** at `GET /api/webui/config` →
@@ -24,13 +24,13 @@ fetch the exact file at the pinned tag instead of reading a local clone:
 
 | File | Purpose |
 | --- | --- |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.0.0/webui-extensions/README.md | Full authoring guide — the source of truth for strata/kinds/hooks/anchors |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.0.0/src/extensions/registry.tsx | The extension registry — exact register() shapes per kind |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.0.0/src/extensions/hooks.ts | Shared fireHooks runner — how open hook events fire |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.0.0/src/lib/domKit.ts | DOM-stratum kit (foreign/watch/styles) + the data-oc-* anchor table |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.0.0/server/ext/types.ts | Proxy-stratum types — server.ts routes/middleware/onEvent/pollers shapes |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.0.0/docs/extension-system-spec.md | The v2 decision record — strata, precedence, deletions, acceptance checks |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.0.0/src/store.ts | The store — actions useStore exposes to extensions |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/webui-extensions/README.md | Full authoring guide — the source of truth for strata/kinds/hooks/anchors |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/src/extensions/registry.tsx | The extension registry — exact register() shapes per kind |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/src/extensions/hooks.ts | Shared fireHooks runner — how open hook events fire |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/src/lib/domKit.ts | DOM-stratum kit (foreign/watch/styles) + the data-oc-* anchor table |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/server/ext/types.ts | Proxy-stratum types — server.ts routes/middleware/onEvent/pollers shapes |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/docs/extension-system-spec.md | The v2 decision record — strata, precedence, deletions, acceptance checks |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/src/store.ts | The store — actions useStore exposes to extensions |
 
 ## Environment
 
@@ -40,15 +40,19 @@ fetch the exact file at the pinned tag instead of reading a local clone:
 | `WEBUI_HOST` | `127.0.0.1` | Bind address — a wildcard is refused without a password. |
 | `WEBUI_PROXY_PORT` | `4097` | Port for the UI and `/api/*`. |
 | `WEBUI_EXTENSION_DIR` | the global + project dirs | Replace both with ONE directory (the sandbox does this to keep WIP isolated). |
+| `WEBUI_ENGINE_URL` | `service.json` discovery | Aim the proxy at a chosen engine — skips `Service.ensure()`, so a stale pid can never spawn a rogue serve. Explicit env wins. |
+| `WEBUI_ENGINE_PASSWORD` | `service.json` password | Engine password for the override above (no file fallback when the URL is overridden — a chosen engine has its own credential). |
+| `WEBUI_SANDBOX_NOVITE` | unset | `1` — sandbox boots the proxy only, no Vite (`--no-vite` flag does the same). |
+| `WEBUI_CRASH_LOG` | `$XDG_STATE_HOME/opencode-webui/proxy-crash.log` | File fatal proxy errors (`uncaughtException`/`unhandledRejection`) are appended to; the last entry prints on next boot. |
 | `WEBUI_DEBUG` | unset | `1` — server/proxy debug logs to stdout. |
 | `WEBUI_DEBUG_LOG` | `/tmp/webui-debug.log` | File the frontend log sink (`POST /api/debug`) appends to. |
 
 ### Parallel sandboxes (one per extension under test)
 
-One command, no flags: `bun run sandbox` detects a running sandbox and
-auto-isolates. Alone it uses the fixed defaults (`:4099`/`:5175` + shared
-scratch dir); when another sandbox already holds those ports, the new
-instance takes free ports + a fresh mkdtemp extension dir and prints what
+Yes — run as many sandboxes at once as you need. `bun run sandbox` stacks
+with no flags: the first instance takes the fixed defaults (`:4099`/`:5175`
++ shared scratch dir); every further instance detects the busy ports and
+auto-isolates onto free ports + a fresh mkdtemp extension dir, printing what
 it picked. Explicit env (`WEBUI_PROXY_PORT` / `WEBUI_VITE_PORT` /
 `WEBUI_EXTENSION_DIR`) always wins per knob. The engine stays shared
 (same sessions everywhere, by design) — only ports + extension dirs are

package/webui-extensions/README.md

@@ -22,6 +22,11 @@ my-extension/
 **Gating — one state, owned by the folder itself:** presence = installed;
 `disabled: true` = paused; delete/move the folder to uninstall. No
 `config.ts` list, no per-browser localStorage gating, no second registry.
+User-facing pause (a settings toggle that stops *behavior*, e.g. an
+extension that idles when its key/feature flag is off) is not manifest
+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".
 
 **Precedence (same id = same swap point, higher wins):**
 
@@ -75,13 +80,56 @@ addressable, no marker placement, no guessing), at leaf granularity (the
 timestamp, token readout, cost badge, copy button — not just `MessageItem`),
 with rich props, so wraps and value-overrides stay surgical.
 
+### Target inventory (the catalog — grep `autoRegister` if this lags)
+
+| Target id | Props (meaningful subset) |
+|---|---|
+| `sidebar` | — (the shell) |
+| `sidebar.sessionRow` | `sessionID`, `title`, `updated`, `active`, `selected`, `subagentsActive`, `onSelect` |
+| `conversation` | full `ConversationProps` |
+| `conversation.header` | full `HeaderProps` |
+| `conversation.empty` | — |
+| `composer` | full `ComposerProps` |
+| `composer.contextReadout` | `parts: string[]` |
+| `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` |
+| `message.cost` | `cost: number` |
+| `message.copyButton` | `variant: "user" \| "assistant"`, `text` |
+| `message:<type>` / `message:*` | replace-with-fall-through per message type |
+| `tool.card` | `part: ToolPart`, `stateKey?` |
+| `tool.edit` / `write` / `shell` / `subagent` / `execute` / `generic` | per-tool view props |
+| `tool:<name>` | replace-with-fall-through per tool name |
+
+Persisted-vs-live guarantee (streaming authors depend on this): persisted
+messages always carry a `[data-oc-message]` ancestor; live projections
+(`LiveAssistantView`) render `MessagePart` directly with none. Code that
+must never touch streaming output can rely on the distinction structurally.
+
+### Entry hygiene (two rules that bite silently)
+
+- **One entry per id.** Same-id `register()` SWAPS (with a console warning
+  when kind/target differ) — a folder's entries need distinct ids or the
+  later evicts the earlier, and loaders track folders by single id so extras
+  leak on disable/delete. One folder → one id per entry, always.
+- **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
+  surface via `getExtensionApi()`.
+- **The `@/` alias works in shipped extensions only.** Same repo, same
+  tsconfig (`@/*` → `./src/*`, e.g. groq-voice imports
+  `@/components/ui/dialog`) — external copies must still use the bridge,
+  never `@/` or relative `src/` paths.
+
 ```tsx
 // index.tsx — wrap the timestamp, own nothing else
 import { register } from "../../src/extensions/registry";
 
 register({
   kind: "wrap",
-  id: "my-timestamps",
+  id: "my-timestamps-wrap",
   target: "Timestamp",
   render: (props, next) => (
     <span title={String(props.iso ?? "")}>{next()}</span>
@@ -90,7 +138,7 @@ register({
 
 register({
   kind: "service",
-  id: "my-timestamps",
+  id: "my-timestamps-format",
   service: "format.timestamp",
   value: (iso: string) => new Date(iso).toLocaleTimeString(),
   precedence: 10,
@@ -266,8 +314,62 @@ An extension folder may carry `engine/` — a valid opencode plugin directory
 (tools the model calls, `experimental.chat.system.transform` prompt hints).
 The webui neither loads nor hot-reloads it; the engine's rules apply
 (boot-time load, restart on edit unless the plugin implements its own shell
-pattern). Convention + worked example (brother-agent in webui terms — one
-folder, three strata): `docs/engine-payload-convention.md`.
+pattern — a stable `index.js` that require-cache-busts a `definitions.cjs`
+on mtime works and is the recommended shape). Convention + worked example
+(brother-agent in webui terms — one folder, three strata):
+`docs/engine-payload-convention.md`. Hard-won facts, stated once so no one
+re-discovers them by trial:
+
+- **Export shape:** `module.exports = { id, setup }` (v2 — the v1 `{server}`
+  / named-export shape is rejected: "must export a default definition with
+  an id and an effect or setup function").
+- **Tool namespace:** the model lists tools as `tools.<name>` — register and
+  match on the `tools.`-prefixed name, never bare.
+- **Tool results must resolve `{ output: string }`.** A bare string fails
+  result validation (`Unknown tool` in the transcript).
+- **System-hint parts need `{ type: "text", text }`.** Pushing `{text}`
+  without `type` fails the whole session drain (schema `MissingKey`).
+- **Session origin tagging** (`metadata: { origin: "…" }`) survives only via
+  REST `POST /api/session` create — the setup-bridge create drops it.
+- **Discovery + auth:** the engine registers at
+  `$XDG_STATE_HOME/opencode/service.json` (Basic `opencode:password` —
+  mirror `@opencode-ai/client`'s service helper); provider credentials live
+  under `XDG_DATA_HOME`, so a `STATE`-only sandbox sees the engine but no
+  models. When agent testing misbehaves, verify the provider first with
+  `POST /session/{id}/generate {"prompt":"OK"}`; when runs fail blank,
+  the cause is in `$XDG_DATA_HOME/opencode/log/opencode.log` (`grep drain`).
+- `server.ts` code that must call the engine has no credential helper yet —
+  parse `service.json` by hand (node builtins only, no core imports); a
+  `ctx.engine` helper is the planned fix (`server/ext/types.ts`).
+
+## Loading lifecycle (where an extension travels)
+
+One folder becomes pixels through four files — follow them in order:
+
+1. **Glob (shipped, repo dev).** `webui-extensions/index.ts` globs
+   `./*/index.{ts,tsx}` and tracks each module's `export const id` (Vite
+   HMR path — edits hot-swap via same-id registry swap, deletions prune
+   owned ids only).
+2. **Discovery (proxy).** `server/userExtensions.ts`
+   (`discoverUserUIEntries`) scans the three sources highest-precedence
+   first — user root, project root, shipped dir — taking the folder id
+   from `manifest.json` (`id`, falling back to the dir name) and the
+   entries from `index.tsx`/`dom.ts`. Same id at a lower source is
+   skipped with a once-per-process `shadowed` warning.
+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 }`
+   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
+   owns them — importing twice would run side effects twice) but shipped
+   `domUrl` still mounts and `disabled` still pauses them.
 
 ## What extensions can use (browser stratum)
 
@@ -337,18 +439,22 @@ register({
 isolated second instance — loopback-only `127.0.0.1:4099`, passwordless (the
 bind address is the guarantee), same engine/sessions, extensions from an
 isolated scratch dir (`WEBUI_EXTENSION_DIR`,
-default `~/.local/state/opencode-webui/sandbox-extensions/`). Iterate there;
-"shipping" = copying the folder into the real extension dir.
+default `~/.local/state/opencode-webui/sandbox-extensions/`).
+`WEBUI_EXTENSION_DIR` is a higher-precedence ADD, not a replace: it swaps
+out the user + project roots only — shipped extensions still load
+underneath, and a same-id scratch folder shadows the shipped copy (the
+`shadowed` log line is the only signal). Iterate there; "shipping" =
+copying the folder into the real extension dir.
 
 ### Parallel sandboxes (agents: read this)
 
-One command, no flags: `bun run sandbox` detects a running sandbox and
-auto-isolates. Alone it uses the fixed defaults (`:4099`/`:5175` + shared
-scratch dir); when another sandbox already holds those ports, the new
-instance takes free ports + a fresh mkdtemp extension dir and prints what
-it picked. Explicit env (`WEBUI_PROXY_PORT` / `WEBUI_VITE_PORT` /
-`WEBUI_EXTENSION_DIR`) always wins per knob and disables that knob's auto
-behavior.
+Yes — run as many sandboxes at once as you need, one per extension under
+test. `bun run sandbox` stacks with no flags: the first instance takes the
+fixed defaults (`:4099`/`:5175` + shared scratch dir); every further
+instance detects the busy ports and auto-isolates onto free ports + a fresh
+mkdtemp extension dir, printing exactly what it picked. Explicit env
+(`WEBUI_PROXY_PORT` / `WEBUI_VITE_PORT` / `WEBUI_EXTENSION_DIR`) always wins
+per knob and disables that knob's auto behavior.
 
 Rules: one sandbox per extension, never two writers to one ext dir, never
 reuse a port. The engine stays shared (same sessions everywhere, by