chrome-relay 0.5.13 → 0.5.15

package/dist/cli.js

@@ -37,26 +37,140 @@ function requireString(obj, key, tool) {
   }
   return v;
 }
-function optString(obj, key) {
+function rejectWrongType(obj, key, expected, tool) {
+  throw new RelayError({
+    code: "invalid_arguments",
+    message: `${tool ?? "<unknown tool>"}: \`${key}\` must be ${expected} (got ${typeof obj[key]}).`,
+    tool,
+    phase: "parse_arguments",
+    details: { field: key, expected, received: obj[key] },
+    retryable: false
+  });
+}
+function optString(obj, key, tool) {
   const v = obj[key];
-  return typeof v === "string" && v ? v : void 0;
+  if (v === void 0 || v === null)
+    return void 0;
+  if (typeof v !== "string")
+    rejectWrongType(obj, key, "a string", tool);
+  return v || void 0;
 }
-function optNumber(obj, key) {
+function optNumber(obj, key, tool) {
   const v = obj[key];
-  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+  if (v === void 0 || v === null)
+    return void 0;
+  if (typeof v !== "number" || !Number.isFinite(v))
+    rejectWrongType(obj, key, "a finite number", tool);
+  return v;
+}
+function optPositiveNumber(obj, key, tool) {
+  const v = optNumber(obj, key, tool);
+  if (v === void 0)
+    return void 0;
+  if (v <= 0) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${tool ?? "<unknown tool>"}: \`${key}\` must be > 0 (got ${v}).`,
+      tool,
+      phase: "parse_arguments",
+      details: { field: key, expected: "> 0", received: v },
+      retryable: false
+    });
+  }
+  return v;
+}
+function optNonNegativeNumber(obj, key, tool) {
+  const v = optNumber(obj, key, tool);
+  if (v === void 0)
+    return void 0;
+  if (v < 0) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${tool ?? "<unknown tool>"}: \`${key}\` must be >= 0 (got ${v}).`,
+      tool,
+      phase: "parse_arguments",
+      details: { field: key, expected: ">= 0", received: v },
+      retryable: false
+    });
+  }
+  return v;
+}
+function coerceTabId(raw, tool) {
+  if (typeof raw === "number") {
+    if (!Number.isFinite(raw)) {
+      throw new RelayError({
+        code: "invalid_arguments",
+        message: `${tool}: invalid tabId ${JSON.stringify(raw)}. Expected a finite number.`,
+        tool,
+        phase: "parse_arguments",
+        details: { received: raw },
+        retryable: false
+      });
+    }
+    return raw;
+  }
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+      throw new RelayError({
+        code: "invalid_arguments",
+        message: `${tool}: invalid tabId ${JSON.stringify(raw)}. Expected a number; got a blank string.`,
+        tool,
+        phase: "parse_arguments",
+        details: { received: raw },
+        retryable: false
+      });
+    }
+    const n = Number(trimmed);
+    if (!Number.isFinite(n)) {
+      throw new RelayError({
+        code: "invalid_arguments",
+        message: `${tool}: invalid tabId ${JSON.stringify(raw)}. Expected a numeric string.`,
+        tool,
+        phase: "parse_arguments",
+        details: { received: raw },
+        retryable: false
+      });
+    }
+    return n;
+  }
+  throw new RelayError({
+    code: "invalid_arguments",
+    message: `${tool}: invalid tabId ${JSON.stringify(raw)}. Expected a number or numeric string.`,
+    tool,
+    phase: "parse_arguments",
+    details: { received: raw },
+    retryable: false
+  });
 }
-function optBool(obj, key) {
+function optBool(obj, key, tool) {
   const v = obj[key];
-  return typeof v === "boolean" ? v : void 0;
+  if (v === void 0 || v === null)
+    return void 0;
+  if (typeof v !== "boolean")
+    rejectWrongType(obj, key, "a boolean", tool);
+  return v;
 }
-function parseTargetArgs(obj) {
+function parseTargetArgs(obj, tool) {
   const out = {};
-  if (typeof obj.tabId === "number")
+  if (obj.tabId !== void 0 && obj.tabId !== null) {
+    if (typeof obj.tabId !== "number" || !Number.isFinite(obj.tabId)) {
+      rejectWrongType(obj, "tabId", "a finite number", tool);
+    }
     out.tabId = obj.tabId;
-  if (typeof obj.workspaceName === "string" && obj.workspaceName)
-    out.workspaceName = obj.workspaceName;
-  if (typeof obj.groupName === "string" && obj.groupName)
-    out.groupName = obj.groupName;
+  }
+  if (obj.workspaceName !== void 0 && obj.workspaceName !== null) {
+    if (typeof obj.workspaceName !== "string")
+      rejectWrongType(obj, "workspaceName", "a string", tool);
+    if (obj.workspaceName)
+      out.workspaceName = obj.workspaceName;
+  }
+  if (obj.groupName !== void 0 && obj.groupName !== null) {
+    if (typeof obj.groupName !== "string")
+      rejectWrongType(obj, "groupName", "a string", tool);
+    if (obj.groupName)
+      out.groupName = obj.groupName;
+  }
   return out;
 }
 var init_shared = __esm({
@@ -69,10 +183,7 @@ var init_shared = __esm({
 // ../protocol/dist/args/navigate.js
 function parseChromeNavigateArgs(input) {
   const obj = asObject(input, TOOL_NAMES.NAVIGATE);
-  const out = {
-    url: requireString(obj, "url", TOOL_NAMES.NAVIGATE),
-    ...parseTargetArgs(obj)
-  };
+  const out = { url: requireString(obj, "url", TOOL_NAMES.NAVIGATE) };
   if (typeof obj.tabId === "string" && obj.tabId) {
     const n = Number(obj.tabId);
     if (!Number.isFinite(n)) {
@@ -87,17 +198,23 @@ function parseChromeNavigateArgs(input) {
     }
     out.tabId = n;
   } else {
-    const n = optNumber(obj, "tabId");
+    const n = optNumber(obj, "tabId", TOOL_NAMES.NAVIGATE);
     if (n !== void 0)
       out.tabId = n;
   }
-  const newTab = optBool(obj, "newTab");
+  const { tabId: _, ...rest } = obj;
+  const target = parseTargetArgs(rest, TOOL_NAMES.NAVIGATE);
+  if (target.workspaceName)
+    out.workspaceName = target.workspaceName;
+  if (target.groupName)
+    out.groupName = target.groupName;
+  const newTab = optBool(obj, "newTab", TOOL_NAMES.NAVIGATE);
   if (newTab !== void 0)
     out.newTab = newTab;
-  const active = optBool(obj, "active");
+  const active = optBool(obj, "active", TOOL_NAMES.NAVIGATE);
   if (active !== void 0)
     out.active = active;
-  const allowPartial = optBool(obj, "allowPartial");
+  const allowPartial = optBool(obj, "allowPartial", TOOL_NAMES.NAVIGATE);
   if (allowPartial !== void 0)
     out.allowPartial = allowPartial;
   void optString;
@@ -114,13 +231,13 @@ var init_navigate = __esm({
 // ../protocol/dist/args/hover.js
 function parseChromeHoverArgs(input) {
   const obj = asObject(input, TOOL_NAMES.HOVER);
-  const target = parseTargetArgs(obj);
-  const x = optNumber(obj, "x");
-  const y = optNumber(obj, "y");
+  const target = parseTargetArgs(obj, TOOL_NAMES.HOVER);
+  const x = optNumber(obj, "x", TOOL_NAMES.HOVER);
+  const y = optNumber(obj, "y", TOOL_NAMES.HOVER);
   if (x !== void 0 && y !== void 0) {
     return { ...target, kind: "coords", x, y };
   }
-  const selector = optString(obj, "selector");
+  const selector = optString(obj, "selector", TOOL_NAMES.HOVER);
   if (selector) {
     return { ...target, kind: "selector", selector };
   }
@@ -197,7 +314,7 @@ function parseChromeNetworkArgs(input) {
     const full = optBool(obj, "full");
     if (full !== void 0)
       out.full = full;
-    const head = optNumber(obj, "head");
+    const head = optPositiveNumber(obj, "head", TOOL_NAMES.NETWORK);
     if (head !== void 0)
       out.head = head;
     return out;
@@ -236,10 +353,14 @@ var init_network = __esm({
 });
 
 // ../protocol/dist/args/simple.js
-function parseGetWindowsAndTabsArgs(_input) {
+function parseGetWindowsAndTabsArgs(input) {
+  if (input !== void 0 && input !== null)
+    asObject(input, TOOL_NAMES.GET_WINDOWS_AND_TABS);
   return {};
 }
-function parseChromeSelfReloadArgs(_input) {
+function parseChromeSelfReloadArgs(input) {
+  if (input !== void 0 && input !== null)
+    asObject(input, TOOL_NAMES.SELF_RELOAD);
   return {};
 }
 function parseChromeReadPageArgs(input) {
@@ -297,27 +418,25 @@ function parseChromeEvaluateArgs(input) {
   const obj = asObject(input, TOOL_NAMES.EVALUATE);
   const out = {
     code: requireString(obj, "code", TOOL_NAMES.EVALUATE),
-    ...parseTargetArgs(obj)
+    ...parseTargetArgs(obj, TOOL_NAMES.EVALUATE)
   };
-  const t = optNumber(obj, "timeoutMs");
+  const t = optPositiveNumber(obj, "timeoutMs", TOOL_NAMES.EVALUATE);
   if (t !== void 0)
     out.timeoutMs = t;
   return out;
 }
 function parseChromeSwitchTabArgs(input) {
   const obj = asObject(input, TOOL_NAMES.SWITCH_TAB);
-  const tabId = Number(obj.tabId);
-  if (!Number.isFinite(tabId)) {
+  if (obj.tabId === void 0 || obj.tabId === null) {
     throw new RelayError({
       code: "invalid_arguments",
       message: `${TOOL_NAMES.SWITCH_TAB} requires a numeric tabId.`,
       tool: TOOL_NAMES.SWITCH_TAB,
       phase: "parse_arguments",
-      details: { received: obj.tabId },
       retryable: false
     });
   }
-  return { tabId };
+  return { tabId: coerceTabId(obj.tabId, TOOL_NAMES.SWITCH_TAB) };
 }
 function parseChromeCloseTabsArgs(input) {
   const obj = asObject(input, TOOL_NAMES.CLOSE_TABS);
@@ -331,18 +450,17 @@ function parseChromeCloseTabsArgs(input) {
       retryable: false
     });
   }
-  const tabIds = obj.tabIds.map((v) => Number(v));
-  if (tabIds.length === 0 || tabIds.some((n) => !Number.isFinite(n))) {
+  if (obj.tabIds.length === 0) {
     throw new RelayError({
       code: "invalid_arguments",
-      message: `${TOOL_NAMES.CLOSE_TABS} requires a non-empty array of numeric tab IDs.`,
+      message: `${TOOL_NAMES.CLOSE_TABS} requires a non-empty array of tab IDs.`,
       tool: TOOL_NAMES.CLOSE_TABS,
       phase: "parse_arguments",
       details: { received: obj.tabIds },
       retryable: false
     });
   }
-  return { tabIds };
+  return { tabIds: obj.tabIds.map((v) => coerceTabId(v, TOOL_NAMES.CLOSE_TABS)) };
 }
 function parseChromeAxArgs(input) {
   const obj = asObject(input, TOOL_NAMES.AX);
@@ -375,21 +493,21 @@ function parseChromeClickAxArgs(input) {
 }
 function parseChromeScreenshotArgs(input) {
   const obj = asObject(input, TOOL_NAMES.SCREENSHOT);
-  const out = { ...parseTargetArgs(obj) };
-  const fp = optBool(obj, "fullPage");
+  const out = { ...parseTargetArgs(obj, TOOL_NAMES.SCREENSHOT) };
+  const fp = optBool(obj, "fullPage", TOOL_NAMES.SCREENSHOT);
   if (fp !== void 0)
     out.fullPage = fp;
-  const bbox = optString(obj, "bbox");
+  const bbox = optString(obj, "bbox", TOOL_NAMES.SCREENSHOT);
   if (bbox)
     out.bbox = bbox;
-  const sel = optString(obj, "selector");
+  const sel = optString(obj, "selector", TOOL_NAMES.SCREENSHOT);
   if (sel)
     out.selector = sel;
-  const pad = optNumber(obj, "padding");
+  const pad = optNonNegativeNumber(obj, "padding", TOOL_NAMES.SCREENSHOT);
   if (pad !== void 0)
     out.padding = pad;
-  const me = optNumber(obj, "maxEdge");
-  if (me !== void 0 && me > 0)
+  const me = optPositiveNumber(obj, "maxEdge", TOOL_NAMES.SCREENSHOT);
+  if (me !== void 0)
     out.maxEdge = me;
   return out;
 }
@@ -532,28 +650,12 @@ function parseChromeWorkspaceArgs(input) {
   return out;
 }
 function parseTabIds(raw) {
-  const reject = (bad) => {
-    throw new RelayError({
-      code: "invalid_arguments",
-      message: `${TOOL_NAMES.GROUP}: invalid tabId ${JSON.stringify(bad)}. Expected a number or a comma-separated list of numbers.`,
-      tool: TOOL_NAMES.GROUP,
-      phase: "parse_tab_ids",
-      details: { received: bad },
-      retryable: false
-    });
-  };
-  const coerce = (v) => {
-    const n = Number(typeof v === "string" ? v.trim() : v);
-    if (!Number.isFinite(n))
-      reject(v);
-    return n;
-  };
   if (Array.isArray(raw))
-    return raw.map(coerce);
+    return raw.map((v) => coerceTabId(v, TOOL_NAMES.GROUP));
   if (typeof raw === "string")
-    return raw.split(",").map(coerce);
+    return raw.split(",").map((s) => coerceTabId(s, TOOL_NAMES.GROUP));
   if (typeof raw === "number")
-    return [raw];
+    return [coerceTabId(raw, TOOL_NAMES.GROUP)];
   return [];
 }
 function parseColor(raw) {
@@ -673,16 +775,27 @@ function parseChromeScreencastArgs(input) {
     }
     out.format = obj.format;
   }
-  const q = optNumber(obj, "quality");
-  if (q !== void 0)
+  const q = optNonNegativeNumber(obj, "quality", TOOL_NAMES.SCREENCAST);
+  if (q !== void 0) {
+    if (q > 100) {
+      throw new RelayError({
+        code: "invalid_arguments",
+        message: `${TOOL_NAMES.SCREENCAST}: quality must be 0-100 (got ${q}).`,
+        tool: TOOL_NAMES.SCREENCAST,
+        phase: "parse_arguments",
+        details: { field: "quality", received: q, range: [0, 100] },
+        retryable: false
+      });
+    }
     out.quality = q;
-  const mw = optNumber(obj, "maxWidth");
+  }
+  const mw = optPositiveNumber(obj, "maxWidth", TOOL_NAMES.SCREENCAST);
   if (mw !== void 0)
     out.maxWidth = mw;
-  const mh = optNumber(obj, "maxHeight");
+  const mh = optPositiveNumber(obj, "maxHeight", TOOL_NAMES.SCREENCAST);
   if (mh !== void 0)
     out.maxHeight = mh;
-  const en = optNumber(obj, "everyNthFrame");
+  const en = optPositiveNumber(obj, "everyNthFrame", TOOL_NAMES.SCREENCAST);
   if (en !== void 0)
     out.everyNthFrame = en;
   return out;
@@ -717,21 +830,50 @@ var init_args = __esm({
   }
 });
 
+// ../protocol/dist/limits.js
+var DEFAULT_TOOL_CALL_TIMEOUT_MS, DEFAULT_PING_TIMEOUT_MS, DEFAULT_READY_TIMEOUT_MS, DEFAULT_EVAL_TIMEOUT_MS, DEFAULT_BODY_PREVIEW_BYTES, NETWORK_BUFFER_MAX_ENTRIES, NETWORK_BUFFER_MAX_BYTES, CONSOLE_BUFFER_MAX_ENTRIES, CONSOLE_BUFFER_MAX_BYTES;
+var init_limits = __esm({
+  "../protocol/dist/limits.js"() {
+    "use strict";
+    DEFAULT_TOOL_CALL_TIMEOUT_MS = 3e4;
+    DEFAULT_PING_TIMEOUT_MS = 2e3;
+    DEFAULT_READY_TIMEOUT_MS = 15e3;
+    DEFAULT_EVAL_TIMEOUT_MS = 15e3;
+    DEFAULT_BODY_PREVIEW_BYTES = 8 * 1024;
+    NETWORK_BUFFER_MAX_ENTRIES = 200;
+    NETWORK_BUFFER_MAX_BYTES = 512 * 1024;
+    CONSOLE_BUFFER_MAX_ENTRIES = 200;
+    CONSOLE_BUFFER_MAX_BYTES = 256 * 1024;
+  }
+});
+
 // ../protocol/dist/index.js
 var dist_exports = {};
 __export(dist_exports, {
   CHROME_WEB_STORE_EXTENSION_ID: () => CHROME_WEB_STORE_EXTENSION_ID,
+  CONSOLE_BUFFER_MAX_BYTES: () => CONSOLE_BUFFER_MAX_BYTES,
+  CONSOLE_BUFFER_MAX_ENTRIES: () => CONSOLE_BUFFER_MAX_ENTRIES,
+  DEFAULT_BODY_PREVIEW_BYTES: () => DEFAULT_BODY_PREVIEW_BYTES,
+  DEFAULT_EVAL_TIMEOUT_MS: () => DEFAULT_EVAL_TIMEOUT_MS,
   DEFAULT_EXTENSION_ID: () => DEFAULT_EXTENSION_ID,
   DEFAULT_EXTENSION_IDS: () => DEFAULT_EXTENSION_IDS,
   DEFAULT_HTTP_PORT: () => DEFAULT_HTTP_PORT,
+  DEFAULT_PING_TIMEOUT_MS: () => DEFAULT_PING_TIMEOUT_MS,
+  DEFAULT_READY_TIMEOUT_MS: () => DEFAULT_READY_TIMEOUT_MS,
+  DEFAULT_TOOL_CALL_TIMEOUT_MS: () => DEFAULT_TOOL_CALL_TIMEOUT_MS,
   LEGACY_DEV_EXTENSION_ID: () => LEGACY_DEV_EXTENSION_ID,
   LOCAL_UNPACKED_EXTENSION_ID: () => LOCAL_UNPACKED_EXTENSION_ID,
   NATIVE_HOST_NAME: () => NATIVE_HOST_NAME,
+  NETWORK_BUFFER_MAX_BYTES: () => NETWORK_BUFFER_MAX_BYTES,
+  NETWORK_BUFFER_MAX_ENTRIES: () => NETWORK_BUFFER_MAX_ENTRIES,
   RelayError: () => RelayError,
   TOOL_NAMES: () => TOOL_NAMES,
   asObject: () => asObject,
+  coerceTabId: () => coerceTabId,
   optBool: () => optBool,
+  optNonNegativeNumber: () => optNonNegativeNumber,
   optNumber: () => optNumber,
+  optPositiveNumber: () => optPositiveNumber,
   optString: () => optString,
   parseChromeAxArgs: () => parseChromeAxArgs,
   parseChromeClickArgs: () => parseChromeClickArgs,
@@ -775,6 +917,7 @@ var init_dist = __esm({
   "../protocol/dist/index.js"() {
     "use strict";
     init_args();
+    init_limits();
     NATIVE_HOST_NAME = "dev.chrome_relay.native_host";
     DEFAULT_HTTP_PORT = 12122;
     CHROME_WEB_STORE_EXTENSION_ID = "cpdiapbifblhlcpnmlmfpgfjlacebokb";
@@ -866,7 +1009,7 @@ var init_dist = __esm({
 import { Command } from "commander";
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.13" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.5.15" : "0.0.0-dev";
 
 // src/commands/shared.ts
 init_dist();
@@ -914,6 +1057,11 @@ async function callTool(name, args) {
 }
 
 // src/commands/shared.ts
+function makeWithBase(baseArgs) {
+  return function withBase(opts, extras) {
+    return { ...baseArgs(opts), ...extras ?? {} };
+  };
+}
 function tabOpt(cmd) {
   return cmd.option("-t, --tab <id>", "target tab ID", (v) => Number(v)).option("--workspace <name>", "target the active tab in a named workspace window (see `chrome-relay workspace`)").option("--group <name>", "target the active tab in a named tab-group (see `chrome-relay group`)");
 }
@@ -1100,6 +1248,23 @@ async function runDoctor() {
 
 // src/release-notes.ts
 var RELEASE_NOTES = {
+  "0.5.15": [
+    "Tab-id coercion is now strict against blank strings. `--tabs '1,,3'` (or `[\"\"]`, or `[' ']`) used to silently become `[1, 0, 3]` because Number('') === 0 \u2014 and tab 0 is a real Chrome target. Now throws RelayError(invalid_arguments). Affects chrome_group create/add/remove, chrome_switch_tab, chrome_close_tabs.",
+    "Numeric range validation added across the parsers. `optPositiveNumber` (> 0) and `optNonNegativeNumber` (>= 0) helpers reject out-of-range values at the parser boundary instead of letting nonsense through to CDP / handler logic. Affects: chrome_evaluate timeoutMs, chrome_screenshot maxEdge + padding, chrome_screencast quality/maxWidth/maxHeight/everyNthFrame, chrome_network body head.",
+    "chrome_screenshot maxEdge <= 0 now throws instead of being silently ignored (was the one remaining `if (x > 0)` silent-drop in the parsers).",
+    "No-args parser comment + behavior aligned. parseGetWindowsAndTabsArgs / parseChromeSelfReloadArgs validate the input is at least an object (rejects strings/arrays) but accept any extra fields. Both handlers now call their parser at the top for consistency with every other tool.",
+    "New @chrome-relay/protocol exports: shared numeric limits in `packages/protocol/src/limits.ts`. Constants (DEFAULT_TOOL_CALL_TIMEOUT_MS, DEFAULT_EVAL_TIMEOUT_MS, DEFAULT_BODY_PREVIEW_BYTES, NETWORK_BUFFER_MAX_ENTRIES/BYTES, CONSOLE_BUFFER_MAX_ENTRIES/BYTES, etc.) now flow from one source \u2014 bridge.ts, console-buffer.ts, network-buffer.ts, and the network/evaluate handlers all import. Future doc/help drift is structurally prevented.",
+    "Tests: +9 in args-all.test.ts covering blank-string rejection, range validation across screenshot/evaluate/screencast/network. Total 416 (was 407)."
+  ],
+  "0.5.14": [
+    "Optional parser fields are now strict \u2014 passing a present-but-wrong-type value (e.g. `{newTab: 'yes'}` instead of `true`) throws RelayError(invalid_arguments) instead of silently being dropped. undefined/null still means 'caller omitted the field' and the handler uses its default.",
+    "parseTargetArgs is strict too: `{tabId: '5'}` rejects (numeric tabId required). Navigate is the one exception \u2014 it coerces string tabId for back-compat since it's used as a 'reference window' rather than a strict target.",
+    "CLI tab-group --tabs arg now forwarded as the raw comma-separated string. The protocol parser (parseChromeGroupArgs) does the strict per-element parsing so `--tabs 1,foo,3` errors instead of silently becoming [1,3].",
+    "Deleted the dead duplicate parser module at apps/extension/src/browser/parsers.ts and its test file. The protocol parsers replace them; behavior identical.",
+    "HAR creator.version now reads from chrome.runtime.getManifest() instead of the hardcoded stale '0.2.x'. Drift-proof.",
+    "New CLI helper `withBase(opts, extras)` collapses the `const args = {}; Object.assign(args, baseArgs(opts)); args.foo = bar` pattern into one expression. All four command modules migrated \u2014 `Object.assign(args, baseArgs(opts))` is gone from the codebase.",
+    "Tests: +2 strict-optional cases. Total 407 (was 433 \u2014 28 dropped were duplicates of protocol parsers)."
+  ],
   "0.5.13": [
     "Protocol arg-parser coverage complete (code-quality-hardening Risk 1 \u2014 finished). Every one of the 22 tools now has an executable parser in @chrome-relay/protocol that returns a typed args object with `code:'invalid_arguments'` errors on malformed input.",
     "New parsers in this release: parseChrome{ReadPage,Click,Fill,Keyboard,Type,Evaluate,SwitchTab,CloseTabs,Ax,ClickAx,Screenshot,Viewport,Console,Workspace,Group,Screencast}Args, plus parseGetWindowsAndTabsArgs and parseChromeSelfReloadArgs.",
@@ -1299,7 +1464,7 @@ function registerInstallUpdate(program) {
 
 // src/commands/navigation.ts
 function registerNavigation(ctx) {
-  const { program, baseArgs, run } = ctx;
+  const { program, withBase, run } = ctx;
   program.command("tabs [verb]").description("List open Chrome windows and tabs. (verb 'list' is accepted as alias)").action(async (verb) => {
     if (verb && verb !== "list") {
       process.stderr.write(`unknown tabs verb: ${verb}. Use 'tabs' or 'tabs list'.
@@ -1328,11 +1493,10 @@ Use "chrome-relay switch ${url}" to activate that tab, or "chrome-relay navigate
       );
       process.exit(1);
     }
-    const args = { url };
-    Object.assign(args, baseArgs(opts));
-    if (opts.new) args.newTab = true;
-    if (opts.inactive) args.active = false;
-    await run("chrome_navigate", args);
+    const extras = { url };
+    if (opts.new) extras.newTab = true;
+    if (opts.inactive) extras.active = false;
+    await run("chrome_navigate", withBase(opts, extras));
   });
   program.command("switch <tabId>").description("Activate a tab by ID.").action(async (tabId) => {
     await run("chrome_switch_tab", { tabId: Number(tabId) });
@@ -1348,20 +1512,16 @@ Use "chrome-relay switch ${url}" to activate that tab, or "chrome-relay navigate
 
 // src/commands/input.ts
 function registerInput(ctx) {
-  const { program, baseArgs, run } = ctx;
+  const { program, withBase, run } = ctx;
   tabOpt(
     program.command("click <selector>").description("Click an element by CSS selector.")
   ).action(async (selector, opts) => {
-    const args = { selector };
-    Object.assign(args, baseArgs(opts));
-    await run("chrome_click_element", args);
+    await run("chrome_click_element", withBase(opts, { selector }));
   });
   tabOpt(
     program.command("fill <selector> <value>").description("Fill an input or textarea.")
   ).action(async (selector, value, opts) => {
-    const args = { selector, value };
-    Object.assign(args, baseArgs(opts));
-    await run("chrome_fill_or_select", args);
+    await run("chrome_fill_or_select", withBase(opts, { selector, value }));
   });
   tabOpt(
     program.command("keys <keys>").description("Press a single key or chord via trusted CDP input (e.g. Enter, Cmd+K).").addHelpText(
@@ -1378,9 +1538,7 @@ For typing text into a field, use \`chrome-relay type\` instead.
 `
     )
   ).action(async (keys, opts) => {
-    const args = { keys };
-    Object.assign(args, baseArgs(opts));
-    await run("chrome_keyboard", args);
+    await run("chrome_keyboard", withBase(opts, { keys }));
   });
   tabOpt(
     program.command("type <text>").description("Insert text via trusted CDP input. Works in contenteditable / Draft.js / Lexical.").option("-s, --selector <selector>", "focus this element first").addHelpText(
@@ -1399,10 +1557,9 @@ When to pick which:
 `
     )
   ).action(async (text, opts) => {
-    const args = { text };
-    Object.assign(args, baseArgs(opts));
-    if (opts.selector) args.selector = opts.selector;
-    await run("chrome_type", args);
+    const extras = { text };
+    if (opts.selector) extras.selector = opts.selector;
+    await run("chrome_type", withBase(opts, extras));
   });
   tabOpt(
     program.command("js <code>").description("Evaluate JavaScript in the page MAIN world. Use `return` for the value.").option("--timeout-ms <ms>", "execution timeout in milliseconds (default 15000)", (v) => Number(v)).addHelpText(
@@ -1421,10 +1578,9 @@ Notes:
 `
     )
   ).action(async (code, opts) => {
-    const args = { code };
-    Object.assign(args, baseArgs(opts));
-    if (typeof opts.timeoutMs === "number") args.timeoutMs = opts.timeoutMs;
-    await run("chrome_evaluate", args);
+    const extras = { code };
+    if (typeof opts.timeoutMs === "number") extras.timeoutMs = opts.timeoutMs;
+    await run("chrome_evaluate", withBase(opts, extras));
   });
   tabOpt(
     program.command("hover [selector]").description("Move the pointer over an element or coordinates. Fires :hover styles.").option("--x <px>", "explicit x coordinate (CSS pixels)", (v) => Number(v)).option("--y <px>", "explicit y coordinate (CSS pixels)", (v) => Number(v)).addHelpText(
@@ -1440,21 +1596,20 @@ tooltip appearance, etc.) that a bare click would skip past too quickly.
 `
     )
   ).action(async (selector, opts) => {
-    const args = {};
-    Object.assign(args, baseArgs(opts));
-    if (selector) args.selector = selector;
+    const extras = {};
+    if (selector) extras.selector = selector;
     if (typeof opts.x === "number" && typeof opts.y === "number") {
-      args.x = opts.x;
-      args.y = opts.y;
+      extras.x = opts.x;
+      extras.y = opts.y;
     }
-    await run("chrome_hover", args);
+    await run("chrome_hover", withBase(opts, extras));
   });
 }
 
 // src/commands/capture.ts
 import { writeFileSync } from "fs";
 function registerCapture(ctx) {
-  const { program, baseArgs, run } = ctx;
+  const { program, withBase, run } = ctx;
   tabOpt(
     program.command("screenshot").description("Capture a screenshot of any tab without activating it.").option("--full", "capture beyond the viewport (full page)").option("--bbox <rect>", "capture a region: 'x,y,width,height' (pixels)").option("--selector <css>", "capture the bounding box of a CSS selector").option("--padding <px>", "pixels of padding around --selector region", (v) => Number(v)).option("--max-edge <px>", "downscale so longer edge \u2264 this many pixels (no default; opt-in)", (v) => Number(v)).option("-o, --out <path>", "save image to path (base64 PNG decoded)").addHelpText(
       "after",
@@ -1473,13 +1628,13 @@ full-tab screenshot when an agent only needs to see one component.
 `
     )
   ).action(async (opts) => {
-    const args = {};
-    Object.assign(args, baseArgs(opts));
-    if (opts.full) args.fullPage = true;
-    if (opts.bbox) args.bbox = opts.bbox;
-    if (opts.selector) args.selector = opts.selector;
-    if (typeof opts.padding === "number") args.padding = opts.padding;
-    if (typeof opts.maxEdge === "number") args.maxEdge = opts.maxEdge;
+    const extras = {};
+    if (opts.full) extras.fullPage = true;
+    if (opts.bbox) extras.bbox = opts.bbox;
+    if (opts.selector) extras.selector = opts.selector;
+    if (typeof opts.padding === "number") extras.padding = opts.padding;
+    if (typeof opts.maxEdge === "number") extras.maxEdge = opts.maxEdge;
+    const args = withBase(opts, extras);
     try {
       const result = await callTool("chrome_screenshot", args);
       if (opts.out && result && typeof result === "object") {
@@ -1503,10 +1658,9 @@ full-tab screenshot when an agent only needs to see one component.
   tabOpt(
     program.command("read").description("Extract page structure and interactive elements.").option("-i, --interactive", "return only interactive elements")
   ).action(async (opts) => {
-    const args = {};
-    Object.assign(args, baseArgs(opts));
-    if (opts.interactive) args.interactiveOnly = true;
-    await run("chrome_read_page", args);
+    const extras = {};
+    if (opts.interactive) extras.interactiveOnly = true;
+    await run("chrome_read_page", withBase(opts, extras));
   });
   tabOpt(
     program.command("ax").description("Extract the accessibility tree \u2014 ~30\xD7 smaller than `read` and more semantic.").option("-i, --interactive-only", "filter to actionable roles (button, link, textbox, ...)").option("--root <role>", "start from the first node matching this role (e.g. 'main')").option("--include-subframes", "walk subframes too (default: top frame only)").addHelpText(
@@ -1524,11 +1678,11 @@ Notes:
 `
     )
   ).action(async (opts) => {
-    const args = baseArgs(opts);
-    if (opts.interactiveOnly) args.interactiveOnly = true;
-    if (opts.root) args.rootRole = opts.root;
-    if (opts.includeSubframes) args.includeSubframes = true;
-    await run("chrome_ax", args);
+    const extras = {};
+    if (opts.interactiveOnly) extras.interactiveOnly = true;
+    if (opts.root) extras.rootRole = opts.root;
+    if (opts.includeSubframes) extras.includeSubframes = true;
+    await run("chrome_ax", withBase(opts, extras));
   });
   tabOpt(
     program.command("click-ax").description("Click an element by its backendDOMNodeId from a previous `ax` call.").requiredOption("--node <id>", "backendDOMNodeId from `chrome-relay ax`", (v) => Number(v)).addHelpText(
@@ -1544,9 +1698,7 @@ Notes:
 `
     )
   ).action(async (opts) => {
-    const args = baseArgs(opts);
-    args.node = opts.node;
-    await run("chrome_click_ax", args);
+    await run("chrome_click_ax", withBase(opts, { node: opts.node }));
   });
   const screencast = program.command("screencast").description("Record a tab via CDP (paint-driven). Requires an active tab.").addHelpText(
     "after",
@@ -1571,20 +1723,18 @@ Notes:
   tabOpt(
     screencast.command("start").description("Begin screencast capture on a tab.").option("--format <fmt>", "jpeg | png (default jpeg)").option("--quality <n>", "jpeg quality 0-100 (default 80)", (v) => Number(v)).option("--max-width <px>", "downscale; aspect preserved", (v) => Number(v)).option("--max-height <px>", "downscale; aspect preserved", (v) => Number(v)).option("--every-nth <n>", "throttle: keep 1 in N frames (default 1)", (v) => Number(v))
   ).action(async (opts) => {
-    const args = { action: "start" };
-    Object.assign(args, baseArgs(opts));
-    if (opts.format) args.format = opts.format;
-    if (typeof opts.quality === "number") args.quality = opts.quality;
-    if (typeof opts.maxWidth === "number") args.maxWidth = opts.maxWidth;
-    if (typeof opts.maxHeight === "number") args.maxHeight = opts.maxHeight;
-    if (typeof opts.everyNth === "number") args.everyNthFrame = opts.everyNth;
-    await run("chrome_screencast", args);
+    const extras = { action: "start" };
+    if (opts.format) extras.format = opts.format;
+    if (typeof opts.quality === "number") extras.quality = opts.quality;
+    if (typeof opts.maxWidth === "number") extras.maxWidth = opts.maxWidth;
+    if (typeof opts.maxHeight === "number") extras.maxHeight = opts.maxHeight;
+    if (typeof opts.everyNth === "number") extras.everyNthFrame = opts.everyNth;
+    await run("chrome_screencast", withBase(opts, extras));
   });
   tabOpt(
     screencast.command("stop").description("Stop the screencast and emit frames (or write to disk).").option("-o, --out <dir>", "write frames as JPEGs into this directory (created if missing)").option("--gif", "after writing frames, ffmpeg them into <dir>.gif (requires ffmpeg on PATH)").option("--mp4", "after writing frames, ffmpeg them into <dir>.mp4 (requires ffmpeg on PATH)").option("--fps <n>", "assumed framerate when invoking ffmpeg (default 15)", (v) => Number(v)).option("--no-dedupe", "keep raw frames; default collapses consecutive identical frames via SHA-256").option("--allow-missing-ffmpeg", "with --gif/--mp4: skip ffmpeg step (and emit a warning) if ffmpeg isn't on PATH, instead of failing with external_dependency_missing")
   ).action(async (opts) => {
-    const args = { action: "stop" };
-    Object.assign(args, baseArgs(opts));
+    const args = withBase(opts, { action: "stop" });
     try {
       const result = await callTool("chrome_screencast", args);
       if (!opts.out) {
@@ -1719,7 +1869,7 @@ function netFilterArgs(opts) {
   return a;
 }
 function registerSessions(ctx) {
-  const { program, baseArgs, run } = ctx;
+  const { program, withBase, run } = ctx;
   const viewport = program.command("viewport").description("Emulate device viewport, DPR, mobile flag, touch, and user agent.").addHelpText(
     "after",
     `
@@ -1740,27 +1890,22 @@ Notes:
   tabOpt(
     viewport.command("set").description("Apply explicit viewport dimensions.").requiredOption("--width <px>", "viewport width in CSS pixels", (v) => Number(v)).requiredOption("--height <px>", "viewport height in CSS pixels", (v) => Number(v)).option("--dpr <ratio>", "device pixel ratio (1, 2, 3...)", (v) => Number(v)).option("--mobile", "set the mobile flag (affects meta viewport interpretation)").option("--touch", "enable touch event emulation").option("--user-agent <ua>", "override the User-Agent header")
   ).action(async (opts) => {
-    const args = { action: "set", width: opts.width, height: opts.height };
-    Object.assign(args, baseArgs(opts));
-    if (opts.dpr !== void 0) args.dpr = opts.dpr;
-    if (opts.mobile) args.mobile = true;
-    if (opts.touch) args.hasTouch = true;
-    if (opts.userAgent) args.userAgent = opts.userAgent;
-    await run("chrome_viewport", args);
+    const extras = { action: "set", width: opts.width, height: opts.height };
+    if (opts.dpr !== void 0) extras.dpr = opts.dpr;
+    if (opts.mobile) extras.mobile = true;
+    if (opts.touch) extras.hasTouch = true;
+    if (opts.userAgent) extras.userAgent = opts.userAgent;
+    await run("chrome_viewport", withBase(opts, extras));
   });
   tabOpt(
     viewport.command("preset <name>").description("Apply a named device preset (iphone-14, pixel-7, desktop-1440, etc).")
   ).action(async (name, opts) => {
-    const args = { action: "preset", name };
-    Object.assign(args, baseArgs(opts));
-    await run("chrome_viewport", args);
+    await run("chrome_viewport", withBase(opts, { action: "preset", name }));
   });
   tabOpt(
     viewport.command("clear").description("Drop the viewport override and return the tab to its native size.")
   ).action(async (opts) => {
-    const args = { action: "clear" };
-    Object.assign(args, baseArgs(opts));
-    await run("chrome_viewport", args);
+    await run("chrome_viewport", withBase(opts, { action: "clear" }));
   });
   viewport.command("list").description("List available presets.").action(async () => {
     await run("chrome_viewport", { action: "list" });
@@ -1821,8 +1966,7 @@ Notes:
 `
   );
   group.command("create <name>").description("Group existing tabs into a new tab-group bound to <name>.").requiredOption("--tabs <ids>", "comma-separated tab IDs to group, e.g. 123,456,789").option("--color <color>", "grey | blue | red | yellow | green | pink | purple | cyan | orange").option("--collapsed", "create the group in its collapsed state").action(async (name, opts) => {
-    const args = { action: "create", name };
-    args.tabIds = String(opts.tabs).split(",").map((s) => Number(s.trim())).filter(Number.isFinite);
+    const args = { action: "create", name, tabIds: String(opts.tabs) };
     if (opts.color) args.color = opts.color;
     if (opts.collapsed) args.collapsed = true;
     await run("chrome_group", args);
@@ -1834,12 +1978,10 @@ Notes:
     await run("chrome_group", { action: "close", name });
   });
   group.command("add <name>").description("Add existing tabs to an existing tab-group.").requiredOption("--tabs <ids>", "comma-separated tab IDs to add").action(async (name, opts) => {
-    const tabIds = String(opts.tabs).split(",").map((s) => Number(s.trim())).filter(Number.isFinite);
-    await run("chrome_group", { action: "add", name, tabIds });
+    await run("chrome_group", { action: "add", name, tabIds: String(opts.tabs) });
   });
   group.command("remove").description("Ungroup specific tabs (they remain open, just outside any tab-group).").requiredOption("--tabs <ids>", "comma-separated tab IDs to ungroup").action(async (opts) => {
-    const tabIds = String(opts.tabs).split(",").map((s) => Number(s.trim())).filter(Number.isFinite);
-    await run("chrome_group", { action: "remove", tabIds });
+    await run("chrome_group", { action: "remove", tabIds: String(opts.tabs) });
   });
   const network = tabOpt(netFilterOpts(
     program.command("network").description("Capture HTTP request/response metadata. Ring buffer, last 200 per tab.")
@@ -1869,41 +2011,38 @@ Notes:
   WebSocket frames and SSE streams are out of scope.
 `
   ).action(async (opts) => {
-    const args = { ...baseArgs(opts), ...netFilterArgs(opts) };
-    await run("chrome_network", args);
+    await run("chrome_network", withBase(opts, netFilterArgs(opts)));
   });
   tabOpt(netFilterOpts(
     network.command("read").description("(alias) list captured network entries.")
   )).action(async (opts) => {
-    const args = { ...baseArgs(opts), ...netFilterArgs(opts) };
-    await run("chrome_network", args);
+    await run("chrome_network", withBase(opts, netFilterArgs(opts)));
   });
   tabOpt(
     network.command("body <requestId>").description("Fetch the response body for one request (lazy; may fail if GC'd).").option("--head <bytes>", "truncate to first N bytes", (v) => Number(v)).option("--full", "return the full body \u2014 default truncates to 8 KB")
   ).action(async (requestId, opts) => {
-    const args = { ...baseArgs(opts), action: "body", requestId };
-    if (opts.full) args.full = true;
-    if (typeof opts.head === "number") args.head = opts.head;
-    await run("chrome_network", args);
+    const extras = { action: "body", requestId };
+    if (opts.full) extras.full = true;
+    if (typeof opts.head === "number") extras.head = opts.head;
+    await run("chrome_network", withBase(opts, extras));
   });
   tabOpt(netFilterOpts(
     network.command("har").description("Emit HAR-compatible JSON for the captured entries.").option("--with-bodies", "fetch response bodies before emitting; strict by default \u2014 fails if any body cannot be fetched").option("--best-effort-bodies", "with --with-bodies: keep the HAR even when some bodies are missing/errored (legacy behavior); per-entry _chrome_relay.bodyState/bodyError records what failed")
   )).action(async (opts) => {
-    const args = { ...baseArgs(opts), ...netFilterArgs(opts), action: "har" };
-    if (opts.withBodies) args.withBodies = true;
-    if (opts.bestEffortBodies) args.bestEffortBodies = true;
+    const extras = { ...netFilterArgs(opts), action: "har" };
+    if (opts.withBodies) extras.withBodies = true;
+    if (opts.bestEffortBodies) extras.bestEffortBodies = true;
     if (!opts.withBodies) {
       process.stderr.write(
         "[chrome-relay] HAR exported WITHOUT response bodies. Pass --with-bodies to include them (strict by default; add --best-effort-bodies to allow per-entry misses).\n"
       );
     }
-    await run("chrome_network", args);
+    await run("chrome_network", withBase(opts, extras));
   });
   tabOpt(
     network.command("clear").description("Wipe the network buffer for this tab.")
   ).action(async (opts) => {
-    const args = { ...baseArgs(opts), action: "clear" };
-    await run("chrome_network", args);
+    await run("chrome_network", withBase(opts, { action: "clear" }));
   });
   tabOpt(
     program.command("console").description("Read console.log/warn/error + page exceptions (ring buffer, last 200).").option("--level <levels>", "comma-separated: log,info,warn,error,debug,exception").option("--since <id>", "only return entries with id > since (live-tail-ish)", (v) => Number(v)).option("--limit <n>", "cap response length", (v) => Number(v)).option("--clear", "wipe the buffer (no read)").addHelpText(
@@ -1923,12 +2062,12 @@ Notes:
 `
     )
   ).action(async (opts) => {
-    const args = baseArgs(opts);
-    if (opts.clear) args.action = "clear";
-    if (opts.level) args.levels = opts.level;
-    if (typeof opts.since === "number") args.since = opts.since;
-    if (typeof opts.limit === "number") args.limit = opts.limit;
-    await run("chrome_console", args);
+    const extras = {};
+    if (opts.clear) extras.action = "clear";
+    if (opts.level) extras.levels = opts.level;
+    if (typeof opts.since === "number") extras.since = opts.since;
+    if (typeof opts.limit === "number") extras.limit = opts.limit;
+    await run("chrome_console", withBase(opts, extras));
   });
 }
 
@@ -1955,9 +2094,11 @@ Notes:
   Tools attach via CDP and run on backgrounded tabs without stealing focus.
 `
   );
+  const baseArgs = makeBaseArgs(program);
   const ctx = {
     program,
-    baseArgs: makeBaseArgs(program),
+    baseArgs,
+    withBase: makeWithBase(baseArgs),
     run: runTool
   };
   registerInstallUpdate(program);

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.13" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.5.15" : "0.0.0-dev";
 export {
   CHROME_RELAY_VERSION
 };

package/dist/native-host.js

@@ -6,6 +6,14 @@ import process from "process";
 // src/http/server.ts
 import Fastify from "fastify";
 
+// ../protocol/dist/limits.js
+var DEFAULT_TOOL_CALL_TIMEOUT_MS = 3e4;
+var DEFAULT_PING_TIMEOUT_MS = 2e3;
+var DEFAULT_READY_TIMEOUT_MS = 15e3;
+var DEFAULT_BODY_PREVIEW_BYTES = 8 * 1024;
+var NETWORK_BUFFER_MAX_BYTES = 512 * 1024;
+var CONSOLE_BUFFER_MAX_BYTES = 256 * 1024;
+
 // ../protocol/dist/index.js
 var DEFAULT_HTTP_PORT = 12122;
 var RelayError = class extends Error {
@@ -48,7 +56,7 @@ function toBridgeError(unknownErr, fallbackTool) {
 }
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.13" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.5.15" : "0.0.0-dev";
 
 // src/release-notes.ts
 function compareSemver(a, b) {
@@ -197,7 +205,7 @@ var ExtensionBridge = class {
       pending.reject(new Error(message.payload.error));
     }
   }
-  async waitUntilReady(timeoutMs = 15e3) {
+  async waitUntilReady(timeoutMs = DEFAULT_READY_TIMEOUT_MS) {
     if (this.ready) {
       return;
     }
@@ -213,7 +221,7 @@ var ExtensionBridge = class {
       this.readyWaiters.add(onReady);
     });
   }
-  async ping(timeoutMs = 2e3) {
+  async ping(timeoutMs = DEFAULT_PING_TIMEOUT_MS) {
     const id = randomUUID();
     const message = { type: "bridge.ping", id };
     return new Promise((resolve) => {
@@ -229,7 +237,7 @@ var ExtensionBridge = class {
       this.send(message);
     });
   }
-  async callTool(name, args, timeoutMs = 3e4) {
+  async callTool(name, args, timeoutMs = DEFAULT_TOOL_CALL_TIMEOUT_MS) {
     await this.waitUntilReady();
     const id = randomUUID();
     return new Promise((resolve, reject) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-relay",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",