opencode-browser-v2 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,386 @@
+# OpenCode Browser MCP Plugin (v2)
+
+An OpenCode plugin that integrates [Browser MCP](https://browsermcp.io) to enable browser automation capabilities within OpenCode. This plugin allows the AI to control a browser, navigate websites, fill forms, click elements, and perform other browser automation tasks.
+
+Published on npm as [`opencode-browser-v2`](https://www.npmjs.com/package/opencode-browser-v2). It is a fork of [michaljach/opencode-browser](https://github.com/michaljach/opencode-browser), ported to the **OpenCode v2 plugin API**. If you are still on OpenCode v1, use the original `opencode-browser` package instead.
+
+## Demo
+
+![Demo](assets/demo.gif)
+
+## Features
+
+- Full browser automation support through Browser MCP
+- **Speed-oriented browser guidance** injected into the model prompt
+- **Tool-specific performance hints** for expensive browser actions
+- **Fast retry behavior** with no artificial reconnect backoff in the plugin
+- Automatic detection of browser-related tasks
+- Context preservation for browser state across session compactions
+- Seamless integration with OpenCode's existing tools
+
+## Prerequisites
+
+Before using this plugin, you need:
+
+1. **Node.js** installed on your system
+2. **OpenCode** installed and configured
+3. **Browser MCP extension** installed in your browser (Chrome/Edge)
+
+## Installation
+
+### Step 1: Install Browser MCP Extension
+
+1. Visit [https://browsermcp.io/install](https://browsermcp.io/install)
+2. Install the Browser MCP extension for your browser (Chrome or Edge)
+3. Follow the extension setup instructions
+
+### Step 2: Configure OpenCode
+
+Fastest path:
+
+```bash
+npx opencode-browser-v2 init
+```
+
+This creates or updates `./opencode.json` with the required `plugins` and `mcp.servers.browsermcp` entries while preserving any unrelated config you already have.
+It also migrates a v1 config in place: `plugin` becomes `plugins`, servers move from `mcp.<name>` to `mcp.servers.<name>`, `agent` becomes `agents`, and the server's `enabled` flag becomes v2's `disabled` flag.
+
+For a global setup instead of a project-local one:
+
+```bash
+npx opencode-browser-v2 init --global
+```
+
+Create or update your `opencode.json` configuration file. You can create this file in one of two locations:
+
+- **Global configuration** (applies to all projects): `~/.config/opencode/opencode.json`
+- **Project-specific configuration** (applies to current project only): `./opencode.json` (in your project root)
+
+Learn more about OpenCode configuration at [https://opencode.ai/docs/config](https://opencode.ai/docs/config)
+
+Add this configuration to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-browser-v2"],
+  "mcp": {
+    "servers": {
+      "browsermcp": {
+        "type": "local",
+        "command": ["npx", "-y", "@browsermcp/mcp@0.1.3"]
+      }
+    }
+  }
+}
+```
+
+This configuration does two things:
+1. **Installs the plugin** - OpenCode automatically downloads `opencode-browser-v2` from npm
+2. **Configures Browser MCP** - Sets up the MCP server that actually controls the browser
+
+That's it! No manual file copying required. OpenCode handles everything automatically.
+
+The generated command pins the Browser MCP package version to avoid the extra `@latest` resolution step on startup and keep launches reproducible.
+
+If you prefer to preview the generated config without writing it yet:
+
+```bash
+npx opencode-browser-v2 init --print
+```
+
+#### Alternative: Install Locally (for development/testing)
+
+If you want to modify the plugin or test changes:
+
+**For global installation:**
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp src/index.ts ~/.config/opencode/plugins/browser-mcp.ts
+```
+
+**For project-specific installation:**
+```bash
+mkdir -p .opencode/plugins
+cp src/index.ts .opencode/plugins/browser-mcp.ts
+```
+
+The plugin will be automatically loaded on OpenCode startup.
+
+## Configuration
+
+### Basic Configuration
+
+The minimal configuration requires only the MCP server setup:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "browsermcp": {
+        "type": "local",
+        "command": ["npx", "-y", "@browsermcp/mcp@0.1.3"]
+      }
+    }
+  }
+}
+```
+
+MCP servers are enabled by default in v2. Set `"disabled": true` on a server to turn it off.
+
+### Advanced Configuration
+
+Define a dedicated agent for browser work under the v2 `agents` key:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "browsermcp": {
+        "type": "local",
+        "command": ["npx", "-y", "@browsermcp/mcp@0.1.3"]
+      }
+    }
+  },
+  "agents": {
+    "browser-agent": {
+      "description": "Agent specialized in browser automation tasks",
+      "mode": "primary"
+    }
+  }
+}
+```
+
+The v1 `tools` allow/deny maps (both the global one and the per-agent one) were replaced in v2 by the
+`permissions` policy list on an agent. See the OpenCode agent configuration docs for the action and
+resource names to use when scoping Browser MCP tools to a single agent.
+
+### Performance Behavior
+
+The plugin improves Browser MCP speed by shaping how the model uses browser tools:
+
+- Adds system guidance that prefers direct navigation and fewer browser calls
+- Annotates expensive tools like snapshots, screenshots, and waits with performance hints
+- Preserves fast-resume guidance during session compaction
+- Avoids plugin-side reconnect delays so you can retry immediately when the browser extension is ready
+
+### Environment Variables
+
+If you need to pass environment variables to the Browser MCP server:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "browsermcp": {
+        "type": "local",
+        "command": ["npx", "-y", "@browsermcp/mcp@0.1.3"],
+        "environment": {
+          "BROWSER_MCP_DEBUG": "true"
+        }
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+Once installed and configured, you can use browser automation in your OpenCode prompts:
+
+### Basic Browser Navigation
+
+```
+Navigate to https://github.com and search for "opencode"
+```
+
+### Form Filling
+
+```
+Go to the contact form at https://example.com/contact and fill in:
+- Name: John Doe
+- Email: john@example.com
+- Message: Hello from OpenCode!
+Then submit the form.
+```
+
+### Web Scraping
+
+```
+Visit https://news.ycombinator.com and get the titles of the top 5 stories
+```
+
+### Complex Automation
+
+```
+Go to https://example.com/login, log in with the test credentials,
+navigate to the dashboard, and screenshot the main metrics panel
+```
+
+### Prompt Tips
+
+For best results when using browser automation:
+
+1. **Be specific** about URLs and actions
+2. **Prefer direct URLs** instead of clicking through intermediate pages
+3. **Reuse page state** instead of rechecking the same screen repeatedly
+4. **Ask for verification only when needed** because snapshots and screenshots are slower than targeted extraction
+5. **Specify selectors** when needed (CSS selectors, text content, etc.)
+
+You can also add browser automation guidelines to your `AGENTS.md` file:
+
+```markdown
+## Browser Automation
+
+When performing browser automation tasks:
+- Always confirm the page has loaded before interacting
+- Use descriptive selectors (prefer text content over CSS selectors)
+- Take screenshots when verification is needed
+- Handle errors gracefully (page not found, element not visible, etc.)
+- Close tabs when the task is complete
+```
+
+## Plugin Features
+
+### Speed-Oriented Guidance
+
+The plugin biases the model toward faster browser workflows:
+
+- Prefers direct `navigate` calls when the destination URL is known
+- Reuses the current tab and page state instead of redoing navigation
+- Minimizes `snapshot`, `screenshot`, and `wait` calls unless they are actually needed
+- Encourages targeted extraction and direct actions over broad inspection
+
+### Lightweight Connection Recovery
+
+The plugin still detects browser connection issues, but it no longer adds artificial retry sleeps:
+
+- Detects common Browser MCP connection failures from tool output
+- Adds immediate retry guidance to the result instead of pausing inside the plugin
+- Marks the connection as restored after the next successful browser action
+
+### Automatic Browser Tool Detection
+
+The plugin automatically detects when Browser MCP tools are being used and applies browser-specific guidance.
+
+### Session Context Preservation
+
+During session compaction, the plugin preserves browser automation context, ensuring the AI remembers:
+- Browser interactions that occurred
+- Current browser state considerations
+- Fast-resume guidance so it can avoid repeating navigation and inspection
+
+### Tool Definition Hints
+
+The plugin annotates Browser MCP tool definitions with performance notes, especially for slower tools like snapshots, screenshots, and waits.
+
+## Troubleshooting
+
+### Browser MCP Connection Lost
+
+If you see connection errors:
+
+1. **Check extension status**: Verify the Browser MCP extension is enabled in Chrome
+2. **Re-enable extension**: If you disabled it, simply re-enable it and retry the browser action immediately
+3. **Check browser is running**: Ensure Chrome/Edge is actually running
+4. **Retry after readiness**: The plugin does not add extra backoff delay, so the next attempt can run right away
+5. **Restart only if needed**: Restart OpenCode only if the browser stays unavailable after retrying
+
+The plugin will display messages like:
+- `[Browser MCP] The browser connection looks unavailable. Re-enable the Browser MCP extension or browser, then retry.`
+- `[Browser MCP] Connection restored. Continuing without extra retry delay.`
+
+### Browser MCP Not Working
+
+1. **Check extension is installed**: Open your browser and verify the Browser MCP extension is installed and enabled
+2. **Verify MCP server config**: Ensure your `opencode.json` has the correct MCP configuration
+3. **Check Node.js**: Ensure Node.js is installed: `node --version`
+4. **Test MCP connection**: Restart OpenCode after adding the MCP configuration
+
+### Plugin Not Loading
+
+1. **Check file location**: Ensure the plugin file is in the correct directory
+2. **Check file name**: Plugin files should end in `.ts` or `.js`
+3. **Check syntax**: Ensure the TypeScript/JavaScript syntax is valid
+4. **Check logs**: Look for plugin initialization messages in OpenCode output
+
+### Tools Not Available
+
+1. **Check MCP server status**: Ensure the Browser MCP server started successfully
+2. **Check tool configuration**: Verify tools aren't disabled in your config
+3. **Restart OpenCode**: Try restarting OpenCode after configuration changes
+
+### Debug Mode
+
+Enable debug logging by modifying the plugin or checking OpenCode logs:
+
+```bash
+# Check OpenCode logs
+opencode --verbose
+```
+
+## Development
+
+### Building from Source
+
+If you want to modify the plugin:
+
+1. Clone the repository
+2. Run `npm install`
+3. Make your changes to `src/index.ts`
+4. Run `npm run typecheck`
+5. Test locally by copying to your OpenCode plugin directory
+6. Submit a PR if you'd like to contribute!
+
+### Plugin Architecture
+
+The plugin is an OpenCode **v2** plugin: it default-exports a `Plugin.define({ id, setup })` definition
+and registers everything through the setup context.
+
+| Registration | Purpose |
+| --- | --- |
+| `ctx.session.hook("context", ...)` | Inject speed-oriented browser guidance and append performance hints to Browser MCP tool descriptions |
+| `ctx.session.hook("generate", ...)` | Apply the same guidance to auxiliary generate requests |
+| `ctx.tool.hook("execute.after", ...)` | Post-process browser tool results and annotate connection failures |
+| `ctx.session.hook("compaction", ...)` | Preserve browser context across compaction |
+| `ctx.event.subscribe()` | Drop per-session state on `session.deleted` |
+
+The cleanup function returned by `setup` aborts the event subscription and clears session state; hook
+registrations are disposed by OpenCode automatically.
+
+Requires `@opencode/plugin` v2. For OpenCode v1, use the original [`opencode-browser`](https://www.npmjs.com/package/opencode-browser) package, which this project is a fork of.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Resources
+
+- [Browser MCP Documentation](https://docs.browsermcp.io/)
+- [OpenCode Documentation](https://opencode.ai/docs/)
+- [OpenCode Plugin Guide](https://opencode.ai/docs/plugins/)
+- [MCP Servers in OpenCode](https://opencode.ai/docs/mcp-servers/)
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Support
+
+For issues and questions:
+
+- Browser MCP issues: [Browser MCP GitHub](https://github.com/browsermcp/browser-mcp)
+- OpenCode issues: [OpenCode GitHub](https://github.com/anomalyco/opencode)
+- Plugin issues: [Open an issue](https://github.com/barrenechea/opencode-browser-v2/issues) in this repository
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes in each version.

package/bin/opencode-browser.js

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, resolve } from "node:path"
+
+const schemaUrl = "https://opencode.ai/config.json"
+const pluginName = "opencode-browser-v2"
+const legacyPluginName = "opencode-browser"
+const serverName = "browsermcp"
+const browserMcpVersion = "0.1.3"
+const legacyBrowserMcpCommand = ["npx", "-y", "@browsermcp/mcp@latest"]
+const defaultBrowserMcpConfig = {
+  type: "local",
+  command: ["npx", "-y", `@browsermcp/mcp@${browserMcpVersion}`],
+}
+
+function isSameCommand(actual, expected) {
+  return Array.isArray(actual) &&
+    actual.length === expected.length &&
+    actual.every((value, index) => value === expected[index])
+}
+
+function printUsage() {
+  console.log(`Usage: opencode-browser-v2 [init] [--project|--global|--path <file>] [--print]\n\n` +
+    `Examples:\n` +
+    `  npx opencode-browser-v2 init\n` +
+    `  npx opencode-browser-v2 init --global\n` +
+    `  npx opencode-browser-v2 init --path ./opencode.json\n` +
+    `  npx opencode-browser-v2 init --print`)
+}
+
+function parseArgs(argv) {
+  const args = [...argv]
+  let command = "init"
+
+  if (args[0] && !args[0].startsWith("-")) {
+    command = args.shift()
+  }
+
+  const options = {
+    mode: "project",
+    configPath: undefined,
+    printOnly: false,
+  }
+
+  while (args.length > 0) {
+    const arg = args.shift()
+
+    if (arg === "--global") {
+      options.mode = "global"
+      continue
+    }
+
+    if (arg === "--project") {
+      options.mode = "project"
+      continue
+    }
+
+    if (arg === "--path") {
+      const customPath = args.shift()
+
+      if (!customPath) {
+        throw new Error("Missing value for --path")
+      }
+
+      options.configPath = customPath
+      continue
+    }
+
+    if (arg === "--print") {
+      options.printOnly = true
+      continue
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true
+      continue
+    }
+
+    throw new Error(`Unknown argument: ${arg}`)
+  }
+
+  return { command, options }
+}
+
+function loadConfig(targetPath) {
+  if (!existsSync(targetPath)) {
+    return {}
+  }
+
+  const raw = readFileSync(targetPath, "utf8")
+
+  try {
+    const parsed = JSON.parse(raw)
+
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("Config must be a JSON object")
+    }
+
+    return parsed
+  } catch (error) {
+    throw new Error(`Unable to parse ${targetPath}: ${error.message}`)
+  }
+}
+
+function ensureObject(value, fieldName) {
+  if (value === undefined) {
+    return {}
+  }
+
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`The "${fieldName}" field must be an object`)
+  }
+
+  return { ...value }
+}
+
+/**
+ * V2 plugin entries are either a package name or `{ package, options }`. V1 also allowed a
+ * `[package, options]` tuple, so tuples are folded into the object form on the way through.
+ */
+function normalizePluginEntry(entry, fieldName) {
+  if (typeof entry === "string") {
+    return { entry, package: entry, migrated: false }
+  }
+
+  if (Array.isArray(entry)) {
+    const [packageName, packageOptions] = entry
+
+    if (typeof packageName !== "string") {
+      throw new Error(`Every "${fieldName}" tuple must start with a package name`)
+    }
+
+    return {
+      entry: packageOptions === undefined
+        ? packageName
+        : { package: packageName, options: packageOptions },
+      package: packageName,
+      migrated: true,
+    }
+  }
+
+  if (entry && typeof entry === "object" && typeof entry.package === "string") {
+    return { entry: { ...entry }, package: entry.package, migrated: false }
+  }
+
+  throw new Error(`Every "${fieldName}" entry must be a package name, a { package, options } object, or a [package, options] tuple`)
+}
+
+function normalizePlugins(pluginField, fieldName) {
+  if (pluginField === undefined) {
+    return { entries: [], migrated: false }
+  }
+
+  const rawEntries = Array.isArray(pluginField) ? pluginField : [pluginField]
+  const entries = []
+  let migrated = false
+
+  for (const rawEntry of rawEntries) {
+    const normalized = normalizePluginEntry(rawEntry, fieldName)
+    migrated = migrated || normalized.migrated
+
+    if (entries.some((existing) => existing.package === normalized.package)) {
+      continue
+    }
+
+    entries.push(normalized)
+  }
+
+  return { entries, migrated }
+}
+
+function mergePlugins(config, changes) {
+  const fromV2 = normalizePlugins(config.plugins, "plugins")
+  const fromV1 = normalizePlugins(config.plugin, "plugin")
+
+  const entries = [...fromV2.entries]
+
+  for (const candidate of fromV1.entries) {
+    if (entries.some((existing) => existing.package === candidate.package)) {
+      continue
+    }
+
+    entries.push(candidate)
+  }
+
+  if (config.plugin !== undefined) {
+    delete config.plugin
+    changes.push('migrated "plugin" to the v2 "plugins" field')
+  } else if (fromV2.migrated) {
+    changes.push('normalized "plugins" entries to the v2 object form')
+  }
+
+  // The v1 package does not run under OpenCode v2, so point an existing entry at this package.
+  const legacy = entries.find((existing) => existing.package === legacyPluginName)
+
+  if (legacy && !entries.some((existing) => existing.package === pluginName)) {
+    legacy.package = pluginName
+    legacy.entry = typeof legacy.entry === "string"
+      ? pluginName
+      : { ...legacy.entry, package: pluginName }
+    changes.push(`replaced the v1 "${legacyPluginName}" plugin with "${pluginName}"`)
+  } else if (legacy) {
+    entries.splice(entries.indexOf(legacy), 1)
+    changes.push(`removed the superseded v1 "${legacyPluginName}" plugin`)
+  }
+
+  if (!entries.some((existing) => existing.package === pluginName)) {
+    entries.push({ entry: pluginName, package: pluginName })
+    changes.push(`enabled ${pluginName} plugin`)
+  }
+
+  config.plugins = entries.map((existing) => existing.entry)
+}
+
+/**
+ * V2 nests servers under `mcp.servers`; V1 put them directly on `mcp`. Anything on `mcp` other
+ * than the two v2 keys is therefore a v1 server entry that needs relocating.
+ */
+function mergeMcp(config, changes) {
+  const mcp = ensureObject(config.mcp, "mcp")
+  const servers = ensureObject(mcp.servers, "mcp.servers")
+  const legacyNames = Object.keys(mcp).filter((key) => key !== "servers" && key !== "timeout")
+
+  for (const name of legacyNames) {
+    servers[name] = { ...servers[name], ...ensureObject(mcp[name], `mcp.${name}`) }
+    delete mcp[name]
+  }
+
+  if (legacyNames.length > 0) {
+    changes.push(`moved ${legacyNames.length} MCP server${legacyNames.length === 1 ? "" : "s"} under "mcp.servers"`)
+  }
+
+  const browsermcp = ensureObject(servers[serverName], `mcp.servers.${serverName}`)
+
+  if (browsermcp.type === undefined) {
+    browsermcp.type = defaultBrowserMcpConfig.type
+    changes.push("set Browser MCP type")
+  }
+
+  if (browsermcp.command === undefined) {
+    browsermcp.command = [...defaultBrowserMcpConfig.command]
+    changes.push("set Browser MCP command")
+  } else if (isSameCommand(browsermcp.command, legacyBrowserMcpCommand)) {
+    browsermcp.command = [...defaultBrowserMcpConfig.command]
+    changes.push("pinned Browser MCP command version")
+  }
+
+  // V2 replaced the `enabled` flag with `disabled`; servers are enabled by default.
+  if (browsermcp.enabled !== undefined) {
+    const wasEnabled = browsermcp.enabled !== false
+    delete browsermcp.enabled
+
+    if (wasEnabled) {
+      delete browsermcp.disabled
+    } else {
+      browsermcp.disabled = true
+    }
+
+    changes.push('replaced the v1 "enabled" flag with the v2 "disabled" flag')
+  }
+
+  servers[serverName] = browsermcp
+  mcp.servers = servers
+  config.mcp = mcp
+}
+
+function mergeAgents(config, changes) {
+  if (config.agent === undefined) {
+    return
+  }
+
+  const legacyAgents = ensureObject(config.agent, "agent")
+  const agents = ensureObject(config.agents, "agents")
+
+  for (const [name, definition] of Object.entries(legacyAgents)) {
+    if (agents[name] === undefined) {
+      agents[name] = definition
+    }
+  }
+
+  delete config.agent
+  config.agents = agents
+  changes.push('migrated "agent" to the v2 "agents" field')
+}
+
+function mergeConfig(config) {
+  const nextConfig = { ...config }
+  const changes = []
+
+  if (!nextConfig.$schema) {
+    nextConfig.$schema = schemaUrl
+    changes.push("added OpenCode schema")
+  }
+
+  mergePlugins(nextConfig, changes)
+  mergeMcp(nextConfig, changes)
+  mergeAgents(nextConfig, changes)
+
+  return { nextConfig, changes }
+}
+
+function getTargetPath(mode, customPath) {
+  if (customPath) {
+    return resolve(customPath)
+  }
+
+  if (mode === "global") {
+    return resolve(homedir(), ".config/opencode/opencode.json")
+  }
+
+  return resolve(process.cwd(), "opencode.json")
+}
+
+async function main() {
+  try {
+    const { command, options } = parseArgs(process.argv.slice(2))
+
+    if (options.help) {
+      printUsage()
+      return
+    }
+
+    if (command !== "init") {
+      throw new Error(`Unknown command: ${command}`)
+    }
+
+    const targetPath = getTargetPath(options.mode, options.configPath)
+    const hadExistingConfig = existsSync(targetPath)
+    const config = loadConfig(targetPath)
+    const { nextConfig, changes } = mergeConfig(config)
+    const output = `${JSON.stringify(nextConfig, null, 2)}\n`
+
+    if (options.printOnly) {
+      process.stdout.write(output)
+      return
+    }
+
+    mkdirSync(dirname(targetPath), { recursive: true })
+    writeFileSync(targetPath, output)
+
+    const action = hadExistingConfig ? "Updated" : "Created"
+    console.log(`${action} ${targetPath}`)
+
+    if (changes.length === 0) {
+      console.log("No changes were needed; Browser MCP is already configured.")
+      return
+    }
+
+    console.log(`Applied ${changes.length} change${changes.length === 1 ? "" : "s"}:`)
+    for (const change of changes) {
+      console.log(`- ${change}`)
+    }
+  } catch (error) {
+    console.error(`[opencode-browser-v2] ${error.message}`)
+    printUsage()
+    process.exitCode = 1
+  }
+}
+
+await main()

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "opencode-browser-v2",
+  "version": "2.0.0",
+  "description": "OpenCode plugin that integrates Browser MCP for browser automation",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "bin": {
+    "opencode-browser-v2": "bin/opencode-browser.js"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "browser",
+    "browser-automation",
+    "mcp",
+    "model-context-protocol",
+    "automation",
+    "browser-control",
+    "web-automation",
+    "puppeteer-alternative",
+    "opencode-v2"
+  ],
+  "author": "barrenechea",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/barrenechea/opencode-browser-v2.git"
+  },
+  "homepage": "https://github.com/barrenechea/opencode-browser-v2#readme",
+  "bugs": {
+    "url": "https://github.com/barrenechea/opencode-browser-v2/issues"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "^2.0.11",
+    "@types/node": "^26.6.2",
+    "typescript": "^7.0.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,345 @@
+import { Plugin } from "@opencode/plugin"
+import { Error as ToolError } from "@opencode/plugin/promise/tool"
+import type { Result as ToolResult } from "@opencode/plugin/promise/tool"
+import type { Context } from "@opencode/plugin/promise/plugin"
+import type { SessionContext } from "@opencode/plugin/promise/session"
+
+/** One entry of the structured `content` list a tool result may carry. */
+type ToolContent = Exclude<ToolResult["content"], string | undefined>[number]
+
+interface ConnectionState {
+  isConnected: boolean
+  lastError?: string
+  failureCount: number
+}
+
+const BROWSER_TOOL_PREFIX = "browsermcp_"
+
+const browserSpeedGuidance = `When using Browser MCP, optimize for speed:
+- Prefer direct URL navigation over click-through flows when the destination is known.
+- Reuse the current tab and page state instead of repeating navigation.
+- Minimize snapshots, screenshots, and waits; use them only after a page change or when visual confirmation is required.
+- Prefer targeted extraction or direct actions over broad inspection.
+- Finish the task in the fewest browser actions that still preserve correctness.`
+
+const browserCompactionContext = `## Browser Automation Context
+
+Browser MCP was used in this session. When resuming:
+- Assume the current browser tab may still be useful.
+- Check browser state once, then reuse it instead of repeating navigation.
+- Prefer direct navigation, extraction, and targeted actions over repeated snapshots or screenshots.
+- Use waits only when the page is still loading or an interaction has not settled yet.`
+
+const browserToolHints = [
+  {
+    suffixes: ["_browser_navigate", "_navigate"],
+    hint: "Prefer this when you already know the destination URL instead of clicking through intermediate pages.",
+  },
+  {
+    suffixes: ["_browser_snapshot", "_snapshot"],
+    hint: "This is relatively expensive. Reuse the latest snapshot unless the page changed or you need fresh element references.",
+  },
+  {
+    suffixes: ["_browser_screenshot", "_screenshot"],
+    hint: "Use only when the user needs visual confirmation. Prefer extraction or targeted checks for faster workflows.",
+  },
+  {
+    suffixes: ["_browser_wait", "_wait"],
+    hint: "Use only when content is still loading or an interaction has not settled. Avoid fixed waits when the next action can validate readiness.",
+  },
+] as const
+
+const connectionErrorPatterns = [
+  /econnrefused/i,
+  /connection refused/i,
+  /failed to connect/i,
+  /could not connect/i,
+  /browser\s*mcp.*(?:disconnected|unavailable|not connected)/i,
+  /extension.*(?:disabled|disconnected|not connected|unavailable)/i,
+  /websocket.*(?:closed|failed)/i,
+  /timed out while connecting/i,
+]
+
+const isBrowserTool = (toolID: string): boolean => toolID.startsWith(BROWSER_TOOL_PREFIX)
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+}
+
+const appendSection = (base: string, section: string): string => {
+  const trimmedSection = section.trim()
+
+  if (!trimmedSection) {
+    return base
+  }
+
+  if (!base) {
+    return trimmedSection
+  }
+
+  if (base.includes(trimmedSection)) {
+    return base
+  }
+
+  return `${base.trimEnd()}\n\n${trimmedSection}`
+}
+
+const stringifyOutput = (value: unknown): string => {
+  if (typeof value === "string") {
+    return value
+  }
+
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return String(value)
+  }
+}
+
+const getFailureFlag = (value: Record<string, unknown>): boolean => {
+  if (value.success === false || value.ok === false) {
+    return true
+  }
+
+  if (value.isError === true || value.error === true) {
+    return true
+  }
+
+  return false
+}
+
+const getConnectionErrorText = (value: unknown): string | undefined => {
+  if (typeof value === "string") {
+    return value
+  }
+
+  if (!isRecord(value)) {
+    return undefined
+  }
+
+  if (typeof value.error === "string") {
+    return value.error
+  }
+
+  if (typeof value.stderr === "string") {
+    return value.stderr
+  }
+
+  if (!getFailureFlag(value)) {
+    return undefined
+  }
+
+  for (const field of ["message", "details"] as const) {
+    if (typeof value[field] === "string") {
+      return value[field]
+    }
+  }
+
+  return undefined
+}
+
+const matchesConnectionError = (text: string | undefined): boolean => {
+  if (!text) {
+    return false
+  }
+
+  return connectionErrorPatterns.some((pattern) => pattern.test(text))
+}
+
+const isConnectionError = (value: unknown): boolean => matchesConnectionError(getConnectionErrorText(value))
+
+const getToolHint = (toolID: string): string => {
+  for (const { suffixes, hint } of browserToolHints) {
+    if (suffixes.some((suffix) => toolID.endsWith(suffix))) {
+      return hint
+    }
+  }
+
+  return "Prefer the smallest action that advances the task, and avoid redundant browser calls when the current page state is already known."
+}
+
+/**
+ * Tool results carry `content` as either a plain string or a list of content parts.
+ * Both shapes need the hint appended without dropping any other part of the result.
+ */
+const appendResultSection = (result: ToolResult, section: string): ToolResult => {
+  const { content } = result
+
+  if (content === undefined) {
+    return { ...result, content: section }
+  }
+
+  if (typeof content === "string") {
+    return { ...result, content: appendSection(content, section) }
+  }
+
+  const alreadyPresent = content.some((part: ToolContent) => part.type === "text" && part.text.includes(section))
+
+  if (alreadyPresent) {
+    return result
+  }
+
+  return { ...result, content: [...content, { type: "text", text: section }] }
+}
+
+/**
+ * A tool result is a success shape, so connection failures surface either as a
+ * thrown `ToolError` or as an error-flavoured payload inside the result.
+ */
+const resultHasConnectionError = (result: ToolResult): boolean => {
+  if (isConnectionError(result.output)) {
+    return true
+  }
+
+  const { content } = result
+
+  if (content === undefined) {
+    return false
+  }
+
+  if (typeof content === "string") {
+    return matchesConnectionError(content)
+  }
+
+  return content.some((part: ToolContent) => part.type === "text" && matchesConnectionError(part.text))
+}
+
+export default Plugin.define({
+  id: "opencode-browser-v2",
+  async setup(ctx: Context) {
+    const browserSessions = new Set<string>()
+    const connectionStates = new Map<string, ConnectionState>()
+    const controller = new AbortController()
+
+    const getConnectionState = (sessionID: string): ConnectionState => {
+      const existingState = connectionStates.get(sessionID)
+
+      if (existingState) {
+        return existingState
+      }
+
+      const nextState: ConnectionState = {
+        isConnected: true,
+        failureCount: 0,
+      }
+
+      connectionStates.set(sessionID, nextState)
+      return nextState
+    }
+
+    const markConnectionFailed = (sessionID: string, error: unknown) => {
+      const connectionState = getConnectionState(sessionID)
+      connectionState.isConnected = false
+      connectionState.failureCount += 1
+      connectionState.lastError = stringifyOutput(error)
+      return connectionState
+    }
+
+    const resetConnectionState = (sessionID: string) => {
+      const connectionState = getConnectionState(sessionID)
+      connectionState.isConnected = true
+      connectionState.failureCount = 0
+      connectionState.lastError = undefined
+    }
+
+    const disconnectedHint = (failureCount: number): string =>
+      failureCount === 1
+        ? "[Browser MCP] The browser connection looks unavailable. Re-enable the Browser MCP extension or browser, then retry. The plugin skips delayed backoff so the next attempt can run immediately."
+        : `[Browser MCP] Browser connection is still unavailable (failure ${failureCount}). Retry as soon as the extension is ready.`
+
+    const restoredHint = "[Browser MCP] Connection restored. Continuing without extra retry delay."
+
+    /**
+     * Applied to every model-request kind that carries tools, so the guidance and the
+     * per-tool performance hints reach the model no matter which loop is running.
+     */
+    const applyBrowserContext = (event: SessionContext) => {
+      const last = event.system.length - 1
+
+      if (last >= 0) {
+        const part = event.system[last]
+
+        if (!part.text.includes(browserSpeedGuidance)) {
+          event.system[last] = { ...part, text: appendSection(part.text, browserSpeedGuidance) }
+        }
+      } else {
+        event.system.push({ type: "text", text: browserSpeedGuidance })
+      }
+
+      for (const [toolID, definition] of Object.entries(event.tools)) {
+        if (!isBrowserTool(toolID)) {
+          continue
+        }
+
+        definition.description = appendSection(definition.description, `Performance: ${getToolHint(toolID)}`)
+      }
+    }
+
+    await ctx.session.hook("context", applyBrowserContext)
+    await ctx.session.hook("generate", applyBrowserContext)
+
+    await ctx.tool.hook("execute.after", (event) => {
+      if (!isBrowserTool(event.tool)) {
+        return
+      }
+
+      browserSessions.add(event.sessionID)
+      const connectionState = getConnectionState(event.sessionID)
+
+      if (event.status === "error") {
+        if (!matchesConnectionError(event.error.message)) {
+          return
+        }
+
+        const { failureCount } = markConnectionFailed(event.sessionID, event.error.message)
+
+        event.error = new ToolError({
+          message: appendSection(event.error.message, disconnectedHint(failureCount)),
+          error: event.error.error,
+          metadata: event.error.metadata,
+        })
+        return
+      }
+
+      if (resultHasConnectionError(event.result)) {
+        const { failureCount } = markConnectionFailed(event.sessionID, event.result.output ?? event.result.content)
+        event.result = appendResultSection(event.result, disconnectedHint(failureCount))
+        return
+      }
+
+      if (!connectionState.isConnected) {
+        resetConnectionState(event.sessionID)
+        event.result = appendResultSection(event.result, restoredHint)
+      }
+    })
+
+    await ctx.session.hook("compaction", (event) => {
+      if (browserSessions.has(event.sessionID)) {
+        event.system.push({ type: "text", text: browserCompactionContext })
+      }
+    })
+
+    void (async () => {
+      try {
+        for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+          if (event.type !== "session.deleted") {
+            continue
+          }
+
+          browserSessions.delete(event.data.sessionID)
+          connectionStates.delete(event.data.sessionID)
+        }
+      } catch (error) {
+        if (!controller.signal.aborted) {
+          throw error
+        }
+      }
+    })()
+
+    return () => {
+      controller.abort()
+      browserSessions.clear()
+      connectionStates.clear()
+    }
+  },
+})