safari-mcp 2.19.0 → 2.20.0

package/extension/background.js

@@ -732,7 +732,16 @@ async function pollForCommands(pollGeneration) {
               _bridgeFetch(`${bridgeUrl}/heartbeat`, { method: "POST" }).catch(() => {});
             }, 5000);
             await previousExecution.catch(() => {});
-            await executeAndReply(msg, bridgeUrl);
+            // 7.9.26: a command whose handleCommand never settles (a tab that never answers,
+            // a runtime call that hangs) used to park this loop for good: the beat kept the
+            // host believing we were alive, /poll went silent for hours, connectToServer
+            // waited on the same claim, and only a Safari restart brought the profile back.
+            // Bound it: past the host's hard ceiling we answer with an error, release the
+            // claim and keep polling; the abandoned promise may settle later into the void.
+            await Promise.race([
+              executeAndReply(msg, bridgeUrl),
+              _wedgedCommandGuard(msg, bridgeUrl),
+            ]);
           }
         } finally {
           if (beat) clearInterval(beat);
@@ -764,6 +773,33 @@ async function pollForCommands(pollGeneration) {
   }
 }
 
+// Ceiling for one command. The host's own hard deadline is max(4×timeout, 180s) and its
+// longest tool timeout is 75s, so nothing legitimate is still awaited after five minutes.
+const _WEDGED_COMMAND_MS = 330000;
+function _wedgedCommandGuard(msg, bridgeUrl) {
+  return new Promise((resolve) => {
+    setTimeout(async () => {
+      console.log("Safari MCP: command wedged, releasing the poll loop", msg && msg.type);
+      try {
+        await _bridgeFetch(`${bridgeUrl}/result`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            type: "response",
+            id: msg.id,
+            result: null,
+            error: `command ${msg.type} did not settle within ${_WEDGED_COMMAND_MS}ms`,
+          }),
+          signal: AbortSignal.timeout(5000),
+        });
+      } catch (e) {
+        /* the host most likely expired it already */
+      }
+      resolve();
+    }, _WEDGED_COMMAND_MS);
+  });
+}
+
 // ========== SHARED: Execute command and send response ==========
 
 async function executeAndReply(msg, bridgeUrl = HTTP_URL) {
@@ -1080,6 +1116,10 @@ async function handleCommand(type, payload) {
     // --- JavaScript Execution — multi-strategy to handle CSP restrictions ---
     // Strategy 1: indirect eval (fast, works when CSP allows unsafe-eval)
     // Strategy 2: script element injection (bypasses CSP in MAIN world context)
+    case "list_frames": {
+      return await listFrames(tabId);
+    }
+
     case "evaluate": {
       // Strategy 0: pages that stall injection outright. Every strategy below reaches
       // the page through scripting.executeScript, which on business.facebook.com never
@@ -1088,6 +1128,12 @@ async function handleCommand(type, payload) {
       // it FIRST once a tab is known to block injection, and fall back to it below
       // when a fresh tab turns out to block it too.
       const evalTabId = tabId || (await getActiveTab()).id;
+      // A frame selector short-circuits every strategy below: those all target the
+      // main frame, which is exactly what makes an embedded app unreachable.
+      if (payload.frame !== undefined && payload.frame !== null && payload.frame !== "") {
+        const _fid = await resolveFrameId(evalTabId, payload.frame);
+        return await evaluateInFrame(evalTabId, _fid, payload.script);
+      }
       const viaBridge = async () => {
         const r = await sendContentCommand(
           evalTabId, "mcp-content-eval", { source: payload.script }, 10000
@@ -4134,6 +4180,86 @@ function _isFrameMiss(value) {
 // Execute in ALL frames (including cross-origin iframes) and return the first real
 // match.  A top-frame `Element not found` is a semantic miss, not a result: allowing
 // it to win used to hide valid matches in every child frame behind it.
+// --- Frame targeting -------------------------------------------------------
+// Every other command reaches only the tab's main frame, so a cross-origin
+// iframe — a micro-frontend app shell, an embedded checkout, GoHighLevel's
+// workflow builder — was effectively invisible: read_page returned the outer
+// shell's loader text and evaluate ran outside the app entirely. Safari's
+// scripting.executeScript can address one frame by id, so these expose the
+// frame list and let a script run inside a chosen frame.
+async function listFrames(tabId = null) {
+  const id = tabId || (await getActiveTab()).id;
+  const results = await _executeAllFrames(() => ({
+    url: location.href,
+    title: document.title,
+    textLength: ((document.body && document.body.innerText) || "").length,
+  }), [], id);
+  return results.map((r, i) => (
+    r && r.error
+      ? { index: i, frameId: Number.isInteger(r.frameId) ? r.frameId : null, error: String(r.error) }
+      : { index: i, frameId: Number.isInteger(r && r.frameId) ? r.frameId : null, ...((r && r.result) || {}) }
+  ));
+}
+
+// Resolve a caller's frame selector to one concrete frameId. `frame` is either a
+// numeric frameId or a substring matched against each frame's URL. Ambiguity is
+// an error rather than a guess: silently picking one of several matching frames
+// is how an automation ends up acting on the wrong document.
+async function resolveFrameId(tabId, frame) {
+  if (typeof frame === "number" && Number.isInteger(frame)) return frame;
+  const needle = String(frame == null ? "" : frame).toLowerCase();
+  if (!needle) throw new Error("frame must be a frameId number or a URL substring");
+  const frames = await listFrames(tabId);
+  const hits = frames.filter((f) => !f.error && typeof f.url === "string" && f.url.toLowerCase().includes(needle));
+  if (hits.length === 0) {
+    throw new Error("No frame matched " + JSON.stringify(String(frame)) + ". Frames present: " +
+      (frames.map((f) => f.url || ("#" + f.index)).join(" | ") || "(none)"));
+  }
+  if (hits.length > 1) {
+    throw new Error("Frame selector " + JSON.stringify(String(frame)) + " matched " + hits.length +
+      " frames — narrow it: " + hits.map((f) => f.url).join(" | "));
+  }
+  if (!Number.isInteger(hits[0].frameId)) throw new Error("Matched frame has no stable frameId");
+  return hits[0].frameId;
+}
+
+// Run one script inside a single frame. MAIN world first so the script sees the
+// page's own globals; ISOLATED as the fallback for frames whose CSP blocks eval —
+// it still reads and mutates the DOM, which is what clicking and filling need.
+async function evaluateInFrame(tabId, frameId, script) {
+  const id = tabId || (await getActiveTab()).id;
+  const runner = async (src) => {
+    try {
+      const result = await (0, eval)(src);
+      if (result === undefined || result === null) return null;
+      return typeof result === "object" ? JSON.stringify(result) : String(result);
+    } catch (e) {
+      const m = String(e && e.message);
+      if (m.includes("unsafe-eval") || m.includes("trusted-types") || m.includes("Trusted Type")) {
+        return "__CSP_BLOCKED__";
+      }
+      return "Error: " + m;
+    }
+  };
+  const run = async (world) => {
+    const results = await _withInjectionDeadline(browser.scripting.executeScript({
+      target: { tabId: id, frameIds: [frameId] },
+      world,
+      func: runner,
+      args: [script],
+    }));
+    const first = results[0];
+    if (first && first.error) throw new Error(first.error);
+    return first && first.result;
+  };
+  const mainResult = await run("MAIN");
+  if (mainResult !== "__CSP_BLOCKED__") return mainResult;
+  const isolated = await run("ISOLATED");
+  return isolated === "__CSP_BLOCKED__"
+    ? "Error: eval is blocked by CSP in both MAIN and ISOLATED worlds for this frame"
+    : isolated;
+}
+
 async function execInAllFrames(func, args = [], tabId = null) {
   try {
     const results = await _executeAllFrames(func, args, tabId);

package/extension/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": 3,
   "name": "Safari MCP Bridge",
   "description": "Connects AI agents to Safari — fast JS execution, screenshots, clicks with your real cookies/logins",
-  "version": "2.10.9",
+  "version": "2.10.11",
   "icons": {
     "48": "images/icon-48.png",
     "96": "images/icon-96.png",
@@ -65,4 +65,4 @@
       "run_at": "document_start"
     }
   ]
-}
+}

package/index.js

@@ -908,15 +908,23 @@ try {
       const heartbeatingWorkerId = _requireActiveHttpWorker(req, res);
       if (!heartbeatingWorkerId) return;
       _extensionLastHeartbeat = Date.now();
-      _extensionLastPollTime = Date.now();
       // Re-arm in-flight deadlines: the worker told us it is still on the command.
       // hardDeadline inside armTimer keeps this from extending indefinitely.
+      let liveInFlight = false;
       for (const pending of _pendingRequests.values()) {
         if (pending.dispatchedWorkerId !== heartbeatingWorkerId) continue;
         if (!pending.armTimer || Date.now() >= pending.hardDeadline) continue;
+        liveInFlight = true;
         clearTimeout(pending.timer);
         pending.timer = pending.armTimer();
       }
+      // A beat proves liveness only while the worker is on a command we still wait for.
+      // 7.9.26: a worker wedged inside one command (its handleCommand never settled) kept
+      // beating every 5s for hours after that command's hard deadline had expired; each
+      // beat refreshed the stale clock, so "HTTP poll timeout" never fired, no successor
+      // could take the lease, and every tool call died with "Extension timeout". Once
+      // nothing dispatched to this worker is in flight, its beats no longer count as polls.
+      if (liveInFlight) _extensionLastPollTime = Date.now();
       res.writeHead(204);
       res.end();
       return;
@@ -1219,6 +1227,18 @@ _staleHttpTimer.unref();  // stale-detection must not keep the Node process aliv
 
 // ========== SHARED EXTENSION LOGIC ==========
 
+// A worker that keeps beating but never finishes a command holds the profile lease
+// hostage. Releasing it is the same bookkeeping the stale timer does on poll timeout.
+function _dropWedgedHttpWorker(reason) {
+  if (!_extensionConnected && !_activeHttpWorkerId) return;
+  _extensionConnected = false;
+  _activeHttpWorkerId = "";
+  _connectingHttpWorkers.clear();
+  _reloadHttpWorkerHandoff = null;
+  _drainOnDisconnect(`wedged worker: ${reason}`);
+  console.error(`[Safari MCP] Extension worker dropped as wedged (${reason})`);
+}
+
 // Drain pending requests and command queue on disconnect — allows fast fallback to AppleScript
 function _drainOnDisconnect(reason) {
   if (process.env.SAFARI_PROFILE) {
@@ -1301,6 +1321,7 @@ function sendToExtension(type, payload = {}, timeoutMs = 30000) {
     // hardDeadline is the ceiling, so a worker that beats forever cannot hang us.
     const hardDeadline = Date.now() + Math.max(timeoutMs * 4, 180000);
     const expire = () => {
+      const pending = _pendingRequests.get(id);
       _pendingRequests.delete(id);
       if (reloadHandoff) _cancelReloadHttpWorkerHandoff(reloadHandoff);
       // Also drop it from the HTTP poll queue — otherwise the extension could poll this command
@@ -1308,6 +1329,15 @@ function sendToExtension(type, payload = {}, timeoutMs = 30000) {
       const qi = _commandQueue.findIndex(c => c.id === id);
       if (qi >= 0) _commandQueue.splice(qi, 1);
       reject(new Error(`Extension timeout after ${timeoutMs}ms`));
+      // The worker took this command and never answered, even past the hard ceiling: it is
+      // wedged (see /heartbeat). Drop its lease now instead of waiting for the stale timer,
+      // so a fresh worker — or Safari re-spawning this one — can connect at once.
+      if (
+        pending && pending.dispatchedWorkerId && pending.dispatchedWorkerId === _activeHttpWorkerId &&
+        Date.now() >= pending.hardDeadline
+      ) {
+        _dropWedgedHttpWorker(`${type} exceeded its hard deadline`);
+      }
     };
     const armTimer = () => setTimeout(expire, Math.min(timeoutMs, Math.max(0, hardDeadline - Date.now())));
     _pendingRequests.set(id, {
@@ -1415,6 +1445,7 @@ const _noOwnershipCheck = new Set([
   "reload_extension",
   // Read-only — don't modify the page
   "read_page", "get_source", "snapshot", "accessibility_snapshot",
+  "list_frames",
   "get_element", "query_all", "screenshot", "screenshot_element",
   "get_console", "list_console_messages", "start_console",
   "get_network", "list_network_requests", "start_network_capture",
@@ -2876,6 +2907,23 @@ server.tool(
   }
 );
 
+// ========== FRAMES ==========
+
+server.tool(
+  "safari_list_frames",
+  "List every document in the tab — the main page plus each iframe — with its frameId, URL and text length. Use when a page's content lives in a cross-origin iframe (an embedded app, a micro-frontend shell, a payment field): safari_read_page and safari_evaluate see only the main document there and come back empty or with a loader. Pass the frameId or a URL substring as safari_evaluate's `frame` to run inside it.",
+  {
+    receipt: z.string().optional().describe("Opaque extension-issued tab receipt"),
+  },
+  async (args) => {
+    const result = await extensionOrFallback(
+      "list_frames", { ..._explicitReceipt(args) },
+      () => { throw new Error("safari_list_frames needs the extension — AppleScript cannot enumerate frames. Check safari_doctor."); }
+    );
+    return { content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2) }] };
+  }
+);
+
 // ========== EVALUATE JAVASCRIPT ==========
 
 server.tool(
@@ -2883,12 +2931,19 @@ server.tool(
   "Execute JavaScript in the current page (a returned Promise is awaited — fetch/timers work in background tabs; requestAnimationFrame never fires there). Automatically falls back to AppleScript when CSP blocks execution (e.g. Google Search Console, LinkedIn). For reading data, prefer safari_read_page or safari_snapshot. For interactions, prefer safari_click/fill with refs.",
   {
     script: z.string().describe("JavaScript code to execute"),
+    frame: z.union([z.string(), z.number()]).optional().describe("Run inside a sub-frame instead of the main document: a frameId from safari_list_frames, or a substring of the frame's URL (must match exactly one). Needed for cross-origin iframes — micro-frontend app shells, embedded checkouts — where the main document only holds a loader."),
     receipt: z.string().optional().describe("Opaque extension-issued tab receipt — pass the one safari_new_tab returned to keep targeting that tab after an MCP reconnect"),
   },
   async (args) => {
     const result = await extensionOrFallback(
-      "evaluate", { script: args.script, ..._explicitReceipt(args) },
-      () => safari.evaluate(args)
+      "evaluate",
+      { script: args.script, ...(args.frame === undefined ? {} : { frame: args.frame }), ..._explicitReceipt(args) },
+      () => {
+        if (args.frame !== undefined) {
+          throw new Error("safari_evaluate: frame targeting needs the extension — AppleScript reaches only the main document. Check the extension is connected (safari_doctor).");
+        }
+        return safari.evaluate(args);
+      }
     );
     return { content: [{ type: "text", text: (typeof result === 'string' ? result : JSON.stringify(result)) || "(no return value)" }] };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safari-mcp",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "mcpName": "io.github.achiya-automation/safari-mcp",
   "description": "Safari browser automation for AI agents — native macOS, zero Chrome overhead. 97 tools via AppleScript + JavaScript.",
   "type": "module",