jeo-code 0.7.32 → 0.7.33

package/CHANGELOG.md

@@ -6,6 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+## [0.7.33] - 2026-07-04
+_Adds `browser` — headless Chromium automation (gjc `browser` parity) — completing the gjc tool-surface parity pass started in 0.7.32._
+
+### Added
+- **`browser` — headless Chromium automation via Playwright (gjc `browser` parity, headless-only for v1 — no existing-profile/CDP-endpoint/Electron attach, no stealth patches).** `browser-session.ts` keeps one shared browser instance alive across calls with named tabs reused ("open once, act many times"); `browser-tab.ts` provides `observe()`-first helpers (tags interactive elements with stable numeric ids instead of a raw DOM dump or a screenshot) plus `click`/`type`/`fill`/`select`/`press`/`scroll`/`goto`/`back`/`extract`/`screenshot`/`evaluate`. The `browser` tool exposes `open`/`close`/`run`/`act`: `act` runs structured steps (navigate/click/type/fill/select/press/scroll/back/wait/observe/extract/screenshot) addressed by numeric `id` (from a prior `observe`) or CSS selector; `run` executes an async-function body with `page`/`browser`/`tab`/`display`/`assert`/`wait` in scope for anything the structured verbs don't cover. Mutating (drives a real browser, `run` executes arbitrary host JS) — excluded from read-only subagent roles. `playwright` moves from `devDependencies` to `dependencies` (it was already bundled for jeo-code's own test suite, so this reuses it rather than adding a second browser-automation engine).
+
+### Verified
+- `bun run typecheck` clean; full suite green.
+- New coverage: `test/browser-tool.test.ts` (open/act round-trip against real headless Chromium — observe → type → click → extract, `run` with display/assert, screenshot-to-file, close/close-all, and error-path guards) with `test.skipIf` fallbacks for environments without the Chromium binary downloaded; `test/subagent-toolset-gating.test.ts` extended to assert `browser` is excluded from every read-only role.
+
 ## [0.7.32] - 2026-07-03
 _gjc tool-surface parity — ast_grep/ast_edit, lsp/lsp_rename, debug, irc, job, and goal tools — plus a `launch.ts` slash-command refactor and four agent-loop guardrail hardenings (destructive-bash denylist, spawn-gate justification quality check, done-verification abuse guard, and a blind unanchored line-range-edit guard)._
 

package/README.ja.md

@@ -207,11 +207,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.33]** (2026-07-04) — Adds `browser` — headless Chromium automation (gjc `browser` parity) — completing the gjc tool-surface parity pass started in 0.7.32.
 - **[0.7.32]** (2026-07-03) — gjc tool-surface parity — ast_grep/ast_edit, lsp/lsp_rename, debug, irc, job, and goal tools — plus a `launch.ts` slash-command refactor and four agent-loop guardrail hardenings (destructive-bash denylist, spawn-gate justification quality check, done-verification abuse guard, and a blind unanchored line-range-edit guard).
 - **[0.7.31]** (2026-07-03) — Three-round speed & memory pass across streaming, memory retrieval, and the TUI render loop (O(n²) → O(n) in several hot paths), a deep-interview repeat-question loop guard, and gajae-code managed-tmux launch sizing parity.
 - **[0.7.30]** (2026-07-02) — GPT/Codex OAuth calls work again, and the 30-minute turn budget now limits no-progress stalls instead of killing genuinely progressing autonomous runs.
 - **[0.7.29]** (2026-07-02) — gajae-code safety-refusal retry parity: Anthropic/OAuth content-classifier refusals no longer end the turn with a fatal "declined to answer" message after the context-reset ladder.
-- **[0.7.28]** (2026-07-02) — gajae-code 0.7.9–0.7.10 OAuth + model-execution parity: generic long rate-limit windows are retried (never fatal), retry waits are abort-cancellable, Codex prompt caching via session correlation, and the Kimi Code device-flow OAuth is completed end-to-end (catalog, gating, discovery, tests).
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -207,11 +207,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.33]** (2026-07-04) — Adds `browser` — headless Chromium automation (gjc `browser` parity) — completing the gjc tool-surface parity pass started in 0.7.32.
 - **[0.7.32]** (2026-07-03) — gjc tool-surface parity — ast_grep/ast_edit, lsp/lsp_rename, debug, irc, job, and goal tools — plus a `launch.ts` slash-command refactor and four agent-loop guardrail hardenings (destructive-bash denylist, spawn-gate justification quality check, done-verification abuse guard, and a blind unanchored line-range-edit guard).
 - **[0.7.31]** (2026-07-03) — Three-round speed & memory pass across streaming, memory retrieval, and the TUI render loop (O(n²) → O(n) in several hot paths), a deep-interview repeat-question loop guard, and gajae-code managed-tmux launch sizing parity.
 - **[0.7.30]** (2026-07-02) — GPT/Codex OAuth calls work again, and the 30-minute turn budget now limits no-progress stalls instead of killing genuinely progressing autonomous runs.
 - **[0.7.29]** (2026-07-02) — gajae-code safety-refusal retry parity: Anthropic/OAuth content-classifier refusals no longer end the turn with a fatal "declined to answer" message after the context-reset ladder.
-- **[0.7.28]** (2026-07-02) — gajae-code 0.7.9–0.7.10 OAuth + model-execution parity: generic long rate-limit windows are retried (never fatal), retry waits are abort-cancellable, Codex prompt caching via session correlation, and the Kimi Code device-flow OAuth is completed end-to-end (catalog, gating, discovery, tests).
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -234,11 +234,11 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.33]** (2026-07-04) — Adds `browser` — headless Chromium automation (gjc `browser` parity) — completing the gjc tool-surface parity pass started in 0.7.32.
 - **[0.7.32]** (2026-07-03) — gjc tool-surface parity — ast_grep/ast_edit, lsp/lsp_rename, debug, irc, job, and goal tools — plus a `launch.ts` slash-command refactor and four agent-loop guardrail hardenings (destructive-bash denylist, spawn-gate justification quality check, done-verification abuse guard, and a blind unanchored line-range-edit guard).
 - **[0.7.31]** (2026-07-03) — Three-round speed & memory pass across streaming, memory retrieval, and the TUI render loop (O(n²) → O(n) in several hot paths), a deep-interview repeat-question loop guard, and gajae-code managed-tmux launch sizing parity.
 - **[0.7.30]** (2026-07-02) — GPT/Codex OAuth calls work again, and the 30-minute turn budget now limits no-progress stalls instead of killing genuinely progressing autonomous runs.
 - **[0.7.29]** (2026-07-02) — gajae-code safety-refusal retry parity: Anthropic/OAuth content-classifier refusals no longer end the turn with a fatal "declined to answer" message after the context-reset ladder.
-- **[0.7.28]** (2026-07-02) — gajae-code 0.7.9–0.7.10 OAuth + model-execution parity: generic long rate-limit windows are retried (never fatal), retry waits are abort-cancellable, Codex prompt caching via session correlation, and the Kimi Code device-flow OAuth is completed end-to-end (catalog, gating, discovery, tests).
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -207,11 +207,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.33]** (2026-07-04) — Adds `browser` — headless Chromium automation (gjc `browser` parity) — completing the gjc tool-surface parity pass started in 0.7.32.
 - **[0.7.32]** (2026-07-03) — gjc tool-surface parity — ast_grep/ast_edit, lsp/lsp_rename, debug, irc, job, and goal tools — plus a `launch.ts` slash-command refactor and four agent-loop guardrail hardenings (destructive-bash denylist, spawn-gate justification quality check, done-verification abuse guard, and a blind unanchored line-range-edit guard).
 - **[0.7.31]** (2026-07-03) — Three-round speed & memory pass across streaming, memory retrieval, and the TUI render loop (O(n²) → O(n) in several hot paths), a deep-interview repeat-question loop guard, and gajae-code managed-tmux launch sizing parity.
 - **[0.7.30]** (2026-07-02) — GPT/Codex OAuth calls work again, and the 30-minute turn budget now limits no-progress stalls instead of killing genuinely progressing autonomous runs.
 - **[0.7.29]** (2026-07-02) — gajae-code safety-refusal retry parity: Anthropic/OAuth content-classifier refusals no longer end the turn with a fatal "declined to answer" message after the context-reset ladder.
-- **[0.7.28]** (2026-07-02) — gajae-code 0.7.9–0.7.10 OAuth + model-execution parity: generic long rate-limit windows are retried (never fatal), retry waits are abort-cancellable, Codex prompt caching via session correlation, and the Kimi Code device-flow OAuth is completed end-to-end (catalog, gating, discovery, tests).
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.7.32",
+  "version": "0.7.33",
 
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
@@ -61,11 +61,11 @@
     "zod": "^3.24.1",
     "chalk": "^5.3.0",
     "js-tiktoken": "^1.0.21",
-    "typescript": "^5.6.3"
+    "typescript": "^5.6.3",
+    "playwright": "^1.61.0"
   },
   "devDependencies": {
     "@types/bun": "^1.1.14",
-    "playwright": "^1.61.0",
     "ws": "^8.21.0"
   },
   "packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800"

package/src/agent/AGENTS.md

@@ -17,6 +17,9 @@ The core runtime loop, tool registry, session management, and state persistence
 | `debug-session.ts` | In-process CDP (V8 Inspector Protocol) client driving a spawned `node --inspect-brk` process (gjc `debug` parity, Node.js only — not Bun, whose inspector speaks a different WebKit dialect); one active session, singleton |
 | `debug-tool.ts` | `debug` tool — launch/set_breakpoint/continue/step/evaluate/stack_trace/scopes/variables/threads/output/terminate via `debug-session.ts`; mutating (runs arbitrary code), excluded from read-only roles |
 | `lsp-rename-tool.ts` | `lsp_rename` tool — cross-file TypeScript/JavaScript rename; mutating, writes via `writeTool`, kept separate from `lsp` so read-only roles can't reach it |
+| `browser-session.ts` | Named-tab headless-Chromium session registry (gjc `browser` parity, via Playwright — already a jeo-code dependency) — one shared browser instance launched lazily, tabs reused by name across calls |
+| `browser-tab.ts` | Per-tab helpers (`observe`/`click`/`type`/`fill`/`select`/`press`/`scroll`/`goto`/`back`/`extract`/`screenshot`/`evaluate`) — `observe()` tags interactive elements with stable numeric ids instead of returning a raw DOM dump or requiring a screenshot |
+| `browser-tool.ts` | `browser` tool — open/close/run/act actions; mutating (drives a real browser, `run` executes arbitrary host JS), excluded from read-only roles |
 | `ast-edit-tool.ts` | `ast_edit` tool — structural codemod using `ast-match.ts`; mutating, writes via `writeTool` |
 | `bash-fixups.ts` | Brief description of purpose |
 | `compaction.ts` | Brief description of purpose |

package/src/agent/browser-session.ts

@@ -0,0 +1,104 @@
+/**
+ * Named-tab browser session registry (gjc `browser` parity, via Playwright — already
+ * a jeo-code dependency for its own test suite, so this reuses it rather than adding
+ * a second automation engine). One shared headless Chromium instance is launched
+ * lazily on the first `open()` and kept alive across calls; tabs are addressed by
+ * name and reused ("open once, reuse many times" — the real tool's stated contract).
+ *
+ * Scope, stated honestly: headless Chromium only for v1 — no existing Chrome profile
+ * attach, no Electron/CDP-endpoint connect, no stealth-mode patches. Those are real
+ * gaps versus the full tool; a plain headless session covers the large majority of
+ * "fetch/observe/click through a page" agent use cases.
+ */
+import { chromium, type Browser, type Page } from "playwright";
+import { createTab, type Tab } from "./browser-tab";
+
+interface TabEntry {
+  page: Page;
+  tab: Tab;
+}
+
+export class BrowserSession {
+  private browser: Browser | undefined;
+  private tabs = new Map<string, TabEntry>();
+
+  get openTabNames(): string[] {
+    return [...this.tabs.keys()];
+  }
+
+  private async ensureBrowser(): Promise<Browser> {
+    if (this.browser && this.browser.isConnected()) return this.browser;
+    this.browser = await chromium.launch({ headless: true });
+    return this.browser;
+  }
+
+  /** Open (or reuse) a named tab. Navigates when `url` is given. */
+  async open(name: string, url?: string, viewport?: { width: number; height: number }): Promise<Tab> {
+    const browser = await this.ensureBrowser();
+    let entry = this.tabs.get(name);
+    if (!entry) {
+      const page = await browser.newPage(viewport ? { viewport } : undefined);
+      entry = { page, tab: createTab(page) };
+      this.tabs.set(name, entry);
+    } else if (viewport) {
+      await entry.page.setViewportSize(viewport);
+    }
+    if (url) await entry.tab.goto(url);
+    return entry.tab;
+  }
+
+  /** Look up an already-open tab by name, or throw a clear error. */
+  get(name: string): Tab {
+    const entry = this.tabs.get(name);
+    if (!entry) {
+      throw new Error(`No open tab named '${name}'. Call browser {action:"open", name} first.`);
+    }
+    return entry.tab;
+  }
+
+  has(name: string): boolean {
+    return this.tabs.has(name);
+  }
+
+  get browserInstance(): Browser | undefined {
+    return this.browser;
+  }
+
+  /** Close one named tab, or every tab (`all`). `all` also closes the shared browser. */
+  async close(name?: string, all = false): Promise<string[]> {
+    const closed: string[] = [];
+    if (all) {
+      for (const [n, entry] of this.tabs) {
+        await entry.page.close().catch(() => {});
+        closed.push(n);
+      }
+      this.tabs.clear();
+      if (this.browser) {
+        await this.browser.close().catch(() => {});
+        this.browser = undefined;
+      }
+      return closed;
+    }
+    if (name) {
+      const entry = this.tabs.get(name);
+      if (entry) {
+        await entry.page.close().catch(() => {});
+        this.tabs.delete(name);
+        closed.push(name);
+      }
+    }
+    return closed;
+  }
+
+  async terminate(): Promise<void> {
+    await this.close(undefined, true);
+  }
+}
+
+/** Process-wide singleton — one shared headless browser, many named tabs. */
+export const browserSession = new BrowserSession();
+
+// Safety net: never leave a headless Chromium process running past the CLI's exit.
+process.on("exit", () => {
+  void browserSession.terminate();
+});

package/src/agent/browser-tab.ts

@@ -0,0 +1,145 @@
+/**
+ * High-level per-tab helpers for the `browser` tool (gjc `browser` parity, via
+ * Playwright instead of puppeteer — jeo-code already ships `playwright` for its own
+ * test suite; this reuses it rather than adding a second automation dependency).
+ *
+ * `observe()` mirrors gjc's accessibility-snapshot-first philosophy: it returns a
+ * bounded list of interactive elements (role/name/value) instead of a raw DOM dump
+ * or a screenshot, and tags each one with a `data-jeo-observe-id` attribute so a
+ * later `act`/`run` call can address it by stable numeric `id` instead of a fragile
+ * CSS selector or pixel coordinates. Ids are stable until the next `observe()`/
+ * navigation, exactly like the real tool's contract.
+ */
+import type { Page } from "playwright";
+
+// Module-scoped (NOT global) DOM shims: these `page.evaluate()` callbacks run
+// INSIDE the browser page, not in this Bun/Node process, so they need `document`/
+// `HTMLElement` in scope for the callback body to type-check — but a real
+// `/// <reference lib="dom" />` pulls DOM's global `ReadableStream`/`Headers`
+// declarations into the WHOLE program's type-checking and breaks unrelated
+// Bun/Node-side files (job-registry.ts, the anthropic provider, ...) that rely on
+// the Node/Bun versions of those types. `declare const`/`type` inside a module
+// file are scoped to this file only, so they carry no such risk.
+declare const document: any;
+type HTMLElement = any;
+type HTMLInputElement = any;
+
+export interface ObservedElement {
+  id: number;
+  role: string;
+  name: string;
+  value: string;
+  tag: string;
+}
+
+const OBSERVE_ATTR = "data-jeo-observe-id";
+const INTERACTIVE_SELECTOR = 'a, button, input, select, textarea, [role], [onclick], [tabindex]';
+const MAX_OBSERVED = 300;
+
+export type ExtractFormat = "markdown" | "text" | "html";
+
+export interface Tab {
+  page: Page;
+  observe(): Promise<ObservedElement[]>;
+  id(n: number): import("playwright").Locator;
+  goto(url: string, opts?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" }): Promise<void>;
+  click(selectorOrId: string | number): Promise<void>;
+  type(selectorOrId: string | number, text: string): Promise<void>;
+  fill(selector: string, value: string): Promise<void>;
+  press(key: string, opts?: { selector?: string }): Promise<void>;
+  scroll(dx: number, dy: number): Promise<void>;
+  select(selector: string, ...values: string[]): Promise<string[]>;
+  waitFor(selectorOrMs: string | number): Promise<void>;
+  back(): Promise<void>;
+  extract(format?: ExtractFormat): Promise<string>;
+  screenshot(opts?: { selector?: string; fullPage?: boolean }): Promise<Buffer>;
+  evaluate<T>(fn: (...args: any[]) => T, ...args: any[]): Promise<T>;
+}
+
+function resolveLocator(page: Page, selectorOrId: string | number) {
+  return typeof selectorOrId === "number" ? page.locator(`[${OBSERVE_ATTR}="${selectorOrId}"]`) : page.locator(selectorOrId).first();
+}
+
+export function createTab(page: Page): Tab {
+  return {
+    page,
+
+    async observe(): Promise<ObservedElement[]> {
+      return page.evaluate(
+        ({ sel, attr, max }) => {
+          const nodes = Array.from(document.querySelectorAll(sel)).slice(0, max) as HTMLElement[];
+          return nodes.map((el, i) => {
+            el.setAttribute(attr, String(i));
+            const tag = el.tagName.toLowerCase();
+            const explicitRole = el.getAttribute("role");
+            const role = explicitRole || (tag === "a" ? "link" : tag === "button" ? "button" : tag === "input" ? "textbox" : tag === "select" ? "combobox" : tag === "textarea" ? "textbox" : tag);
+            const name = el.getAttribute("aria-label") || (el as HTMLInputElement).placeholder || el.textContent?.trim().replace(/\s+/g, " ").slice(0, 200) || "";
+            const value = (el as HTMLInputElement).value ?? "";
+            return { id: i, role, name, value, tag };
+          });
+        },
+        { sel: INTERACTIVE_SELECTOR, attr: OBSERVE_ATTR, max: MAX_OBSERVED },
+      );
+    },
+
+    id(n: number) {
+      return page.locator(`[${OBSERVE_ATTR}="${n}"]`);
+    },
+
+    async goto(url, opts) {
+      await page.goto(url, { waitUntil: opts?.waitUntil ?? "load" });
+    },
+
+    async click(selectorOrId) {
+      await resolveLocator(page, selectorOrId).click();
+    },
+
+    async type(selectorOrId, text) {
+      const loc = resolveLocator(page, selectorOrId);
+      await loc.fill("");
+      await loc.pressSequentially(text);
+    },
+
+    async fill(selector, value) {
+      await page.locator(selector).first().fill(value);
+    },
+
+    async press(key, opts) {
+      if (opts?.selector) await page.locator(opts.selector).first().press(key);
+      else await page.keyboard.press(key);
+    },
+
+    async scroll(dx, dy) {
+      await page.mouse.wheel(dx, dy);
+    },
+
+    async select(selector, ...values) {
+      return page.locator(selector).first().selectOption(values);
+    },
+
+    async waitFor(selectorOrMs) {
+      if (typeof selectorOrMs === "number") await page.waitForTimeout(selectorOrMs);
+      else await page.waitForSelector(selectorOrMs);
+    },
+
+    async back() {
+      await page.goBack({ waitUntil: "load" });
+    },
+
+    async extract(format: ExtractFormat = "markdown") {
+      if (format === "html") return page.content();
+      // No readability port for v1 — markdown/text both collapse to the page's
+      // rendered plain text (still far more compact/relevant than raw HTML).
+      return page.evaluate(() => document.body?.innerText ?? "");
+    },
+
+    async screenshot(opts) {
+      if (opts?.selector) return page.locator(opts.selector).first().screenshot();
+      return page.screenshot({ fullPage: !!opts?.fullPage });
+    },
+
+    async evaluate(fn, ...args) {
+      return page.evaluate(fn as any, ...(args as any));
+    },
+  };
+}

package/src/agent/browser-tool.ts

@@ -0,0 +1,188 @@
+/**
+ * `browser` tool — headless Chromium automation via Playwright (gjc `browser`
+ * parity — see `browser-session.ts`'s header for the exact scope: headless-only,
+ * no profile/CDP/Electron attach, no stealth patches). MUTATING: drives a real
+ * browser and can run arbitrary page/host JS via `run`, so it is excluded from
+ * read-only subagent roles the same way `bash`/`computer`/`debug` are.
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import { browserSession, type BrowserSession } from "./browser-session";
+import type { ObservedElement, ExtractFormat } from "./browser-tab";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const BROWSER_TOOL_PROTOCOL_LINE =
+  `browser {action:"open"|"close"|"run"|"act", name?, url?, viewport?, code?, actions?, all?} — headless ` +
+  `Chromium automation (Playwright). 'open' {name, url?} opens/reuses a named tab (name defaults to "main"). ` +
+  `'close' {name?, all?} closes one tab or every tab. 'act' {name, actions:[{verb, ...}]} runs structured steps ` +
+  `(navigate/click/type/fill/select/press/scroll/back/wait/observe/extract/screenshot) — address elements by ` +
+  `numeric 'id' from a prior 'observe' step (preferred) or a CSS 'selector'; prefer 'observe' over 'screenshot' ` +
+  `for understanding page state. 'run' {name, code} executes an async function BODY with page/browser/tab/` +
+  `display/assert/wait in scope for anything the structured verbs don't cover.`;
+
+function err(message: string): ToolResult {
+  return { success: false, output: "", error: message };
+}
+
+function tabNameOf(args: Record<string, any>): string {
+  const n = typeof args.name === "string" ? args.name.trim() : "";
+  return n || "main";
+}
+
+interface ActStep {
+  verb: string;
+  [key: string]: unknown;
+}
+
+async function runActStep(session: BrowserSession, name: string, step: ActStep): Promise<Record<string, unknown>> {
+  const tab = session.get(name);
+  const verb = String(step.verb ?? "").trim().toLowerCase();
+  try {
+    switch (verb) {
+      case "navigate": {
+        const url = String(step.url ?? "");
+        if (!url) return { verb, ok: false, error: "navigate requires 'url'." };
+        await tab.goto(url, { waitUntil: step.wait_until as any });
+        return { verb, ok: true, url: tab.page.url() };
+      }
+      case "click": {
+        const target = step.id !== undefined ? Number(step.id) : String(step.selector ?? "");
+        if (target === "" ) return { verb, ok: false, error: "click requires 'id' or 'selector'." };
+        await tab.click(target);
+        return { verb, ok: true };
+      }
+      case "type": {
+        const target = step.id !== undefined ? Number(step.id) : String(step.selector ?? "");
+        const text = String(step.text ?? "");
+        if (target === "") return { verb, ok: false, error: "type requires 'id' or 'selector'." };
+        await tab.type(target, text);
+        return { verb, ok: true };
+      }
+      case "fill": {
+        const selector = String(step.selector ?? "");
+        if (!selector) return { verb, ok: false, error: "fill requires 'selector'." };
+        await tab.fill(selector, String(step.value ?? ""));
+        return { verb, ok: true };
+      }
+      case "select": {
+        const selector = String(step.selector ?? "");
+        if (!selector) return { verb, ok: false, error: "select requires 'selector'." };
+        const values = Array.isArray(step.values) ? step.values.map((v: unknown) => String(v)) : [];
+        const selected = await tab.select(selector, ...values);
+        return { verb, ok: true, selected };
+      }
+      case "press": {
+        const key = String(step.key ?? "");
+        if (!key) return { verb, ok: false, error: "press requires 'key'." };
+        await tab.press(key, { selector: typeof step.selector === "string" ? step.selector : undefined });
+        return { verb, ok: true };
+      }
+      case "scroll": {
+        await tab.scroll(Number(step.dx ?? 0), Number(step.dy ?? 0));
+        return { verb, ok: true };
+      }
+      case "back": {
+        await tab.back();
+        return { verb, ok: true, url: tab.page.url() };
+      }
+      case "wait": {
+        if (typeof step.ms === "number") await tab.waitFor(step.ms);
+        else if (typeof step.selector === "string") await tab.waitFor(step.selector);
+        else return { verb, ok: false, error: "wait requires 'selector' or 'ms'." };
+        return { verb, ok: true };
+      }
+      case "observe": {
+        const elements: ObservedElement[] = await tab.observe();
+        return { verb, ok: true, url: tab.page.url(), title: await tab.page.title(), elements };
+      }
+      case "extract": {
+        const format = (typeof step.format === "string" ? step.format : "markdown") as ExtractFormat;
+        const content = await tab.extract(format);
+        return { verb, ok: true, content: content.length > 8000 ? content.slice(0, 8000) + "…" : content };
+      }
+      case "screenshot": {
+        const buf = await tab.screenshot({ selector: typeof step.selector === "string" ? step.selector : undefined, fullPage: !!step.fullPage });
+        const savePath = path.join(os.tmpdir(), `jeo-browser-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.png`);
+        await fs.writeFile(savePath, buf);
+        return { verb, ok: true, saved: savePath, bytes: buf.length };
+      }
+      default:
+        return { verb, ok: false, error: `Unknown act verb '${verb}'.` };
+    }
+  } catch (e: any) {
+    return { verb, ok: false, error: e.message ?? String(e) };
+  }
+}
+
+export function createBrowserTool(): ToolHandler {
+  return async (args: Record<string, any>, _cwd: string): Promise<ToolResult> => {
+    const action = String(args.action ?? "").trim().toLowerCase();
+
+    if (action === "open") {
+      const name = tabNameOf(args);
+      const url = typeof args.url === "string" && args.url.trim() ? args.url.trim() : undefined;
+      const viewport = args.viewport && typeof args.viewport === "object"
+        ? { width: Number(args.viewport.width) || 1280, height: Number(args.viewport.height) || 800 }
+        : undefined;
+      try {
+        const tab = await browserSession.open(name, url, viewport);
+        return { success: true, output: `Tab '${name}' open at ${tab.page.url() || "about:blank"}.` };
+      } catch (e: any) {
+        return err(`Failed to open tab '${name}': ${e.message ?? e}`);
+      }
+    }
+
+    if (action === "close") {
+      const all = args.all === true;
+      const name = typeof args.name === "string" ? args.name.trim() : undefined;
+      if (!all && !name) return err(`browser {action:"close"} requires "name" or "all:true".`);
+      const closed = await browserSession.close(name, all);
+      return { success: true, output: closed.length ? `Closed: ${closed.join(", ")}.` : "No matching open tab." };
+    }
+
+    if (action === "run") {
+      const name = tabNameOf(args);
+      const code = typeof args.code === "string" ? args.code : "";
+      if (!code.trim()) return err(`browser {action:"run"} requires a non-empty "code" body.`);
+      if (!browserSession.has(name)) return err(`No open tab named '${name}'. Call browser {action:"open", name} first.`);
+      const tab = browserSession.get(name);
+      const displayed: string[] = [];
+      const display = (v: unknown) => { displayed.push(typeof v === "string" ? v : JSON.stringify(v, null, 2)); };
+      const assert = (cond: unknown, message?: string) => { if (!cond) throw new Error(message ?? "Assertion failed"); };
+      const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+      try {
+        const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor as new (...a: string[]) => (...a: unknown[]) => Promise<unknown>;
+        const fn = new AsyncFunction("page", "browser", "tab", "display", "assert", "wait", code);
+        const result = await fn(tab.page, browserSession.browserInstance, tab, display, assert, wait);
+        const resultText = result === undefined ? "" : `\n\nReturn value:\n${typeof result === "string" ? result : JSON.stringify(result, null, 2)}`;
+        return { success: true, output: `${displayed.join("\n")}${resultText}`.trim() || "(no output)" };
+      } catch (e: any) {
+        return err(`browser run failed: ${e.message ?? e}`);
+      }
+    }
+
+    if (action === "act") {
+      const name = tabNameOf(args);
+      if (!browserSession.has(name)) {
+        try {
+          await browserSession.open(name);
+        } catch (e: any) {
+          return err(`Failed to open tab '${name}': ${e.message ?? e}`);
+        }
+      }
+      const steps = Array.isArray(args.actions) ? args.actions as ActStep[] : [];
+      if (steps.length === 0) return err(`browser {action:"act"} requires a non-empty "actions" array.`);
+      const results: Record<string, unknown>[] = [];
+      for (const step of steps) {
+        results.push(await runActStep(browserSession, name, step));
+      }
+      const allOk = results.every((r) => r.ok === true);
+      return { success: allOk, output: JSON.stringify(results, null, 2) };
+    }
+
+    return err(`Unknown browser action '${action}'. Use open | close | run | act.`);
+  };
+}

package/src/agent/engine.ts

@@ -21,6 +21,7 @@ import { createAstEditTool } from "./ast-edit-tool";
 import { createLspTool } from "./lsp-tool";
 import { createLspRenameTool } from "./lsp-rename-tool";
 import { createDebugTool } from "./debug-tool";
+import { createBrowserTool } from "./browser-tool";
 import { isRateLimitError, waitAbortable } from "../util/retry";
 import { isContextOverflowError, isRefusalError, friendlyProviderError } from "../util/provider-error";
 import { runPreToolHooks, runPostTurnHooksForBatch } from "./hooks";
@@ -103,6 +104,7 @@ export const DEFAULT_TOOLS: Record<string, ToolHandler> = {
   lsp: createLspTool(),
   lsp_rename: createLspRenameTool(),
   debug: createDebugTool(),
+  browser: createBrowserTool(),
 };
 /** Tool-protocol description injected into the system prompt. */
 export const TOOL_PROTOCOL = [
@@ -123,7 +125,8 @@ export const TOOL_PROTOCOL = [
   "14. lsp {action, file, line?, symbol?} — TypeScript/JavaScript language-service queries (definition/references/hover/symbols/diagnostics); 'symbol' resolves the column on 'line' (append #N for the Nth occurrence)",
   "15. lsp_rename {file, line, symbol?, new_name, apply?} — cross-file TypeScript/JavaScript rename (apply defaults true; apply:false previews only)",
   "16. debug {action, ...} — Node.js debugging (launch/set_breakpoint/continue/step_over/step_in/step_out/pause/evaluate/stack_trace/scopes/variables/threads/output/terminate); one active session, 'launch' spawns 'node --inspect-brk' and pauses at start",
-  "17. done   {reason?}                  — call when the task is fully implemented AND verified",
+  "17. browser {action:\"open\"|\"close\"|\"run\"|\"act\", name?, url?, actions?} — headless Chromium automation (Playwright); 'act' runs structured steps (navigate/click/type/fill/select/press/scroll/back/wait/observe/extract/screenshot) addressing elements by numeric id from 'observe' or a CSS selector; 'run' executes JS with page/browser/tab/display/assert/wait in scope",
+  "18. done   {reason?}                  — call when the task is fully implemented AND verified",
   "",
   "Reply with STRICT JSON only — no code fences. You MAY include an optional leading",
   '"reasoning" string (one short sentence on your plan) before "tool":',

package/src/agent/subagents.ts

@@ -252,7 +252,7 @@ export function bashCommandAllowed(command: string, prefixes: string[]): boolean
  */
 export function subagentToolset(role: SubagentRole): Record<string, ToolHandler> {
   if (role.readOnly) {
-    const MUTATING = new Set(["write", "edit", "bash", "mkdir", "delete", "ast_edit", "computer", "lsp_rename", "debug"]);
+    const MUTATING = new Set(["write", "edit", "bash", "mkdir", "delete", "ast_edit", "computer", "lsp_rename", "debug", "browser"]);
     const ro: Record<string, ToolHandler> = {};
     for (const [name, handler] of Object.entries(DEFAULT_TOOLS)) {
       if (MUTATING.has(name)) continue;

package/src/commands/launch.ts

@@ -525,7 +525,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   // pi-style: load project context (JEO.md / AGENTS.md / .jeo/context.md / CLAUDE.md) into the prompt.
   const contextFiles = await loadProjectContext(cwd);
 
-  const KNOWN_TOOLS = new Set(["read", "write", "edit", "bash", "find", "search", "ls", "task", "todo", "subagent", "job", "irc", "goal", "ast_grep", "ast_edit", "computer", "lsp", "lsp_rename", "debug"]);
+  const KNOWN_TOOLS = new Set(["read", "write", "edit", "bash", "find", "search", "ls", "task", "todo", "subagent", "job", "irc", "goal", "ast_grep", "ast_edit", "computer", "lsp", "lsp_rename", "debug", "browser"]);
   let allowedTools = new Set(KNOWN_TOOLS);
 
   if (flags.noTools) {