jeo-code 0.7.31 → 0.7.33

package/src/agent/ast-match.ts

@@ -0,0 +1,241 @@
+/**
+ * Structural AST pattern matcher for TypeScript/JavaScript (gjc `ast_grep`/`ast_edit`
+ * parity, scoped to TS/JS/TSX/JSX — jeo-code has zero native dependencies, so this is
+ * a pure-TS reimplementation of ast-grep's metavariable matching against the
+ * `typescript` compiler API's AST, NOT the real ast-grep binary and NOT multi-language.
+ *
+ * Pattern syntax (matches the `ast_grep`/`ast_edit` tool contract):
+ *  - `$NAME`  — capture exactly ONE node; two occurrences of the same name in a
+ *    pattern must match IDENTICAL source text (e.g. `assertEqual($A, $A)`).
+ *  - `$_`     — wildcard, matches exactly one node without binding a capture.
+ *  - `$$$NAME`/`$$$` — capture/ignore ZERO OR MORE sibling nodes in a LIST position
+ *    (call arguments, array/object elements, statement lists, class members,
+ *    named-import specifiers, parameter lists, ...). At most one `$$$`-style
+ *    metavariable per list is supported.
+ *
+ * Implementation notes:
+ *  - `ts.Node.forEachChild(cbNode, cbNodeArray)` is used to enumerate a node's
+ *    children in canonical source order, distinguishing single-child "slots" from
+ *    list ("NodeArray") slots — this is what lets `$$$` bind a variable-length
+ *    span instead of a single node.
+ *  - A metavariable identifier is frequently parsed WRAPPED in a structural node
+ *    rather than standing bare — e.g. `($$$ARGS)` is a lone `ParameterDeclaration`
+ *    whose `.name` is the identifier, `{ $$$IMPORTS }` is a lone `ImportSpecifier`,
+ *    `: $_` is a `TypeReferenceNode`, `{ $$$BODY }` is a `Block` containing one
+ *    `ExpressionStatement`. `unwrapBareWrapper()` sees through these SPECIFIC,
+ *    well-known "no extra shape" wrappers so metavariable detection is not
+ *    accidentally defeated by the parser's own AST shape.
+ *  - Structural comparison otherwise requires the SAME `SyntaxKind` and recurses
+ *    slot-by-slot. A pattern is allowed to OMIT trailing optional slots the
+ *    candidate has (e.g. no `else` branch, no return type) and to be missing a
+ *    LEADING/MIDDLE list-shaped slot the candidate has (typically `modifiers`/
+ *    `decorators`, e.g. matching un-exported AND exported declarations with the
+ *    same pattern) — up to a small bounded number of skipped candidate slots.
+ */
+import * as ts from "typescript";
+
+export type MetaKind = "single" | "multi" | "wild" | "wildmulti";
+export interface Meta { kind: MetaKind; name: string }
+
+function unwrapBareWrapper(node: ts.Node): ts.Node | null {
+  if (ts.isParameter(node) && ts.isIdentifier(node.name) && !node.type && !node.initializer
+      && !node.questionToken && !node.dotDotDotToken && (!node.modifiers || node.modifiers.length === 0)) {
+    return node.name;
+  }
+  if (ts.isImportSpecifier(node) && !node.propertyName && !node.isTypeOnly) return node.name;
+  if (ts.isExportSpecifier(node) && !node.propertyName && !node.isTypeOnly) return node.name;
+  if (ts.isBindingElement(node) && !node.propertyName && !node.initializer && !node.dotDotDotToken && ts.isIdentifier(node.name)) return node.name;
+  if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && !node.typeArguments) return node.typeName;
+  if (ts.isExpressionStatement(node)) return node.expression;
+  if (ts.isShorthandPropertyAssignment(node) && !node.objectAssignmentInitializer) return node.name;
+  return null;
+}
+
+/** Classify a (possibly wrapper-unwrapped) node as a metavariable, or `null` for
+ *  an ordinary AST node that must be matched structurally. */
+export function metaOf(node: ts.Node): Meta | null {
+  const inner = unwrapBareWrapper(node);
+  if (inner) return metaOf(inner);
+  if (!ts.isIdentifier(node)) return null;
+  const t = node.text;
+  if (t === "$_") return { kind: "wild", name: "_" };
+  if (t === "$$$") return { kind: "wildmulti", name: "_" };
+  const m3 = /^\$\$\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(t);
+  if (m3) return { kind: "multi", name: m3[1]! };
+  const m1 = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(t);
+  if (m1) return { kind: "single", name: m1[1]! };
+  return null;
+}
+
+export interface Bindings {
+  single: Map<string, string>;
+  multi: Map<string, string[]>;
+}
+
+function newBindings(): Bindings {
+  return { single: new Map(), multi: new Map() };
+}
+
+type Slot = { kind: "node"; node: ts.Node } | { kind: "list"; nodes: readonly ts.Node[] };
+
+function slotsOf(node: ts.Node): Slot[] {
+  const out: Slot[] = [];
+  node.forEachChild(
+    child => { out.push({ kind: "node", node: child }); return undefined; },
+    arr => { out.push({ kind: "list", nodes: arr }); return undefined; },
+  );
+  return out;
+}
+
+function leafText(node: ts.Node): string | undefined {
+  if (ts.isIdentifier(node) || ts.isPrivateIdentifier(node)) return node.text;
+  if (ts.isStringLiteralLike(node)) return node.text;
+  if (ts.isNumericLiteral(node) || ts.isBigIntLiteral(node)) return node.text;
+  return undefined;
+}
+
+/** How many candidate-only slots (e.g. `export`/decorators the pattern omitted) a
+ *  single structural comparison may skip over before giving up. */
+const MAX_SLOT_SKIPS = 2;
+
+function matchNode(pattern: ts.Node, patternSf: ts.SourceFile, candidate: ts.Node, candidateSf: ts.SourceFile, b: Bindings): boolean {
+  const meta = metaOf(pattern);
+  if (meta) {
+    if (meta.kind === "wild") return true;
+    if (meta.kind === "single") {
+      const text = candidate.getText(candidateSf).trim();
+      const prev = b.single.get(meta.name);
+      if (prev !== undefined) return prev === text;
+      b.single.set(meta.name, text);
+      return true;
+    }
+    // `$$$NAME`/`$$$` reached outside a list slot (unusual pattern shape) — fall back
+    // to treating it as a single capture of the whole candidate rather than failing.
+    const text = candidate.getText(candidateSf).trim();
+    if (meta.kind === "multi") {
+      const prev = b.multi.get(meta.name);
+      if (prev !== undefined) return prev.join(" ") === text;
+      b.multi.set(meta.name, [text]);
+    }
+    return true;
+  }
+  if (pattern.kind !== candidate.kind) return false;
+  const lt = leafText(pattern);
+  if (lt !== undefined) return lt === leafText(candidate);
+
+  const pSlots = slotsOf(pattern);
+  const cSlots = slotsOf(candidate);
+  let pi = 0, ci = 0, skips = 0;
+  while (pi < pSlots.length) {
+    const ps = pSlots[pi]!;
+    if (ci >= cSlots.length) return false;
+    const cs = cSlots[ci]!;
+    if (ps.kind === cs.kind) {
+      const ok = ps.kind === "list"
+        ? matchList(ps.nodes, patternSf, (cs as { kind: "list"; nodes: readonly ts.Node[] }).nodes, candidateSf, b)
+        : matchNode((ps as { kind: "node"; node: ts.Node }).node, patternSf, (cs as { kind: "node"; node: ts.Node }).node, candidateSf, b);
+      if (!ok) {
+        if (skips < MAX_SLOT_SKIPS && ci + 1 < cSlots.length) { skips++; ci++; continue; }
+        return false;
+      }
+      pi++; ci++;
+      continue;
+    }
+    // Slot-KIND mismatch (list vs single) at this relative position — most commonly a
+    // `modifiers`/`decorators` list the candidate has and the pattern omitted. Skip the
+    // candidate slot and retry the SAME pattern slot against the next one.
+    if (skips < MAX_SLOT_SKIPS) { skips++; ci++; continue; }
+    return false;
+  }
+  return true; // trailing extra candidate slots are fine — unspecified optional parts
+}
+
+function matchList(patternNodes: readonly ts.Node[], patternSf: ts.SourceFile, candidateNodes: readonly ts.Node[], candidateSf: ts.SourceFile, b: Bindings): boolean {
+  const idx = patternNodes.findIndex(n => { const m = metaOf(n); return m?.kind === "multi" || m?.kind === "wildmulti"; });
+  if (idx === -1) {
+    if (patternNodes.length !== candidateNodes.length) return false;
+    for (let i = 0; i < patternNodes.length; i++) {
+      if (!matchNode(patternNodes[i]!, patternSf, candidateNodes[i]!, candidateSf, b)) return false;
+    }
+    return true;
+  }
+  const prefixLen = idx;
+  const suffixLen = patternNodes.length - idx - 1;
+  if (candidateNodes.length < prefixLen + suffixLen) return false;
+  for (let i = 0; i < prefixLen; i++) {
+    if (!matchNode(patternNodes[i]!, patternSf, candidateNodes[i]!, candidateSf, b)) return false;
+  }
+  for (let i = 0; i < suffixLen; i++) {
+    if (!matchNode(patternNodes[patternNodes.length - 1 - i]!, patternSf, candidateNodes[candidateNodes.length - 1 - i]!, candidateSf, b)) return false;
+  }
+  const middle = candidateNodes.slice(prefixLen, candidateNodes.length - suffixLen);
+  const meta = metaOf(patternNodes[idx]!)!;
+  if (meta.kind === "multi") {
+    const texts = middle.map(n => n.getText(candidateSf).trim());
+    const prev = b.multi.get(meta.name);
+    if (prev !== undefined) return prev.join(",") === texts.join(",");
+    b.multi.set(meta.name, texts);
+  }
+  return true;
+}
+
+/** Parse a pattern string to a single matchable node. Multi-statement snippets are
+ *  rejected with a clear error — wrap them in a block/valid context instead (same
+ *  discipline as real ast-grep). A bare expression statement is unwrapped to its
+ *  expression so `$A && $A()` matches an Expression, not only an ExpressionStatement. */
+export function parsePattern(src: string): { node: ts.Node; sf: ts.SourceFile } {
+  const sf = ts.createSourceFile("__pattern__.tsx", src, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  if (sf.statements.length !== 1) {
+    throw new Error(`pattern must parse to exactly one top-level statement (got ${sf.statements.length}) — wrap multi-statement snippets in a block or valid context`);
+  }
+  let node: ts.Node = sf.statements[0]!;
+  if (ts.isExpressionStatement(node)) node = node.expression;
+  return { node, sf };
+}
+
+export interface MatchCaptures {
+  single: Record<string, string>;
+  multi: Record<string, string[]>;
+}
+
+export interface MatchResult {
+  node: ts.Node;
+  captures: MatchCaptures;
+}
+
+/** Find every non-overlapping-by-construction match of `patternSrc` in `sourceFile`.
+ *  A fast prefilter only attempts nodes whose `SyntaxKind` equals the pattern's root
+ *  kind (unless the pattern root is itself a bare metavariable). */
+export function findMatches(patternSrc: string, sourceFile: ts.SourceFile): MatchResult[] {
+  const { node: patternNode, sf: patternSf } = parsePattern(patternSrc);
+  const patternIsBareMeta = metaOf(patternNode) !== null;
+  const out: MatchResult[] = [];
+  const visit = (node: ts.Node) => {
+    if (patternIsBareMeta || node.kind === patternNode.kind) {
+      const b = newBindings();
+      if (matchNode(patternNode, patternSf, node, sourceFile, b)) {
+        out.push({ node, captures: { single: Object.fromEntries(b.single), multi: Object.fromEntries(b.multi) } });
+      }
+    }
+    node.forEachChild(visit);
+  };
+  sourceFile.forEachChild(visit);
+  return out;
+}
+
+/** Render a replacement template, substituting `$NAME`/`$$$NAME` with their bound
+ *  capture text (multi-captures join with ", "). An unbound metavariable (including
+ *  `$_`/`$$$`, which never bind) is left as literal text in the output. */
+export function renderReplacement(template: string, captures: MatchCaptures): string {
+  return template.replace(/\$\$\$([A-Za-z_][A-Za-z0-9_]*)|\$([A-Za-z_][A-Za-z0-9_]*)/g, (whole, multiName?: string, singleName?: string) => {
+    if (multiName !== undefined) {
+      const vals = captures.multi[multiName];
+      return vals !== undefined ? vals.join(", ") : whole;
+    }
+    if (singleName !== undefined) {
+      const val = captures.single[singleName];
+      return val !== undefined ? val : whole;
+    }
+    return whole;
+  });
+}

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.`);
+  };
+}