@vymalo/opencode-browser 0.7.0 → 0.7.1

package/README.md

@@ -31,7 +31,7 @@ flowchart LR
 - [Targeting elements](#targeting-elements--prefer-refs)
 - [Screenshots](#screenshots)
 - [Named groups](#named-groups)
-- [Scoping tools per agent](#scoping-tools-per-agent)
+- [Scoping tools and token cost](#scoping-tools-and-token-cost)
 - [Multiple browsers & agents](#multiple-browsers--agents)
 - [Executors: CDP vs content-script](#executors-cdp-vs-content-script)
 - [Stopping / releasing control](#stopping--releasing-control)
@@ -184,90 +184,76 @@ map to real `chrome.tabGroups` (titled, colored); on Firefox they're a logical r
 keep each task's tabs isolated and inspectable, and are the unit of ownership when multiple
 agents share one bridge.
 
-## Scoping tools per agent
+## Scoping tools and token cost
 
-There are **two independent levers**, and they answer different questions:
+Two levers, and they compose:
 
-| Lever | Scope | Use it to |
-| --- | --- | --- |
-| `groups` plugin option | **Global** — which tools are *registered* at all | Set the org-wide default surface. |
-| OpenCode agent `tools` map | **Per-agent** — which registered tools an agent may *call* | Give each agent only the tools it needs. |
-
-If your team keeps **all groups enabled by default** (`"groups": ["page","control","debug"]`),
-the `groups` option won't narrow anything — every `browser_*` tool is registered. To restrict an
-individual agent, use OpenCode's per-agent **`tools`** map (a `{ "<tool>": true|false }` record on
-the agent). The tool names are stable `browser_*` identifiers (see [the 33 tools](#the-33-tools)),
-so you target them directly. This is OpenCode's own mechanism — nothing plugin-specific.
-
-### Denylist — drop the sensitive tools (most common)
+- **`groups` (global)** — which tools are *registered* at all. The ceiling: an agent can only ever
+  be granted tools that are registered.
+- **Per-agent `permission` (per agent)** — which registered tools each agent actually gets. **In
+  the flat string form this trims the agent's injected tool list, so it genuinely cuts context
+  tokens** — not just execution.
 
-Keep everything except the `debug` group and destructive actions for a general agent:
+Approximate context cost of the full surface (tool name + description + args JSON schema the model
+sees — rough, ≈chars/4):
 
-```jsonc
-// opencode.json
-{
-  "plugin": [["@vymalo/opencode-browser", {}]],   // all groups stay registered
-  "agent": {
-    "build": {
-      "tools": {
-        "browser_eval": false,
-        "browser_cookies": false,
-        "browser_console": false,
-        "browser_network": false,
-        "browser_handle_dialog": false,
-        "browser_set_viewport": false,
-        "browser_close": false
-      }
-    }
-  }
-}
-```
-
-### Allowlist — a read-only research agent (observe, never drive)
-
-Disable the whole namespace with a wildcard, then re-enable only the `page` tools you want. A
-more specific key wins over the `browser_*` wildcard:
+| Registered `groups` | Tools | ≈ tokens (an agent granted all of them) |
+| --- | --- | --- |
+| `["page"]` | 8 | ~1,000 |
+| `["page","control"]` *(default)* | 27 | ~3,700 |
+| `["page","control","debug"]` | 33 | ~4,560 |
+| `debug` adds | 6 | ~830 |
+
+> ### ⚠️ Flat string vs nested — the token footgun
+> Per-agent scoping only reclaims tokens in the **flat string** `permission` form. The other forms
+> gate *execution* but still inject the schema (so they flood context):
+>
+> | Form | Example | Trims context? |
+> | --- | --- | --- |
+> | flat string `permission` | `"browser_eval": "deny"` | ✅ removed from the agent's tools |
+> | nested `permission` | `"browser_eval": { "*": "deny" }` | ❌ execution gate only |
+> | `tools` map (deprecated) | `"browser_eval": false` (≡ nested `{"*":"deny"}`) | ❌ execution gate only |
+>
+> Verified on OpenCode **1.17.6** — confirm on your version by checking an agent's actual context
+> token count with tools denied. (This is exactly the trap behind "registering a group floods every
+> agent": that observation comes from the `tools`-boolean / nested form.)
+
+### Recommended: register everything, scope per agent
+
+If your org wants the full surface available but **not** flooding every agent's context, register
+all groups once and give each agent only the tools it needs with **flat string** `permission`:
 
 ```jsonc
 {
+  // full surface registered once — global
+  "plugin": [["@vymalo/opencode-browser", { "groups": ["page", "control", "debug"] }]],
   "agent": {
     "researcher": {
-      "description": "Reads pages, never changes them.",
-      "tools": {
-        "browser_*": false,
-        "browser_open": true,
-        "browser_navigate": true,
-        "browser_snapshot": true,
-        "browser_get_text": true,
-        "browser_query": true,
-        "browser_screenshot": true,
-        "browser_tabs": true
+      // FLAT STRING form → denied tools are dropped from this agent's injected
+      // tools, so its context carries only the allowed ones.
+      "permission": {
+        "browser_*": "deny",          // start from nothing…
+        "browser_open": "allow",      // …allow only what this agent needs
+        "browser_navigate": "allow",
+        "browser_snapshot": "allow",
+        "browser_get_text": "allow",
+        "browser_query": "allow",
+        "browser_screenshot": "allow"
       }
-    }
+    },
+    "automator": { "permission": { "browser_*": "allow" } }   // full drive
   }
 }
 ```
 
-### Markdown agents
-
-The same `tools` map works in a `.opencode/agent/<name>.md` front-matter file:
-
-```markdown
----
-description: Reads pages, never changes them.
-tools:
-  browser_*: false
-  browser_snapshot: true
-  browser_get_text: true
-  browser_screenshot: true
----
-You are a read-only web researcher. Use browser_snapshot to get refs, then read.
-```
+(Specific keys override the `browser_*` wildcard. If you'd rather not rely on that precedence,
+list explicit `"deny"`s for the tools an agent shouldn't have instead of a wildcard.)
 
-> The plugin-level `groups` option is still useful as a hard floor — e.g. **never** register
-> `debug` org-wide with `{ "groups": ["page","control"] }`, then no agent can re-enable
-> `browser_eval` no matter its `tools` map. Use `groups` for "nobody gets this," and the agent
-> `tools` map for "this agent only gets these."
+If you don't need per-agent differences, just register the minimum union globally — `["page"]` for
+read-only research, `["page","control"]` to drive — and skip `debug` unless a workflow needs
+`eval`/`cookies`/`network`. Either way the schemas sit in the cached prefix, so prompt caching
+softens the per-request **dollar** cost; trimming still helps the context window and cache writes.
+See OpenCode's [agent docs](https://opencode.ai/docs/agents/) for the `permission` field.
 
 ## Multiple browsers & agents
 

package/dist/token-file.js

@@ -1,26 +1,58 @@
-import { chmodSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
 /**
  * Per-user state file so multiple adapters (plugin + MCP server) on one machine
- * share a bridge token without the operator wiring one up. Best-effort: a
- * simultaneous cold start can race (each generates its own token before either
- * writes); set an explicit token if you need that guaranteed. The extension
- * still needs the token pasted into its dashboard.
+ * share a bridge token without the operator wiring one up. It lives in the
+ * persistent per-OS app-data dir (NOT the temp dir), so a generated token
+ * survives reboots — you paste it into the extension once, not every session.
+ * Best-effort: a simultaneous cold start can race (each generates its own token
+ * before either writes); set an explicit token if you need that guaranteed.
  */
-const FILE = join(tmpdir(), "opencode-browser-bridge.json");
-export function readBridgeFile() {
+// Only honor an env-provided root if it's a usable absolute path — an empty or
+// relative value (e.g. exported `XDG_STATE_HOME=""`) would otherwise resolve the
+// state file relative to the process cwd, scattering per-directory tokens. Fall
+// back to the home-based default instead.
+function envRoot(value, fallback) {
+    return value && isAbsolute(value) ? value : fallback;
+}
+// Resolved lazily (not at module load) so a sandboxed homedir() failure can't
+// break import, and tests can vary process.env / platform between calls.
+function resolveStateRoot() {
+    if (process.platform === "win32") {
+        return envRoot(process.env.APPDATA, join(homedir(), "AppData", "Roaming"));
+    }
+    if (process.platform === "darwin") {
+        return join(homedir(), "Library", "Application Support");
+    }
+    return envRoot(process.env.XDG_STATE_HOME, join(homedir(), ".local", "state"));
+}
+function bridgeFilePath() {
+    return join(resolveStateRoot(), "opencode-browser", "bridge.json");
+}
+// ≤0.7.x kept this in the temp dir, where the OS clears it on reboot (so the
+// token kept changing). Read it once as a fallback so upgrading doesn't force a
+// re-paste; the next write migrates it to the persistent location above.
+function legacyBridgeFilePath() {
+    return join(tmpdir(), "opencode-browser-bridge.json");
+}
+function readFileAt(path) {
     try {
-        return JSON.parse(readFileSync(FILE, "utf8"));
+        return JSON.parse(readFileSync(path, "utf8"));
     }
     catch {
         return null;
     }
 }
+export function readBridgeFile() {
+    return readFileAt(bridgeFilePath()) ?? readFileAt(legacyBridgeFilePath());
+}
 export function writeBridgeFile(port, token) {
     try {
-        writeFileSync(FILE, JSON.stringify({ port, token }), { mode: 0o600 });
-        chmodSync(FILE, 0o600);
+        const file = bridgeFilePath();
+        mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+        writeFileSync(file, JSON.stringify({ port, token }), { mode: 0o600 });
+        chmodSync(file, 0o600);
     }
     catch {
         /* best-effort */

package/dist/token-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-file.js","sourceRoot":"","sources":["../src/token-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,8BAA8B,CAAC,CAAC;AAO5D,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAe,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,KAAa;IACzD,IAAI,CAAC;QACH,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACtE,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB;IACnB,CAAC;AACH,CAAC;AAID,yFAAyF;AACzF,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,QAA4B,EAC5B,QAAsB;IAEtB,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACjD,CAAC;IACD,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAC;IAClC,IAAI,QAAQ,EAAE,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/E,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IACnD,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACpD,CAAC"}
+{"version":3,"file":"token-file.js","sourceRoot":"","sources":["../src/token-file.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vymalo/opencode-browser",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "OpenCode plugin that gives the model hands in a real browser: it registers browser_* tools (open, click, type, scroll, screenshot, snapshot, …) and hosts a localhost WebSocket bridge that a companion Chromium/Firefox extension connects to. Tabs are organized into named groups so each task stays isolated and inspectable.",
   "license": "MIT",
   "author": "vymalo contributors",