@hiai-gg/hiai-opencode 0.1.2 → 0.1.3

package/.env.example

@@ -32,7 +32,7 @@ OPENROUTER_API_KEY=your_openrouter_api_key_here
 # Optional - Stitch AI remote MCP service
 # STITCH_AI_API_KEY=your_stitch_api_key_here
 
-# Optional - Firecrawl web scraping MCP (npx -y firecrawl-mcp)
+# Optional - Firecrawl web scraping MCP
 # FIRECRAWL_API_KEY=your_firecrawl_api_key_here
 
 # Optional - Context7 code search MCP
@@ -51,7 +51,18 @@ OPENROUTER_API_KEY=your_openrouter_api_key_here
 # Optional - Python command for MemPalace MCP (python3, python, or full path)
 # MEMPALACE_PYTHON=python3
 
+# Optional - custom MemPalace data directory
+# MEMPALACE_PALACE_PATH=./.opencode/palace
+
+# Optional - set to 0, false, or no to prevent first-run Python package install
+# HIAI_MCP_AUTO_INSTALL=1
+
+# Playwright MCP
+
+# Optional - set to 1, true, or yes to install Chromium during launcher startup
+# HIAI_PLAYWRIGHT_INSTALL_BROWSERS=0
+
 # RAG MCP
 
-# Optional - RAG endpoint URL (default: http://localhost:9002)
-# RAG_ENDPOINT=http://localhost:9002
+# Optional - RAG search tool endpoint
+# OPENCODE_RAG_URL=http://localhost:9002/tools/search

package/AGENTS.md

@@ -4,7 +4,9 @@ This file is for autonomous agents or tooling that need to install, configure, v
 
 ## Purpose
 
-`hiai-opencode` is an OpenCode plugin repository published as `@hiai-gg/hiai-opencode`. It is not a standalone app. The normal workflow is:
+`hiai-opencode` is an OpenCode plugin repository published as `@hiai-gg/hiai-opencode`. It is not a standalone app. It wires OpenCode agents, prompts, skills, MCP server launch commands, LSP defaults, and compatibility behavior around external upstream tools. Do not describe MCP servers, skills, model providers, or auxiliary OpenCode plugins as owned by this repository.
+
+The normal workflow is:
 
 1. install it through OpenCode or build it locally
 2. register `@hiai-gg/hiai-opencode` in OpenCode
@@ -15,7 +17,19 @@ This file is for autonomous agents or tooling that need to install, configure, v
 
 ### Native OpenCode Install
 
-Add the package name to OpenCode config. OpenCode installs npm plugins automatically at startup.
+Use the OpenCode plugin CLI:
+
+```bash
+opencode plugin @hiai-gg/hiai-opencode@latest --global
+```
+
+Optional Dynamic Context Pruning plugin:
+
+```bash
+opencode plugin @tarquinen/opencode-dcp@latest --global
+```
+
+Manual alternative:
 
 ```json
 {
@@ -33,7 +47,13 @@ bun run build
 
 ### Register In OpenCode
 
-Add this to OpenCode config:
+Use the plugin CLI:
+
+```bash
+opencode plugin @hiai-gg/hiai-opencode@latest --global
+```
+
+Manual alternative:
 
 ```json
 {
@@ -49,6 +69,85 @@ opencode debug config
 opencode mcp list --print-logs --log-level INFO
 ```
 
+## Post-Install Bootstrap Instructions
+
+When a user asks OpenCode or another agent to finish installing this plugin, follow this procedure.
+
+### Operating Rules
+
+- Keep OpenCode plugins separate from MCP servers.
+- Register `@hiai-gg/hiai-opencode` as an OpenCode plugin.
+- Register `@tarquinen/opencode-dcp` only when the user wants Dynamic Context Pruning; it is a separate OpenCode plugin.
+- Do not add MCP server npm packages to the OpenCode `plugin` array.
+- Use `hiai-opencode.json` as the project-level service switchboard.
+- Use `src/mcp/registry.ts` as the source of truth for default MCP launch wiring.
+- Use `.env.example` as the key template, but never print, invent, commit, or hardcode secret values.
+- Prefer user-level or project-local installs. Do not use sudo/admin rights unless the user explicitly asks.
+
+### Bootstrap Checklist
+
+1. Check tool availability:
+   - `opencode --version`
+   - `node --version`
+   - `npx --version`
+   - `bun --version`
+   - `python --version` or `python3 --version`
+   - `uv --version` when available
+2. Check plugin registration with `opencode debug config`.
+3. Find or create `hiai-opencode.json` in the project root or `.opencode/`.
+4. Configure the `mcp` object there. Disable services that cannot run on the host.
+5. Check environment variables without printing values:
+   - `OPENROUTER_API_KEY`
+   - `FIRECRAWL_API_KEY`
+   - `STITCH_AI_API_KEY`
+   - `CONTEXT7_API_KEY`
+   - `MEMPALACE_PYTHON`
+   - `OPENCODE_RAG_URL`
+   - `HIAI_PLAYWRIGHT_INSTALL_BROWSERS`
+   - `HIAI_MCP_AUTO_INSTALL`
+6. Verify with:
+   - `opencode debug config`
+   - `opencode mcp list --print-logs --log-level INFO`
+
+### MCP Setup Matrix
+
+| Service | Enable when | Dependency behavior |
+|---|---|---|
+| `playwright` | Node and npx are available | Helper launcher runs `@playwright/mcp@latest`; set `HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1` to install Chromium on first start |
+| `sequential-thinking` | Node and npx are available | Helper launcher runs `@modelcontextprotocol/server-sequential-thinking` |
+| `firecrawl` | `FIRECRAWL_API_KEY` is set | Helper launcher runs `firecrawl-mcp` |
+| `mempalace` | `uv` is available, or Python 3.9+ with pip is available | Launcher prefers `uv`; otherwise uses Python and can run `python -m pip install --user mempalace` when `HIAI_MCP_AUTO_INSTALL` is not disabled |
+| `rag` | User has a local or remote RAG endpoint | Uses `OPENCODE_RAG_URL`, defaulting to `http://localhost:9002/tools/search` |
+| `stitch` | `STITCH_AI_API_KEY` is set | Remote MCP endpoint |
+| `context7` | User wants Context7 docs/search | Remote MCP endpoint; use `CONTEXT7_API_KEY` if available |
+
+### Prompt For OpenCode Users
+
+Users can paste this into OpenCode after installing the plugin:
+
+```text
+Finish hiai-opencode setup in this workspace.
+
+Keep OpenCode plugins separate from MCP servers. Do not add MCP server packages to the OpenCode plugin list.
+
+Verify @hiai-gg/hiai-opencode is registered. If I ask for Dynamic Context Pruning, install @tarquinen/opencode-dcp as a separate OpenCode plugin.
+
+Find or create hiai-opencode.json in the project root or .opencode/. Use its mcp object as the only switchboard for MCP enable/disable.
+
+Check which services can run here:
+- playwright: node/npx; optionally HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1.
+- sequential-thinking: node/npx.
+- firecrawl: FIRECRAWL_API_KEY.
+- mempalace: uv or Python 3.9+ with pip; MEMPALACE_PYTHON if needed; HIAI_MCP_AUTO_INSTALL controls first-run pip install.
+- rag: OPENCODE_RAG_URL or http://localhost:9002/tools/search.
+- stitch: STITCH_AI_API_KEY.
+- context7: optional CONTEXT7_API_KEY.
+
+Report missing keys without printing secret values. Never invent or hardcode API keys.
+
+Run opencode debug config and opencode mcp list --print-logs --log-level INFO if available. If something is missing, propose or run only user-level/project-local install commands.
+```
+
 ## Expected Agent State
 
 Visible primary agents:
@@ -129,8 +228,8 @@ Use this table when you need to change something and want the right file immedia
 | Change closure protocol appended to prompts | [src/shared/closure-protocol.ts](src/shared/closure-protocol.ts) | It is injected after prompt construction |
 | Change prompt override / prompt_append behavior | `src/agents/builtin-agents/agent-overrides.ts` | Override merge logic lives there |
 | Change environment context appended to prompts | `src/agents/builtin-agents/environment-context.ts` | Runtime environment prompt injection lives there |
-| Change MCP defaults | [src/config/defaults.ts](src/config/defaults.ts) | Default MCP definitions live there |
-| Change fallback packaged MCP behavior | [src/mcp/index.ts](src/mcp/index.ts) | Packaged MCP assembly lives there |
+| Change MCP defaults | [src/mcp/registry.ts](src/mcp/registry.ts) | Default MCP wiring lives there |
+| Change OpenCode MCP assembly | [src/mcp/index.ts](src/mcp/index.ts) | Final MCP config assembly lives there |
 | Change local MCP helper launcher logic | `assets/mcp/*` | Runtime launcher scripts live there |
 | Change npm bootstrap behavior for MCP/LSP tools | [assets/runtime/npm-package-runner.mjs](assets/runtime/npm-package-runner.mjs) | Shared npm bootstrap logic lives there |
 | Change LSP defaults | [src/config/defaults.ts](src/config/defaults.ts) | LSP defaults live there |
@@ -204,11 +303,11 @@ So:
 
 ## MCP Rules
 
-Default MCP definitions live in:
+Default MCP wiring lives in:
 
-- [src/config/defaults.ts](src/config/defaults.ts)
+- [src/mcp/registry.ts](src/mcp/registry.ts)
 
-Fallback/packaged MCP assembly lives in:
+OpenCode MCP config assembly lives in:
 
 - [src/mcp/index.ts](src/mcp/index.ts)
 
@@ -248,6 +347,10 @@ Common keys:
 - `OLLAMA_BASE_URL`
 - `OLLAMA_MODEL`
 - `MEMPALACE_PYTHON`
+- `MEMPALACE_PALACE_PATH`
+- `OPENCODE_RAG_URL`
+- `HIAI_PLAYWRIGHT_INSTALL_BROWSERS`
+- `HIAI_MCP_AUTO_INSTALL`
 
 ## Known Runtime Caveats
 

package/ARCHITECTURE.md

@@ -187,10 +187,10 @@ The final runtime prompt can also be affected by:
 
 ## Skills
 
-Two skill sources are combined:
+Two skill sources are wired into OpenCode:
 
-- project skills shipped in [skills](skills)
-- built-in skills materialized into the OpenCode-visible skill tree
+- project skill definitions in [skills](skills)
+- skill materialization into the OpenCode-visible skill tree
 
 Relevant files:
 
@@ -201,11 +201,11 @@ Relevant files:
 
 ### Definitions
 
-Default MCP definitions are in:
+Default MCP wiring is in:
 
-- [src/config/defaults.ts](src/config/defaults.ts)
+- [src/mcp/registry.ts](src/mcp/registry.ts)
 
-Fallback assembly for packaged MCP support is in:
+OpenCode MCP config assembly is in:
 
 - [src/mcp/index.ts](src/mcp/index.ts)
 

package/README.md

@@ -1,14 +1,40 @@
 # hiai-opencode
 
-`hiai-opencode` is an OpenCode plugin that bundles:
+`hiai-opencode` is an OpenCode plugin that wires together:
 
 - a curated multi-agent runtime
-- project and built-in skills
+- project and OpenCode skills
 - MCP integrations
 - LSP defaults
 - migration and compatibility wiring
 
 This repository is intended to be usable by someone who clones it from GitHub without any internal context.
+The external MCP servers, skills, model providers, and auxiliary OpenCode plugins remain their own upstream projects; this plugin only provides OpenCode wiring, defaults, prompts, launchers, and documentation around them.
+
+## Why This Exists
+
+I wanted the "one install, give me the whole cockpit" setup. More agents, more MCP servers, more skills, better defaults, fewer tiny config islands. 🚀
+
+The problem: all those great tools do not magically become friends just because you installed them. Some are npm packages, some are Python tools, some need API keys, some need a local service, and some only wake up after the first run. Meanwhile your main agent can waste half the context window just reading everything you bolted on. Not chill. 😅
+
+So `hiai-opencode` is my attempt to wire the best pieces I use into one OpenCode-friendly shape: agents, prompts, skills, MCP launchers, LSP defaults, and a clean config surface. It does not claim ownership of the upstream tools. It just tries to make them cooperate.
+
+After the first install, a few MCP services may still need local dependencies or keys. You have two options:
+
+- Follow the setup sections below: [Install](#install), [Environment](#environment), and [MCP Service Notes](#mcp-service-notes).
+- Or ask OpenCode to do the boring part for you. Paste this after installing:
+
+```text
+Read AGENTS.md and finish hiai-opencode setup for this workspace.
+
+Keep OpenCode plugins separate from MCP servers. Do not add MCP server packages to the OpenCode plugin list.
+
+Check which MCP services can run on this machine, update hiai-opencode.json, install only missing user-level or project-local dependencies, and report missing API keys without printing secret values.
+
+Then run opencode debug config and opencode mcp list --print-logs --log-level INFO if available.
+```
+
+For the full operator playbook, see [AGENTS.md](AGENTS.md). 🤖
 
 ## What You Get
 
@@ -20,7 +46,7 @@ This repository is intended to be usable by someone who clones it from GitHub wi
   - `deep`, `ultrabrain`, `visual-engineering`, `artistry`, and `unspecified-high` are the deep Coder contour
   - `Critic` and `Researcher` are selected explicitly
   - `Designer`, `Brainstormer`, `Manager`, and `Vision` are direct callable specialists
-- Built-in skill materialization into OpenCode's `skills/` view
+- Skill materialization into OpenCode's `skills/` view
 - MCP wiring for `playwright`, `stitch`, `sequential-thinking`, `firecrawl`, `rag`, `mempalace`, `context7`, plus remote `websearch` and `grep_app`
 - LSP wiring for TypeScript, Svelte, Python, Bash, and ESLint
 
@@ -47,9 +73,19 @@ Optional, depending on which services you want:
 
 ## Install
 
-Recommended native OpenCode install, once published:
+Recommended native OpenCode install:
+
+```bash
+opencode plugin @hiai-gg/hiai-opencode@latest --global
+```
+
+Optional DCP plugin:
+
+```bash
+opencode plugin @tarquinen/opencode-dcp@latest --global
+```
 
-Add the npm package to your OpenCode config. OpenCode installs npm plugins automatically at startup.
+Manual config alternative:
 
 ```json
 {
@@ -81,7 +117,19 @@ bun run build
 
 ## Register The Plugin In OpenCode
 
-Add this to your OpenCode config:
+Use the OpenCode plugin CLI:
+
+```bash
+opencode plugin @hiai-gg/hiai-opencode@latest --global
+```
+
+If you also want Dynamic Context Pruning, install its separate plugin next:
+
+```bash
+opencode plugin @tarquinen/opencode-dcp@latest --global
+```
+
+If you prefer manual config, add the plugin package to your OpenCode config. OpenCode installs npm plugins automatically at startup.
 
 ```json
 {
@@ -94,6 +142,8 @@ The packaged minimal example lives in [config/opencode.json](config/opencode.jso
 
 The richer example config lives in [hiai-opencode.json](hiai-opencode.json).
 
+Do not put MCP server packages such as `firecrawl-mcp`, `@playwright/mcp`, or `@modelcontextprotocol/server-sequential-thinking` into the OpenCode `plugin` array. They are MCP servers, not OpenCode plugins. `hiai-opencode` only provides the OpenCode-side launch wiring for them through its `mcp` config and helper launchers.
+
 ## Quick Start
 
 ```bash
@@ -105,6 +155,18 @@ bun run build
 
 Register the plugin in OpenCode:
 
+```bash
+opencode plugin @hiai-gg/hiai-opencode@latest --global
+```
+
+Optional:
+
+```bash
+opencode plugin @tarquinen/opencode-dcp@latest --global
+```
+
+Manual equivalent:
+
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
@@ -112,6 +174,22 @@ Register the plugin in OpenCode:
 }
 ```
 
+Project-level service config goes in `hiai-opencode.json` at the project root or under `.opencode/`:
+
+```json
+{
+  "mcp": {
+    "playwright": { "enabled": true },
+    "sequential-thinking": { "enabled": true },
+    "firecrawl": { "enabled": true },
+    "mempalace": { "enabled": true },
+    "rag": { "enabled": false },
+    "stitch": { "enabled": false },
+    "context7": { "enabled": true }
+  }
+}
+```
+
 Then verify:
 
 ```bash
@@ -119,6 +197,37 @@ opencode debug config
 opencode mcp list --print-logs --log-level INFO
 ```
 
+## Post-Install Bootstrap Prompt
+
+After installing the plugin, you can ask OpenCode to finish local setup with this prompt:
+
+```text
+Inspect this OpenCode workspace and finish hiai-opencode setup.
+
+Do not add MCP server packages to the OpenCode plugin list. Keep OpenCode plugins separate from MCP servers.
+
+Check that @hiai-gg/hiai-opencode is registered. If Dynamic Context Pruning is requested, install @tarquinen/opencode-dcp as a separate OpenCode plugin.
+
+Find or create hiai-opencode.json in the project root or .opencode/. Use its mcp object as the single switchboard for enabling or disabling MCP services.
+
+Enable only services that can run on this machine:
+- playwright: requires node/npx; optionally set HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1 before first run if browser binaries are needed.
+- sequential-thinking: requires node/npx.
+- firecrawl: requires FIRECRAWL_API_KEY.
+- mempalace: requires uv or Python 3.9+ with pip; set MEMPALACE_PYTHON if needed. Leave HIAI_MCP_AUTO_INSTALL enabled unless the user forbids package installation.
+- rag: requires OPENCODE_RAG_URL or a running local endpoint at http://localhost:9002/tools/search.
+- stitch: requires STITCH_AI_API_KEY.
+- context7: works without a key but use CONTEXT7_API_KEY if available.
+
+Check .env.example, report missing keys without printing secret values, and never invent or hardcode API keys.
+
+Run verification commands where available:
+- opencode debug config
+- opencode mcp list --print-logs --log-level INFO
+
+If a dependency is missing, install only user-level or project-local dependencies, explain every command before running it, and do not use sudo/admin rights unless the user explicitly asks.
+```
+
 ## Where To Change Things
 
 ### Models
@@ -164,21 +273,21 @@ Name mapping and visibility:
 
 ### Skills
 
-Packaged project skills live under:
+Project skill definitions live under:
 
 - [skills](skills)
 
-Built-in skill materialization logic:
+Skill materialization logic:
 
 - [src/features/builtin-skills/materialize.ts](src/features/builtin-skills/materialize.ts)
 
 ### MCP
 
-Default MCP definitions:
+Default MCP registry:
 
-- [src/config/defaults.ts](src/config/defaults.ts)
+- [src/mcp/registry.ts](src/mcp/registry.ts)
 
-Fallback MCP assembly:
+OpenCode MCP config assembly:
 
 - [src/mcp/index.ts](src/mcp/index.ts)
 
@@ -215,6 +324,19 @@ Use [.env.example](.env.example) as the reference template. Create a local `.env
 
 ## MCP Service Notes
 
+The user-facing MCP switchboard is the `mcp` object in `hiai-opencode.json`:
+
+```json
+{
+  "mcp": {
+    "playwright": { "enabled": true },
+    "mempalace": { "enabled": false }
+  }
+}
+```
+
+The source of truth for default MCP wiring is `src/mcp/registry.ts`. Change that file when adding a new MCP integration or changing its launch command, required env vars, or install strategy.
+
 ### Works well as remote MCP
 
 - `stitch`
@@ -224,14 +346,22 @@ Use [.env.example](.env.example) as the reference template. Create a local `.env
 
 ### Works with local helper bootstrap
 
-- `playwright`
+- `playwright`: launches `@playwright/mcp@latest` through the helper npm runner. Set `HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1` if you want the launcher to install Chromium on first start.
+- `sequential-thinking`: launches `@modelcontextprotocol/server-sequential-thinking` through the helper npm runner.
+- `firecrawl`: launches `firecrawl-mcp` through the helper npm runner and requires `FIRECRAWL_API_KEY`.
 
 ### Needs upstream runtime or extra setup
 
-- `mempalace`: requires `uv` or Python with `mempalace` installed
-- `firecrawl`: requires `FIRECRAWL_API_KEY`
+- `mempalace`: prefers `uv`; otherwise uses Python. If `HIAI_MCP_AUTO_INSTALL` is not `0`, `false`, or `no`, the launcher can run `python -m pip install --user mempalace` on first start.
 - `rag`: requires your own running endpoint
-- `sequential-thinking`: uses upstream stdio launch
+
+### Additional OpenCode Plugin
+
+`opencode-dcp` is a separate OpenCode plugin, not an MCP server:
+
+```bash
+opencode plugin @tarquinen/opencode-dcp@latest --global
+```
 
 ### Important Windows note
 
@@ -242,16 +372,6 @@ On some Windows/OpenCode environments, local MCP process spawning can fail with
 
 This most often affects `sequential-thinking` and `mempalace`, and sometimes local `npx`-backed tools.
 
-## Optional External Plugin
-
-`opencode-dcp` is intentionally not bundled.
-
-Install it separately if you want it:
-
-```bash
-opencode plugin @tarquinen/opencode-dcp@latest --global
-```
-
 ## Build And Publish
 
 Build:

package/assets/mcp/mempalace.mjs

@@ -74,6 +74,37 @@ function resolvePythonForMempalace() {
   return null;
 }
 
+function resolvePythonForPip() {
+  for (const candidate of pythonCandidates()) {
+    const probe = spawnSync(
+      candidate.command,
+      [...candidate.args, "-m", "pip", "--version"],
+      { stdio: "ignore", timeout: 10000 },
+    );
+
+    if (probe.status === 0) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function shouldAutoInstall() {
+  const value = process.env.HIAI_MCP_AUTO_INSTALL?.trim().toLowerCase();
+  return value !== "0" && value !== "false" && value !== "no";
+}
+
+function installMempalaceWithPip(candidate) {
+  const result = spawnSync(
+    candidate.command,
+    [...candidate.args, "-m", "pip", "install", "--user", "mempalace"],
+    { stdio: "inherit", timeout: 300000 },
+  );
+
+  return result.status === 0 && canRunModule(candidate, "mempalace.mcp_server");
+}
+
 function resolveUvCacheRoot() {
   return process.env.UV_CACHE_DIR
     || join(resolveCacheRoot(), "hiai-opencode", "uv");
@@ -128,16 +159,28 @@ function main() {
   }
 
   const python = resolvePythonForMempalace();
-  if (!python) {
+  const fallbackPython =
+    python
+    || (shouldAutoInstall()
+      ? (() => {
+        const pipPython = resolvePythonForPip();
+        if (pipPython && installMempalaceWithPip(pipPython)) {
+          return pipPython;
+        }
+        return null;
+      })()
+      : null);
+
+  if (!fallbackPython) {
     console.error(
-      "[hiai-opencode] mempalace skipped: install uv or Python 3.9+ with `pip install mempalace`",
+      "[hiai-opencode] mempalace skipped: install uv or Python 3.9+ with `pip install --user mempalace`",
     );
     process.exit(0);
   }
 
   const child = spawn(
-    python.command,
-    [...python.args, "-m", "mempalace.mcp_server", "--palace", palacePath],
+    fallbackPython.command,
+    [...fallbackPython.args, "-m", "mempalace.mcp_server", "--palace", palacePath],
     {
       stdio: "inherit",
       env: {

package/assets/mcp/playwright.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { mkdirSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { spawn, spawnSync } from "node:child_process"
+
+function resolveCacheRoot() {
+  const xdgCache = process.env.XDG_CACHE_HOME?.trim()
+  if (xdgCache) return xdgCache
+
+  const scriptDir = dirname(fileURLToPath(import.meta.url))
+  const pluginRoot = join(scriptDir, "..", "..")
+  return join(pluginRoot, ".runtime-cache")
+}
+
+function runNpx(args, stdio = "inherit") {
+  const cacheRoot = join(resolveCacheRoot(), "hiai-opencode", "npm")
+  const tempRoot = join(cacheRoot, "tmp")
+  mkdirSync(tempRoot, { recursive: true })
+
+  const npxCommand = process.platform === "win32" ? "npx.cmd" : "npx"
+  return spawnSync(npxCommand, args, {
+    stdio,
+    shell: process.platform === "win32",
+    env: {
+      ...process.env,
+      npm_config_cache: cacheRoot,
+      NPM_CONFIG_CACHE: cacheRoot,
+      TEMP: tempRoot,
+      TMP: tempRoot,
+    },
+  })
+}
+
+function shouldInstallBrowsers() {
+  const value = process.env.HIAI_PLAYWRIGHT_INSTALL_BROWSERS?.trim().toLowerCase()
+  return value === "1" || value === "true" || value === "yes"
+}
+
+if (shouldInstallBrowsers()) {
+  const result = runNpx(["-y", "playwright@latest", "install", "chromium"])
+  if (result.status !== 0) {
+    console.error("[hiai-opencode] playwright browser install failed")
+  }
+}
+
+const cacheRoot = join(resolveCacheRoot(), "hiai-opencode", "npm")
+const tempRoot = join(cacheRoot, "tmp")
+mkdirSync(tempRoot, { recursive: true })
+
+const npxCommand = process.platform === "win32" ? "npx.cmd" : "npx"
+const child = spawn(npxCommand, ["-y", "@playwright/mcp@latest", ...process.argv.slice(2)], {
+  stdio: "inherit",
+  shell: process.platform === "win32",
+  env: {
+    ...process.env,
+    npm_config_cache: cacheRoot,
+    NPM_CONFIG_CACHE: cacheRoot,
+    TEMP: tempRoot,
+    TMP: tempRoot,
+  },
+})
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal)
+    return
+  }
+  process.exit(code ?? 0)
+})
+
+child.on("error", (error) => {
+  console.error("[hiai-opencode] playwright launcher failed:", error)
+  process.exit(1)
+})

package/dist/config/defaults.d.ts

@@ -1,2 +1,5 @@
+/**
+ * Default config values for hiai-opencode
+ */
 import type { HiaiOpencodeConfig } from "./types.js";
 export declare const defaultConfig: HiaiOpencodeConfig;

package/dist/config/platform-schema.d.ts

@@ -72,6 +72,7 @@ export declare const McpServerConfigSchema: z.ZodObject<{
         local: "local";
     }>>;
     url: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     command: z.ZodOptional<z.ZodArray<z.ZodString>>;
     timeout: z.ZodOptional<z.ZodNumber>;
     environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -971,6 +972,7 @@ export declare const HiaiOpencodeConfigSchema: z.ZodObject<{
             local: "local";
         }>>;
         url: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         command: z.ZodOptional<z.ZodArray<z.ZodString>>;
         timeout: z.ZodOptional<z.ZodNumber>;
         environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;