chore(release): v0.6.1

Author: vlgalib

AGENTS.md

@@ -33,8 +33,12 @@ When asked to finish setup in a workspace:
 4. **Env keys** (without printing values — see [bob.env.example](bob.env.example)):
    - `FIRECRAWL_API_KEY` — required for the Firecrawl CLI skill
    - `CONTEXT7_API_KEY` — optional, on-demand via `skill("explore/context7")`
-   - `AGENT_BROWSER_SESSION`, `GREP_APP_API_KEY`, `OLLAMA_*` — optional
-5. **Verify**: `opencode debug config`, `hiai-opencode doctor`, `hiai-opencode mcp-status`.
+   - `AGENT_BROWSER_SESSION`, `AGENT_BROWSER_ENGINE`, `GREP_APP_API_KEY`, `OLLAMA_*` — optional
+5. **Browser tooling** (required for the `/agent-browser` skill — details in [Browser automation](#browser-automation)):
+   - Install the CLI: `bun add -g agent-browser && agent-browser install` — `agent-browser install` provisions only the **Chrome fallback** engine.
+   - Lightpanda is **optional** and **headless-only**: install via the official user-level installer (not `cargo`) — `curl -fsSL https://pkg.lightpanda.io/install.sh | bash` (site: https://lightpanda.io).
+   - Engine rules: Lightpanda is auto-preferred when its binary is installed; Chrome is the fallback; an explicit `AGENT_BROWSER_ENGINE=chrome|lightpanda` overrides auto-selection.
+6. **Verify**: `opencode debug config`, `hiai-opencode doctor`, `hiai-opencode mcp-status`; for browser tooling confirm `agent-browser --version` and, if Lightpanda was installed, `lightpanda version`.
 
 Operating rules: keep OpenCode plugins separate from MCP servers; never add MCP server packages to the `plugin` array; never print/invent/commit API keys; prefer user-level or project-local installs (no sudo).
 
@@ -101,7 +105,7 @@ Use [bob.env.example](bob.env.example) as the canonical template. Model provider
 | `FIRECRAWL_API_KEY` | Firecrawl CLI skill (web scraping) |
 | `CONTEXT7_API_KEY` | On-demand library docs via `skill("explore/context7")` |
 | `AGENT_BROWSER_SESSION` | Browser automation session name |
-| `AGENT_BROWSER_ENGINE` | Browser engine — `chrome` (default) \| `lightpanda` (optional, headless-only) |
+| `AGENT_BROWSER_ENGINE` | Browser engine — auto-selects `lightpanda` when its binary is installed; `chrome` is the fallback; an explicit `chrome` \| `lightpanda` value overrides auto-selection |
 | `GREP_APP_API_KEY` | Optional grep.app search |
 | `OLLAMA_BASE_URL`, `OLLAMA_MODEL` | Local Ollama models |
 | `HIAI_OPENCODE_AUTO_EXPORT_MCP` | `if-missing` (default) \| `always` \| `off` |
@@ -153,17 +157,23 @@ The plugin can't find its bundled config. Run `bun run build` to populate `dist/
 Firecrawl is a CLI skill, not an MCP server. The env var must be in the shell that runs the CLI skill — `export FIRECRAWL_API_KEY=fc-...` before starting OpenCode, or set it in `bob.env`. It is NOT configured in the `mcp` block.
 
 ### Browser automation
-Use the `/agent-browser` skill (not MCP). Install: `bun add -g agent-browser && agent-browser install`. Uses native Chrome via CDP — no Playwright. Key env: `AGENT_BROWSER_HEADED=1`, `AGENT_BROWSER_SESSION=name`. Pattern: `snapshot -i --json` → @eN refs → `click @e2`. Repo: https://github.com/vercel-labs/agent-browser
+Use the `/agent-browser` skill (not MCP). Install: `bun add -g agent-browser && agent-browser install`. Uses CDP against Lightpanda (preferred when installed) or Chrome (fallback) — no Playwright. Key env: `AGENT_BROWSER_HEADED=1`, `AGENT_BROWSER_SESSION=name`. Pattern: `snapshot -i --json` → @eN refs → `click @e2`. Repo: https://github.com/vercel-labs/agent-browser
 
-`agent-browser install` only sets up the **default engine (Chrome)** — it does **not** install Lightpanda.
+`agent-browser install` only provisions the **fallback engine (Chrome)** — it does **not** install Lightpanda, and neither does the npm plugin (no binary auto-download).
 
-**Lightpanda (optional, headless-only):** install via the official one-liner (not `cargo`):
+**Engine auto-selection:** if the `lightpanda` binary is installed and `AGENT_BROWSER_ENGINE` is **not** set, the runtime prefers **Lightpanda** (headless-only). **Chrome is the fallback** — used when Lightpanda is absent, or when an explicit override forces it.
+
+**Lightpanda (optional, headless-only):** separate user-level install via the official installer (not `cargo`):
 
 ```bash
 curl -fsSL https://pkg.lightpanda.io/install.sh | bash
 ```
 
-Select it per-run with the CLI flag `agent-browser --engine lightpanda open <url>`, or set `AGENT_BROWSER_ENGINE=lightpanda` for the whole session. Headed mode (`AGENT_BROWSER_HEADED=1`) works only with Chrome — Lightpanda is headless-only. Chrome remains the default and fallback engine.
+**Explicit override** (beats auto-selection) — env var for the whole session, or CLI flag per run:
+- `AGENT_BROWSER_ENGINE=chrome` / `agent-browser --engine chrome open <url>` — force Chrome
+- `AGENT_BROWSER_ENGINE=lightpanda` / `agent-browser --engine lightpanda open <url>` — force Lightpanda
+
+Headed mode (`AGENT_BROWSER_HEADED=1`) works only with Chrome — Lightpanda is headless-only.
 
 ### Agent prompt correct in source but wrong at runtime
 The runtime prompt is assembled in layers: (1) `src/agents/<agent>.ts`, (2) `src/prompt-library/*.ts` imports, (3) runtime hooks (closure-injector, caveman-system-injector), (4) `hooks.config` in [src/index.ts](src/index.ts) applies model/visibility/permissions. Inspect `hooks.config` first when runtime output diverges from source.

ARCHITECTURE.md

@@ -186,7 +186,18 @@ CLI skills (not MCP, invoked via `skill("...")` or shell):
 
 - `firecrawl` — web scraping (requires `FIRECRAWL_API_KEY`)
 - `context7` — on-demand library docs via `skill("explore/context7")`
-- `agent-browser` — browser automation via Chrome CDP (uses `/agent-browser` skill)
+- `agent-browser` — browser automation via CDP on Lightpanda (preferred when installed) or Chrome (fallback) (uses `/agent-browser` skill)
+
+### Browser engine selection
+
+The external `agent-browser` CLI owns launching the browser engine — the plugin never starts, downloads, or embeds one. The plugin's only engine logic is a small availability-aware selection step in [src/shared/agent-browser-engine.ts](src/shared/agent-browser-engine.ts): `applyAgentBrowserEngineDefault()` (invoked from [src/index.ts](src/index.ts) before agent creation) checks whether a `lightpanda` binary exists on `$PATH` and, if so while `AGENT_BROWSER_ENGINE` is unset, sets the variable to `lightpanda`. Otherwise the variable is left **unset** so upstream `agent-browser` falls back to its own default engine, **Chrome** — the plugin never hardcodes Chrome, and the Chrome fallback remains.
+
+- **Auto-selection:** if the `lightpanda` binary is on `$PATH` and `AGENT_BROWSER_ENGINE` is **not** set, the plugin sets `AGENT_BROWSER_ENGINE=lightpanda`, so upstream prefers **Lightpanda** (headless-only).
+- **Fallback:** **Chrome**, `agent-browser`'s own default engine, provisioned by `agent-browser install`.
+- **Explicit override** beats auto-selection: `AGENT_BROWSER_ENGINE=chrome|lightpanda` (env, whole session) or `agent-browser --engine chrome|lightpanda open <url>` (CLI flag, per run). An explicit value is always honored verbatim.
+- **Install boundary:** Lightpanda is a separate **user-level** install via its official installer (`curl -fsSL https://pkg.lightpanda.io/install.sh | bash`, not `cargo`). Neither the npm plugin nor `agent-browser install` downloads the Lightpanda binary — the plugin only detects an already-installed binary on `$PATH`.
+
+Headed mode (`AGENT_BROWSER_HEADED=1`) works only with Chrome.
 
 ## MCP
 

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.1] — 2026-08-13
+
+### 🌐 Runtime Lightpanda auto-selection
+
+- **New availability-aware engine default.** `applyAgentBrowserEngineDefault()` (`src/shared/agent-browser-engine.ts`), invoked from the plugin entry before agents are created, checks whether a `lightpanda` binary is on `$PATH` and — while `AGENT_BROWSER_ENGINE` is unset — sets the variable to `lightpanda`. Otherwise the variable stays **unset** so upstream `agent-browser` falls back to its own default engine, **Chrome**; the plugin never hardcodes Chrome.
+- **Explicit override always wins:** `AGENT_BROWSER_ENGINE=chrome|lightpanda` (env, whole session) or `agent-browser --engine chrome|lightpanda open <url>` (CLI flag, per run) beats auto-selection; `chrome` forces the fallback engine even when Lightpanda is installed.
+- **Install boundary clarified:** Lightpanda is a separate **user-level** install via its official installer (`curl -fsSL https://pkg.lightpanda.io/install.sh | bash`, not `cargo`). Neither the npm plugin nor `agent-browser install` downloads the Lightpanda binary — `agent-browser install` provisions Chrome only; the plugin detects an already-installed binary on `$PATH`, it never downloads or embeds an engine.
+- New unit tests for PATH discovery and the auto-selection default (`src/shared/agent-browser-engine.test.ts`).
+
+### 🖥️ CLI doctor diagnostics
+
+- **`hiai-opencode mcp-status` now reports the browser-engine state:** a **Lightpanda engine** check (ok when the binary is on PATH; info when missing, with the install one-liner hint) and an **Agent-browser effective engine** check that traces the resolution chain — explicit `AGENT_BROWSER_ENGINE` → auto-selected Lightpanda on PATH → Chrome fallback.
+- **New info status level (ℹ️)** for non-blocking diagnostics alongside ok/warn/error.
+- **`hiai-opencode diagnose` now includes `AGENT_BROWSER_ENGINE`** in the environment snapshot.
+
+### 📚 Docs & install guidance
+
+- **Engine auto-selection documented consistently** across `README.md`, `ARCHITECTURE.md`, `AGENTS.md`, `bob.env.example`, and the vision skills: the runtime prefers **Lightpanda** (headless-only) when its binary is installed and `AGENT_BROWSER_ENGINE` is unset; **Chrome** is the fallback.
+- **README gains a dedicated "Install browser automation" step** (optional): `bun add -g agent-browser && agent-browser install` provisions the Chrome fallback, Lightpanda installs via its official one-liner, and engine overrides plus the headed-mode caveat (`AGENT_BROWSER_HEADED=1` is Chrome-only) are spelled out.
+- **`AGENTS.md` bootstrap checklist and browser-automation troubleshooting** now cover Lightpanda installation, engine auto-selection rules, and explicit overrides; **`ARCHITECTURE.md`** gains a "Browser engine selection" section describing the plugin's engine boundary (detect, never launch/download/embed).
+- `bob.env.example` now shows `AGENT_BROWSER_ENGINE` as an explicit override example (both `lightpanda` and `chrome`), with no secrets added.
+
 ## [0.6.0] — 2026-08-10
 
 ### 📁 Ancestor-directory config discovery (bob.json / bob.env)

README.md

@@ -22,7 +22,7 @@ Most AI coding tools drop you into one big context window and hope the model sel
 - 🔍 **Diagnostics are mandatory, not optional.** Edit a file and the completion gate blocks until `lsp_diagnostics` has run clean and any failing `test` / `lint` / `typecheck` passes.
 - 🧠 **A real team, not a monologue.** Bob routes by category — quick work to a cheap executor, hard implementation to a Senior Engineer, architecture to a Principal Architect, UI to a Designer, docs to a Writer.
 - 🗜️ **Context that survives compaction.** Long sessions compact gracefully — in-memory gate state (failed quality check, pending diagnostics, unreviewed changes) is re-injected into the compaction context so the post-compaction agent still knows what blocks completion.
-- ⚡ **No external services.** Everything is local: SQLite memory (Bun), LSP via `npx`, browser via Chrome CDP. Zero cloud dependencies, zero data leaves your machine.
+- ⚡ **No external services.** Everything is local: SQLite memory (Bun), LSP via `npx`, browser via local Lightpanda/Chrome CDP. Zero cloud dependencies, zero data leaves your machine.
 - 🪝 **One line to install.** No separate MCP server config, no manual wiring — `opencode plugin @hiai-gg/hiai-opencode@latest --global`.
 
 ---
@@ -54,7 +54,25 @@ cp bob.env.example bob.env
 # Edit bob.env — add FIRECRAWL_API_KEY for web scraping (optional)
 ```
 
-### 4. Verify
+### 4. (Optional) Install browser automation
+
+Vision's browser tools talk to a local engine over CDP. Engine selection is automatic: **Lightpanda** when its binary is on your PATH, **Chrome** otherwise.
+
+Install the CLI and provision the Chrome fallback:
+
+```bash
+bun add -g agent-browser && agent-browser install
+```
+
+**Lightpanda** ([lightpanda.io](https://lightpanda.io)) — optional, preferred when installed, headless-only. Separate user-level install via the official installer, not `cargo`:
+
+```bash
+curl -fsSL https://pkg.lightpanda.io/install.sh | bash
+```
+
+Force an engine per session with `AGENT_BROWSER_ENGINE=chrome|lightpanda`, or per run with `agent-browser --engine chrome|lightpanda open <url>`. Headed mode (`AGENT_BROWSER_HEADED=1`) works only with Chrome.
+
+### 5. Verify
 
 ```bash
 opencode debug config
@@ -72,7 +90,12 @@ Paste this into a fresh session:
 Read AGENTS.md and finish hiai-opencode setup for this workspace.
 Check that @hiai-gg/hiai-opencode is registered, enable MCP services that can run here
 (sequential-thinking: node/npx; grep_app: no key), verify with opencode debug config
-and hiai-opencode doctor. Report missing keys without printing secret values.
+and hiai-opencode doctor.
+Install and configure browser automation for Vision as documented in AGENTS.md:
+bun add -g agent-browser && agent-browser install, plus Lightpanda via its official
+installer when possible. Verify with agent-browser --version and lightpanda version
+(if installed), then run hiai-opencode doctor again.
+Report missing keys without printing secret values.
 ```
 
 ---
@@ -99,13 +122,15 @@ Bob routes work; the rest execute. Three are visible in the picker (you can invo
 ### Tools — 35 registered
 
 - **LSP (6)** — `lsp_diagnostics`, `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_prepare_rename`, `lsp_rename`. TypeScript, Svelte, ESLint, Python, Bash.
-- **Agent Browser (14)** — Navigate, snapshot, click, fill, screenshot, eval, console, and more. Native Chrome via CDP — no Playwright. Restricted to Vision/General agents.
+- **Agent Browser (14)** — Navigate, snapshot, click, fill, screenshot, eval, console, and more. CDP via Lightpanda (preferred when installed) or Chrome (fallback) — no Playwright. Restricted to Vision/General agents.
 - **Memory (1)** — `hiai_memory_search`: BM25-ranked SQLite FTS5 search over MEMORY.md, checkpoints, notes, and task progress.
 - **Session Manager (4)** — List, read, search, and inspect sessions.
 - **Worktree (4)** — `hiai_worktree_create`/`_list`/`_remove`/`_status` for isolated parallel work.
 - **Skills (1)** — `skill("build/shadcn-ui")`, `skill("explore/context7")`, etc.
 - **Firecrawl (3)** — Web scrape, search, sitemap (CLI skill, requires `FIRECRAWL_API_KEY`).
 
+**Browser engines (auto-selected):** the runtime prefers **Lightpanda** ([lightpanda.io](https://lightpanda.io); headless-only) when its binary is on your PATH and `AGENT_BROWSER_ENGINE` is unset; **Chrome** is the fallback. Override per session with `AGENT_BROWSER_ENGINE=chrome|lightpanda`, or per run with `agent-browser --engine chrome|lightpanda open <url>`. Headed mode (`AGENT_BROWSER_HEADED=1`) works only with Chrome. Lightpanda installs separately via its official installer (not `cargo`) — neither the npm plugin nor `agent-browser install` downloads it. See [Install](#install).
+
 ### MCP servers — 2, zero-config
 
 | Server | Type | Use |

assets/cli/hiai-opencode.mjs

@@ -236,6 +236,40 @@ function checkAgentBrowser() {
   }
 }
 
+// Resolve the effective agent-browser engine using the documented priority:
+//   1. explicit AGENT_BROWSER_ENGINE wins;
+//   2. otherwise lightpanda if its binary is on PATH;
+//   3. otherwise Chrome (the default and fallback engine).
+// Presence detection only — never installs or touches the network.
+function detectAgentBrowserEngine() {
+  const explicit = process.env.AGENT_BROWSER_ENGINE?.trim().toLowerCase() || ""
+  const lightpandaPresent = hasBinary("lightpanda")
+  const effective = explicit || (lightpandaPresent ? "lightpanda" : "chrome")
+  return { explicit, lightpandaPresent, effective }
+}
+
+function checkLightpandaPresence() {
+  const { lightpandaPresent } = detectAgentBrowserEngine()
+  if (lightpandaPresent) {
+    return { level: "ok", detail: "lightpanda binary found on PATH" }
+  }
+  // Missing Lightpanda is non-blocking (info): Chrome is the fallback engine.
+  return {
+    level: "info",
+    detail: "lightpanda not installed — Chrome fallback in effect (optional: curl -fsSL https://pkg.lightpanda.io/install.sh | bash)",
+  }
+}
+
+function checkAgentBrowserEngine() {
+  const { explicit, lightpandaPresent, effective } = detectAgentBrowserEngine()
+  const source = explicit
+    ? `explicit AGENT_BROWSER_ENGINE=${explicit}`
+    : lightpandaPresent
+      ? "auto (lightpanda binary on PATH)"
+      : "fallback (lightpanda not found)"
+  return { level: "info", detail: `effective engine=${effective} [${source}]` }
+}
+
 function checkOpenCodePluginRegistration() {
   for (const path of candidateOpenCodeConfigPaths()) {
     if (!existsSync(path)) continue
@@ -787,6 +821,7 @@ function hasEnvOrAuth(config, envName, authKey) {
 function statusIcon(level) {
   if (level === "ok") return "✅"
   if (level === "warn") return "⚠️ "
+  if (level === "info") return "ℹ️ "
   return "❌"
 }
 
@@ -879,6 +914,14 @@ async function mcpStatus(options = {}) {
     track(agentBrowser.level)
     outInfo(`${statusIcon(agentBrowser.level)} Agent-browser CLI - ${agentBrowser.detail}`)
 
+    const lightpanda = checkLightpandaPresence()
+    track(lightpanda.level)
+    outInfo(`${statusIcon(lightpanda.level)} Lightpanda engine - ${lightpanda.detail}`)
+
+    const engine = checkAgentBrowserEngine()
+    track(engine.level)
+    outInfo(`${statusIcon(engine.level)} Agent-browser effective engine - ${engine.detail}`)
+
     outInfo("")
     outInfo("MCP Tool Probes:")
     const probeResults = await probeMcpServers(config)
@@ -920,6 +963,7 @@ async function runDiagnose(outputPath) {
     "HIAI_OPENCODE_EXPORT_MCP_MODE",
     "CONTEXT7_API_KEY",
     "AGENT_BROWSER_SESSION",
+    "AGENT_BROWSER_ENGINE",
     "GREP_APP_API_KEY",
     "OLLAMA_BASE_URL",
     "OLLAMA_MODEL",