surf-cli 2.8.0 → 2.10.0

package/native/cli.cjs

@@ -1,19 +1,34 @@
 #!/usr/bin/env node
-const net = require("net");
 const fs = require("fs");
 const path = require("path");
-const os = require("os");
 const { execFileSync, execSync } = require("child_process");
 const { loadConfig, getConfigPath, createStarterConfig } = require("./config.cjs");
 const networkFormatters = require("./formatters/network.cjs");
-const networkStore = require("./network-store.cjs");
-const { parseDoCommands } = require("./do-parser.cjs");
+const {
+  applyArgDefaults,
+  formatStep,
+  getWorkflowDirs,
+  getWorkflowInfo,
+  listWorkflows,
+  normalizeWorkflow,
+  parseDoCommands,
+  resolveWorkflow,
+  validateWorkflowArgs,
+  validateWorkflowFile,
+} = require("./workflow-definition.cjs");
 const { executeDoSteps } = require("./do-executor.cjs");
+const { openClientTransport } = require("./client-transport.cjs");
 const { version: VERSION } = require("../package.json");
+const { formatPlaybookOutput, handlePlaybookCli, playbookCommandNeedsBrowser } = require("./playbook-cli.cjs");
 
 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 +44,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));
@@ -58,249 +73,6 @@ function installBrowserLock({ noLock, timeoutMs }) {
   });
 }
 
-// ============================================================================
-// Workflow Resolution and Management
-// ============================================================================
-
-/**
- * Get workflow search directories
- * @returns {Array<{path: string, scope: string}>}
- */
-function getWorkflowDirs() {
-  return [
-    { path: path.join(process.cwd(), '.surf', 'workflows'), scope: 'project' },
-    { path: path.join(os.homedir(), '.surf', 'workflows'), scope: 'user' },
-  ];
-}
-
-/**
- * Resolve a workflow by name or path
- * @param {string} nameOrPath - Workflow name or file path
- * @returns {{ type: 'inline'|'file'|'not_found', content?: string, path?: string, name?: string }}
- */
-function resolveWorkflow(nameOrPath) {
-  // Check if it's an inline workflow (contains pipe)
-  if (nameOrPath.includes('|')) {
-    return { type: 'inline', content: nameOrPath };
-  }
-
-  // Check if it's a direct file path (with extension or path separator)
-  if (nameOrPath.includes('/') || nameOrPath.includes('\\') || nameOrPath.endsWith('.json')) {
-    if (fs.existsSync(nameOrPath)) {
-      return { type: 'file', path: nameOrPath };
-    }
-    return { type: 'not_found', name: nameOrPath };
-  }
-
-  // Look up by name in workflow directories
-  const searchDirs = getWorkflowDirs();
-
-  for (const { path: dir } of searchDirs) {
-    const filePath = path.join(dir, `${nameOrPath}.json`);
-    if (fs.existsSync(filePath)) {
-      return { type: 'file', path: filePath };
-    }
-  }
-
-  return { type: 'not_found', name: nameOrPath };
-}
-
-/**
- * List all available workflows
- * @returns {Array<{name: string, description: string, scope: string, path: string, args?: object}>}
- */
-function listWorkflows() {
-  const workflows = [];
-  const searchDirs = getWorkflowDirs();
-
-  for (const { path: dir, scope } of searchDirs) {
-    if (fs.existsSync(dir)) {
-      try {
-        const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
-        for (const file of files) {
-          const filePath = path.join(dir, file);
-          try {
-            const content = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-            workflows.push({
-              name: content.name || file.replace('.json', ''),
-              description: content.description || '',
-              scope,
-              path: filePath,
-              args: content.args,
-              stepCount: content.steps?.length || 0,
-            });
-          } catch {
-            // Skip invalid JSON files
-          }
-        }
-      } catch {
-        // Skip inaccessible directories
-      }
-    }
-  }
-
-  return workflows;
-}
-
-/**
- * Get detailed info about a workflow
- * @param {string} name - Workflow name
- * @returns {{ error?: string, name?: string, description?: string, args?: object, steps?: Array, path?: string }}
- */
-function getWorkflowInfo(name) {
-  const resolved = resolveWorkflow(name);
-
-  if (resolved.type === 'not_found') {
-    return { error: `Workflow not found: ${name}` };
-  }
-
-  if (resolved.type === 'inline') {
-    return { error: 'Cannot get info for inline workflows' };
-  }
-
-  try {
-    const content = JSON.parse(fs.readFileSync(resolved.path, 'utf8'));
-    return {
-      name: content.name || name,
-      description: content.description || '',
-      args: content.args || {},
-      steps: content.steps || [],
-      path: resolved.path,
-    };
-  } catch (e) {
-    return { error: `Failed to parse workflow: ${e.message}` };
-  }
-}
-
-/**
- * Validate workflow args against schema
- * @param {object} workflow - Workflow with args schema
- * @param {object} providedArgs - User-provided args
- * @returns {string[]} - Array of error messages
- */
-function validateWorkflowArgs(workflow, providedArgs) {
-  const errors = [];
-  if (workflow.args) {
-    for (const [name, spec] of Object.entries(workflow.args)) {
-      if (spec.required && providedArgs[name] === undefined) {
-        errors.push(`Missing required argument: --${name}`);
-      }
-    }
-  }
-  return errors;
-}
-
-/**
- * Apply default values to workflow args
- * @param {object} workflow - Workflow with args schema
- * @param {object} providedArgs - User-provided args
- * @returns {object} - Args with defaults applied
- */
-function applyArgDefaults(workflow, providedArgs) {
-  const vars = { ...providedArgs };
-  if (workflow.args) {
-    for (const [name, spec] of Object.entries(workflow.args)) {
-      if (vars[name] === undefined && spec.default !== undefined) {
-        vars[name] = spec.default;
-      }
-    }
-  }
-  return vars;
-}
-
-/**
- * Validate a workflow JSON file
- * @param {string} filePath - Path to workflow file
- * @returns {{ valid: boolean, error?: string, workflow?: object }}
- */
-function validateWorkflowFile(filePath) {
-  if (!fs.existsSync(filePath)) {
-    return { valid: false, error: `File not found: ${filePath}` };
-  }
-
-  try {
-    const content = fs.readFileSync(filePath, 'utf8');
-    const workflow = JSON.parse(content);
-
-    // Basic structure validation
-    if (!workflow.steps || !Array.isArray(workflow.steps)) {
-      return { valid: false, error: "Workflow must have a 'steps' array" };
-    }
-
-    if (workflow.steps.length === 0) {
-      return { valid: false, error: "Workflow has no steps" };
-    }
-
-    // Validate each step
-    for (let i = 0; i < workflow.steps.length; i++) {
-      const step = workflow.steps[i];
-
-      // Check for loops
-      if (step.repeat !== undefined || step.each !== undefined) {
-        if (!step.steps || !Array.isArray(step.steps)) {
-          return { valid: false, error: `Step ${i + 1}: loop must have a 'steps' array` };
-        }
-        continue;
-      }
-
-      // Regular step must have tool/cmd
-      if (!step.tool && !step.cmd) {
-        return { valid: false, error: `Step ${i + 1}: must have 'tool' field` };
-      }
-    }
-
-    // Validate args schema if present
-    if (workflow.args && typeof workflow.args !== 'object') {
-      return { valid: false, error: "'args' must be an object" };
-    }
-
-    return { valid: true, workflow };
-  } catch (e) {
-    return { valid: false, error: `Invalid JSON: ${e.message}` };
-  }
-}
-
-/**
- * Format a step for display
- * @param {object} step - Workflow step
- * @param {number} indent - Indentation level
- * @returns {string}
- */
-function formatStep(step, indent = 0) {
-  const pad = '  '.repeat(indent);
-
-  if (step.repeat !== undefined) {
-    const lines = [`${pad}repeat ${step.repeat} times:`];
-    for (const s of step.steps || []) {
-      lines.push(formatStep(s, indent + 1));
-    }
-    if (step.until) {
-      lines.push(`${pad}  until: ${step.until.tool || step.until.cmd}`);
-    }
-    return lines.join('\n');
-  }
-
-  if (step.each !== undefined) {
-    const lines = [`${pad}each ${step.each} as ${step.as || 'item'}:`];
-    for (const s of step.steps || []) {
-      lines.push(formatStep(s, indent + 1));
-    }
-    return lines.join('\n');
-  }
-
-  const tool = step.tool || step.cmd;
-  const args = step.args || {};
-  const argStr = Object.entries(args)
-    .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
-    .join(' ');
-
-  let line = `${pad}${tool}`;
-  if (argStr) line += ` ${argStr}`;
-  if (step.as) line += ` → ${step.as}`;
-
-  return line;
-}
-
 // Cross-platform image resize (macOS: sips, Linux: ImageMagick)
 function resizeImage(filePath, maxSize) {
   const platform = process.platform;
@@ -336,7 +108,67 @@ 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);
+}
+
+if (["playbook", "pb", "use"].includes(args[0])) {
+  if (playbookCommandNeedsBrowser(args)) {
+    installBrowserLock(parseBrowserLockOptions(args.includes("--no-lock")), endpoint);
+  }
+  handlePlaybookCli(args, { endpoint, cwd: process.cwd() })
+    .then((result) => {
+      if (!result.handled) throw new Error("Playbook command was not handled");
+      if (result.value !== undefined) console.log(formatPlaybookOutput(result.value, result.json));
+      process.exit(0);
+    })
+    .catch((error) => {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    });
+  return;
+}
 
 const ALIASES = {
   snap: "screenshot",
@@ -405,7 +237,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 +360,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 +513,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 +521,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 +662,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)" },
@@ -896,6 +735,9 @@ const TOOLS = {
           all: "Show all (no limit)",
           v: "Verbose output",
           vv: "Very verbose output",
+          "body-mode": "Response bodies: none, text, or all (default: text)",
+          "per-body-bytes": "Maximum captured bytes per response body",
+          "total-body-bytes": "Maximum captured response-body bytes per tab session",
           clear: "Clear after reading",
           stream: "Continuous output"
         },
@@ -960,9 +802,17 @@ const TOOLS = {
       "network.export": {
         desc: "Export captured requests",
         args: [],
-        opts: { jsonl: "Export as JSONL", output: "Output file path" },
+        opts: {
+          har: "Export as HAR 1.2",
+          jsonl: "Export as JSONL",
+          output: "Output file path",
+          "body-mode": "Response bodies: none, text, or all (default: text)",
+          "per-body-bytes": "Maximum captured bytes per response body",
+          "total-body-bytes": "Maximum captured response-body bytes per tab session",
+        },
         examples: [
-          { cmd: "network.export --jsonl --output /tmp/requests.jsonl", desc: "Export as JSONL" }
+          { cmd: "network.export --jsonl --output /tmp/requests.jsonl", desc: "Export as JSONL" },
+          { cmd: "network.export --har --output /tmp/requests.har", desc: "Export as HAR" },
         ]
       },
       "network.path": {
@@ -1567,7 +1417,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 +1509,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...)
@@ -1701,6 +1555,10 @@ const showFullHelp = () => {
 
 Usage: surf <command> [args] [options]
 
+Playbooks:
+  surf playbook|pb <list|show|ops|run|record|suggest|save|client|trace|export|import>
+  surf use <playbook> <op> [--arg value]
+
 `);
   for (const [groupName, group] of Object.entries(TOOLS)) {
     console.log(`${groupName.toUpperCase()} - ${group.desc}`);
@@ -1715,6 +1573,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 +1582,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 +1802,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 +1818,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 +1843,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 +1988,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 +2063,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;
 }
 
@@ -2346,9 +2201,7 @@ if (args[0] === "do") {
 
     // Process workflow file if loaded
     if (workflow) {
-      if (!workflow.steps || !Array.isArray(workflow.steps)) {
-        throw new Error("Workflow must have a 'steps' array");
-      }
+      workflow = normalizeWorkflow(workflow);
 
       // Validate required args
       const argErrors = validateWorkflowArgs(workflow, workflowArgs);
@@ -2368,30 +2221,7 @@ if (args[0] === "do") {
         process.exit(1);
       }
 
-      // Convert steps: support both { tool, args } and { cmd, args } formats
-      // Also preserve loop steps as-is
-      steps = workflow.steps.map(s => {
-        if (s.repeat !== undefined || s.each !== undefined) {
-          // Loop step - convert nested steps recursively
-          const convertSteps = (stepsArr) => stepsArr.map(ns => {
-            if (ns.repeat !== undefined || ns.each !== undefined) {
-              // Recursively convert nested loop steps and until condition
-              return {
-                ...ns,
-                steps: convertSteps(ns.steps || []),
-                until: ns.until ? { cmd: ns.until.tool || ns.until.cmd, args: ns.until.args || {} } : undefined
-              };
-            }
-            return { cmd: ns.tool || ns.cmd, args: ns.args || {}, as: ns.as };
-          });
-          return {
-            ...s,
-            steps: convertSteps(s.steps || []),
-            until: s.until ? { cmd: s.until.tool || s.until.cmd, args: s.until.args || {} } : undefined
-          };
-        }
-        return { cmd: s.tool || s.cmd, args: s.args || {}, as: s.as };
-      });
+      steps = workflow.steps;
     }
   } catch (e) {
     console.error(`Error: Failed to parse workflow: ${e.message}`);
@@ -2425,7 +2255,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 +2266,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 +2278,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 +2438,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 +2573,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 +2605,7 @@ const PRIMARY_ARG_MAP = {
   "select": "selector",
 };
 
-const toolArgs = { ...options };
+let toolArgs = { ...options };
 
 if (tool === "scroll" && firstArg) {
   if (firstArg === "top" || firstArg === "bottom") {
@@ -2824,7 +2666,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 +2676,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>"
@@ -2869,9 +2722,9 @@ if (toolArgs["window-id"] !== undefined) {
   globalOpts.windowId = wid;
   delete toolArgs["window-id"];
 }
-if (toolArgs["network-path"] !== undefined) {
-  networkStore.setBasePath(toolArgs["network-path"]);
-  delete toolArgs["network-path"];
+if (toolArgs["network-path"] !== undefined && typeof toolArgs["network-path"] !== "string") {
+  console.error("Error: --network-path requires a directory");
+  process.exit(1);
 }
 const wantJson = toolArgs.json === true;
 delete toolArgs.json;
@@ -2898,23 +2751,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 +2786,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 +2796,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 +2815,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 +2839,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 +2850,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 +2864,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 +2927,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 +2946,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 +3126,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 +3140,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 +3259,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;