march-cli 0.1.28 → 0.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "march-cli",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "March CLI — terminal-native coding agent with context reconstruction",
   "type": "module",
   "main": "./src/main.mjs",

package/src/agent/runner.mjs

@@ -81,7 +81,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
     });
   } else {
     const sessionOptions = resolveRunnerSessionOptions({
-      cwd, provider, modelId, modelRegistry, engine, ui: runtimeUi,
+      cwd, stateRoot, provider, modelId, modelRegistry, engine, ui: runtimeUi,
       memoryTools, shellRuntime, lspService, mcpTools, webTools, permissionController,
       authStorage: resolvedAuth, projectMarchDir,
       getCurrentModel: () => sessionBinding.get()?.model ?? selectedModel,

package/src/agent/runtime/runner-runtime-host.mjs

@@ -48,6 +48,7 @@ export async function createRunnerRuntimeHost({
       registerCustomProviders(activeModelRegistry, providers);
       return resolveRunnerSessionOptions({
         cwd: sessionCwd,
+        stateRoot,
         provider,
         modelId,
         modelRegistry: activeModelRegistry,

package/src/agent/session/session-options.mjs

@@ -17,6 +17,7 @@ export function resolveRunnerSessionOptions({
   permissionController = null,
   authStorage = null,
   projectMarchDir = null,
+  stateRoot = null,
   getCurrentModel = null,
 }) {
   if (engine.cwd !== cwd) {
@@ -29,7 +30,7 @@ export function resolveRunnerSessionOptions({
     ?? (provider && modelId ? getModel(provider, modelId) : null);
   if (!model) throw new Error(`Model not found: ${provider}/${modelId}`);
 
-  const customTools = createMarchCustomTools({ cwd, engine, ui, memoryTools, shellRuntime, lspService, mcpTools, webTools, permissionController, authStorage, projectMarchDir, getCurrentModel: () => getCurrentModel?.() ?? model });
+  const customTools = createMarchCustomTools({ cwd, engine, ui, memoryTools, shellRuntime, lspService, mcpTools, webTools, permissionController, authStorage, projectMarchDir, stateRoot, getCurrentModel: () => getCurrentModel?.() ?? model });
   const customToolNames = customTools.map((tool) => tool.name);
   const tools = [
     ...customToolNames.filter((name) => name === "read"),

package/src/agent/tools.mjs

@@ -9,8 +9,9 @@ import { toolText } from "./tool-result.mjs";
 import { createShellTools } from "../shell/tools.mjs";
 import { initImageGen } from "../image-gen/index.mjs";
 import { createSuperGrokTool } from "../supergrok/tool.mjs";
+import { createBrowserTools } from "../browser/tools/index.mjs";
 
-export function createMarchCustomTools({ cwd, engine, ui, memoryTools = [], shellRuntime = null, lspService = null, mcpTools = [], webTools = [], permissionController = null, authStorage = null, projectMarchDir = null, getCurrentModel = null }) {
+export function createMarchCustomTools({ cwd, engine, ui, memoryTools = [], shellRuntime = null, lspService = null, mcpTools = [], webTools = [], permissionController = null, authStorage = null, projectMarchDir = null, stateRoot = null, getCurrentModel = null }) {
   const commandExecTool = createCommandExecTool({ cwd });
   const contextStatsTool = createContextStatsTool({ engine });
   const editFileTool = createEditFileTool({ engine, ui, lspService });
@@ -31,6 +32,7 @@ export function createMarchCustomTools({ cwd, engine, ui, memoryTools = [], shel
     ...memoryTools,
     ...mcpTools,
     ...webTools,
+    ...createBrowserTools({ stateRoot }),
     ...(authStorage ? [createSuperGrokTool({ authStorage, projectMarchDir })] : []),
     ...(authStorage ? initImageGen({ authStorage, projectMarchDir }) : []),
   ];

package/src/browser/cli/command.mjs

@@ -0,0 +1,61 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ensureBrowserDaemon, stopBrowserDaemon } from "../client/lifecycle.mjs";
+import { readBrowserDaemonState } from "../client/state.mjs";
+import { requestBrowserDaemon } from "../client/http.mjs";
+import { installedBrowserExtensionPath, syncBrowserExtensionInstall } from "../extension-install.mjs";
+import { openBrowserUrl } from "./open-url.mjs";
+
+export async function runBrowserCommand(args, { stateRoot = join(homedir(), ".march") } = {}) {
+  const subcommand = args.command.args[0] ?? "status";
+  if (subcommand === "install") return await installBrowser({ stateRoot });
+  if (subcommand === "status") return await printStatus({ stateRoot });
+  if (subcommand === "restart") return await restartBrowserDaemon({ stateRoot });
+  if (subcommand === "daemon" && args.foreground) return await runForegroundDaemon({ stateRoot });
+  process.stderr.write("Usage: march browser install|status|restart\n");
+  return 1;
+}
+
+async function installBrowser({ stateRoot }) {
+  const extensionPath = syncBrowserExtensionInstall(stateRoot);
+  const state = await ensureBrowserDaemon({ stateRoot });
+  await openBrowserUrl("chrome://extensions");
+  process.stdout.write(`March Browser developer install\n\n`);
+  process.stdout.write(`1. Chrome extensions page opened: chrome://extensions\n`);
+  process.stdout.write(`2. Enable Developer mode.\n`);
+  process.stdout.write(`3. Click Load unpacked.\n`);
+  process.stdout.write(`4. Select this folder:\n   ${extensionPath}\n`);
+  process.stdout.write(`5. If the extension is already loaded, click its Reload button.\n\n`);
+  process.stdout.write(`Daemon: ${state.url}\n`);
+  process.stdout.write(`Extension WebSocket: ${state.wsUrl}\n`);
+  return await printStatus({ stateRoot });
+}
+
+async function printStatus({ stateRoot }) {
+  const state = readBrowserDaemonState(stateRoot);
+  try {
+    const status = await requestBrowserDaemon(state.url, "/status", null, { timeoutMs: 800 });
+    process.stdout.write(`Browser daemon: running pid=${status.pid}\n`);
+    process.stdout.write(`Browser extension: ${status.extensionConnected ? "connected" : "not connected"}\n`);
+    process.stdout.write(`Extension path: ${installedBrowserExtensionPath(stateRoot)}\n`);
+    return 0;
+  } catch {
+    process.stdout.write("Browser daemon: not running\n");
+    process.stdout.write(`Extension path: ${installedBrowserExtensionPath(stateRoot)}\n`);
+    return 0;
+  }
+}
+
+async function restartBrowserDaemon({ stateRoot }) {
+  await stopBrowserDaemon({ stateRoot });
+  await ensureBrowserDaemon({ stateRoot });
+  return await printStatus({ stateRoot });
+}
+
+async function runForegroundDaemon({ stateRoot }) {
+  const { createBrowserDaemonServer } = await import("../daemon/server.mjs");
+  const server = createBrowserDaemonServer({ stateRoot });
+  await server.start();
+  process.stdout.write(`Browser daemon foreground: ${readBrowserDaemonState(stateRoot).url}\n`);
+  return new Promise(() => {});
+}

package/src/browser/cli/open-url.mjs

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+
+export function openBrowserUrl(url) {
+  return new Promise((resolve, reject) => {
+    const { command, args } = openUrlCommand(url);
+    const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.once("error", reject);
+    child.once("spawn", () => {
+      child.unref();
+      resolve();
+    });
+  });
+}
+
+function openUrlCommand(url) {
+  if (process.platform === "win32") {
+    return { command: "powershell.exe", args: ["-NoProfile", "-Command", "Start-Process $args[0]", url] };
+  }
+  if (process.platform === "darwin") return { command: "open", args: [url] };
+  return { command: "xdg-open", args: [url] };
+}

package/src/browser/client/http.mjs

@@ -0,0 +1,18 @@
+export async function requestBrowserDaemon(url, path, body = null, { timeoutMs = 5000 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`${url}${path}`, {
+      method: body ? "POST" : "GET",
+      headers: body ? { "content-type": "application/json" } : undefined,
+      body: body ? JSON.stringify(body) : undefined,
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    const payload = text ? JSON.parse(text) : null;
+    if (!response.ok) throw new Error(payload?.error ?? `Browser daemon HTTP ${response.status}`);
+    return payload;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/browser/client/lifecycle.mjs

@@ -0,0 +1,57 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { readBrowserDaemonState, removeBrowserDaemonState } from "./state.mjs";
+import { requestBrowserDaemon } from "./http.mjs";
+
+export async function ensureBrowserDaemon({ stateRoot, quiet = true } = {}) {
+  const state = readBrowserDaemonState(stateRoot);
+  if (await pingBrowserDaemon(state.url)) return state;
+
+  removeBrowserDaemonState(stateRoot);
+  const child = spawn(process.execPath, [daemonEntryPath(), "--state-root", stateRoot], {
+    detached: true,
+    stdio: quiet ? "ignore" : "inherit",
+    windowsHide: true,
+  });
+  child.once("error", () => {});
+  child.unref();
+
+  const deadline = Date.now() + 4000;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    await sleep(120);
+    try {
+      const next = readBrowserDaemonState(stateRoot);
+      if (await pingBrowserDaemon(next.url)) return next;
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  throw new Error(`Browser daemon did not start${lastError ? `: ${lastError.message}` : ""}`);
+}
+
+export async function pingBrowserDaemon(url) {
+  try {
+    const status = await requestBrowserDaemon(url, "/status", null, { timeoutMs: 700 });
+    return Boolean(status?.ok);
+  } catch {
+    return false;
+  }
+}
+
+export async function stopBrowserDaemon({ stateRoot } = {}) {
+  const state = readBrowserDaemonState(stateRoot);
+  try {
+    await requestBrowserDaemon(state.url, "/shutdown", {}, { timeoutMs: 1500 });
+  } catch {}
+  removeBrowserDaemonState(stateRoot);
+}
+
+function daemonEntryPath() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "../daemon/entry.mjs");
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/browser/client/rpc.mjs

@@ -0,0 +1,8 @@
+import { ensureBrowserDaemon } from "./lifecycle.mjs";
+import { requestBrowserDaemon } from "./http.mjs";
+
+export async function callBrowserDaemon({ stateRoot, method, params = {}, timeoutMs = 30000 }) {
+  const state = await ensureBrowserDaemon({ stateRoot });
+  const response = await requestBrowserDaemon(state.url, "/rpc", { method, params, timeoutMs }, { timeoutMs: timeoutMs + 1000 });
+  return response.result;
+}

package/src/browser/client/state.mjs

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { BROWSER_DAEMON_HOST, BROWSER_DAEMON_PORT, BROWSER_DAEMON_STATE_FILE } from "../daemon/constants.mjs";
+
+export function browserDaemonStatePath(stateRoot) {
+  return join(stateRoot, BROWSER_DAEMON_STATE_FILE);
+}
+
+export function defaultBrowserDaemonState() {
+  return {
+    pid: null,
+    url: `http://${BROWSER_DAEMON_HOST}:${BROWSER_DAEMON_PORT}`,
+    wsUrl: `ws://${BROWSER_DAEMON_HOST}:${BROWSER_DAEMON_PORT}/extension`,
+    startedAt: null,
+  };
+}
+
+export function readBrowserDaemonState(stateRoot) {
+  const path = browserDaemonStatePath(stateRoot);
+  if (!existsSync(path)) return defaultBrowserDaemonState();
+  try {
+    return { ...defaultBrowserDaemonState(), ...JSON.parse(readFileSync(path, "utf8")) };
+  } catch {
+    return defaultBrowserDaemonState();
+  }
+}
+
+export function writeBrowserDaemonState(stateRoot, state) {
+  mkdirSync(stateRoot, { recursive: true });
+  writeFileSync(browserDaemonStatePath(stateRoot), JSON.stringify(state, null, 2));
+}
+
+export function removeBrowserDaemonState(stateRoot) {
+  try { rmSync(browserDaemonStatePath(stateRoot), { force: true }); } catch {}
+}

package/src/browser/daemon/constants.mjs

@@ -0,0 +1,3 @@
+export const BROWSER_DAEMON_PORT = 4328;
+export const BROWSER_DAEMON_HOST = "127.0.0.1";
+export const BROWSER_DAEMON_STATE_FILE = "browser-daemon.json";

package/src/browser/daemon/entry.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createBrowserDaemonServer } from "./server.mjs";
+
+const args = parseArgs(process.argv.slice(2));
+const stateRoot = args["state-root"] ?? join(homedir(), ".march");
+const server = createBrowserDaemonServer({ stateRoot });
+
+process.on("SIGTERM", () => server.shutdown().then(() => process.exit(0)));
+process.on("SIGINT", () => server.shutdown().then(() => process.exit(0)));
+
+try {
+  await server.start();
+} catch (err) {
+  process.stderr.write(`Browser daemon failed: ${err.message}\n`);
+  process.exitCode = 1;
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (!argv[i].startsWith("--")) continue;
+    const key = argv[i].slice(2);
+    out[key] = argv[i + 1]?.startsWith("--") ? true : argv[++i];
+  }
+  return out;
+}

package/src/browser/daemon/server.mjs

@@ -0,0 +1,146 @@
+import { createServer } from "node:http";
+import WebSocket, { WebSocketServer } from "ws";
+import { BROWSER_DAEMON_HOST, BROWSER_DAEMON_PORT } from "./constants.mjs";
+import { writeBrowserDaemonState } from "../client/state.mjs";
+
+export function createBrowserDaemonServer({ stateRoot, port = BROWSER_DAEMON_PORT } = {}) {
+  const bridge = createExtensionBridge();
+  const server = createServer((req, res) => handleHttp(req, res, bridge, () => shutdown()));
+  const wss = new WebSocketServer({ noServer: true });
+
+  server.on("upgrade", (req, socket, head) => {
+    if (new URL(req.url, "http://localhost").pathname !== "/extension") {
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => bridge.attach(ws));
+  });
+
+  async function start() {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, BROWSER_DAEMON_HOST, resolve);
+    });
+    const address = server.address();
+    const actualPort = typeof address === "object" ? address.port : port;
+    writeBrowserDaemonState(stateRoot, {
+      pid: process.pid,
+      url: `http://${BROWSER_DAEMON_HOST}:${actualPort}`,
+      wsUrl: `ws://${BROWSER_DAEMON_HOST}:${actualPort}/extension`,
+      startedAt: Date.now(),
+    });
+  }
+
+  async function shutdown() {
+    bridge.close();
+    wss.close();
+    await new Promise((resolve) => server.close(resolve));
+  }
+
+  return { start, shutdown, bridge };
+}
+
+function createExtensionBridge() {
+  let socket = null;
+  const pending = new Map();
+
+  function attach(ws) {
+    if (socket && socket.readyState === WebSocket.OPEN) socket.close();
+    socket = ws;
+    ws.on("message", (data) => handleExtensionMessage(data));
+    ws.on("close", () => {
+      if (socket === ws) socket = null;
+    });
+  }
+
+  async function request(method, params = {}, timeoutMs = 30000) {
+    if (!socket || socket.readyState !== WebSocket.OPEN) throw new Error("Browser extension is not connected. Run: march browser install");
+    const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    const message = JSON.stringify({ id, method, params });
+    return await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`Browser extension request timed out: ${method}`));
+      }, timeoutMs);
+      pending.set(id, { resolve, reject, timer });
+      socket.send(message, (err) => {
+        if (!err) return;
+        clearTimeout(timer);
+        pending.delete(id);
+        reject(err);
+      });
+    });
+  }
+
+  function handleExtensionMessage(data) {
+    let msg;
+    try { msg = JSON.parse(String(data)); } catch { return; }
+    const entry = pending.get(msg.id);
+    if (!entry) return;
+    clearTimeout(entry.timer);
+    pending.delete(msg.id);
+    msg.ok === false ? entry.reject(new Error(formatExtensionError(msg.error))) : entry.resolve(msg.result);
+  }
+
+  function close() {
+    for (const [id, entry] of pending) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error("Browser daemon is shutting down"));
+      pending.delete(id);
+    }
+    socket?.close();
+  }
+
+  return { attach, request, close, isConnected: () => Boolean(socket && socket.readyState === WebSocket.OPEN) };
+}
+
+async function handleHttp(req, res, bridge, shutdown) {
+  try {
+    const path = new URL(req.url, "http://localhost").pathname;
+    if (req.method === "GET" && path === "/status") {
+      return sendJson(res, 200, { ok: true, pid: process.pid, extensionConnected: bridge.isConnected() });
+    }
+    if (req.method === "POST" && path === "/rpc") {
+      const body = await readJson(req);
+      const result = await bridge.request(body.method, body.params, body.timeoutMs);
+      return sendJson(res, 200, { ok: true, result });
+    }
+    if (req.method === "POST" && path === "/shutdown") {
+      sendJson(res, 200, { ok: true });
+      setTimeout(() => shutdown().then(() => process.exit(0)), 10);
+      return;
+    }
+    sendJson(res, 404, { ok: false, error: "Not found" });
+  } catch (err) {
+    sendJson(res, 500, { ok: false, error: err.message });
+  }
+}
+
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.on("data", (chunk) => { body += chunk; });
+    req.on("end", () => {
+      try { resolve(body ? JSON.parse(body) : {}); } catch (err) { reject(err); }
+    });
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(payload));
+}
+
+export function formatExtensionError(error) {
+  if (!error) return "Browser extension request failed";
+  if (typeof error === "string") return error;
+  if (typeof error.stack === "string" && error.stack) return error.stack;
+  if (typeof error.message === "string" && error.message) return error.message;
+  if (error.message && typeof error.message === "object") return safeStringify(error.message);
+  return safeStringify(error);
+}
+
+function safeStringify(value) {
+  try { return JSON.stringify(value); } catch { return String(value); }
+}

package/src/browser/extension/background.js

@@ -0,0 +1,225 @@
+import { buildExecCode } from "./execute-code.js";
+import { serializeError } from "./errors.js";
+
+const DAEMON_WS = "ws://127.0.0.1:4328/extension";
+let socket = null;
+let reconnectTimer = null;
+let connecting = false;
+
+startBridge();
+chrome.runtime.onStartup.addListener(startBridge);
+chrome.runtime.onInstalled.addListener(startBridge);
+chrome.alarms.onAlarm.addListener((alarm) => {
+  if (alarm.name === "march-browser-reconnect") connect();
+  if (alarm.name === "march-browser-keepalive") keepAlive();
+});
+
+function startBridge() {
+  connect();
+  chrome.alarms.create("march-browser-reconnect", { periodInMinutes: 0.5 });
+}
+
+function connect() {
+  if (connecting || socket?.readyState === WebSocket.OPEN || socket?.readyState === WebSocket.CONNECTING) return;
+  connecting = true;
+  try {
+    socket = new WebSocket(DAEMON_WS);
+  } catch {
+    connecting = false;
+    scheduleReconnect();
+    return;
+  }
+  socket.onopen = () => {
+    connecting = false;
+    setBadge("on");
+    scheduleKeepAlive();
+  };
+  socket.onmessage = (event) => handleMessage(event.data);
+  socket.onclose = scheduleReconnect;
+  socket.onerror = () => socket?.close();
+}
+
+function keepAlive() {
+  if (socket?.readyState === WebSocket.OPEN) {
+    send({ type: "ping" });
+    scheduleKeepAlive();
+  } else {
+    scheduleReconnect();
+  }
+}
+
+function scheduleKeepAlive() {
+  chrome.alarms.create("march-browser-keepalive", { delayInMinutes: 0.4 });
+}
+
+function scheduleReconnect() {
+  connecting = false;
+  setBadge("off");
+  if (reconnectTimer) return;
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = null;
+    connect();
+  }, 1000);
+}
+
+async function handleMessage(data) {
+  const request = JSON.parse(data);
+  if (!request.id) return;
+  try {
+    const result = await dispatch(request.method, request.params ?? {});
+    send({ id: request.id, ok: true, result });
+  } catch (err) {
+    send({ id: request.id, ok: false, error: serializeError(err) });
+  }
+}
+
+function send(payload) {
+  if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify(payload));
+}
+
+function setBadge(state) {
+  chrome.action.setBadgeText({ text: state === "on" ? "ON" : "" });
+  chrome.action.setBadgeBackgroundColor({ color: "#16a34a" });
+}
+
+async function dispatch(method, params) {
+  if (method === "tabs") return { tabs: (await chrome.tabs.query({})).map(formatTab) };
+  if (method === "open") return await openTab(params);
+  if (method === "read") return await readTab(params);
+  if (method === "script") return await runScript(params);
+  throw new Error(`Unknown browser method: ${method}`);
+}
+
+async function openTab(params) {
+  const action = params.action;
+  const tabId = parseTabId(params.tabId);
+  if (action === "new") return { tab: formatTab(await chrome.tabs.create({ url: requiredUrl(params.url), active: params.active ?? true })) };
+  if (!tabId) throw new Error(`${action} requires tabId`);
+  if (action === "navigate") return { tab: formatTab(await chrome.tabs.update(tabId, { url: requiredUrl(params.url), active: params.active })) };
+  if (action === "focus") return await focusTab(tabId);
+  if (action === "close") { await chrome.tabs.remove(tabId); return { closed: String(tabId) }; }
+  if (action === "reload") { await chrome.tabs.reload(tabId); return { reloaded: String(tabId) }; }
+  if (action === "back" || action === "forward") return await navHistory(tabId, action);
+  throw new Error(`Unknown open action: ${action}`);
+}
+
+async function focusTab(tabId) {
+  const tab = await chrome.tabs.update(tabId, { active: true });
+  if (tab.windowId) await chrome.windows.update(tab.windowId, { focused: true });
+  return { tab: formatTab(tab) };
+}
+
+async function navHistory(tabId, action) {
+  await executePageCode(tabId, action === "back" ? "history.back(); true" : "history.forward(); true");
+  return { tabId: String(tabId), action };
+}
+
+async function readTab(params) {
+  const tabId = requireTabId(params.tabId, "read");
+  const include = params.include ?? { text: true, elements: true };
+  const page = await executePageCode(tabId, buildReadCode(include));
+  const tab = await chrome.tabs.get(tabId);
+  return { tab: formatTab(tab), page };
+}
+
+async function runScript(params) {
+  const tabId = requireTabId(params.tabId, "script");
+  const result = await executePageCode(tabId, String(params.code ?? ""));
+  return { tabId: String(tabId), result };
+}
+
+async function executePageCode(tabId, code) {
+  const wrapped = buildExecCode(code);
+  const injected = await executeViaScripting(tabId, wrapped).catch((err) => ({ ok: false, csp: true, error: serializeError(err) }));
+  if (injected?.ok) return injected.data;
+  if (!injected?.csp) throwErrorResult(injected);
+  const cdp = await executeViaCdp(tabId, wrapped).catch((err) => ({ ok: false, error: serializeError(err) }));
+  if (cdp?.ok) return cdp.data;
+  throwErrorResult(cdp);
+}
+
+async function executeViaScripting(tabId, source) {
+  const [injection] = await chrome.scripting.executeScript({
+    target: { tabId },
+    world: "MAIN",
+    func: (script) => eval(script),
+    args: [source],
+  });
+  if (!injection) return { ok: false, error: { message: `No script injection result for tab ${tabId}` } };
+  if (injection.result == null) return { ok: false, csp: true, error: { message: "Script returned no value" } };
+  return injection.result;
+}
+
+async function executeViaCdp(tabId, expression) {
+  const target = { tabId };
+  let attached = false;
+  try {
+    await chrome.debugger.attach(target, "1.3");
+    attached = true;
+    const response = await chrome.debugger.sendCommand(target, "Runtime.evaluate", {
+      expression,
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    if (response.exceptionDetails) {
+      return { ok: false, error: { message: response.exceptionDetails.exception?.description || "CDP Runtime.evaluate failed" } };
+    }
+    return response.result?.value ?? { ok: true, data: undefined };
+  } finally {
+    if (attached) await chrome.debugger.detach(target).catch(() => {});
+  }
+}
+
+function buildReadCode(include) {
+  return `return (() => {
+    const include = ${JSON.stringify(include)};
+    const page = { title: document.title, url: location.href };
+    if (include.text !== false) page.text = document.body?.innerText || "";
+    if (include.html) page.html = document.documentElement?.outerHTML || "";
+    if (include.elements !== false) page.elements = Array.from(document.querySelectorAll("a,button,input,textarea,select,[role=button],[role=link],[contenteditable=true]")).slice(0, 300).map((el, index) => {
+      const tag = el.tagName.toLowerCase();
+      const text = (el.innerText || el.value || el.getAttribute("aria-label") || "").trim().slice(0, 200);
+      return { index, tag, type: el.getAttribute("type") || undefined, role: el.getAttribute("role") || undefined, text, placeholder: el.getAttribute("placeholder") || undefined, href: el.href || undefined, selector: selectorFor(el) };
+    });
+    return page;
+    function selectorFor(el) {
+      if (el.id) return "#" + CSS.escape(el.id);
+      const name = el.getAttribute("name");
+      if (name) return tagName(el) + "[name=\\\"" + CSS.escape(name) + "\\\"]";
+      const parts = [];
+      for (let node = el; node && node.nodeType === Node.ELEMENT_NODE && parts.length < 4; node = node.parentElement) {
+        const tag = tagName(node);
+        const siblings = Array.from(node.parentElement?.children || []).filter((child) => child.tagName === node.tagName);
+        parts.unshift(siblings.length > 1 ? tag + ":nth-of-type(" + (siblings.indexOf(node) + 1) + ")" : tag);
+      }
+      return parts.join(" > ");
+    }
+    function tagName(el) { return el.tagName.toLowerCase(); }
+  })()`;
+}
+
+function throwErrorResult(result) {
+  const error = result?.error;
+  if (typeof error === "string") throw new Error(error);
+  throw new Error(error?.stack || error?.message || "Browser script failed");
+}
+
+function formatTab(tab) {
+  return { id: String(tab.id), windowId: tab.windowId, active: tab.active, title: tab.title, url: tab.url, status: tab.status };
+}
+
+function requireTabId(value, action) {
+  const tabId = parseTabId(value);
+  if (!tabId) throw new Error(`${action} requires tabId`);
+  return tabId;
+}
+
+function parseTabId(value) {
+  const id = Number(value);
+  return Number.isFinite(id) ? id : null;
+}
+
+function requiredUrl(url) {
+  if (!url) throw new Error("url is required");
+  return url;
+}