opencode-webui 2.0.0 → 2.2.0

package/dist/assets/{report-9wOQi_Kx.js → report-B9LU5-59.js}

@@ -1,2 +1,2 @@
-import{n as e,t}from"./index-BHminhzR.js";var n=`report`,r=t(),{notify:i}=r,a=`AbdelftahZowail/opencode-webui`,o=10,s=window;function c(e){let t=s.__reportErrors??=[];t.push(e),t.length>o&&t.splice(0,t.length-o)}s.__reportErrorsInstalled||(s.__reportErrorsInstalled=!0,window.onerror=(e,t,n,r,i)=>{c({message:String(e).slice(0,500),source:t??``,line:n??0,stack:i instanceof Error?i.stack?.slice(0,500):void 0})},window.addEventListener(`unhandledrejection`,e=>{let t=e.reason;c({message:(t instanceof Error?t.message:String(t)).slice(0,500),source:`unhandledrejection`,line:0,stack:t instanceof Error?t.stack?.slice(0,500):void 0})}));async function l(e){try{let t=await fetch(e);return t.ok?await t.json():null}catch{return null}}async function u(t){let[n,r]=await Promise.all([l(`/api/webui/config`),l(`/api/webui/extensions`)]);return{url:location.href,userAgent:navigator.userAgent,language:navigator.language,viewport:`${window.innerWidth}x${window.innerHeight}`,version:n?.version??`unknown`,reportRepo:n?.reportRepo??a,builtins:e(),runtimeExtensions:(r?.data??[]).map(e=>e.id??``).filter(Boolean),errors:s.__reportErrors??[],sessionID:t,timestamp:new Date().toISOString()}}function d(e,t){let n=`WebUI bug: ${e?e.slice(0,80):`user report`}`,r=[`### What happened`,e||``,``,`### Steps to reproduce`,`1. `,``,`### Expected`,``,`### Actual`,``,`<details><summary>Diagnostics</summary>`,``,"```json",JSON.stringify(t,null,2),"```",`</details>`].join(`
+import{n as e,t}from"./index-DDE-utaG.js";var n=`report`,r=t(),{notify:i}=r,a=`AbdelftahZowail/opencode-webui`,o=10,s=window;function c(e){let t=s.__reportErrors??=[];t.push(e),t.length>o&&t.splice(0,t.length-o)}s.__reportErrorsInstalled||(s.__reportErrorsInstalled=!0,window.onerror=(e,t,n,r,i)=>{c({message:String(e).slice(0,500),source:t??``,line:n??0,stack:i instanceof Error?i.stack?.slice(0,500):void 0})},window.addEventListener(`unhandledrejection`,e=>{let t=e.reason;c({message:(t instanceof Error?t.message:String(t)).slice(0,500),source:`unhandledrejection`,line:0,stack:t instanceof Error?t.stack?.slice(0,500):void 0})}));async function l(e){try{let t=await fetch(e);return t.ok?await t.json():null}catch{return null}}async function u(t){let[n,r]=await Promise.all([l(`/api/webui/config`),l(`/api/webui/extensions`)]);return{url:location.href,userAgent:navigator.userAgent,language:navigator.language,viewport:`${window.innerWidth}x${window.innerHeight}`,version:n?.version??`unknown`,reportRepo:n?.reportRepo??a,builtins:e(),runtimeExtensions:(r?.data??[]).map(e=>e.id??``).filter(Boolean),errors:s.__reportErrors??[],sessionID:t,timestamp:new Date().toISOString()}}function d(e,t){let n=`WebUI bug: ${e?e.slice(0,80):`user report`}`,r=[`### What happened`,e||``,``,`### Steps to reproduce`,`1. `,``,`### Expected`,``,`### Actual`,``,`<details><summary>Diagnostics</summary>`,``,"```json",JSON.stringify(t,null,2),"```",`</details>`].join(`
 `);return{title:n,body:r,url:`https://github.com/${t.reportRepo}/issues/new?title=${encodeURIComponent(n)}&body=${encodeURIComponent(r)}`}}async function f(e){try{return await navigator.clipboard.writeText(e),!0}catch{return!1}}async function p(e,t){let n=e.trim(),a=n.startsWith(`--agent`),o=a?n.replace(/^--agent\b/,``).trim():n,s=await u(t.sessionID??r.store.getState().currentSessionID??null),{title:c,body:l,url:p}=d(o,s);if(a){let e=`File a bug against ${s.reportRepo} using the gh CLI: create an issue with the title and body below, then reply with the issue URL. Do not include any private session content beyond the diagnostics JSON.\n\nTitle: ${c}\n\n${l}`,n=t.sessionID??r.store.getState().currentSessionID??null;if(n&&r.store.isDraftSession(n))try{n=await r.store.materializeDraft(``)}catch{n=null}if(!n){let t=await f(e);i({title:t?`No active session — report prompt copied`:`No active session`,description:t?`Paste it into a session to have the agent file the issue.`:`Could not copy the report prompt either.`,variant:t?`default`:`destructive`});return}i({title:`Report handed to the agent`,description:`It will file the issue and reply with the URL.`}),await r.store.sendPromptTo(n,e);return}if(window.open(p,`_blank`))i({title:`Opening GitHub issue…`});else{let e=await f(p);i({title:e?`Report ready — link copied`:`Report link`,description:e?`Popup blocked; paste the link in a browser.`:`Popup blocked and the clipboard is unavailable.`,variant:e?`default`:`destructive`})}}r.register({kind:`contribute`,id:`report`,collection:`slash`,item:{name:`report`,aliases:[`bug`],description:`Report a webui bug on GitHub — diag bundle prefilled`,run:p}});export{n as id};

package/dist/index.html

@@ -19,7 +19,7 @@
         }
       }
     </script>
-    <script type="module" crossorigin src="/assets/index-BHminhzR.js"></script>
+    <script type="module" crossorigin src="/assets/index-DDE-utaG.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-d4KcyqrZ.css">
   </head>
   <body>

package/package.json

@@ -3,7 +3,7 @@
   "description": "Web UI for the OpenCode coding agent — chat, streaming, tool cards, and extensions over the OpenCode engine's HTTP API.",
   "private": false,
   "type": "module",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -37,6 +37,7 @@
     "start": "NODE_ENV=production bun run server/index.ts",
     "typecheck": "tsc --noEmit",
     "gen:skill": "bun run scripts/gen-skill.ts",
+    "check:ext": "bun run scripts/check-ext.ts",
     "check:swap": "bun run scripts/uitest/swap-ready.ts",
     "prepublishOnly": "bun run typecheck && bun run gen:skill && bun run build"
   },

package/server/ext/engine.ts

@@ -0,0 +1,161 @@
+/**
+ * Engine credential helper (proxy stratum).
+ *
+ * `server.ts` authors hand-parsed `service.json` to call the engine (third
+ * occurrence → kit by the IN-4 rule). Use `ctx.engine` instead — no core
+ * import needed on the extension side; the context shape is structural:
+ *
+ * ```ts
+ * // my-extension/server.ts — no imports needed
+ * export default {
+ *   pollers: [
+ *     {
+ *       id: "watch",
+ *       intervalMs: 30_000,
+ *       run: async (ctx) => {
+ *         const res = await ctx.engine.fetch("/api/session/active");
+ *         if (!res.ok) return; // engine momentarily unreachable — retry next tick
+ *         const { data } = (await res.json()) as { data?: unknown };
+ *         await ctx.kv.set("lastSeen", Date.now());
+ *       },
+ *     },
+ *   ],
+ * };
+ * ```
+ *
+ * Discovery mirrors `Service.ensure()`'s registration file
+ * (`$XDG_STATE_HOME/opencode/service.json`, default
+ * `~/.local/state/opencode/service.json`, `{ url, password }`), with
+ * explicit env winning per knob:
+ *
+ * - URL: `WEBUI_ENGINE_URL` wins, else the file's `url`. Trailing slashes
+ *   are stripped. `null` when neither exists (engine never ran here).
+ * - Password: `WEBUI_ENGINE_PASSWORD` wins. With an explicit URL override
+ *   the file password is deliberately NOT reused — a chosen engine has its
+ *   own credential, and falling back to the default state file's password
+ *   would send the wrong secret (the stale-pid rogue-serve incident).
+ *   Without an override the file password applies. Empty = no auth.
+ *
+ * Auth is HTTP Basic (`opencode:<password>`), the same header
+ * `Service.headers()` builds. The proxy's own discovery path
+ * (`serviceEndpoint()` in `server/index.ts`) honors the same overrides via
+ * `resolveEngineOverride()` — and an override URL skips `Service.ensure()`
+ * entirely, so a stale `service.json` pid can never spawn a rogue serve.
+ *
+ * Node builtins only (`node:fs`/`node:os`/`node:path` + global
+ * `fetch`/`Buffer`) — this module creates no import cycle with
+ * `server/index.ts`, which is why the credential logic lives here and not
+ * behind `Service`.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtEngine } from "./types";
+
+export const ENGINE_USERNAME = "opencode";
+export const ENGINE_REQUEST_TIMEOUT_MS = 15_000;
+
+function nonEmpty(value: string | undefined): string | undefined {
+  return value !== undefined && value.length > 0 ? value : undefined;
+}
+
+function serviceFilePath(): string {
+  const state = process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+  return join(state, "opencode", "service.json");
+}
+
+/** Raw registration-file read. Never throws — absent/corrupt = null. */
+function readServiceFile(): { url?: unknown; password?: unknown } | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(serviceFilePath(), "utf8"));
+    if (parsed && typeof parsed === "object") return parsed as { url?: unknown; password?: unknown };
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Effective engine base URL: `WEBUI_ENGINE_URL` wins, else the registration
+ * file's `url`. `null` when neither exists.
+ */
+export function resolveEngineBaseUrl(): string | null {
+  const override = nonEmpty(process.env.WEBUI_ENGINE_URL);
+  if (override !== undefined) return override.replace(/\/+$/, "");
+  const info = readServiceFile();
+  if (info && typeof info.url === "string" && info.url.length > 0) {
+    return info.url.replace(/\/+$/, "");
+  }
+  return null;
+}
+
+/**
+ * Effective engine password: `WEBUI_ENGINE_PASSWORD` wins; with an explicit
+ * URL override there is no file fallback (see module doc); otherwise the
+ * registration file's password. `undefined` = no auth.
+ */
+export function resolveEnginePassword(): string | undefined {
+  const override = nonEmpty(process.env.WEBUI_ENGINE_PASSWORD);
+  if (override !== undefined) return override;
+  if (nonEmpty(process.env.WEBUI_ENGINE_URL) !== undefined) return undefined;
+  const info = readServiceFile();
+  return typeof info?.password === "string" && info.password !== "" ? info.password : undefined;
+}
+
+/** Auth headers for the engine — the same Basic header `Service.headers()` builds. */
+export function engineAuthHeaders(): Record<string, string> {
+  const password = resolveEnginePassword();
+  if (password === undefined) return {};
+  return { authorization: "Basic " + Buffer.from(`${ENGINE_USERNAME}:${password}`).toString("base64") };
+}
+
+/**
+ * Override endpoint for the proxy's own discovery path. Non-null iff
+ * `WEBUI_ENGINE_URL` is set — explicit env wins, and the caller must skip
+ * `Service.ensure()` (no spawn, no version-kill of the chosen engine).
+ * Shape matches the `Endpoint` type `Service.ensure()` resolves to.
+ */
+export function resolveEngineOverride(): {
+  url: string;
+  auth?: { type: "basic"; username: string; password: string };
+} | null {
+  const raw = nonEmpty(process.env.WEBUI_ENGINE_URL);
+  if (raw === undefined) return null;
+  const url = raw.replace(/\/+$/, "");
+  const password = nonEmpty(process.env.WEBUI_ENGINE_PASSWORD);
+  if (password === undefined) return { url };
+  return { url, auth: { type: "basic", username: ENGINE_USERNAME, password } };
+}
+
+/**
+ * Fetch against the engine (`/api/...` paths; a leading slash is optional).
+ * Caller headers are kept; engine auth always wins over a caller-supplied
+ * `authorization` (same rule as the proxy passthrough). Aborts after
+ * `ENGINE_REQUEST_TIMEOUT_MS` unless the caller passes its own signal.
+ * Throws with a remedy when the engine is undiscoverable; HTTP errors are
+ * returned (not thrown) so pollers can retry next tick.
+ */
+export async function engineFetch(path: string, init: RequestInit = {}): Promise<Response> {
+  const base = resolveEngineBaseUrl();
+  if (!base) {
+    throw new Error(
+      "[webui] engine undiscoverable: set WEBUI_ENGINE_URL or start the opencode service (no service.json found)",
+    );
+  }
+  const { headers: initHeaders, signal, ...rest } = init;
+  const headers = new Headers(initHeaders);
+  for (const [k, v] of Object.entries(engineAuthHeaders())) headers.set(k, v);
+  return fetch(`${base}${path.startsWith("/") ? path : `/${path}`}`, {
+    ...rest,
+    headers,
+    signal: signal ?? AbortSignal.timeout(ENGINE_REQUEST_TIMEOUT_MS),
+  });
+}
+
+/** The singleton wired into every `ExtServerContext` as `ctx.engine`. */
+export const engine: ExtEngine = {
+  baseUrl: resolveEngineBaseUrl,
+  headers: engineAuthHeaders,
+  fetch: engineFetch,
+};

package/server/ext/kv.ts

@@ -1,9 +1,8 @@
 /**
  * Proxy-stratum KV store (spec §8).
  *
- * One small persistent store service for server extensions — the
- * `~/.dsh/brother-watches.json` equivalent — so each extension doesn't roll
- * its own file I/O. JSON-file backed (per spec: "bun:sqlite or JSON-file"),
+ * One small persistent store service for server extensions — so each
+ * extension doesn't roll its own file I/O. JSON-file backed (per spec: "bun:sqlite or JSON-file"),
  * namespaced per extension id: `kvFor("brother-watcher")` only ever sees
  * its own top-level key.
  *

package/server/ext/registry.ts

@@ -26,15 +26,15 @@
  *
  * GAPS (follow-ups, not in this scaffolding):
  * - `server/` directory form (only bare `server.ts` is discovered).
- * - Engine-credential passthrough for pollers that must call the engine
- *   (needs a Service.headers helper that doesn't create an index.ts cycle).
  * - SSE manifest push for server-module versions (browser bundle only).
+ * (Engine credentials shipped as `ctx.engine` — see `engine.ts`.)
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { globalUserExtensionsDir, projectUserExtensionsDir, warnOnce } from "../userExtensions";
+import { engine } from "./engine";
 import { kvFor } from "./kv";
 import type { ExtEngineEvent, ExtServerContext, ServerExtensionModule } from "./types";
 
@@ -82,7 +82,7 @@ function isServerExtensionModule(obj: unknown): obj is ServerExtensionModule {
 }
 
 function ctxFor(id: string): ExtServerContext {
-  return { extID: id, kv: kvFor(id) };
+  return { extID: id, kv: kvFor(id), engine };
 }
 
 async function loadEntry(id: string, dir: string, entry: string): Promise<void> {

package/server/ext/types.ts

@@ -42,6 +42,30 @@ export interface ExtServerContext {
   extID: string;
   /** Namespaced persistent KV (JSON-file backed, see kv.ts). */
   kv: ExtKV;
+  /**
+   * Engine fetch helper (see `engine.ts`). Replaces hand-parsing
+   * `service.json`: `await ctx.engine.fetch("/api/session/active")`.
+   * Honors `WEBUI_ENGINE_URL` / `WEBUI_ENGINE_PASSWORD` (explicit env
+   * wins); auth headers always win over caller-supplied ones.
+   */
+  engine: ExtEngine;
+}
+
+/**
+ * Engine credential helper (implemented in `engine.ts`, node builtins only
+ * — no core import needed on the extension side; the context is structural).
+ */
+export interface ExtEngine {
+  /** Effective engine base URL (`WEBUI_ENGINE_URL` wins, else `service.json`). `null` when undiscoverable. */
+  baseUrl(): string | null;
+  /** Auth headers for the engine (Basic `opencode:<password>`), or `{}` when unauthenticated. */
+  headers(): Record<string, string>;
+  /**
+   * Fetch against the engine (`/api/...` paths; leading slash optional).
+   * Throws with a remedy when undiscoverable; HTTP errors are returned, not
+   * thrown. Aborts after 15s unless the caller passes its own signal.
+   */
+  fetch(path: string, init?: RequestInit): Promise<Response>;
 }
 
 /** Extra context for route handlers. */

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.2.0 (matches the `v2.2.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.2.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.2.0/src/extensions/registry.tsx | The extension registry — exact register() shapes per kind |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.2.0/src/extensions/hooks.ts | Shared fireHooks runner — how open hook events fire |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.2.0/src/lib/domKit.ts | DOM-stratum kit (foreign/watch/styles) + the data-oc-* anchor table |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.2.0/server/ext/types.ts | Proxy-stratum types — server.ts routes/middleware/onEvent/pollers shapes |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.2.0/docs/extension-system-spec.md | The v2 decision record — strata, precedence, deletions, acceptance checks |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.2.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. a shipped extension 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,61 @@ 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 (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)
 
@@ -305,8 +406,7 @@ kit, `kv`) — used identically by our shipped ones.
 > User tweaks only the timestamp format. Maintainer later redesigns the
 > token counter and adds a finish badge in the same header. **The user gets
 > both, visibly** — parent and siblings are still core's; the user's wrap
-> delegates by default. (`docs/extension-system-spec.md` §5.4; scenario
-> script: `docs/extension-timestamp-test.md`.)
+> delegates by default. (`docs/extension-system-spec.md` §5.4.)
 
 ```tsx
 // ✅ RIGHT — wrap (stale-proof): the header redesign flows through
@@ -337,18 +437,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