viyv-browser-mcp 0.5.4 → 0.5.6

package/dist/index.js

@@ -27,7 +27,15 @@ var TIMEOUTS = {
   /** CDP idle detach delay */
   CDP_IDLE_DETACH: 5e3,
   /** Tab lock TTL (deadlock prevention) */
-  TAB_LOCK_TTL: 6e4
+  TAB_LOCK_TTL: 6e4,
+  /** Default scenario max_duration_ms (30 min) */
+  SCENARIO_MAX_DURATION: 18e5,
+  /** Buffer added to scenario max_duration for MCP timeout */
+  MCP_SCENARIO_BUFFER: 6e4,
+  /** MCP timeout for sm_job_run with wait_for_completion (4 hours) */
+  MCP_JOB_WAIT: 4 * 60 * 60 * 1e3,
+  /** Dialog pause timeout (2 min) — auto-fail if no resume */
+  DIALOG_PAUSE_TIMEOUT: 12e4
 };
 var LIMITS = {
   /** Native Messaging max message size (Chrome limit) */
@@ -93,12 +101,13 @@ function decompressPayload(data, isCompressed) {
 }
 
 // src/native-host/transport.ts
-var MAX_MESSAGE_SIZE = 1024 * 1024;
+var MAX_OUTBOUND_SIZE = 1024 * 1024;
+var MAX_INBOUND_SIZE = 100 * 1024 * 1024;
 function encodeMessage(message) {
   const json = JSON.stringify(message);
   const body = Buffer.from(json, "utf-8");
-  if (body.length > MAX_MESSAGE_SIZE) {
-    throw new Error(`Message too large: ${body.length} bytes (max ${MAX_MESSAGE_SIZE})`);
+  if (body.length > MAX_OUTBOUND_SIZE) {
+    throw new Error(`Message too large: ${body.length} bytes (max ${MAX_OUTBOUND_SIZE})`);
   }
   const header = Buffer.alloc(4);
   header.writeUInt32LE(body.length, 0);
@@ -114,8 +123,8 @@ function createMessageReader(stream, onMessage, onError, onClose) {
         if (buffer.length < 4) break;
         expectedLength = buffer.readUInt32LE(0);
         buffer = buffer.subarray(4);
-        if (expectedLength > MAX_MESSAGE_SIZE) {
-          onError?.(new Error(`Message too large: ${expectedLength} bytes`));
+        if (expectedLength > MAX_INBOUND_SIZE) {
+          onError?.(new Error(`Message too large: ${expectedLength} bytes (max ${MAX_INBOUND_SIZE})`));
           expectedLength = null;
           buffer = Buffer.alloc(0);
           break;
@@ -297,16 +306,27 @@ function startBridge(options) {
     const chrome = chromeConnections.get(chromeId);
     if (chrome) {
       chrome.send(message);
+      return;
+    }
+    const fallback = chromeConnections.values().next().value;
+    if (fallback) {
+      process.stderr.write(
+        `${LOG_PREFIX2} WARNING: '${chromeId}' not found, using ${fallback.chromeId}
+`
+      );
+      fallback.send(message);
     } else {
       process.stderr.write(
-        `${LOG_PREFIX2} WARNING: chromeId '${chromeId}' not found, falling back to primary
+        `${LOG_PREFIX2} WARNING: No Chrome connections available, dropping message
 `
       );
-      chromeConnections.get(primaryChromeId)?.send(message);
     }
   }
   function getChromeForAgent(agentId) {
-    return agentToChrome.get(agentId) ?? primaryChromeId;
+    const mapped = agentToChrome.get(agentId);
+    if (mapped && chromeConnections.has(mapped)) return mapped;
+    const first = chromeConnections.keys().next().value;
+    return first ?? primaryChromeId;
   }
   function connIdForAgent(agentId) {
     return agentToConn.get(agentId);
@@ -373,12 +393,17 @@ function startBridge(options) {
         agentToConn.set(agentId, connId);
         mcpConnections.get(connId)?.agentIds.add(agentId);
         const chromeProfile = message.chromeProfile;
-        const resolvedChrome = chromeProfile && chromeConnections.has(chromeProfile) ? chromeProfile : primaryChromeId;
-        if (chromeProfile && !chromeConnections.has(chromeProfile)) {
-          process.stderr.write(
-            `${LOG_PREFIX2} WARNING: chromeProfile '${chromeProfile}' not found, using primary
+        let resolvedChrome;
+        if (chromeProfile && chromeConnections.has(chromeProfile)) {
+          resolvedChrome = chromeProfile;
+        } else {
+          if (chromeProfile) {
+            process.stderr.write(
+              `${LOG_PREFIX2} WARNING: chromeProfile '${chromeProfile}' not found, using default
 `
-          );
+            );
+          }
+          resolvedChrome = chromeConnections.keys().next().value ?? primaryChromeId;
         }
         agentToChrome.set(agentId, resolvedChrome);
         chromeConnections.get(resolvedChrome)?.agentIds.add(agentId);
@@ -455,6 +480,75 @@ function startBridge(options) {
 `);
     }
   }
+  function removeChromeConnection(chromeId) {
+    const chrome = chromeConnections.get(chromeId);
+    if (!chrome) return;
+    for (const agentId of [...chrome.agentIds]) {
+      const connId = connIdForAgent(agentId);
+      if (connId) {
+        sendToMcp(connId, {
+          id: randomUUID(),
+          type: "session_close",
+          agentId,
+          timestamp: Date.now()
+        });
+        cleanupAgent(agentId, connId);
+      } else {
+        agentToChrome.delete(agentId);
+      }
+    }
+    chromeConnections.delete(chromeId);
+    broadcastChromeProfiles();
+  }
+  let primaryStdinClosed = false;
+  const ORPHAN_TIMEOUT = 6e4;
+  let orphanTimer = null;
+  function gracefulExit(reason) {
+    process.stderr.write(`${LOG_PREFIX2} ${reason}, exiting
+`);
+    if (orphanTimer) {
+      clearTimeout(orphanTimer);
+      orphanTimer = null;
+    }
+    const closingMsg = JSON.stringify({ type: "bridge_closing", timestamp: Date.now() });
+    for (const [, conn] of mcpConnections) {
+      try {
+        conn.socket.write(`${closingMsg}
+`);
+      } catch {
+      }
+    }
+    for (const [, conn] of mcpConnections) {
+      conn.socket.destroy();
+    }
+    mcpConnections.clear();
+    agentToConn.clear();
+    agentToChrome.clear();
+    chromeConnections.clear();
+    requestOrigin.clear();
+    clearInterval(cleanupTimer2);
+    server?.close();
+    process.exit(0);
+  }
+  function maybeExitIfEmpty() {
+    if (!primaryStdinClosed) return;
+    if (chromeConnections.size > 0 && orphanTimer) {
+      clearTimeout(orphanTimer);
+      orphanTimer = null;
+      return;
+    }
+    if (chromeConnections.size === 0 && mcpConnections.size === 0) {
+      gracefulExit("No connections remaining");
+    }
+    if (chromeConnections.size === 0 && !orphanTimer) {
+      orphanTimer = setTimeout(() => {
+        orphanTimer = null;
+        if (chromeConnections.size === 0) {
+          gracefulExit(`No Chrome reconnected within ${ORPHAN_TIMEOUT}ms`);
+        }
+      }, ORPHAN_TIMEOUT);
+    }
+  }
   function setupRelayConnection(socket) {
     const chromeId = `chrome-${nextChromeIndex++}`;
     const chrome = {
@@ -483,6 +577,7 @@ function startBridge(options) {
       chrome.send({ type: "bridge_status", connected: true, timestamp: Date.now() });
     }
     broadcastChromeProfiles();
+    maybeExitIfEmpty();
     const processData = createTcpLineReader((message) => handleChromeMessage(message), onError);
     socket.on("data", processData);
     socket.on("error", (error) => {
@@ -494,22 +589,8 @@ function startBridge(options) {
         `${LOG_PREFIX2} Chrome relay disconnected: ${chromeId} (remaining chromes: ${chromeConnections.size - 1})
 `
       );
-      for (const agentId of [...chrome.agentIds]) {
-        const connId = connIdForAgent(agentId);
-        if (connId) {
-          sendToMcp(connId, {
-            id: randomUUID(),
-            type: "session_close",
-            agentId,
-            timestamp: Date.now()
-          });
-          cleanupAgent(agentId, connId);
-        } else {
-          agentToChrome.delete(agentId);
-        }
-      }
-      chromeConnections.delete(chromeId);
-      broadcastChromeProfiles();
+      removeChromeConnection(chromeId);
+      maybeExitIfEmpty();
     });
   }
   function handleTcpConnection(socket) {
@@ -616,6 +697,7 @@ function startBridge(options) {
       if (mcpConnections.size === 0) {
         notifyChromeConnected(false);
       }
+      maybeExitIfEmpty();
     });
   }
   server = createServer((socket) => handleTcpConnection(socket));
@@ -643,49 +725,24 @@ function startBridge(options) {
       onError
     );
     notifyChromeConnected(false);
-    function shutdown() {
-      const closingMsg = JSON.stringify({ type: "bridge_closing", timestamp: Date.now() });
-      for (const [, conn] of mcpConnections) {
-        try {
-          conn.socket.write(`${closingMsg}
-`);
-        } catch {
-        }
-      }
-      for (const [, conn] of mcpConnections) {
-        conn.socket.destroy();
-      }
-      mcpConnections.clear();
-      agentToConn.clear();
-      agentToChrome.clear();
-      chromeConnections.clear();
-      requestOrigin.clear();
-      clearInterval(cleanupTimer2);
-      server?.close();
-      server = null;
-    }
-    process.on("SIGINT", () => {
-      shutdown();
-      process.exit(0);
-    });
-    process.on("SIGTERM", () => {
-      shutdown();
-      process.exit(0);
-    });
+    process.on("SIGINT", () => gracefulExit("SIGINT received"));
+    process.on("SIGTERM", () => gracefulExit("SIGTERM received"));
     process.stdin.on("end", () => {
-      process.stderr.write(`${LOG_PREFIX2} stdin closed, shutting down
+      process.stderr.write(`${LOG_PREFIX2} Primary Chrome stdin closed
 `);
-      shutdown();
-      process.exit(0);
+      primaryStdinClosed = true;
+      removeChromeConnection(primaryChromeId);
+      maybeExitIfEmpty();
     });
   });
 }
 
 // src/server.ts
 import { randomUUID as randomUUID3 } from "crypto";
-import { existsSync, statSync } from "fs";
+import { existsSync, mkdirSync, statSync, writeFileSync } from "fs";
 import http from "http";
 import { createConnection as createConnection2 } from "net";
+import { dirname } from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -919,10 +976,16 @@ Options:
 - maxChars: Limit output size (default: 50000). Use 100000 for full page content.`;
 
 // src/tools/core/handle-dialog.ts
-var HANDLE_DIALOG_DESCRIPTION = `Handle JavaScript dialogs such as alert, confirm, and prompt.
-Allows accepting or dismissing the dialog, and optionally providing
-input text for prompt dialogs. Must be called while a dialog
-is actively displayed on the page.`;
+var HANDLE_DIALOG_DESCRIPTION = `Handle JavaScript dialogs (alert, confirm, prompt).
+
+Two modes:
+1. Handle current dialog: provide action ('accept'/'dismiss') and optional text
+2. Set next policy: provide nextPolicy to pre-configure how the next
+   auto-handled dialog will be processed. The policy is one-shot \u2014
+   consumed after a single dialog, then reverts to default behavior.
+
+Use mode 2 after seeing _auto_handled_dialogs in a tool result to change
+how the next dialog will be handled when you re-trigger the action.`;
 
 // src/tools/core/hover.ts
 var HOVER_DESCRIPTION = `Move mouse to coordinates or element without clicking.
@@ -1039,38 +1102,6 @@ Returns details of HTTP requests and responses including URL, method,
 status code, headers, and timing information. Supports filtering
 by URL pattern or resource type.`;
 
-// src/tools/sheets/descriptions.ts
-var SHEETS_READ_DESCRIPTION = `Read data from the active Google Sheets spreadsheet.
-
-Uses the gviz/tq endpoint with session cookies \u2014 works with private sheets without OAuth.
-Supports range selection, tq query language for filtering/aggregation, and row limits.
-
-tq query examples:
-- "SELECT A, B WHERE C > 100" \u2014 filter rows
-- "SELECT A, SUM(B) GROUP BY A" \u2014 aggregate
-- "SELECT * ORDER BY C DESC LIMIT 5" \u2014 sort and limit
-
-Set formulas=true to read raw formulas (e.g., =IMAGE(), =HYPERLINK()) instead of computed values.
-Formula mode reads cell-by-cell via the formula bar, limited to 200 cells.
-The tab must be on a Google Sheets page (docs.google.com/spreadsheets/).`;
-var SHEETS_WRITE_DESCRIPTION = `Write data to the active Google Sheets spreadsheet.
-
-For single cell: navigates to the cell via Name Box and types the value.
-For multiple cells: converts 2D array to TSV, copies to clipboard via Offscreen Document, then pastes with Ctrl+V. Sheets auto-expands TSV into multiple cells.
-
-Provide either "value" (single cell string) or "values" (2D array), not both.
-The tab must be on a Google Sheets page.`;
-var SHEETS_INFO_DESCRIPTION = `Get metadata about the active Google Sheets spreadsheet.
-
-Returns spreadsheet ID, document title, sheet list (name, index, row/col counts, active status), active cell reference, and URL.
-Uses DOM inspection and gviz/tq queries for sheet dimensions.
-The tab must be on a Google Sheets page.`;
-var SHEETS_NAVIGATE_DESCRIPTION = `Navigate within the active Google Sheets spreadsheet.
-
-Jump to a specific cell (e.g., "A1", "Z100") via the Name Box, or switch to a different sheet tab by name.
-Both cell and sheet can be specified together.
-The tab must be on a Google Sheets page.`;
-
 // src/tools/semantic/sm-add-action.ts
 var SM_ADD_ACTION_DESCRIPTION = `Define a semantic action (step sequence) for a registered page.
 
@@ -1151,6 +1182,10 @@ var SM_CAPABILITIES_DESCRIPTION = `Query semantic capabilities available for the
 Returns the matched page definition, available actions, and fetches for the active tab.
 Uses page signature matching (URL pattern + DOM markers) to identify the current page state.
 
+Parameters:
+- tabId: target tab
+- include_other_pages (optional): include list of other registered pages on the same domain (default: false). Enable when looking for related pages to navigate to.
+
 Returns:
 - ok: whether a page match was found
 - domain: hostname of the current tab
@@ -1158,7 +1193,7 @@ Returns:
 - match_score: confidence score of the match
 - actions[]: available actions with their parameters
 - fetches[]: available data extractions with their parameters
-- other_pages[]: other registered pages on the same domain (for cross-page navigation)
+- other_pages[]: (only when include_other_pages=true) other registered pages on the same domain
 - hint: guidance message when no page matches
 
 Use this before sm_invoke or sm_fetch to discover what operations are available.
@@ -1245,15 +1280,52 @@ Returns:
 - cascaded: (page deletion) lists of deleted targets, actions, fetches
 - warnings: (target deletion) referencing actions/fetches that may break`;
 
+// src/tools/semantic/sm-execution-resume.ts
+var SM_EXECUTION_RESUME_DESCRIPTION = `Resume a paused scenario/job execution.
+
+When execution is paused (e.g. a browser dialog appeared), use this tool to decide how to proceed.
+Check sm_execution_status or sm_job_report_get (status 'dialog_paused') to detect pauses.
+
+Actions:
+- continue: Dialog already handled, continue to next step
+- retry: Set dialog policy and re-execute the step that triggered the dialog
+- skip_iteration: Skip to next loop iteration (only inside a loop)
+- skip_scenario: Skip entire scenario (marks as cancelled)
+- fail: Fail the current step (scenario continues or stops based on on_error)
+
+Returns execution result or another dialog_paused if a new dialog appears.`;
+
+// src/tools/semantic/sm-execution-status.ts
+var SM_EXECUTION_STATUS_DESCRIPTION = `Check what is currently executing on a tab.
+
+Returns the execution type (job/scenario/none), IDs, progress, and pause state.
+Use this to see if a tab is busy before starting new work, or to get IDs for polling.
+
+Parameters:
+- tabId: tab to check
+
+Returns:
+- type: 'job' | 'scenario' | 'none'
+- label: execution label
+- started_at: execution start timestamp
+- job_id, job_report_id: (job only) IDs for polling with sm_job_report_get
+- scenario_id, report_id: (standalone scenario only) IDs for polling with sm_report_get
+- current_scenario: (job only) currently running scenario {scenario_id, scenario_label, report_id}
+- progress: (job only) {current_entry_index, total_entries, entries_completed}
+- is_paused: whether execution is paused due to dialog
+- pause_info: dialog details if paused`;
+
 // src/tools/semantic/sm-export.ts
 var SM_EXPORT_DESCRIPTION = `Export semantic configuration as JSON.
 
-Exports pages, targets, actions, and fetches. Optionally filter by domain.
+Exports pages, targets, actions, and fetches scoped by the current tab's page.
 Secret parameter default values are stripped from the export.
 Includes a SHA-256 checksum for integrity verification on import.
 
 Parameters:
-- domain (optional): export only pages matching this domain (subdomain-aware). If omitted, exports all.
+- tabId (required): Tab ID to identify the current page
+- scope (optional): "page" (default) exports only the current page's config, "domain" exports all pages for the tab's domain, "all" exports everything
+- file_path (optional): save to this path and return metadata only (keeps data out of context)
 
 Returns:
 - SemanticExport JSON with schema_version, checksum, pages[], targets[], actions[], fetches[]`;
@@ -1378,7 +1450,10 @@ Parameters:
 
 Returns:
 - job_id, job_label
-- snapshots[]: list of {snapshot_id, status, started_at, completed_at, duration_ms, scenario_count}`;
+- snapshots[]: list of {snapshot_id, job_report_id, status, started_at, completed_at, duration_ms, scenario_count, scenarios[]}
+  - job_report_id: use with sm_job_report_get for detailed results
+  - scenarios[]: per-scenario {scenario_id, scenario_label, report_id, status}
+    - report_id: use with sm_report_get or sm_report_export for individual scenario data`;
 var SM_JOB_COMPARE_DESCRIPTION = `Compare two job executions to see data changes between them.
 
 Matches scenarios by scenario_id, data groups by result_key, and rows by loop_params. Computes per-cell diffs with numeric deltas.
@@ -1398,9 +1473,10 @@ Use this to inspect the full captured data for a single execution, including all
 
 Parameters:
 - snapshot_id: the snapshot to retrieve (SNP_xxxx)
+- summary_only: if true, omit data_groups from scenario snapshots to reduce payload size (default: false)
 
 Returns:
-- snapshot: full JobSnapshot with scenario_snapshots and data_groups`;
+- snapshot: full JobSnapshot with scenario_snapshots and data_groups (or empty data_groups if summary_only)`;
 
 // src/tools/semantic/sm-job-list.ts
 var SM_JOB_LIST_DESCRIPTION = `List all defined jobs with entry counts and configuration.
@@ -1429,6 +1505,11 @@ var SM_JOB_REPORT_GET_DESCRIPTION = `Get job execution status and results.
 Shows overall progress and per-scenario report summaries.
 Use sm_report_get with individual report_ids for detailed scenario data.
 
+Poll this after sm_job_run to track progress:
+- status 'running': job is still executing
+- status 'dialog_paused': a browser dialog appeared, use sm_execution_resume to continue
+- status 'completed'/'failed': job finished
+
 Parameters:
 - job_report_id: job report ID (JRP_xxxx)
 
@@ -1439,8 +1520,7 @@ Returns:
 // src/tools/semantic/sm-job-run.ts
 var SM_JOB_RUN_DESCRIPTION = `Execute a job on a browser tab. Scenarios run sequentially.
 
-Returns job_report_id immediately by default. Poll with sm_job_report_get to check progress.
-Set wait_for_completion=true to block until all scenarios finish.
+Always returns immediately with job_report_id. Poll sm_job_report_get to check progress.
 
 Only one job or scenario can run per tab at a time.
 
@@ -1448,12 +1528,16 @@ Parameters:
 - tabId: target tab for execution
 - job_id: the job to execute
 - params: optional per-scenario param overrides keyed by scenario_id
-- wait_for_completion: if true, wait for all scenarios to complete (default: false)
 
 Returns:
-- job_report_id: ID of the created job report (JRP_xxxx)
+- job_report_id: ID of the created job report (JRP_xxxx) \u2014 use with sm_job_report_get to poll
 - job_id: the executed job
-- status: 'running' (async) or 'completed'/'failed' (when wait_for_completion=true)`;
+- status: 'running' | 'failed' (failed = could not start)
+
+Workflow:
+1. sm_job_run \u2192 get job_report_id
+2. sm_job_report_get(job_report_id) \u2192 poll until status is 'completed'/'failed'
+3. If status is 'dialog_paused', use sm_execution_resume to continue`;
 
 // src/tools/semantic/sm-job-update.ts
 var SM_JOB_UPDATE_DESCRIPTION = `Update an existing job definition.
@@ -1627,12 +1711,17 @@ Parameters:
 - scenario_id: the scenario to execute
 - params: parameter values for template substitution
 - wait_for_completion: if true, wait for scenario to finish (up to max_duration_ms)
+- max_duration_ms (optional): override scenario timeout in milliseconds (default: scenario's own value, typically 1800000ms / 30min)
 
 Returns:
 - report_id: ID of the created report (RPT_xxxx)
 - scenario_id: the executed scenario
 - status: 'running' (async) or 'completed'/'failed' (when wait_for_completion=true)
-- error: error message if startup failed`;
+- error: error message if startup failed
+
+When wait_for_completion=true, may return status 'dialog_paused' if a browser dialog
+appeared during execution. The dialog was auto-handled to unblock the page.
+Use sm_execution_resume to decide how to proceed.`;
 
 // src/tools/semantic/sm-scenario-update.ts
 var SM_SCENARIO_UPDATE_DESCRIPTION = `Update an existing scenario.
@@ -1663,14 +1752,16 @@ Parameters:
 - page_id (optional): filter results to a specific page
 - domain (optional): filter results to pages matching this domain
 - test_resolve (optional): if true, resolve all targets on the current tab
+- summary_only (optional): return only summary counts and page list, omitting targets/actions/fetches/integrity arrays (default: true)
 
 Returns:
 - summary: {total_pages, total_targets, total_actions, total_fetches}
 - pages[]: page definitions with page_type, domains, url_patterns, and counts
-- targets[]: targets with locator info and optional resolve_result
-- actions[]: actions with step count and param names
-- fetches[]: fetches with field count
-- integrity[]: referential integrity warnings`;
+- When summary_only is false, also includes:
+  - targets[]: targets with locator info and optional resolve_result
+  - actions[]: actions with step count and param names
+  - fetches[]: fetches with field count
+  - integrity[]: referential integrity warnings`;
 
 // src/tools/semantic/sm-test-target.ts
 var SM_TEST_TARGET_DESCRIPTION = `Test a specific target's locators against the current page.
@@ -1688,6 +1779,38 @@ Returns:
 - element: resolved element info {tag, text, rect} if found
 - test_status: updated test status saved to storage`;
 
+// src/tools/sheets/descriptions.ts
+var SHEETS_READ_DESCRIPTION = `Read data from the active Google Sheets spreadsheet.
+
+Uses the gviz/tq endpoint with session cookies \u2014 works with private sheets without OAuth.
+Supports range selection, tq query language for filtering/aggregation, and row limits.
+
+tq query examples:
+- "SELECT A, B WHERE C > 100" \u2014 filter rows
+- "SELECT A, SUM(B) GROUP BY A" \u2014 aggregate
+- "SELECT * ORDER BY C DESC LIMIT 5" \u2014 sort and limit
+
+Set formulas=true to read raw formulas (e.g., =IMAGE(), =HYPERLINK()) instead of computed values.
+Formula mode reads cell-by-cell via the formula bar, limited to 200 cells.
+The tab must be on a Google Sheets page (docs.google.com/spreadsheets/).`;
+var SHEETS_WRITE_DESCRIPTION = `Write data to the active Google Sheets spreadsheet.
+
+For single cell: navigates to the cell via Name Box and types the value.
+For multiple cells: converts 2D array to TSV, copies to clipboard via Offscreen Document, then pastes with Ctrl+V. Sheets auto-expands TSV into multiple cells.
+
+Provide either "value" (single cell string) or "values" (2D array), not both.
+The tab must be on a Google Sheets page.`;
+var SHEETS_INFO_DESCRIPTION = `Get metadata about the active Google Sheets spreadsheet.
+
+Returns spreadsheet ID, document title, sheet list (name, index, row/col counts, active status), active cell reference, and URL.
+Uses DOM inspection and gviz/tq queries for sheet dimensions.
+The tab must be on a Google Sheets page.`;
+var SHEETS_NAVIGATE_DESCRIPTION = `Navigate within the active Google Sheets spreadsheet.
+
+Jump to a specific cell (e.g., "A1", "Z100") via the Name Box, or switch to a different sheet tab by name.
+Both cell and sheet can be specified together.
+The tab must be on a Google Sheets page.`;
+
 // src/tools/tabs/select-tab.ts
 var SELECT_TAB_DESCRIPTION = `Switch focus to a specific tab by its identifier.
 Makes the target tab the active tab in the agent's group,
@@ -1930,8 +2053,12 @@ var handleDialogTool = {
   description: HANDLE_DIALOG_DESCRIPTION,
   inputSchema: z.object({
     tabId: z.coerce.number().describe("Tab ID"),
-    action: z.enum(["accept", "dismiss"]).describe("Dialog action"),
-    text: z.string().optional().describe("Text for prompt dialog")
+    action: z.enum(["accept", "dismiss"]).optional().describe("Dialog action (required when handling current dialog)"),
+    text: z.string().optional().describe("Text for prompt dialog"),
+    nextPolicy: z.object({
+      action: z.enum(["accept", "dismiss"]).describe("Action for next dialog"),
+      text: z.string().optional().describe("Text for prompt dialog")
+    }).optional().describe("Set one-shot policy for the next auto-handled dialog. Consumed after one use.")
   })
 };
 var tabsContextTool = {
@@ -2116,7 +2243,8 @@ var smCapabilitiesTool = {
   name: "sm_capabilities",
   description: SM_CAPABILITIES_DESCRIPTION,
   inputSchema: z.object({
-    tabId: z.coerce.number().describe("Tab ID")
+    tabId: z.coerce.number().describe("Tab ID"),
+    include_other_pages: z.boolean().optional().describe("Include list of other registered pages on the same domain (default: false)")
   })
 };
 var smInvokeTool = {
@@ -2209,7 +2337,17 @@ var smAddActionTool = {
     ).optional().describe("Parameter definitions"),
     steps: z.array(
       z.object({
-        type: z.enum(["click", "type", "select", "wait", "scroll", "key", "navigate", "file_upload", "script"]).describe("Step type"),
+        type: z.enum([
+          "click",
+          "type",
+          "select",
+          "wait",
+          "scroll",
+          "key",
+          "navigate",
+          "file_upload",
+          "script"
+        ]).describe("Step type"),
         target_id: z.string().optional().describe("Target to act on"),
         params: z.object({
           text: z.string().optional(),
@@ -2277,7 +2415,8 @@ var smStatusTool = {
     tabId: z.coerce.number().optional().describe("Tab ID (required for test_resolve)"),
     page_id: z.string().optional().describe("Filter by page ID"),
     domain: z.string().optional().describe("Filter results to pages matching this domain"),
-    test_resolve: z.boolean().optional().describe("Test-resolve all targets")
+    test_resolve: z.boolean().optional().describe("Test-resolve all targets"),
+    summary_only: z.boolean().optional().describe("Return only summary counts and page list, omitting detail arrays (default: true)")
   })
 };
 var smTestTargetTool = {
@@ -2301,7 +2440,9 @@ var smExportTool = {
   name: "sm_export",
   description: SM_EXPORT_DESCRIPTION,
   inputSchema: z.object({
-    domain: z.string().optional().describe("Export only pages matching this domain (subdomain-aware). Omit for all.")
+    tabId: z.coerce.number().describe("Tab ID to identify the current page"),
+    scope: z.enum(["page", "domain", "all"]).optional().describe("Export scope (default: page)"),
+    file_path: z.string().optional().describe("Save to this path and return metadata only (keeps data out of context)")
   })
 };
 var smImportTool = {
@@ -2432,7 +2573,8 @@ var smScenarioRunTool = {
     tabId: z.coerce.number().describe("Tab ID for execution"),
     scenario_id: z.string().describe("Scenario to execute"),
     params: z.record(z.unknown()).optional().describe("Parameter values"),
-    wait_for_completion: z.boolean().optional().describe("Wait for completion (default: false, async)")
+    wait_for_completion: z.boolean().optional().describe("Wait for completion (default: false, async)"),
+    max_duration_ms: z.coerce.number().optional().describe("Override scenario timeout in ms (default: scenario value, typically 1800000)")
   })
 };
 var smReportListTool = {
@@ -2462,7 +2604,8 @@ var smReportExportTool = {
   description: SM_REPORT_EXPORT_DESCRIPTION,
   inputSchema: z.object({
     report_id: z.string().describe("Report ID to export"),
-    format: z.enum(["json", "csv"]).optional().describe("Export format (default: json)")
+    format: z.enum(["json", "csv"]).optional().describe("Export format (default: json)"),
+    file_path: z.string().optional().describe("Save to this path and return metadata only (keeps data out of context)")
   })
 };
 var jobEntrySchema = z.object({
@@ -2509,8 +2652,7 @@ var smJobRunTool = {
   inputSchema: z.object({
     tabId: z.coerce.number().describe("Tab ID to execute scenarios on"),
     job_id: z.string().describe("Job ID to execute"),
-    params: z.record(z.record(z.unknown())).optional().describe("Per-scenario param overrides keyed by scenario_id"),
-    wait_for_completion: z.boolean().optional().describe("Wait for all scenarios to complete (default: false)")
+    params: z.record(z.record(z.unknown())).optional().describe("Per-scenario param overrides keyed by scenario_id")
   })
 };
 var smJobCancelTool = {
@@ -2520,6 +2662,17 @@ var smJobCancelTool = {
     tabId: z.coerce.number().describe("Tab ID where the job is running")
   })
 };
+var smExecutionResumeTool = {
+  name: "sm_execution_resume",
+  description: SM_EXECUTION_RESUME_DESCRIPTION,
+  inputSchema: z.object({
+    tabId: z.coerce.number().describe("Tab ID where execution is paused"),
+    action: z.enum(["continue", "retry", "skip_iteration", "skip_scenario", "fail"]).describe("How to proceed after the dialog"),
+    accept: z.boolean().optional().describe("For retry: accept (true) or dismiss (false) the dialog"),
+    prompt_text: z.string().optional().describe("For retry on prompt dialogs: text to enter"),
+    wait_for_completion: z.boolean().optional().default(true).describe("Wait for execution to finish or hit another pause")
+  })
+};
 var smJobReportGetTool = {
   name: "sm_job_report_get",
   description: SM_JOB_REPORT_GET_DESCRIPTION,
@@ -2532,7 +2685,8 @@ var smJobReportExportTool = {
   description: SM_JOB_REPORT_EXPORT_DESCRIPTION,
   inputSchema: z.object({
     job_report_id: z.string().describe("Job report ID to export"),
-    format: z.enum(["json", "csv"]).optional().describe("Export format (default: json)")
+    format: z.enum(["json", "csv"]).optional().describe("Export format (default: json)"),
+    file_path: z.string().optional().describe("Save to this path and return metadata only (keeps data out of context)")
   })
 };
 var smJobHistoryTool = {
@@ -2557,7 +2711,15 @@ var smJobSnapshotGetTool = {
   name: "sm_job_snapshot_get",
   description: SM_JOB_SNAPSHOT_GET_DESCRIPTION,
   inputSchema: z.object({
-    snapshot_id: z.string().describe("Snapshot ID to retrieve (SNP_xxxx)")
+    snapshot_id: z.string().describe("Snapshot ID to retrieve (SNP_xxxx)"),
+    summary_only: z.boolean().optional().describe("If true, omit data_groups from scenario snapshots to reduce payload")
+  })
+};
+var smExecutionStatusTool = {
+  name: "sm_execution_status",
+  description: SM_EXECUTION_STATUS_DESCRIPTION,
+  inputSchema: z.object({
+    tabId: z.coerce.number().describe("Tab ID to check execution status")
   })
 };
 var dataBindingSchema = z.object({
@@ -2724,12 +2886,15 @@ var allTools = [
   smJobListTool,
   smJobRunTool,
   smJobCancelTool,
+  smExecutionResumeTool,
   smJobReportGetTool,
   smJobReportExportTool,
   // Job History (3)
   smJobHistoryTool,
   smJobCompareTool,
   smJobSnapshotGetTool,
+  // Execution Status (1)
+  smExecutionStatusTool,
   // Custom View (5)
   smCustomViewCreateTool,
   smCustomViewUpdateTool,
@@ -2743,6 +2908,25 @@ var allTools = [
   sheetsNavigateTool
 ];
 
+// src/tools/timeout.ts
+var FILE_EXPORT_TOOLS = /* @__PURE__ */ new Set(["sm_report_export", "sm_job_report_export", "sm_export"]);
+function computeToolTimeout(tool, input) {
+  if (tool === "wait_for" && typeof input.timeout === "number") {
+    return input.timeout + 5e3;
+  }
+  if (FILE_EXPORT_TOOLS.has(tool)) {
+    return 3e5;
+  }
+  if (tool === "sm_scenario_run" && input.wait_for_completion === true) {
+    const maxDuration = typeof input.max_duration_ms === "number" ? input.max_duration_ms : TIMEOUTS.SCENARIO_MAX_DURATION;
+    return maxDuration + TIMEOUTS.MCP_SCENARIO_BUFFER;
+  }
+  if (tool === "sm_execution_resume" && input.wait_for_completion !== false) {
+    return TIMEOUTS.MCP_JOB_WAIT;
+  }
+  return TIMEOUTS.MCP_TOOL;
+}
+
 // src/server.ts
 var pendingRequests = /* @__PURE__ */ new Map();
 var extensionSocket = null;
@@ -2766,6 +2950,31 @@ function coerceShape(shape) {
   }
   return result;
 }
+function handleFileExport(filePath, result) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  let content;
+  let metadata;
+  if (typeof result.data === "string") {
+    const { data, ...rest } = result;
+    content = data;
+    metadata = { ...rest, file_path: filePath };
+    if (result.format === "csv") {
+      const lines = content.split("\n").filter((l) => l.trim());
+      const headerLine = lines[0]?.replace(/^\uFEFF/, "") ?? "";
+      const columns = headerLine.split(",").map((h) => h.replace(/^"|"$/g, "").trim());
+      metadata.row_count = lines.length - 1;
+      metadata.column_count = columns.length;
+      metadata.columns = columns;
+    }
+  } else {
+    content = JSON.stringify(result, null, 2);
+    const pages = Array.isArray(result.pages) ? result.pages : [];
+    metadata = { ok: true, file_path: filePath, page_count: pages.length };
+  }
+  writeFileSync(filePath, content, "utf-8");
+  metadata.file_size = Buffer.byteLength(content, "utf-8");
+  return metadata;
+}
 function createConfiguredMcpServer() {
   const server = new McpServer({
     name: MCP_SERVER.NAME,
@@ -3318,6 +3527,29 @@ function handleExtensionMessage(message) {
     });
   }
 }
+function formatAutoHandledDialogs(result) {
+  const dialogs = result._auto_handled_dialogs;
+  if (!dialogs?.length) return null;
+  const lines = dialogs.map((d) => {
+    const action = d.action === "accept" ? "accepted" : "dismissed";
+    return `- [${d.type}] ${action}: "${d.message}"`;
+  });
+  return [
+    "[Auto-handled dialog] A browser dialog appeared during this operation and was automatically handled:",
+    ...lines,
+    "Use handle_dialog with nextPolicy to change how future dialogs are handled."
+  ].join("\n");
+}
+function formatDialogPaused(result) {
+  if (result.status !== "dialog_paused") return null;
+  const dp = result.dialog_pause;
+  if (!dp) return null;
+  return [
+    `[Execution Paused] A ${dp.dialog_type} dialog appeared during "${dp.step_context}":`,
+    `"${dp.dialog_message}" (auto-${dp.auto_action}ed)`,
+    "Use sm_execution_resume to decide: continue, retry, skip_iteration, skip_scenario, or fail."
+  ].join("\n");
+}
 async function callExtensionTool(tool, input) {
   if (tool === "browser_health") {
     return {
@@ -3383,10 +3615,7 @@ async function callExtensionTool(tool, input) {
   const agentId = getDefaultAgentId();
   touchSession(agentId);
   const sock = extensionSocket;
-  let toolTimeout = TIMEOUTS.MCP_TOOL;
-  if (tool === "wait_for" && typeof input.timeout === "number") {
-    toolTimeout = input.timeout + 5e3;
-  }
+  const toolTimeout = computeToolTimeout(tool, input);
   return new Promise((resolve2) => {
     const onError = () => {
       const pending = pendingRequests.get(requestId);
@@ -3428,22 +3657,53 @@ async function callExtensionTool(tool, input) {
         ]
       });
     }, toolTimeout);
+    const { chromeProfile, file_path: filePath, ...cleanInput } = input;
     pendingRequests.set(requestId, {
       resolve: (result) => {
         removeErrorListener();
+        if (FILE_EXPORT_TOOLS.has(tool) && typeof filePath === "string" && ("data" in result || "pages" in result)) {
+          try {
+            const metadata = handleFileExport(filePath, result);
+            resolve2({
+              content: [{ type: "text", text: JSON.stringify(metadata) }]
+            });
+          } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            resolve2({
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: {
+                      code: "FILE_WRITE_ERROR",
+                      message: `Failed to write ${filePath}: ${msg}`
+                    }
+                  })
+                }
+              ]
+            });
+          }
+          return;
+        }
+        const dialogNote = formatAutoHandledDialogs(result);
+        const pauseNote = formatDialogPaused(result);
         if (tool === "screenshot" && typeof result.data === "string") {
           const { data, ...metadata } = result;
           const mimeType = metadata.format === "png" ? "image/png" : "image/jpeg";
-          resolve2({
-            content: [
-              { type: "image", data, mimeType },
-              { type: "text", text: JSON.stringify(metadata) }
-            ]
-          });
+          const content = [
+            { type: "image", data, mimeType },
+            { type: "text", text: JSON.stringify(metadata) }
+          ];
+          if (dialogNote) content.push({ type: "text", text: dialogNote });
+          if (pauseNote) content.push({ type: "text", text: pauseNote });
+          resolve2({ content });
         } else {
-          resolve2({
-            content: [{ type: "text", text: JSON.stringify(result) }]
-          });
+          const content = [
+            { type: "text", text: JSON.stringify(result) }
+          ];
+          if (dialogNote) content.push({ type: "text", text: dialogNote });
+          if (pauseNote) content.push({ type: "text", text: pauseNote });
+          resolve2({ content });
         }
       },
       reject: (error) => {
@@ -3461,7 +3721,6 @@ async function callExtensionTool(tool, input) {
       },
       timer
     });
-    const { chromeProfile, ...cleanInput } = input;
     const request = {
       id: requestId,
       type: "tool_call",
@@ -3540,9 +3799,9 @@ async function handleSwitchBrowser() {
 
 // src/setup.ts
 import { execSync } from "child_process";
-import { chmodSync, existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { chmodSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
 import { homedir, platform } from "os";
-import { dirname, resolve } from "path";
+import { dirname as dirname2, resolve } from "path";
 function runSetup(options = {}) {
   const os = platform();
   const binaryPath = getBinaryPath();
@@ -3569,11 +3828,11 @@ function runSetup(options = {}) {
     allowed_origins: allowedOrigins
   };
   const manifestPath = getManifestPath(os);
-  const manifestDir = dirname(manifestPath);
+  const manifestDir = dirname2(manifestPath);
   console.log(`Wrapper: ${wrapperPath}`);
   console.log(`Manifest path: ${manifestPath}`);
-  mkdirSync(manifestDir, { recursive: true });
-  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  mkdirSync2(manifestDir, { recursive: true });
+  writeFileSync2(manifestPath, JSON.stringify(manifest, null, 2));
   chmodSync(manifestPath, 420);
   console.log("\nNative Messaging Host registered successfully!");
   console.log("\nNext steps:");
@@ -3595,18 +3854,18 @@ function getBinaryPath() {
   return resolve(currentScript);
 }
 function createNativeHostWrapper(os, binaryPath) {
-  const manifestDir = dirname(getManifestPath(os));
-  mkdirSync(manifestDir, { recursive: true });
+  const manifestDir = dirname2(getManifestPath(os));
+  mkdirSync2(manifestDir, { recursive: true });
   const nodePath = getNodePath();
   if (os === "win32") {
     const wrapperPath2 = resolve(manifestDir, `${NATIVE_HOST_NAME}.bat`);
-    writeFileSync(wrapperPath2, `@echo off\r
+    writeFileSync2(wrapperPath2, `@echo off\r
 "${nodePath}" "${binaryPath}" --native-host\r
 `);
     return wrapperPath2;
   }
   const wrapperPath = resolve(manifestDir, `${NATIVE_HOST_NAME}.sh`);
-  writeFileSync(wrapperPath, `#!/bin/bash
+  writeFileSync2(wrapperPath, `#!/bin/bash
 exec "${nodePath}" "${binaryPath}" --native-host
 `);
   chmodSync(wrapperPath, 493);
@@ -3664,7 +3923,7 @@ function setupClaudeDesktopConfig() {
   if (!config.mcpServers || typeof config.mcpServers !== "object") {
     config.mcpServers = {};
   }
-  const nodeBinDir = dirname(getNodePath());
+  const nodeBinDir = dirname2(getNodePath());
   const defaultPath = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
   const envPath = nodeBinDir ? `${nodeBinDir}:${defaultPath}` : defaultPath;
   config.mcpServers["viyv-browser"] = {
@@ -3672,9 +3931,9 @@ function setupClaudeDesktopConfig() {
     args: ["-y", "viyv-browser-mcp@latest"],
     env: { PATH: envPath }
   };
-  const configDir = dirname(configPath);
-  mkdirSync(configDir, { recursive: true });
-  writeFileSync(configPath, JSON.stringify(config, null, 2));
+  const configDir = dirname2(configPath);
+  mkdirSync2(configDir, { recursive: true });
+  writeFileSync2(configPath, JSON.stringify(config, null, 2));
   console.log(`npx path: ${npxPath}`);
   console.log("\nClaude Desktop config updated successfully!");
   console.log("Please restart Claude Desktop for changes to take effect.");