@btraut/browser-bridge 0.4.2 → 0.5.0

package/dist/index.js

@@ -36,6 +36,9 @@ var ErrorCodeSchema = import_zod.z.enum([
   "FAILED_PRECONDITION",
   "UNAUTHORIZED",
   "FORBIDDEN",
+  "PERMISSION_REQUIRED",
+  "PERMISSION_DENIED",
+  "PERMISSION_PROMPT_TIMEOUT",
   "CONFLICT",
   "TIMEOUT",
   "CANCELLED",
@@ -584,89 +587,21 @@ var DiagnosticsDoctorOutputSchema = DiagnosticReportSchema;
 
 // packages/cli/src/cli-output.ts
 var import_zod3 = require("zod");
-var CliError = class extends Error {
-  constructor(info) {
-    super(info.message);
-    this.info = info;
-  }
-};
-var parseInput = (schema, payload) => {
-  const result = schema.safeParse(payload);
-  if (result.success) {
-    return result.data;
-  }
-  const [issue] = result.error.issues;
-  throw new CliError({
-    code: "INVALID_ARGUMENT",
-    message: issue?.message ?? "Invalid input.",
-    retryable: false,
-    details: { issues: result.error.issues }
-  });
-};
-var outputEnvelope = (envelope2, options) => {
-  if (options.json) {
-    console.log(JSON.stringify(envelope2, null, 2));
-    return;
-  }
-  if (envelope2.ok) {
-    if (typeof envelope2.result === "string") {
-      console.log(envelope2.result);
-      return;
-    }
-    console.log(JSON.stringify(envelope2.result, null, 2));
-    return;
-  }
-  console.error(`${envelope2.error.code}: ${envelope2.error.message}`);
-  if (envelope2.error.details) {
-    console.error(JSON.stringify(envelope2.error.details, null, 2));
-  }
-};
-var toErrorInfo = (error) => {
-  if (error instanceof CliError) {
-    return error.info;
-  }
-  if (error instanceof import_zod3.ZodError) {
-    const [issue] = error.issues;
-    return {
-      code: "INVALID_ARGUMENT",
-      message: issue?.message ?? "Invalid input.",
-      retryable: false,
-      details: { issues: error.issues }
-    };
-  }
-  if (error instanceof Error) {
-    return {
-      code: "INTERNAL",
-      message: error.message,
-      retryable: false
-    };
-  }
-  return {
-    code: "INTERNAL",
-    message: "Unknown error.",
-    retryable: false
-  };
-};
-var outputError = (error, options) => {
-  const info = toErrorInfo(error);
-  const envelope2 = { ok: false, error: info };
-  if (options.json) {
-    console.log(JSON.stringify(envelope2, null, 2));
-    return;
-  }
-  console.error(`${info.code}: ${info.message}`);
-  if (info.details) {
-    console.error(JSON.stringify(info.details, null, 2));
-  }
-};
 
 // packages/cli/src/core-client.ts
 var import_node_child_process = require("node:child_process");
 var import_node_path = require("node:path");
 var import_promises = require("node:timers/promises");
+var CoreClientError = class extends Error {
+  constructor(info) {
+    super(info.message);
+    this.name = "CoreClientError";
+    this.info = info;
+  }
+};
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 3210;
-var DEFAULT_TIMEOUT_MS = 4e3;
+var DEFAULT_TIMEOUT_MS = 3e4;
 var HEALTH_RETRY_MS = 250;
 var HEALTH_ATTEMPTS = 20;
 var resolveHost = (host) => {
@@ -711,14 +646,31 @@ var createCoreClient = (options = {}) => {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
-      const response = await fetchImpl(`${baseUrl}${normalizePath(path9)}`, {
-        method,
-        headers: {
-          "content-type": "application/json"
-        },
-        body: body === void 0 ? void 0 : JSON.stringify(body),
-        signal: controller.signal
-      });
+      let response;
+      try {
+        response = await fetchImpl(`${baseUrl}${normalizePath(path9)}`, {
+          method,
+          headers: {
+            "content-type": "application/json"
+          },
+          body: body === void 0 ? void 0 : JSON.stringify(body),
+          signal: controller.signal
+        });
+      } catch (error) {
+        if (controller.signal.aborted || error instanceof Error && error.name === "AbortError") {
+          throw new CoreClientError({
+            code: "TIMEOUT",
+            message: `Core request timed out after ${timeoutMs}ms.`,
+            retryable: true,
+            details: {
+              timeout_ms: timeoutMs,
+              base_url: baseUrl,
+              path: normalizePath(path9)
+            }
+          });
+        }
+        throw error;
+      }
       const raw = await response.text();
       if (!raw) {
         throw new Error(`Empty response from Core (${response.status}).`);
@@ -738,10 +690,18 @@ var createCoreClient = (options = {}) => {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), timeoutMs);
       try {
-        const response = await fetchImpl(`${baseUrl}/health`, {
-          method: "GET",
-          signal: controller.signal
-        });
+        let response;
+        try {
+          response = await fetchImpl(`${baseUrl}/health`, {
+            method: "GET",
+            signal: controller.signal
+          });
+        } catch (error) {
+          if (controller.signal.aborted || error instanceof Error && error.name === "AbortError") {
+            return false;
+          }
+          throw error;
+        }
         if (!response.ok) {
           return false;
         }
@@ -806,6 +766,86 @@ startCoreServer({ host: ${JSON.stringify(
   return { baseUrl, ensureReady, post };
 };
 
+// packages/cli/src/cli-output.ts
+var CliError = class extends Error {
+  constructor(info) {
+    super(info.message);
+    this.info = info;
+  }
+};
+var parseInput = (schema, payload) => {
+  const result = schema.safeParse(payload);
+  if (result.success) {
+    return result.data;
+  }
+  const [issue] = result.error.issues;
+  throw new CliError({
+    code: "INVALID_ARGUMENT",
+    message: issue?.message ?? "Invalid input.",
+    retryable: false,
+    details: { issues: result.error.issues }
+  });
+};
+var outputEnvelope = (envelope2, options) => {
+  if (options.json) {
+    console.log(JSON.stringify(envelope2, null, 2));
+    return;
+  }
+  if (envelope2.ok) {
+    if (typeof envelope2.result === "string") {
+      console.log(envelope2.result);
+      return;
+    }
+    console.log(JSON.stringify(envelope2.result, null, 2));
+    return;
+  }
+  console.error(`${envelope2.error.code}: ${envelope2.error.message}`);
+  if (envelope2.error.details) {
+    console.error(JSON.stringify(envelope2.error.details, null, 2));
+  }
+};
+var toErrorInfo = (error) => {
+  if (error instanceof CliError) {
+    return error.info;
+  }
+  if (error instanceof CoreClientError) {
+    return error.info;
+  }
+  if (error instanceof import_zod3.ZodError) {
+    const [issue] = error.issues;
+    return {
+      code: "INVALID_ARGUMENT",
+      message: issue?.message ?? "Invalid input.",
+      retryable: false,
+      details: { issues: error.issues }
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      code: "INTERNAL",
+      message: error.message,
+      retryable: false
+    };
+  }
+  return {
+    code: "INTERNAL",
+    message: "Unknown error.",
+    retryable: false
+  };
+};
+var outputError = (error, options) => {
+  const info = toErrorInfo(error);
+  const envelope2 = { ok: false, error: info };
+  if (options.json) {
+    console.log(JSON.stringify(envelope2, null, 2));
+    return;
+  }
+  console.error(`${info.code}: ${info.message}`);
+  if (info.details) {
+    console.error(JSON.stringify(info.details, null, 2));
+  }
+};
+
 // packages/cli/src/cli-runtime.ts
 var getRootCommand = (command) => {
   let current = command;
@@ -996,7 +1036,7 @@ var parseJson = (value, label) => {
 };
 var registerDriveCommands = (program2) => {
   const drive = program2.command("drive").description("Drive commands");
-  drive.command("navigate").description("Navigate to a URL").requiredOption("--session-id <id>", "Session identifier").requiredOption("--url <url>", "URL to navigate to").option("--tab-id <id>", "Tab identifier (defaults to active tab)").option("--wait <mode>", "Wait mode (none, domcontentloaded)").action(async (options, command) => {
+  drive.command("navigate").description("Navigate to a URL").requiredOption("--session-id <id>", "Session identifier").requiredOption("--url <url>", "URL to navigate to").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").option("--wait <mode>", "Wait mode (none, domcontentloaded)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(DriveNavigateInputSchema, {
         session_id: options.sessionId,
@@ -1007,7 +1047,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/navigate", payload);
     });
   });
-  drive.command("go-back").description("Go back in browser history").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier").action(async (options, command) => {
+  drive.command("go-back").description("Go back in browser history").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(DriveGoBackInputSchema, {
         session_id: options.sessionId,
@@ -1016,7 +1056,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/go_back", payload);
     });
   });
-  drive.command("back").description("Go back in browser history").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier").action(async (options, command) => {
+  drive.command("back").description("Go back in browser history").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(DriveBackInputSchema, {
         session_id: options.sessionId,
@@ -1025,7 +1065,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/back", payload);
     });
   });
-  drive.command("go-forward").description("Go forward in browser history").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier").action(async (options, command) => {
+  drive.command("go-forward").description("Go forward in browser history").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(DriveGoForwardInputSchema, {
         session_id: options.sessionId,
@@ -1034,7 +1074,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/go_forward", payload);
     });
   });
-  drive.command("forward").description("Go forward in browser history").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier").action(async (options, command) => {
+  drive.command("forward").description("Go forward in browser history").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(DriveForwardInputSchema, {
         session_id: options.sessionId,
@@ -1043,7 +1083,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/forward", payload);
     });
   });
-  drive.command("click").description("Click an element").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier").option("--locator-ref <ref>", "Locator ref (e.g., @e1)").option("--locator-testid <id>", "Locator test id").option("--locator-css <selector>", "Locator CSS selector").option("--locator-text <text>", "Locator text").option("--locator-role <role>", "Locator role name").option("--locator-role-value <value>", "Locator role value").option("--click-count <count>", "Click count").action(async (options, command) => {
+  drive.command("click").description("Click an element").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").option("--locator-ref <ref>", "Locator ref (e.g., @e1)").option("--locator-testid <id>", "Locator test id").option("--locator-css <selector>", "Locator CSS selector").option("--locator-text <text>", "Locator text").option("--locator-role <role>", "Locator role name").option("--locator-role-value <value>", "Locator role value").option("--click-count <count>", "Click count").action(async (options, command) => {
     await runCommand(command, (client) => {
       const locator = requireLocator({
         locatorRef: options.locatorRef,
@@ -1062,7 +1102,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/click", payload);
     });
   });
-  drive.command("hover").description("Hover over an element").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier").option("--locator-ref <ref>", "Locator ref (e.g., @e1)").option("--locator-testid <id>", "Locator test id").option("--locator-css <selector>", "Locator CSS selector").option("--locator-text <text>", "Locator text").option("--locator-role <role>", "Locator role name").option("--locator-role-value <value>", "Locator role value").option("--delay-ms <ms>", "Delay after hover in milliseconds").action(async (options, command) => {
+  drive.command("hover").description("Hover over an element").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").option("--locator-ref <ref>", "Locator ref (e.g., @e1)").option("--locator-testid <id>", "Locator test id").option("--locator-css <selector>", "Locator CSS selector").option("--locator-text <text>", "Locator text").option("--locator-role <role>", "Locator role name").option("--locator-role-value <value>", "Locator role value").option("--delay-ms <ms>", "Delay after hover in milliseconds").action(async (options, command) => {
     await runCommand(command, (client) => {
       const locator = requireLocator({
         locatorRef: options.locatorRef,
@@ -1081,7 +1121,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/hover", payload);
     });
   });
-  drive.command("select").description("Select an option in a dropdown").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier").option("--locator-ref <ref>", "Locator ref (e.g., @e1)").option("--locator-testid <id>", "Locator test id").option("--locator-css <selector>", "Locator CSS selector").option("--locator-text <text>", "Locator text").option("--locator-role <role>", "Locator role name").option("--locator-role-value <value>", "Locator role value").option("--value <value>", "Option value attribute").option("--text <text>", "Option visible text").option("--index <index>", "Option index (0-based)").action(async (options, command) => {
+  drive.command("select").description("Select an option in a dropdown").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").option("--locator-ref <ref>", "Locator ref (e.g., @e1)").option("--locator-testid <id>", "Locator test id").option("--locator-css <selector>", "Locator CSS selector").option("--locator-text <text>", "Locator text").option("--locator-role <role>", "Locator role name").option("--locator-role-value <value>", "Locator role value").option("--value <value>", "Option value attribute").option("--text <text>", "Option visible text").option("--index <index>", "Option index (0-based)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const locator = requireLocator({
         locatorRef: options.locatorRef,
@@ -1102,7 +1142,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/select", payload);
     });
   });
-  drive.command("type").description("Type into a field").requiredOption("--session-id <id>", "Session identifier").requiredOption("--text <text>", "Text to enter").option("--tab-id <id>", "Tab identifier").option("--locator-ref <ref>", "Locator ref (e.g., @e1)").option("--locator-testid <id>", "Locator test id").option("--locator-css <selector>", "Locator CSS selector").option("--locator-text <text>", "Locator text").option("--locator-role <role>", "Locator role name").option("--locator-role-value <value>", "Locator role value").option("--clear", "Clear input before typing").option("--submit", "Submit after typing").action(async (options, command) => {
+  drive.command("type").description("Type into a field").requiredOption("--session-id <id>", "Session identifier").requiredOption("--text <text>", "Text to enter").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").option("--locator-ref <ref>", "Locator ref (e.g., @e1)").option("--locator-testid <id>", "Locator test id").option("--locator-css <selector>", "Locator CSS selector").option("--locator-text <text>", "Locator text").option("--locator-role <role>", "Locator role name").option("--locator-role-value <value>", "Locator role value").option("--clear", "Clear input before typing").option("--submit", "Submit after typing").action(async (options, command) => {
     await runCommand(command, (client) => {
       const locator = buildLocator({
         locatorRef: options.locatorRef,
@@ -1123,7 +1163,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/type", payload);
     });
   });
-  drive.command("fill-form").description("Fill multiple form fields").requiredOption("--session-id <id>", "Session identifier").requiredOption("--fields <json>", "JSON array of fields to fill").option("--tab-id <id>", "Tab identifier").action(async (options, command) => {
+  drive.command("fill-form").description("Fill multiple form fields").requiredOption("--session-id <id>", "Session identifier").requiredOption("--fields <json>", "JSON array of fields to fill").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const fields = parseJson(options.fields, "fields");
       const payload = parseInput(DriveFillFormInputSchema, {
@@ -1134,7 +1174,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/fill_form", payload);
     });
   });
-  drive.command("drag").description("Drag an element to a target").requiredOption("--session-id <id>", "Session identifier").option("--from-locator-ref <ref>", "Source locator ref (e.g., @e1)").option("--from-locator-testid <id>", "Source locator test id").option("--from-locator-css <selector>", "Source locator CSS selector").option("--from-locator-text <text>", "Source locator text").option("--from-locator-role <role>", "Source locator role name").option("--from-locator-role-value <value>", "Source locator role value").option("--to-locator-ref <ref>", "Target locator ref (e.g., @e1)").option("--to-locator-testid <id>", "Target locator test id").option("--to-locator-css <selector>", "Target locator CSS selector").option("--to-locator-text <text>", "Target locator text").option("--to-locator-role <role>", "Target locator role name").option("--to-locator-role-value <value>", "Target locator role value").option("--steps <steps>", "Number of drag steps").option("--tab-id <id>", "Tab identifier").action(async (options, command) => {
+  drive.command("drag").description("Drag an element to a target").requiredOption("--session-id <id>", "Session identifier").option("--from-locator-ref <ref>", "Source locator ref (e.g., @e1)").option("--from-locator-testid <id>", "Source locator test id").option("--from-locator-css <selector>", "Source locator CSS selector").option("--from-locator-text <text>", "Source locator text").option("--from-locator-role <role>", "Source locator role name").option("--from-locator-role-value <value>", "Source locator role value").option("--to-locator-ref <ref>", "Target locator ref (e.g., @e1)").option("--to-locator-testid <id>", "Target locator test id").option("--to-locator-css <selector>", "Target locator CSS selector").option("--to-locator-text <text>", "Target locator text").option("--to-locator-role <role>", "Target locator role name").option("--to-locator-role-value <value>", "Target locator role value").option("--steps <steps>", "Number of drag steps").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const from = requireLocator({
         locatorRef: options.fromLocatorRef,
@@ -1162,7 +1202,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/drag", payload);
     });
   });
-  drive.command("handle-dialog").description("Handle a JavaScript dialog").requiredOption("--session-id <id>", "Session identifier").requiredOption("--action <action>", "Dialog action (accept, dismiss)").option("--prompt-text <text>", "Prompt text for prompt() dialogs").option("--tab-id <id>", "Tab identifier").action(async (options, command) => {
+  drive.command("handle-dialog").description("Handle a JavaScript dialog").requiredOption("--session-id <id>", "Session identifier").requiredOption("--action <action>", "Dialog action (accept, dismiss)").option("--prompt-text <text>", "Prompt text for prompt() dialogs").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(DriveHandleDialogInputSchema, {
         session_id: options.sessionId,
@@ -1173,7 +1213,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/handle_dialog", payload);
     });
   });
-  drive.command("key-press").description("Press a keyboard key").requiredOption("--session-id <id>", "Session identifier").requiredOption("--key <key>", "Key to press (e.g. Enter, ArrowDown)").option("--ctrl", "Hold control modifier").option("--alt", "Hold alt modifier").option("--shift", "Hold shift modifier").option("--meta", "Hold meta modifier").option("--tab-id <id>", "Tab identifier").action(async (options, command) => {
+  drive.command("key-press").description("Press a keyboard key").requiredOption("--session-id <id>", "Session identifier").requiredOption("--key <key>", "Key to press (e.g. Enter, ArrowDown)").option("--ctrl", "Hold control modifier").option("--alt", "Hold alt modifier").option("--shift", "Hold shift modifier").option("--meta", "Hold meta modifier").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(DriveKeyPressInputSchema, {
         session_id: options.sessionId,
@@ -1194,7 +1234,7 @@ var registerDriveCommands = (program2) => {
     "Modifier key (ctrl, alt, shift, meta)",
     (value, previous) => [...previous ?? [], value],
     []
-  ).option("--repeat <count>", "Number of times to press").option("--tab-id <id>", "Tab identifier").action(async (options, command) => {
+  ).option("--repeat <count>", "Number of times to press").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(DriveKeyInputSchema, {
         session_id: options.sessionId,
@@ -1206,7 +1246,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/key", payload);
     });
   });
-  drive.command("scroll").description("Scroll the page").requiredOption("--session-id <id>", "Session identifier").option("--delta-x <px>", "Scroll delta X").option("--delta-y <px>", "Scroll delta Y").option("--top <px>", "Scroll top position").option("--left <px>", "Scroll left position").option("--behavior <mode>", "Scroll behavior (auto, smooth)").option("--tab-id <id>", "Tab identifier").action(async (options, command) => {
+  drive.command("scroll").description("Scroll the page").requiredOption("--session-id <id>", "Session identifier").option("--delta-x <px>", "Scroll delta X").option("--delta-y <px>", "Scroll delta Y").option("--top <px>", "Scroll top position").option("--left <px>", "Scroll left position").option("--behavior <mode>", "Scroll behavior (auto, smooth)").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(DriveScrollInputSchema, {
         session_id: options.sessionId,
@@ -1220,7 +1260,7 @@ var registerDriveCommands = (program2) => {
       return client.post("/drive/scroll", payload);
     });
   });
-  drive.command("wait-for").description("Wait for a condition").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier").requiredOption(
+  drive.command("wait-for").description("Wait for a condition").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").requiredOption(
     "--kind <kind>",
     "Condition kind (locator_visible, text_present, url_matches)"
   ).requiredOption("--value <value>", "Condition value").option("--timeout-ms <ms>", "Timeout in milliseconds").action(async (options, command) => {
@@ -1381,7 +1421,7 @@ var registerInspectCommands = (program2) => {
 // packages/mcp-adapter/src/core-client.ts
 var DEFAULT_HOST2 = "127.0.0.1";
 var DEFAULT_PORT2 = 3210;
-var DEFAULT_TIMEOUT_MS2 = 4e3;
+var DEFAULT_TIMEOUT_MS2 = 3e4;
 var resolveHost2 = (host) => {
   const candidate = host?.trim() || process.env.BROWSER_BRIDGE_CORE_HOST || process.env.BROWSER_VISION_CORE_HOST;
   if (candidate && candidate.length > 0) {
@@ -1664,7 +1704,7 @@ var TOOL_DEFINITIONS = [
     name: "drive.scroll",
     config: {
       title: "Drive Scroll",
-      description: "Scroll the active tab.",
+      description: "Scroll the default tab (agent window/tab unless tab_id is provided).",
       inputSchema: DriveScrollInputSchema,
       outputSchema: envelope(DriveScrollOutputSchema),
       corePath: "/drive/scroll"