safari-mcp 2.18.1 → 2.19.1

package/README.md

@@ -356,6 +356,9 @@ Prefer stdio (one process per agent) over a persistent daemon? That works too
 | `SAFARI_MCP_HTTP_PORT` | `9225` | Port for that daemon. |
 | `SAFARI_PROFILE` | unset | Bind sessions to a named Safari profile. Unset = your ordinary windows. |
 | `SAFARI_MCP_RAISE_ON_NAVIGATE` | off | Let navigation bring Safari to the front, and stop the focus guard from putting your previous app back. |
+| `SAFARI_MCP_SCREENSHOT_MAX_WIDTH` | unset | Downscale every `safari_screenshot` to this pixel width (Retina captures are 2× the viewport). Per-call `maxWidth` overrides it. |
+| `SAFARI_MCP_KEEPALIVE_TAB` | off | Keep one daemon-served page open in the profile window so Safari never parks the extension worker between commands. |
+| `SAFARI_MCP_OPEN_WINDOW_CMD` | unset | Command run with the profile name when the profile window is absent (e.g. after a reboot). Must open the window without focusing Safari. |
 
 `SAFARI_MCP_RAISE_ON_NAVIGATE=1` is for agents whose whole point is *showing* you a page — a voice assistant answering "open YouTube", a demo driver. Everything else should leave it off: by default Safari MCP works in the background and hands focus back to whatever app you were using, so an agent can drive a page while you keep typing somewhere else.
 

package/extension/background.js

@@ -452,6 +452,13 @@ browser.runtime.onMessage.addListener((msg, sender, sendResponse) => {
     if (Object.keys(msg).length !== 1) return false;
     if (!Number.isInteger(sender?.tab?.id)) return false;
     if (!_enabled || _bridgeWorkerSuperseded || _bridgeWorkerRetiring) return false;
+    // A page pinging while this worker sits in reconnect backoff is the earliest sign that
+    // the bridge is reachable again (the daemon releases wake polls while it has no verified
+    // worker). Retry now instead of waiting out a backoff of up to a minute.
+    if (!isConnected && !_connecting) {
+      if (_reconnectTimer) { clearTimeout(_reconnectTimer); _reconnectTimer = null; }
+      connect();
+    }
     sendResponse({ ok: true });
     return false;
   }
@@ -725,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);
@@ -757,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) {

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.8",
+  "version": "2.10.10",
   "icons": {
     "48": "images/icon-48.png",
     "96": "images/icon-96.png",

package/index.js

@@ -417,6 +417,10 @@ const _HTTP_WORKER_TTL_MS = 60 * 1000;
 const _HTTP_RELOAD_HANDOFF_TTL_MS = 30 * 1000;
 const _HTTP_WORKER_SUCCESSOR_GRACE_MS = 20 * 1000;
 const _HTTP_WORKER_DISCONNECT_MS = 30 * 1000;
+// Safari parks an idle profile worker every ~30s and its 1-minute alarm wakes it. Declaring
+// it gone in between bought nothing (a profile has no fallback) and cost a full
+// re-verification per minute — 61 flaps in two hours. Wait one alarm cycle plus margin.
+const _HTTP_WORKER_PARK_GRACE_MS = 75 * 1000;
 let _extensionLastPollTime = 0;
 let _extensionLastHeartbeat = 0;
 let _reloadHttpWorkerHandoff = null;
@@ -742,6 +746,16 @@ try {
       return;
     }
 
+    // GET /keepalive — a plain page for the keepalive tab (SAFARI_MCP_KEEPALIVE_TAB=1).
+    // Any http(s) page of the profile hosts the content script, whose wake long-poll and
+    // runtime pings are what keep Safari's MV3 worker from parking; this page exists so
+    // there is always one, even after every owned tab was closed or Safari was relaunched.
+    if (req.method === "GET" && req.url.split("?")[0].split("#")[0] === "/keepalive") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
+      res.end(KEEPALIVE_HTML);
+      return;
+    }
+
     // Every Safari-extension HTTP endpoint is authenticated in addition to its
     // CORS check. Origin alone is not authority: another extension has its own
     // extension-scheme origin, and a local process can forge or omit Origin.
@@ -880,6 +894,7 @@ try {
           _extensionConnected = true;
           console.error("[Safari MCP] Extension connected via HTTP polling");
         }
+        _scheduleKeepaliveTab();
       }
       if (!process.env.SAFARI_PROFILE) _extensionLastPollTime = Date.now();
       res.writeHead(200, { "Content-Type": "application/json" });
@@ -893,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;
@@ -933,6 +956,7 @@ try {
         console.error("[Safari MCP] Extension connected and profile-verified via HTTP polling");
       }
       _extensionLastPollTime = Date.now();
+      _scheduleKeepaliveTab();
       res.writeHead(200, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ status: "verified" }));
       return;
@@ -1164,8 +1188,16 @@ async function _proxyToExtension(type, payload, timeoutMs = 30000) {
 // Detect stale HTTP connection (no poll in 30s = disconnected)
 // Only applies to primary instance (extension host) — not proxy mode
 const _staleHttpTimer = setInterval(() => {
+  // After a daemon restart the profile worker can sit in its reconnect backoff for minutes
+  // (measured 9 min on 4.9.26) while pages of the profile are already long-polling us for
+  // wake-ups. Releasing those polls makes each page ping the worker, and a pinged worker
+  // retries /connect at once (extension ≥2.10.9) instead of waiting out the backoff.
+  if (_isExtensionHost && process.env.SAFARI_PROFILE && !_profileExtensionVerified && _contentWakePolls.size) {
+    _releaseContentWakePolls();
+  }
   if (_isExtensionHost && _extensionConnected && !_extensionWs && _extensionLastPollTime > 0) {
     if (Date.now() - _extensionLastPollTime > _HTTP_WORKER_DISCONNECT_MS) {
+      if (process.env.SAFARI_PROFILE && Date.now() - _extensionLastPollTime <= _HTTP_WORKER_PARK_GRACE_MS) return;
       // A command already delivered to this worker is an at-most-once fence.
       // Its own bounded request timer releases the fence; disconnect cleanup must
       // not make an ordinary successor eligible while the old worker may finish it.
@@ -1195,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) {
@@ -1277,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
@@ -1284,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, {
@@ -1329,6 +1383,44 @@ const _commandTimeouts = {
 // that typically arrive first after idle must outlive that cycle instead of failing at 30s.
 if (process.env.SAFARI_PROFILE) { _commandTimeouts.new_tab = 75000; _commandTimeouts.list_tabs = 75000; }
 
+// ========== KEEPALIVE TAB (opt-in) ==========
+// Safari parks an idle extension worker; the first command afterwards then waits for the
+// 1-minute alarm (measured: new_tab 18s, or a hard failure before the queue fix). A page of
+// the profile that carries the content script relays wake-ups instantly and keeps the worker
+// alive — so keep exactly one such page open, served by this daemon itself.
+const KEEPALIVE_TAB_ENABLED = process.env.SAFARI_MCP_KEEPALIVE_TAB === "1";
+const KEEPALIVE_HTML = '<!doctype html><html lang="he" dir="rtl"><head><meta charset="utf-8"><title>Safari MCP · keepalive</title><meta name="robots" content="noindex"><style>body{font-family:-apple-system,system-ui,sans-serif;margin:3rem auto;max-width:36rem;padding:0 1rem;color:#1a2230;background:#f3f5f8;line-height:1.6}code{background:#ddeff2;padding:.1em .4em;border-radius:3px}</style></head><body><h1>Safari MCP</h1><p>הטאב הזה משאיר את ההרחבה ערה ברקע, כדי שהפקודה הראשונה אחרי הפסקה תרוץ מיד. אפשר להשאיר אותו פתוח; אם סוגרים אותו, הוא ייפתח שוב לבד.</p><p>לביטול: <code>SAFARI_MCP_KEEPALIVE_TAB=0</code> בהגדרות הדמון.</p></body></html>';
+const KEEPALIVE_URL = `http://127.0.0.1:${HTTP_PORT}/keepalive`;
+const KEEPALIVE_SESSION = `${SESSION_ID}:keepalive`;
+let _keepaliveBusy = false;
+let _keepaliveTimer = null;
+async function _ensureKeepaliveTab() {
+  if (!KEEPALIVE_TAB_ENABLED || _keepaliveBusy || !_isExtensionHost || !_extensionConnected) return;
+  if (_preferAppleScript && !_profileExtensionVerified) return;
+  _keepaliveBusy = true;
+  try {
+    const tabs = await sendToExtension("list_tabs", { sessionId: KEEPALIVE_SESSION }, 30000);
+    const list = Array.isArray(tabs) ? tabs : [];
+    // No window at all → new_tab would have to create one, and a WebExtension-created
+    // window is not guaranteed to land in this profile. Wait for a real window instead.
+    if (!list.length) return;
+    if (list.some((t) => String(t?.safeUrl || t?.url || "").startsWith(KEEPALIVE_URL))) return;
+    await sendToExtension("new_tab", { url: KEEPALIVE_URL, sessionId: KEEPALIVE_SESSION }, 45000);
+    console.error(`[Safari MCP] keepalive tab opened (${KEEPALIVE_URL})`);
+  } catch (err) {
+    console.error(`[Safari MCP] keepalive tab check skipped: ${err.message}`);
+  } finally {
+    _keepaliveBusy = false;
+  }
+}
+function _scheduleKeepaliveTab(delayMs = 3000) {
+  if (!KEEPALIVE_TAB_ENABLED) return;
+  if (_keepaliveTimer) clearTimeout(_keepaliveTimer);
+  _keepaliveTimer = setTimeout(() => { _keepaliveTimer = null; void _ensureKeepaliveTab(); }, delayMs);
+  _keepaliveTimer.unref();
+}
+if (KEEPALIVE_TAB_ENABLED) setInterval(() => void _ensureKeepaliveTab(), 10 * 60 * 1000).unref();
+
 // Commands where null result means failure (should fall back to AppleScript)
 const _nullMeansFailure = new Set([
   "click", "double_click", "right_click", "fill",
@@ -1426,11 +1518,26 @@ function _safeUrlForOutput(rawUrl) {
   }
 }
 
+// Receipts this daemon rotated on the caller's behalf (a cross-origin safari_navigate) stay
+// usable under their old name: callers routinely keep the first receipt they saw and ignore
+// the fresh one in the navigate result (nine consecutive "not valid for this origin" failures
+// in one session on 4.9.26). Whoever held the old capability held the tab.
+const _receiptAliases = new Map(); // old token → newer token
+function _aliasReceipt(oldToken, newToken) {
+  if (!oldToken || !newToken || oldToken === newToken) return;
+  _receiptAliases.set(oldToken, newToken);
+  if (_receiptAliases.size > 500) _receiptAliases.delete(_receiptAliases.keys().next().value);
+}
 function _receiptToken(value) {
   const raw = String(value || "");
-  if (/^[A-Za-z0-9_-]{24,}$/.test(raw)) return raw;
-  const legacy = raw.match(/(?:[?#&])mcp-tab=([A-Za-z0-9_-]{24,})(?:[&#]|$)/);
-  return legacy ? legacy[1] : "";
+  let token = "";
+  if (/^[A-Za-z0-9_-]{24,}$/.test(raw)) token = raw;
+  else {
+    const legacy = raw.match(/(?:[?#&])mcp-tab=([A-Za-z0-9_-]{24,})(?:[&#]|$)/);
+    token = legacy ? legacy[1] : "";
+  }
+  for (let hops = 0; token && _receiptAliases.has(token) && hops < 8; hops++) token = _receiptAliases.get(token);
+  return token;
 }
 
 // A caller-supplied receipt is the documented way for a stateless caller to name its
@@ -1936,12 +2043,17 @@ server.tool(
     // origin", ~80×/week). The caller chose the destination, so rotating here is safe —
     // hand back the new receipt instead of letting the caller discover the trap.
     const landed = result && typeof result === "object" ? result.url : "";
-    if (landed && _originOf(landed) !== _originOf(oldUrl) && _receiptToken(receipt || _getActiveReceipt())) {
+    const usedReceipt = _receiptToken(receipt || _getActiveReceipt());
+    if (landed && _originOf(landed) !== _originOf(oldUrl) && usedReceipt) {
       try {
         const fresh = _sanitizeTabResult(await extensionOrFallback(
           "get_tab_receipt", { ..._explicitReceipt({ receipt }) }, () => null
         ));
-        if (fresh?.receipt) { _setActiveReceipt(fresh.receipt); result = { ...result, receipt: fresh.receipt }; }
+        if (fresh?.receipt) {
+          _aliasReceipt(usedReceipt, fresh.receipt);
+          _setActiveReceipt(fresh.receipt);
+          result = { ...result, receipt: fresh.receipt };
+        }
       } catch { /* the navigation itself succeeded — a failed rotation must not fail the tool */ }
     }
     return textResult(result);
@@ -2568,6 +2680,7 @@ server.tool(
     // session now gets its own MAX_TABS and can only evict its own.
     const mySession = `${SESSION_ID}:${currentSessionId()}`;
     const myTabs = [..._openedTabs].filter(([, info]) => (info.sessionId || "") === mySession);
+    let evictedTab = null;
     if (myTabs.length >= MAX_TABS) {
       let oldestIdx = null, oldestTime = Infinity;
       for (const [idx, info] of myTabs) {
@@ -2583,6 +2696,7 @@ server.tool(
           );
         } catch {}
         _untrackTab(oldestIdx);
+        evictedTab = oldestIdx;
       }
     }
 
@@ -2610,7 +2724,12 @@ server.tool(
     }
     if (!requestedUrl) _markBlankTabOpened();
     if (safeResult?.receipt) _setActiveReceipt(safeResult.receipt);
-    return { content: [{ type: "text", text: typeof safeResult === 'string' ? safeResult : JSON.stringify(safeResult) }] };
+    // The eviction used to be stderr-only, so a session learned about its closed tab from
+    // the next "receipt … stale" error. Say it in the response instead.
+    const out = evictedTab !== null && safeResult && typeof safeResult === "object"
+      ? { ...safeResult, evictedTab, note: `Tab cap ${MAX_TABS}/session reached — your oldest tab #${evictedTab} was closed. Close tabs you are done with (safari_close_tab).` }
+      : safeResult;
+    return { content: [{ type: "text", text: typeof out === 'string' ? out : JSON.stringify(out) }] };
   }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safari-mcp",
-  "version": "2.18.1",
+  "version": "2.19.1",
   "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",

package/safari.js

@@ -304,6 +304,7 @@ async function refreshTargetWindow(force = false) {
     _targetWindowCacheTime = 0;
     _profileWindowMissing = true;
     _profileMisses++;
+    _maybeOpenProfileWindow();
     // Log on transition into the missing state, then at most once per 5 minutes —
     // this steady state used to append one line per poll, unbounded (#81).
     if (_profileMisses === 1 || now - _lastMissingLogTime > 300000) {
@@ -313,6 +314,34 @@ async function refreshTargetWindow(force = false) {
   }
 }
 
+// ponytail: opt-in self-heal for the "profile window is closed" steady state (198 refusals in
+// one log, every morning after a reboot). SAFARI_MCP_OPEN_WINDOW_CMD is run with the profile
+// name once absence is established (3 consecutive misses), at most every 2 minutes; the poll
+// below then rediscovers the window. The command must open the window WITHOUT focusing
+// Safari (e.g. ~/bin/safari-bg-window, which presses the File-menu item via Accessibility).
+const OPEN_WINDOW_CMD = process.env.SAFARI_MCP_OPEN_WINDOW_CMD || "";
+let _lastOpenWindowAttempt = 0;
+function _maybeOpenProfileWindow() {
+  if (!OPEN_WINDOW_CMD || !SAFARI_PROFILE || _profileMisses < 3) return;
+  const now = Date.now();
+  if (now - _lastOpenWindowAttempt < 120000) return;
+  _lastOpenWindowAttempt = now;
+  _logProfile(`Profile "${SAFARI_PROFILE}" window absent — running ${OPEN_WINDOW_CMD}`);
+  // The opener presses a File-menu item, which needs Safari running and NOT hidden
+  // (`open -g -j` leaves the menu bar inaccessible). Launch it in the background first.
+  const ensureRunning = execFileAsync("/usr/bin/pgrep", ["-x", "Safari"]).then(() => null, () =>
+    execFileAsync("/usr/bin/open", ["-g", "-a", "Safari"])
+      .then(() => new Promise((r) => setTimeout(r, 5000)))
+      .catch(() => null));
+  ensureRunning
+    .then(() => execFileAsync(OPEN_WINDOW_CMD, [SAFARI_PROFILE], { timeout: 30000 }))
+    .then(() => {
+      _profileMisses = 0; // re-arm the subprocess retry for the fresh window
+      setTimeout(() => { refreshTargetWindow(true).catch(() => {}); }, 3000).unref();
+    })
+    .catch((err) => _logProfile(`Open-window command failed: ${err.message}`));
+}
+
 // Background verification: periodically check that cached window ID still belongs to profile
 if (SAFARI_PROFILE) {
   // Self-scheduling poll with exponential backoff (#81): 3s while the window is