surf-cli 2.8.0 → 2.9.0

package/native/cli.cjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-const net = require("net");
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
@@ -9,11 +8,17 @@ const networkFormatters = require("./formatters/network.cjs");
 const networkStore = require("./network-store.cjs");
 const { parseDoCommands } = require("./do-parser.cjs");
 const { executeDoSteps } = require("./do-executor.cjs");
+const { openClientTransport } = require("./client-transport.cjs");
 const { version: VERSION } = require("../package.json");
 
 const IS_WIN = process.platform === "win32";
-const { SOCKET_PATH, SURF_TMP, formatSocketError } = require("./socket-path.cjs");
+const { SURF_TMP, formatSocketError } = require("./socket-path.cjs");
 const { acquireBrowserLock } = require("./browser-lock.cjs");
+const { selectEndpoint, connectEndpoint, formatEndpointError } = require("./endpoint.cjs");
+const { createFrameParser, createSocketWriter, writeFrame } = require("./remote-transport.cjs");
+const { resolveRequestDeadlineMs } = require("./host-sessions.cjs");
+const { AUTO_SCREENSHOT_TOOLS, prepareRemoteTool, validateLocalToolPaths } = require("./file-transfer.cjs");
+const { authorizeClient, listClients, revokeClient, getStateDir } = require("./remote-auth.cjs");
 if (IS_WIN) { try { fs.mkdirSync(SURF_TMP, { recursive: true }); } catch {} }
 
 function parseBrowserLockOptions(noLockFlag) {
@@ -29,11 +34,11 @@ function parseBrowserLockOptions(noLockFlag) {
   return { noLock, timeoutMs };
 }
 
-function installBrowserLock({ noLock, timeoutMs }) {
+function installBrowserLock({ noLock, timeoutMs }, endpoint) {
   let releaseBrowserLock = () => {};
   if (!noLock) {
     try {
-      const lock = acquireBrowserLock(SOCKET_PATH, SURF_TMP, { timeoutMs });
+      const lock = acquireBrowserLock(endpoint.key, SURF_TMP, { timeoutMs });
       releaseBrowserLock = lock.release;
     } catch (error) {
       console.error("Error:", error && error.message ? error.message : String(error));
@@ -336,7 +341,50 @@ function resizeImage(filePath, maxSize) {
     return { success: false, error: e.message };
   }
 }
-const args = process.argv.slice(2);
+let args = process.argv.slice(2);
+if (args[0] === "remote") {
+  const remoteArgs = args.slice(1);
+  const subcommand = remoteArgs[0];
+  const stateDir = getStateDir();
+  try {
+    if (subcommand === "authorize") {
+      const label = remoteArgs[1];
+      const outputIndex = remoteArgs.indexOf("--output");
+      const output = outputIndex === -1 ? undefined : remoteArgs[outputIndex + 1];
+      if (!label || !output || output.startsWith("--")) throw new Error("Usage: surf remote authorize <label> --output <credential-file>");
+      const client = authorizeClient(label, output, stateDir);
+      console.log(`Authorized remote client: ${client.label}`);
+      console.log(`Credential: ${client.output}`);
+      process.exit(0);
+    }
+    if (subcommand === "list") {
+      const clients = listClients(stateDir);
+      if (clients.length === 0) console.log("No authorized remote clients.");
+      else for (const client of clients) console.log(`${client.label}\t${client.id}\t${client.createdAt}`);
+      process.exit(0);
+    }
+    if (subcommand === "revoke") {
+      const label = remoteArgs[1];
+      if (!label || label.startsWith("--")) throw new Error("Usage: surf remote revoke <label>");
+      revokeClient(label, stateDir);
+      console.log(`Revoked remote client: ${label}`);
+      process.exit(0);
+    }
+    console.error("Usage: surf remote authorize <label> --output <credential-file> | list | revoke <label>");
+    process.exit(1);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+let endpoint;
+try {
+  ({ args, endpoint } = selectEndpoint(args));
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}
 
 const ALIASES = {
   snap: "screenshot",
@@ -405,7 +453,7 @@ const TOOLS = {
         args: ["query"],
         opts: {
           "with-page": "Include current page context",
-          model: "Model: gemini-3-pro (default), gemini-2.5-pro, gemini-2.5-flash",
+          model: "Model: gemini-3.1-pro (default), gemini-3.5-flash, gemini-3.1-flash-lite",
           file: "Attach file to analyze",
           "generate-image": "Generate image and save to path",
           "edit-image": "Edit existing image (use with --output)",
@@ -528,6 +576,12 @@ const TOOLS = {
         opts: { ids: "Close multiple tabs" },
         examples: [{ cmd: "tab.close 123", desc: "Close tab" }]
       },
+      "tab.move": {
+        desc: "Move tab to another window",
+        args: ["id"],
+        opts: { ids: "Move multiple tabs", "to-window": "Destination window ID", index: "Destination index" },
+        examples: [{ cmd: "tab.move 123 --to-window 456", desc: "Move tab to window" }]
+      },
       "tab.name": {
         desc: "Register current tab with a name",
         args: ["name"],
@@ -675,6 +729,7 @@ const TOOLS = {
           "no-text": "Exclude visible text content",
           depth: "Maximum tree depth (default: unlimited)",
           compact: "Remove empty structural elements",
+          "max-bytes": "Maximum visible text bytes",
         },
         examples: [
           { cmd: "page.read", desc: "Interactive elements + text content" },
@@ -682,7 +737,7 @@ const TOOLS = {
           { cmd: "page.read --no-text", desc: "Interactive elements only (no text)" },
           { cmd: "page.read --depth 3", desc: "Limit to 3 levels deep" },
           { cmd: "page.read --compact", desc: "Skip empty containers" },
-          { cmd: "page.read --depth 3 --compact", desc: "Shallow + compact (60% smaller)" },
+          { cmd: "page.read --depth 3 --compact --max-bytes 2000", desc: "Shallow + compact output" },
           { cmd: "read", desc: "Alias" },
         ]
       },
@@ -823,7 +878,7 @@ const TOOLS = {
           ref: "Element ref (uses JS DOM method, more reliable for modals)",
           submit: "Press enter after",
           clear: "Clear first",
-          method: "cdp|js (default: cdp, but ref uses JS automatically)"
+          method: "cdp|js (cursor typing uses CDP; selector/ref targets use JS)"
         },
         examples: [
           { cmd: 'type "hello world"', desc: "Type at cursor (CDP events)" },
@@ -1567,7 +1622,7 @@ const ALL_SOCKET_TOOLS = [
   "computer",
   "page.read", "page.text", "page.state",
   "locate.role", "locate.text", "locate.label",
-  "tab.list", "tab.new", "tab.switch", "tab.close", "tab.name", "tab.unname", "tab.named",
+  "tab.list", "tab.new", "tab.switch", "tab.close", "tab.move", "tab.name", "tab.unname", "tab.named",
   "tab.group", "tab.ungroup", "tab.groups", "tab.reload",
   "scroll.top", "scroll.bottom", "scroll.to", "scroll.info",
   "wait.element", "wait.network", "wait.url", "wait.dom", "wait.load",
@@ -1659,6 +1714,10 @@ Quick Examples:
   surf window.new "https://example.com" && surf --window-id 123 go "https://other.com"
 
 More Help:
+  --remote <host>:<port>    Route requests to a remote native host
+  --remote-credential <path>  Use a mode-0600 Ed25519 remote credential file
+  surf remote authorize <label> --output <path>
+  surf remote list | surf remote revoke <label>
   surf --help-full           All commands
   surf --llm-context         Compact reference for AI agents
   surf --help-topic <topic>  Topic guide (refs, semantic, frames, devices...)
@@ -1715,6 +1774,8 @@ Usage: surf <command> [args] [options]
   console.log(`Aliases: snap -> screenshot, read -> page.read, find -> search, go -> navigate
 
 Options:
+  --remote <host>:<port>       Route requests to a remote native host
+  --remote-credential <path>   Use a mode-0600 Ed25519 remote credential file
   --tab-id <id>     Target specific tab
   --window-id <id>  Target specific window (isolate from your browsing)
   --json            Output raw JSON
@@ -1722,6 +1783,11 @@ Options:
   --soft-fail       On error: warn and exit 0 (for non-critical commands)
   --no-lock         Bypass the per-socket browser request lock
 
+Remote Credentials (run on the browser host):
+  surf remote authorize <label> --output <credential-file>
+  surf remote list
+  surf remote revoke <label>
+
 Script Mode:
   surf --script <file>     Run workflow from JSON
   surf --script <file> --dry-run
@@ -1937,7 +2003,7 @@ if (args[0] === "server") {
     process.exit(0);
   }
   const { PiChromeMcpServer } = require("./mcp-server.cjs");
-  const server = new PiChromeMcpServer();
+  const server = new PiChromeMcpServer(endpoint);
   server.start().catch((err) => {
     console.error("MCP Server error:", err.message);
     process.exit(1);
@@ -1953,7 +2019,7 @@ if (args[0] === "extension-path" || args[0] === "path") {
 
 if (args[0] === "doctor") {
   const { runDoctorCli } = require("./doctor.cjs");
-  runDoctorCli(args.slice(1)).then((code) => process.exit(code));
+  runDoctorCli(args.slice(1), endpoint).then((code) => process.exit(code));
   return;
 }
 
@@ -1978,6 +2044,8 @@ Options:
                   Multiple: --browser chrome,brave
   --target        Install target: auto, linux, windows
                   On WSL2, auto installs for Windows Chrome. Use linux for WSLg/Linux browsers.
+  --listen <tailscale-ip>:<port>
+                  Requires surf remote authorize <label> --output <path> first.
 
 Examples:
   surf install hnfbepgmaoklhekckbpjnleifhahkcpl
@@ -2121,44 +2189,24 @@ if (args.includes("--script")) {
     process.exit(1);
   }
 
+  let scriptTransport;
   const sendScriptRequest = (toolName, toolArgs = {}) => {
-    return new Promise((resolve, reject) => {
-      const sock = net.createConnection(SOCKET_PATH, () => {
-        const req = {
-          type: "tool_request",
-          method: "execute_tool",
-          params: { tool: toolName, args: toolArgs },
-          id: "cli-" + Date.now() + "-" + Math.random(),
-        };
-        if (scriptTabId) req.tabId = parseInt(scriptTabId, 10);
-        sock.write(JSON.stringify(req) + "\n");
-      });
-      let buf = "";
-      sock.on("data", (d) => {
-        buf += d.toString();
-        const lines = buf.split("\n");
-        buf = lines.pop();
-        for (const line of lines) {
-          if (!line.trim()) continue;
-          try {
-            const resp = JSON.parse(line);
-            sock.end();
-            resolve(resp);
-          } catch {
-            sock.end();
-            reject(new Error("Invalid JSON"));
-          }
-        }
-      });
-      sock.on("error", (e) => reject(new Error(formatSocketError(e))));
-      let timeoutId;
-      timeoutId = setTimeout(() => { sock.destroy(); reject(new Error("Timeout")); }, 30000);
-      sock.on("close", () => clearTimeout(timeoutId));
-    });
+    const req = {
+      type: "tool_request",
+      method: "execute_tool",
+      params: { tool: toolName, args: toolArgs },
+      id: "cli-" + Date.now() + "-" + Math.random(),
+    };
+    if (scriptTabId) req.tabId = parseInt(scriptTabId, 10);
+    const prepared = endpoint.kind === "remote" ? prepareRemoteTool(toolName, toolArgs) : (() => { const args = validateLocalToolPaths(toolName, toolArgs); return { args, uploads: [], downloads: [] }; })();
+    req.params.args = prepared.args;
+    return scriptTransport.request(req, resolveRequestDeadlineMs(toolName, prepared.args), prepared);
   };
 
   const runScript = async () => {
-    const total = script.steps.length;
+    try {
+      if (!dryRun) scriptTransport = await openClientTransport(endpoint);
+      const total = script.steps.length;
     const results = [];
     let failed = 0;
 
@@ -2216,14 +2264,22 @@ if (args.includes("--script")) {
       console.log(`Summary: ${passed} passed, ${failed} failed, ${total} total`);
     }
 
-    process.exit(failed > 0 ? 1 : 0);
+      return failed > 0 ? 1 : 0;
+    } finally {
+      await scriptTransport?.close();
+    }
   };
 
   if (!dryRun) {
-    installBrowserLock(parseBrowserLockOptions(args.includes("--no-lock")));
+    installBrowserLock(parseBrowserLockOptions(args.includes("--no-lock")), endpoint);
   }
 
-  runScript();
+  runScript()
+    .then((code) => process.exit(code))
+    .catch((error) => {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    });
   return;
 }
 
@@ -2425,7 +2481,7 @@ if (args[0] === "do") {
     process.exit(0);
   }
 
-  installBrowserLock(parseBrowserLockOptions(doArgs.includes("--no-lock")));
+  installBrowserLock(parseBrowserLockOptions(doArgs.includes("--no-lock")), endpoint);
 
   if (!wantJson) {
     if (workflowName) {
@@ -2436,7 +2492,10 @@ if (args[0] === "do") {
   }
 
   const runWorkflow = async () => {
-    const result = await executeDoSteps(steps, {
+    let transport;
+    try {
+      transport = await openClientTransport(endpoint);
+      const result = await executeDoSteps(steps, {
       onError,
       autoWait: !noAutoWait,
       stepDelay,
@@ -2445,30 +2504,40 @@ if (args[0] === "do") {
       context: {
         tabId,
         windowId,
+        endpoint,
+        transport,
       },
-    });
+      });
 
     // Print summary
     if (wantJson) {
       console.log(JSON.stringify(result, null, 2));
-      process.exit(result.status === "completed" ? 0 : 1);
+      return result.status === "completed" ? 0 : 1;
     }
 
     console.log("");
     if (result.status === "completed") {
       console.log(`Completed: ${result.completedSteps}/${result.totalSteps} steps (${result.totalMs}ms)`);
-      process.exit(0);
+      return 0;
     } else if (result.status === "partial") {
       console.log(`Partial: ${result.completedSteps}/${result.totalSteps} steps completed, ${result.failed} failed`);
-      process.exit(1);
+      return 1;
     } else {
       console.error(`Failed: ${result.completedSteps}/${result.totalSteps} steps completed`);
       if (result.error) console.error(`Error: ${result.error}`);
-      process.exit(1);
+      return 1;
+      }
+    } finally {
+      transport?.close();
     }
   };
 
-  runWorkflow();
+  runWorkflow()
+    .then((code) => process.exit(code))
+    .catch((error) => {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    });
   return;
 }
 
@@ -2595,8 +2664,6 @@ if (args[0] === "workflow.validate") {
 
 const BOOLEAN_FLAGS = ["auto-capture", "json", "stream", "dry-run", "stop-on-error", "fail-fast", "clear", "submit", "all", "case-sensitive", "hard", "annotate", "fullpage", "full-page", "reset", "no-screenshot", "full", "soft-fail", "has-body", "exclude-static", "v", "vv", "request", "by-tab", "har", "jsonl", "no-save", "no-auto-wait", "no-lock"];
 
-const AUTO_SCREENSHOT_TOOLS = ["click", "type", "key", "smart_type", "form.fill", "form_input", "drag", "hover", "scroll", "scroll.top", "scroll.bottom", "scroll.to", "dialog.accept", "dialog.dismiss", "js", "eval"];
-
 const parseArgs = (rawArgs) => {
   const result = { positional: [], options: {} };
   for (let i = 0; i < rawArgs.length; i++) {
@@ -2732,6 +2799,7 @@ const PRIMARY_ARG_MAP = {
   "tab.switch": "id",
   close_tab: "tab_id",
   "tab.close": "id",
+  "tab.move": "id",
   "tab.name": "name",
   "tab.unname": "name",
   scroll_to_position: "position",
@@ -2763,7 +2831,7 @@ const PRIMARY_ARG_MAP = {
   "select": "selector",
 };
 
-const toolArgs = { ...options };
+let toolArgs = { ...options };
 
 if (tool === "scroll" && firstArg) {
   if (firstArg === "top" || firstArg === "bottom") {
@@ -2824,7 +2892,7 @@ if (firstArg !== undefined) {
   }
 }
 
-if (tool === "js" && toolArgs.file) {
+if ((tool === "js" || tool === "frame.js") && toolArgs.file) {
   try {
     toolArgs.code = fs.readFileSync(toolArgs.file, "utf8");
     delete toolArgs.file;
@@ -2834,6 +2902,17 @@ if (tool === "js" && toolArgs.file) {
   }
 }
 
+if (tool === "batch" && toolArgs.file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(toolArgs.file, "utf8"));
+    toolArgs.actions = parsed;
+    delete toolArgs.file;
+  } catch (e) {
+    console.error(`Error: Failed to read batch file: ${e.message}`);
+    process.exit(1);
+  }
+}
+
 // Handle select command: capture multiple values after selector
 if (tool === "select" && positional.length > 2) {
   const values = positional.slice(2);  // All args after "select <selector>"
@@ -2898,23 +2977,18 @@ if (tool === "aistudio.build" && outputPath) {
   toolArgs.output = path.resolve(outputPath);
 }
 if (tool === "gemini") {
-  if (outputPath) toolArgs.output = path.resolve(outputPath);
-  if (toolArgs["generate-image"] && typeof toolArgs["generate-image"] === "string") {
-    toolArgs["generate-image"] = path.resolve(toolArgs["generate-image"]);
-  }
-  if (toolArgs["edit-image"] && typeof toolArgs["edit-image"] === "string") {
-    toolArgs["edit-image"] = path.resolve(toolArgs["edit-image"]);
-  }
-  if (toolArgs.file && typeof toolArgs.file === "string") {
-    toolArgs.file = path.resolve(toolArgs.file);
+  if (outputPath !== undefined) toolArgs.output = outputPath;
+  if (toolArgs.model) {
+    const known = ["gemini-3.1-pro", "gemini-3.5-flash", "gemini-3.1-flash-lite"];
+    if (!known.includes(toolArgs.model)) {
+      process.stderr.write(
+        `warning: unknown Gemini model "${toolArgs.model}"; using "gemini-3.1-pro". Available: ${known.join(", ")}\n`,
+      );
+    }
   }
 }
-if (tool === "chatgpt" && toolArgs.file) {
-  if (Array.isArray(toolArgs.file)) {
-    toolArgs.file = toolArgs.file.map((filePath) => path.resolve(filePath));
-  } else if (typeof toolArgs.file === "string") {
-    toolArgs.file = path.resolve(toolArgs.file);
-  }
+if (tool === "network.export" && outputPath !== undefined) {
+  toolArgs.output = outputPath;
 }
 
 if ((tool === "screenshot" || tool === "record" || tool === "perf-audit") && outputPath && typeof outputPath !== "string") {
@@ -2938,7 +3012,9 @@ const streamMode = toolArgs.stream === true;
 delete toolArgs.stream;
 
 const streamLevel = toolArgs.level;
-delete toolArgs.level;
+if (tool === "console" || tool === "network") {
+  delete toolArgs.level;
+}
 
 const streamFilter = toolArgs.filter;
 delete toolArgs.filter;
@@ -2946,11 +3022,15 @@ delete toolArgs.filter;
 let finalTool = tool;
 if (methodFlag === "js") {
   if (tool === "type") {
-    if (!toolArgs.selector) {
-      console.error("Error: --selector or --into required for type with --method js");
-      process.exit(1);
+    if (toolArgs.ref) {
+      finalTool = "type";
+    } else {
+      if (!toolArgs.selector) {
+        console.error("Error: --selector, --into, or --ref required for type with --method js");
+        process.exit(1);
+      }
+      finalTool = "smart_type";
     }
-    finalTool = "smart_type";
   } else if (tool === "click") {
     if (!toolArgs.selector) {
       console.error("Error: --selector required for click with --method js");
@@ -2961,8 +3041,13 @@ if (methodFlag === "js") {
     finalTool = "js";
   }
 } else if (methodFlag === "cdp") {
+  if (tool === "type" && (toolArgs.selector || toolArgs.ref)) {
+    console.error("Error: --method cdp types at the current focus and cannot be combined with --into, --selector, or --ref");
+    process.exit(1);
+  }
   if (tool === "smart_type") {
-    finalTool = "type";
+    console.error("Error: smart_type uses the JS input path and cannot be combined with --method cdp");
+    process.exit(1);
   }
 }
 
@@ -2980,8 +3065,10 @@ if (streamMode && (tool === "console" || tool === "network")) {
 
   let connectionTimeout = null;
   let receivedData = false;
+  let streamWriter;
 
-  const sock = net.createConnection(SOCKET_PATH, () => {
+  const sock = connectEndpoint(endpoint, () => {
+    streamWriter = createSocketWriter(sock, { onOverflow: ({ error }) => sock.destroy(error) });
     const req = {
       type: "stream_request",
       streamType,
@@ -2989,7 +3076,11 @@ if (streamMode && (tool === "console" || tool === "network")) {
       id: "cli-stream-" + Date.now(),
       ...globalOpts,
     };
-    sock.write(JSON.stringify(req) + "\n");
+    streamWriter.send(req).catch((error) => sock.destroy(error));
+    if (connectionTimeout) {
+      clearTimeout(connectionTimeout);
+      connectionTimeout = null;
+    }
     connectionTimeout = setTimeout(() => {
       if (!receivedData) {
         console.error("Error: Stream connection timeout (10s) - no data received");
@@ -2999,57 +3090,62 @@ if (streamMode && (tool === "console" || tool === "network")) {
     }, 10000);
   });
 
-  let buf = "";
-  sock.on("data", (d) => {
-    if (!receivedData) {
-      receivedData = true;
-      if (connectionTimeout) {
-        clearTimeout(connectionTimeout);
-        connectionTimeout = null;
-      }
-    }
-    buf += d.toString();
-    const lines = buf.split("\n");
-    buf = lines.pop();
-    for (const line of lines) {
-      if (!line.trim()) continue;
-      try {
-        const msg = JSON.parse(line);
-        if (msg.error) {
-          console.error("Error:", msg.error);
-          sock.end();
-          process.exit(1);
-        }
-        if (msg.type === "extension_disconnected") {
-          console.error(msg.message);
-          sock.end();
-          process.exit(1);
-        }
-        if (msg.type === "stream_started") {
-          continue;
-        }
-        if (msg.type === "console_event") {
-          const { level, text, timestamp } = msg;
-          if (streamLevel && level !== streamLevel) continue;
-          console.log(`[console] [${level}] ${formatTime(timestamp)} ${text}`);
-        } else if (msg.type === "network_event") {
-          const { method, url, status, duration } = msg;
-          if (streamFilter && !url.includes(streamFilter)) continue;
-          const statusStr = status !== undefined ? status : "...";
-          const durationStr = duration !== undefined ? ` (${duration}ms)` : "";
-          console.log(`[network] ${method} ${url} ${statusStr}${durationStr}`);
+  connectionTimeout = setTimeout(() => {
+    console.error(`Error: Stream connection timeout (10s) - could not connect to ${endpoint.display}`);
+    sock.destroy();
+    process.exit(1);
+  }, 10000);
+
+  const parser = createFrameParser({
+    onFrame(msg) {
+      if (!receivedData) {
+        receivedData = true;
+        if (connectionTimeout) {
+          clearTimeout(connectionTimeout);
+          connectionTimeout = null;
         }
-      } catch {}
-    }
+      }
+      if (msg.error) {
+        console.error("Error:", msg.error);
+        sock.end();
+        process.exit(1);
+      }
+      if (msg.type === "extension_disconnected") {
+        console.error(msg.message);
+        sock.end();
+        process.exit(1);
+      }
+      if (msg.type === "stream_started") return;
+      if (msg.type === "console_event") {
+        const { level, text, timestamp } = msg;
+        if (streamLevel && level !== streamLevel) return;
+        console.log(`[console] [${level}] ${formatTime(timestamp)} ${text}`);
+      } else if (msg.type === "network_event") {
+        const { method, url, status, duration } = msg;
+        if (streamFilter && !url.includes(streamFilter)) return;
+        const statusStr = status !== undefined ? status : "...";
+        const durationStr = duration !== undefined ? ` (${duration}ms)` : "";
+        console.log(`[network] ${method} ${url} ${statusStr}${durationStr}`);
+      }
+    },
+    onError(error) {
+      if (connectionTimeout) clearTimeout(connectionTimeout);
+      console.error("Error:", error.message);
+      sock.destroy();
+      process.exit(1);
+    },
   });
+  sock.on("data", (data) => parser.push(data));
 
   sock.on("error", (e) => {
-    console.error("Error:", formatSocketError(e));
+    if (connectionTimeout) clearTimeout(connectionTimeout);
+    console.error("Error:", formatEndpointError(e, endpoint, formatSocketError));
     process.exit(1);
   });
 
   process.on("SIGINT", () => {
-    sock.write(JSON.stringify({ type: "stream_stop" }) + "\n");
+    if (connectionTimeout) clearTimeout(connectionTimeout);
+    streamWriter?.send({ type: "stream_stop" }).catch(() => {});
     sock.end();
     process.exit(0);
   });
@@ -3057,6 +3153,17 @@ if (streamMode && (tool === "console" || tool === "network")) {
   return;
 }
 
+let transferPlan;
+try {
+  transferPlan = endpoint.kind === "remote" ? prepareRemoteTool(finalTool, toolArgs) : (() => { const args = validateLocalToolPaths(finalTool, toolArgs); return { args, uploads: [], downloads: [] }; })();
+} catch (error) {
+  const message = finalTool === "record" && endpoint.kind === "remote"
+    ? `record is not supported with remote endpoint ${endpoint.display}`
+    : error.message;
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+toolArgs = transferPlan.args;
 const request = {
   type: "tool_request",
   method: "execute_tool",
@@ -3065,45 +3172,20 @@ const request = {
   ...globalOpts,
 };
 
-const sendRequest = (toolName, toolArgs = {}, timeoutMs = 5000) => {
-  return new Promise((resolve, reject) => {
-    const sock = net.createConnection(SOCKET_PATH, () => {
-      const req = {
-        type: "tool_request",
-        method: "execute_tool",
-        params: { tool: toolName, args: toolArgs },
-        id: "cli-" + Date.now() + "-" + Math.random(),
-        ...globalOpts,
-      };
-      sock.write(JSON.stringify(req) + "\n");
-    });
-    let buf = "";
-    sock.on("data", (d) => {
-      buf += d.toString();
-      const lines = buf.split("\n");
-      buf = lines.pop();
-      for (const line of lines) {
-        if (!line.trim()) continue;
-        try {
-          const resp = JSON.parse(line);
-          if (resp.type === "extension_disconnected") {
-            sock.end();
-            reject(new Error(resp.message));
-            return;
-          }
-          sock.end();
-          resolve(resp);
-        } catch {
-          sock.end();
-          reject(new Error("Invalid JSON"));
-        }
-      }
-    });
-    sock.on("error", (e) => reject(new Error(formatSocketError(e))));
-    let timeoutId;
-    timeoutId = setTimeout(() => { sock.destroy(); reject(new Error("Timeout")); }, timeoutMs);
-    sock.on("close", () => clearTimeout(timeoutId));
-  });
+const sendRequest = async (toolName, toolArgs = {}, timeoutMs = 5000) => {
+  const transport = await openClientTransport(endpoint, { requestTimeoutMs: timeoutMs });
+  try {
+    const prepared = endpoint.kind === "remote" ? prepareRemoteTool(toolName, toolArgs) : (() => { const args = validateLocalToolPaths(toolName, toolArgs); return { args, uploads: [], downloads: [] }; })();
+    return await transport.request({
+      type: "tool_request",
+      method: "execute_tool",
+      params: { tool: toolName, args: prepared.args },
+      id: "cli-" + Date.now() + "-" + Math.random(),
+      ...globalOpts,
+    }, timeoutMs, prepared);
+  } finally {
+    await transport.close();
+  }
 };
 
 function parseRecordNumber(value, fallback, name, min, max) {
@@ -3270,7 +3352,11 @@ const performAutoCapture = async () => {
 };
 
 if (finalTool === "record") {
-  installBrowserLock(lockOptions);
+  if (endpoint.kind === "remote") {
+    console.error(`Error: record is not supported with remote endpoint ${endpoint.display}`);
+    process.exit(1);
+  }
+  installBrowserLock(lockOptions, endpoint);
   runRecord()
     .then(() => process.exit(0))
     .catch((error) => {
@@ -3280,57 +3366,67 @@ if (finalTool === "record") {
   return;
 }
 
-installBrowserLock(lockOptions);
+installBrowserLock(lockOptions, endpoint);
+let socket;
+let timeout;
+
+if (endpoint.kind === "remote") {
+  socket = { end() {}, destroy() {} };
+  const requestTimeout = resolveRequestDeadlineMs(tool, toolArgs);
+  openClientTransport(endpoint, { requestTimeoutMs: requestTimeout })
+    .then(async (transport) => {
+      try {
+        const response = await transport.request(request, requestTimeout, transferPlan);
+        await handleResponse(response);
+      } finally {
+        await transport.close();
+      }
+    })
+    .catch((error) => {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    });
+  return;
+}
 
-const socket = net.createConnection(SOCKET_PATH, () => {
-  socket.write(JSON.stringify(request) + "\n");
+socket = connectEndpoint(endpoint, () => {
+  writeFrame(socket, request).catch((error) => socket.destroy(error));
 });
 
-const AI_TOOLS = ["smoke", "chatgpt", "gemini", "perplexity", "grok", "aistudio", "aistudio.build", "ai"];
-let requestTimeout = AI_TOOLS.includes(tool) ? 300000 : 30000;
-if (tool === "aistudio.build") {
-  const userTimeoutSec = parseInt(options.timeout || "600", 10);
-  requestTimeout = (userTimeoutSec * 1000) + 60000;
-}
-const timeout = setTimeout(() => {
+const requestTimeout = resolveRequestDeadlineMs(tool, options);
+timeout = setTimeout(() => {
   console.error(`Error: Request timed out (${requestTimeout / 1000}s)`);
   socket.destroy();
   process.exit(1);
 }, requestTimeout);
 
-let buffer = "";
-
-socket.on("data", (data) => {
-  buffer += data.toString();
-  const lines = buffer.split("\n");
-  buffer = lines.pop();
-
-  for (const line of lines) {
-    if (!line.trim()) continue;
-    try {
-      const msg = JSON.parse(line);
-
-      if (msg.type === "extension_disconnected") {
-        clearTimeout(timeout);
-        console.error(msg.message);
-        socket.end();
-        process.exit(1);
-      }
-
-      handleResponse(msg).catch((err) => {
-        console.error("Handler error:", err.message);
-        process.exit(1);
-      });
-    } catch (e) {
-      console.error("Invalid JSON response:", line);
+const responseParser = createFrameParser({
+  onFrame(msg) {
+    if (msg.type === "extension_disconnected") {
+      clearTimeout(timeout);
+      console.error(msg.message);
+      socket.end();
       process.exit(1);
     }
-  }
+    if (msg.id !== request.id) return;
+    handleResponse(msg).catch((err) => {
+      console.error("Handler error:", err.message);
+      process.exit(1);
+    });
+  },
+  onError(error) {
+    clearTimeout(timeout);
+    console.error("Invalid response frame:", error.message);
+    socket.destroy();
+    process.exit(1);
+  },
 });
 
+socket.on("data", (data) => responseParser.push(data));
+
 socket.on("error", (err) => {
   clearTimeout(timeout);
-  console.error("Error:", formatSocketError(err));
+  console.error("Error:", formatEndpointError(err, endpoint, formatSocketError));
   process.exit(1);
 });
 
@@ -3389,7 +3485,7 @@ async function handleResponse(response) {
   }
 
   if (tool === "screenshot" && data?.base64 && (outputPath || toolArgs.savePath)) {
-    const saveTo = outputPath || toolArgs.savePath;
+    const saveTo = transferPlan.downloads?.[0]?.destination || toolArgs.savePath || outputPath;
     fs.writeFileSync(saveTo, Buffer.from(data.base64, "base64"));
 
     const skipResize = options.full || toolArgs.full;