poltertab 1.7.0-beta.3 → 1.8.0-beta.1

package/README.md

@@ -203,7 +203,8 @@ next use.
 
 One agent can drive many tabs. Each agent (and each secondary server) has its
 own **current tab**; page-facing tools without `tabId`/`session` act there. An
-explicit `tabId` acts on that tab without changing the current one. If the
+explicit `tabId` acts on that tab without changing the current one; a `tabId`
+Chrome does not have returns `tab_not_found` on any tool that takes one. If the
 current tab is closed, untargeted calls fail with a message naming the closed
 tab instead of quietly acting on another one.
 
@@ -211,7 +212,7 @@ tab instead of quietly acting on another one.
 | -------- | ----------- | ------------- |
 | `browser_tab_new` | `url`, `session`, `background` | Open a tab and make it current |
 | `browser_tab_list` | `all` | PolterTab's tabs (or every tab), marking the current one |
-| `browser_tab_switch` | `tabId` or `session`, `focus` | Make another tab current |
+| `browser_tab_switch` | `tabId` or `session`, `focus` | Make another tab current. A tab that does not exist in Chrome returns `tab_not_found`. |
 | `browser_tab_close` | `tabId` or `session`, `force` | Close a tab (default: current). Tabs not opened by PolterTab (including ones adopted via `browser_session_create({tabId})`) return `needs_user_permission` — ask the user, then retry with `force: true`. A tab that does not exist in Chrome returns `tab_not_found`. |
 
 ### Site memory
@@ -243,8 +244,11 @@ themselves into **secondary** mode, proxying their commands through the primary,
 so concurrent agents share one browser with no extra configuration. The
 primary tags each secondary's commands with its id, and the extension keeps a
 separate current tab per agent, so agents get their own tabs. Up to
-5 secondaries are accepted, and if the primary exits one of them promotes itself
-to replace it. The extension popup lists whichever agents are connected.
+50 secondaries are accepted (set `POLTERTAB_MAX_SECONDARIES` to change the
+limit). A secondary refused for capacity is told why and retries with backoff
+(2s doubling to 60s) instead of looping. If the primary exits, exactly one
+secondary promotes itself to replace it and the others reconnect to it. The
+extension popup lists whichever agents are connected.
 
 **Changing the WebSocket Port:**
 Only needed when something that *isn't* PolterTab already holds `7822` —

package/mcp-server/bridge.js

@@ -12,6 +12,7 @@
 
 const WebSocket = require("ws");
 const crypto = require("crypto");
+const net = require("net");
 const {
   resolvePort,
   DEFAULT_WS_PORT,
@@ -23,6 +24,9 @@ const {
   NETWORK_MAX_BODY_BYTES,
   PROMOTION_DELAY_MS,
   PROMOTION_JITTER_MS,
+  PROMOTION_BACKOFF_INITIAL_MS,
+  PROMOTION_BACKOFF_MAX_MS,
+  PROMOTION_BACKOFF_JITTER,
   MAX_SECONDARIES,
   POLTERTAB_HOME,
 } = require("./config.js");
@@ -47,6 +51,15 @@ let nodeId = null;
 let wss = null;
 let httpServer = null;
 
+// Secondary-side retry state. One counter for the whole reconnect/probe/promote
+// cycle, reset only by a Primary's secondary_accepted; `refusal` and
+// `unreachable` say why this node is between connections, so a command sent
+// meanwhile can name the cause instead of a generic "not connected".
+let backoffAttempt = 0;
+let retryTimer = null;
+let refusal = null;
+let unreachable = false;
+
 function broadcastSessionState() {
   if (extensionSocket && extensionSocket.readyState === WebSocket.OPEN) {
     const sessions = [];
@@ -107,6 +120,10 @@ function setupPrimaryServer() {
       console.error(
         `[PolterTab MCP] Port ${WS_PORT} in use, switching to Secondary Mode...`,
       );
+      // A server that never bound is still a handle; every lost promotion race
+      // used to leave one behind.
+      httpServer.close();
+      httpServer = null;
       startSecondaryMode();
     } else {
       console.error(`[PolterTab MCP] HTTP server error: ${e.message}`);
@@ -174,7 +191,10 @@ function setupPrimaryServer() {
 
 function startSecondaryMode() {
   isSecondary = true;
-  nodeId = crypto.randomUUID();
+  // Once per process. The extension keys this agent's current tab by nodeId,
+  // so a fresh one after a lost promotion race orphaned that pointer and the
+  // agent's next untargeted command landed on the user's focused tab.
+  if (!nodeId) nodeId = crypto.randomUUID();
   console.error(
     `[PolterTab MCP] Node ${nodeId} running as Secondary. Connecting to Primary...`,
   );
@@ -182,19 +202,93 @@ function startSecondaryMode() {
   connectToPrimary();
 }
 
+// The retry schedule: INITIAL × 2^attempt, capped, ±JITTER so a crowd of
+// refused Secondaries does not come back in step. `rand` is injectable for
+// the tests.
+function _backoffDelay(attempt, rand = Math.random) {
+  const base = Math.min(
+    PROMOTION_BACKOFF_INITIAL_MS * 2 ** attempt,
+    PROMOTION_BACKOFF_MAX_MS,
+  );
+  const jitter = 1 + PROMOTION_BACKOFF_JITTER * (2 * rand() - 1);
+  return Math.min(Math.round(base * jitter), PROMOTION_BACKOFF_MAX_MS);
+}
+
+function scheduleRetry(fn, delay) {
+  clearTimeout(retryTimer);
+  retryTimer = setTimeout(fn, delay);
+}
+
+// Is anything listening on the port? Binding to find out is what leaked a
+// server per attempt; a refused TCP connect is the only answer that means the
+// Primary is gone.
+function probePrimary() {
+  return new Promise((resolve) => {
+    const sock = net.connect(WS_PORT, "localhost");
+    // A listener with a full accept backlog answers with neither connect nor
+    // error, which would park this node with no retry scheduled. Treat silence
+    // as "something is there": connectToPrimary's handshake timeout then sorts
+    // a hung Primary from a live one and keeps the backoff running.
+    sock.setTimeout(1000, () => {
+      sock.destroy();
+      resolve(true);
+    });
+    sock.once("connect", () => {
+      sock.destroy();
+      resolve(true);
+    });
+    sock.once("error", (err) => resolve(err.code !== "ECONNREFUSED"));
+  });
+}
+
+async function promoteOrRejoin() {
+  if (await probePrimary()) {
+    connectToPrimary();
+    return;
+  }
+  isSecondary = false;
+  setupPrimaryServer();
+}
+
 function connectToPrimary() {
-  extensionSocket = new WebSocket(`ws://localhost:${WS_PORT}`, {
+  const ws = new WebSocket(`ws://localhost:${WS_PORT}`, {
     perMessageDeflate: true,
+    // A Primary that accepts TCP but never answers the upgrade (event loop
+    // blocked, SIGSTOP) would otherwise hold this node forever.
+    handshakeTimeout: 5000,
   });
+  extensionSocket = ws;
+  let opened = false;
+  let accepted = false;
+  let errCode = null;
 
-  extensionSocket.on("open", () => {
+  ws.on("open", () => {
+    opened = true;
     console.error("[PolterTab MCP] Connected to Primary MCP Server.");
-    extensionSocket.send(JSON.stringify({ type: "secondary_mcp", nodeId }));
+    // The version is what tells a Primary this node understands 4xxx closes.
+    ws.send(
+      JSON.stringify({
+        type: "secondary_mcp",
+        nodeId,
+        version: OWN_VERSION,
+        pid: process.pid,
+        parentPid: process.ppid,
+      }),
+    );
   });
 
-  extensionSocket.on("message", (message) => {
+  ws.on("message", (message) => {
     try {
       const msg = JSON.parse(message);
+      // Frames about this connection carry a type, never a command id, and
+      // are handled before the id branch so none can settle a pending command.
+      if (msg.type === "secondary_accepted") {
+        accepted = true;
+        backoffAttempt = 0;
+        refusal = null;
+        unreachable = false;
+        return;
+      }
       if (msg.id && pendingCommands.has(msg.id)) {
         const { resolve, reject, timer } = pendingCommands.get(msg.id);
         clearTimeout(timer);
@@ -214,30 +308,70 @@ function connectToPrimary() {
     }
   });
 
-  extensionSocket.on("close", () => {
-    console.error(
-      "[PolterTab MCP] Connection to Primary lost. Attempting to become Primary...",
-    );
-    extensionSocket = null;
+  ws.on("close", (code, reason) => {
+    if (extensionSocket === ws) extensionSocket = null;
+    // Each branch below sets the one that applies; neither may outlive the
+    // close that caused it.
+    refusal = null;
+    unreachable = false;
+
+    const refused = code >= 4000 && code <= 4999;
+    let info = {};
+    if (refused) {
+      try {
+        info = JSON.parse(reason.toString());
+      } catch (_) {}
+    }
 
     // Reject all pending commands
+    const aborted =
+      info.reason === "capacity_rejected"
+        ? `[capacity_rejected limit=${info.limit}] Primary (pid ${info.pid}) refused this node. Command aborted.`
+        : "Primary node disconnected. Command aborted.";
     for (const [id, { reject, timer }] of pendingCommands) {
       clearTimeout(timer);
-      reject(new Error("Primary node disconnected. Command aborted."));
+      reject(new Error(aborted));
       pendingCommands.delete(id);
     }
 
-    // Try to become primary with exponential backoff & jitter
-    const delay =
-      PROMOTION_DELAY_MS + Math.floor(Math.random() * PROMOTION_JITTER_MS);
+    // Refused by a live Primary: it is not dying, so promoting can only fail.
+    if (refused) {
+      const delay = _backoffDelay(backoffAttempt++);
+      refusal = { ...info, retryAt: Date.now() + delay };
+      console.error(
+        `[PolterTab MCP] Primary refused this node (${code} ${info.reason || "unknown"}). Retrying as Secondary in ${delay}ms.`,
+      );
+      scheduleRetry(connectToPrimary, delay);
+      return;
+    }
+
+    // Something holds the port but never completed the handshake: a hung
+    // Primary, or not a PolterTab one. Promoting would only hit EADDRINUSE.
+    if (!opened && errCode !== "ECONNREFUSED") {
+      const delay = _backoffDelay(backoffAttempt++);
+      unreachable = true;
+      console.error(
+        `[PolterTab MCP] Primary on port ${WS_PORT} is not responding (${errCode || code}). Retrying in ${delay}ms.`,
+      );
+      scheduleRetry(connectToPrimary, delay);
+      return;
+    }
 
-    setTimeout(() => {
-      isSecondary = false;
-      setupPrimaryServer();
-    }, delay);
+    // The Primary went away, or closed this node without saying why (as a
+    // pre-1.8 Primary does at its limit). Probe first; promote only if the port
+    // is free. A node that was never accepted stays on the backoff schedule, so
+    // even a codeless refusal cannot loop at full speed.
+    const delay = accepted
+      ? PROMOTION_DELAY_MS + Math.floor(Math.random() * PROMOTION_JITTER_MS)
+      : _backoffDelay(backoffAttempt++);
+    console.error(
+      `[PolterTab MCP] Connection to Primary lost. Attempting to become Primary in ${delay}ms...`,
+    );
+    scheduleRetry(promoteOrRejoin, delay);
   });
 
-  extensionSocket.on("error", (err) => {
+  ws.on("error", (err) => {
+    errCode = err.code || null;
     console.error(`[PolterTab MCP] Secondary WebSocket error: ${err.message}`);
   });
 }
@@ -270,6 +404,7 @@ async function readNetworkState(params = {}) {
 function setupPrimaryWss(wss) {
   wss.on("connection", (ws) => {
     ws.isAlive = true;
+    ws.supportsNewCloseCodes = false;
     ws.on("pong", () => {
       ws.isAlive = true;
     });
@@ -279,18 +414,55 @@ function setupPrimaryWss(wss) {
         const msg = JSON.parse(message);
 
         if (msg.type === "secondary_mcp") {
-          if (secondaryClients.size >= MAX_SECONDARIES) {
-            console.error(
-              `[PolterTab MCP] Rejecting secondary node ${msg.nodeId} - limit reached.`,
-            );
-            ws.close();
-            return;
+          // Only a Secondary that names its version understands a 4xxx close.
+          // An older one answers any close by trying to promote — the loop this
+          // limit used to trigger — so it is never refused and never counted.
+          ws.supportsNewCloseCodes =
+            typeof msg.version === "string" && msg.version !== "";
+          if (ws.supportsNewCloseCodes) {
+            let v2 = 0;
+            for (const [id, c] of secondaryClients) {
+              if (id !== msg.nodeId && c.supportsNewCloseCodes) v2++;
+            }
+            if (v2 >= MAX_SECONDARIES) {
+              console.error(
+                `[PolterTab MCP] Rejecting secondary node ${msg.nodeId} - limit reached.`,
+              );
+              ws.close(
+                4000,
+                JSON.stringify({
+                  reason: "capacity_rejected",
+                  limit: MAX_SECONDARIES,
+                  retry_in_ms: PROMOTION_BACKOFF_INITIAL_MS,
+                  pid: process.pid,
+                }),
+              );
+              return;
+            }
+          }
+          // Same node, new socket: the old one is dead weight the client may
+          // never end, and the close guard below keeps its close harmless.
+          const displaced = secondaryClients.get(msg.nodeId);
+          if (displaced && displaced !== ws && displaced.readyState === WebSocket.OPEN) {
+            displaced.close(1000);
           }
           secondaryClients.set(msg.nodeId, ws);
           ws.nodeId = msg.nodeId;
+          ws.version = msg.version || null;
+          ws.pid = msg.pid || null;
+          ws.parentPid = msg.parentPid || null;
           console.error(
             `[PolterTab MCP] Secondary node connected: ${msg.nodeId}. Total secondaries: ${secondaryClients.size}`,
           );
+          if (ws.supportsNewCloseCodes) {
+            ws.send(
+              JSON.stringify({
+                type: "secondary_accepted",
+                nodeId: msg.nodeId,
+                primaryVersion: OWN_VERSION,
+              }),
+            );
+          }
           broadcastSessionState();
           return;
         }
@@ -302,6 +474,23 @@ function setupPrimaryWss(wss) {
 
         if (msg.type === "proxy_command") {
           const { id, action } = msg;
+          // No nodeId means no secondary_mcp yet — or a socket refused with
+          // 4000 an instant ago. The extension would bucket its command as the
+          // Primary agent's and move that agent's current tab; a refused
+          // socket would not even get the reply. A well-behaved client's
+          // handshake always precedes its first command on the same socket.
+          if (!ws.nodeId) {
+            if (ws.readyState === WebSocket.OPEN) {
+              ws.send(
+                JSON.stringify({
+                  id,
+                  success: false,
+                  error: "[not_registered] Send secondary_mcp before proxy_command.",
+                }),
+              );
+            }
+            return;
+          }
           // Stamp which agent is asking, from the socket rather than the
           // message, so the extension keeps this Secondary's current tab apart
           // from the Primary's and every other Secondary's.
@@ -359,7 +548,15 @@ function setupPrimaryWss(wss) {
           }, COMMAND_TIMEOUT_MS);
 
           pendingCommands.set(id, { isProxy: true, sourceWs: ws, timer });
-          extensionSocket.send(JSON.stringify({ id, action, ...params }));
+          // Same envelope construction as the direct path, so a tool argument
+          // named id or action cannot override the routing here either. The
+          // Primary's own id is kept last: pendingCommands is keyed on it.
+          extensionSocket.send(
+            JSON.stringify({
+              ..._buildEnvelope(action, msg.params, ws.nodeId),
+              id,
+            }),
+          );
           return;
         }
 
@@ -473,8 +670,12 @@ function setupPrimaryWss(wss) {
         console.error(
           `[PolterTab MCP] Secondary node disconnected: ${ws.nodeId}`,
         );
-        secondaryClients.delete(ws.nodeId);
-        broadcastSessionState();
+        // A node now keeps its id across reconnects, so its new socket may
+        // already be registered by the time the old one's close arrives.
+        if (secondaryClients.get(ws.nodeId) === ws) {
+          secondaryClients.delete(ws.nodeId);
+          broadcastSessionState();
+        }
       } else if (extensionSocket === ws) {
         console.error("[PolterTab MCP] Chrome extension disconnected.");
         extensionSocket = null;
@@ -552,6 +753,17 @@ async function sendCommand(action, params) {
 
   if (isSecondary) {
     if (!isConnected) {
+      if (refusal && refusal.reason === "capacity_rejected") {
+        const s = Math.max(0, Math.ceil((refusal.retryAt - Date.now()) / 1000));
+        throw new Error(
+          `[capacity_rejected limit=${refusal.limit}] Primary (pid ${refusal.pid}) has ${refusal.limit} secondaries. Retry in ${s}s.`,
+        );
+      }
+      if (unreachable) {
+        throw new Error(
+          `[primary_unreachable port=${WS_PORT}] Primary is not responding. Backing off.`,
+        );
+      }
       throw new Error("Secondary node not connected to Primary MCP server.");
     }
 
@@ -610,4 +822,6 @@ module.exports = {
   isSecondary: () => isSecondary,
   extensionVersion: () => extensionVersion,
   _buildEnvelope,
+  _backoffDelay,
+  _probePrimary: probePrimary,
 };

package/mcp-server/config.js

@@ -46,6 +46,18 @@ function resolvePort(argv = process.argv, env = process.env) {
   return DEFAULT_WS_PORT;
 }
 
+// The v2 Secondary ceiling: POLTERTAB_MAX_SECONDARIES if it is a whole number
+// ≥ 0, else 50. 0 is honoured — it refuses every versioned Secondary (old ones
+// are still accepted, see MAX_SECONDARIES below) — so an explicit 0 must not
+// fall through to the default the way `parseInt(x) || 50` let it.
+const DEFAULT_MAX_SECONDARIES = 50;
+function resolveMaxSecondaries(env = process.env) {
+  const raw = env.POLTERTAB_MAX_SECONDARIES;
+  if (raw === undefined || raw.trim() === "") return DEFAULT_MAX_SECONDARIES;
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 0 ? n : DEFAULT_MAX_SECONDARIES;
+}
+
 module.exports = {
   POLTERTAB_HOME,
   MEMORY_DIR: path.join(POLTERTAB_HOME, "navigation_memory"),
@@ -53,6 +65,7 @@ module.exports = {
 
   DEFAULT_WS_PORT,
   resolvePort,
+  resolveMaxSecondaries,
 
   // See the budget above before changing this.
   COMMAND_TIMEOUT_MS: 35000,
@@ -74,9 +87,20 @@ module.exports = {
   PROMOTION_DELAY_MS: 500,
   PROMOTION_JITTER_MS: 2000,
 
-  // More concurrent agents than this sharing one browser stops being useful and
-  // starts being a way to lose track of which tab belongs to whom.
-  MAX_SECONDARIES: 5,
+  // A refused or unreachable Secondary retries on this schedule — 2 s, 4 s,
+  // 8 s … ±25%, capped — and the whole probe/connect/promote cycle runs under
+  // it, reset only when a Primary sends secondary_accepted. Without it a
+  // refusal was answered by an immediate reconnect, refused again, forever.
+  PROMOTION_BACKOFF_INITIAL_MS: 2000,
+  PROMOTION_BACKOFF_MAX_MS: 60000,
+  PROMOTION_BACKOFF_JITTER: 0.25,
+
+  // A safety net against runaway processes, not a usage limit: at 5 it was
+  // routinely hit by idle helpers, and every refusal fed the loop above. Only
+  // Secondaries that declare a version count; an old one is always accepted,
+  // because the only refusal it understands is a close it answers by trying to
+  // promote.
+  MAX_SECONDARIES: resolveMaxSecondaries(),
 
   // Lazy-loaded content arrives after the scroll returns. Long enough for the
   // XHR it triggered to land in the capture buffer, short enough that a

package/mcp-server/tools.js

@@ -11,7 +11,7 @@ const TARGET = {
   tabId: {
     type: "number",
     description:
-      "Act on this tab (an id from browser_tab_list) without making it current. Omit to use this agent's current tab: the last one navigated, opened or switched to.",
+      "Act on this tab (an id from browser_tab_list) without making it current. Omit to use this agent's current tab: the last one navigated, opened or switched to. A tabId Chrome does not have returns tab_not_found.",
   },
   session: {
     type: "string",
@@ -498,7 +498,11 @@ const BROWSER_TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        tabId: { type: "number" },
+        tabId: {
+          type: "number",
+          description:
+            "Tab to switch to; a tabId Chrome does not have returns tab_not_found",
+        },
         session: { type: "string" },
         focus: {
           type: "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poltertab",
-  "version": "1.7.0-beta.3",
+  "version": "1.8.0-beta.1",
   "description": "Let any AI assistant drive and scrape your existing Chrome profile — no headless browser, no complex setup.",
   "bin": {
     "poltertab": "./bin/poltertab.js"

package/skills/browser-navigation-strategy/SKILL.md

@@ -204,7 +204,9 @@ commandeer the tab the user is looking at — and later calls reuse it.
 For several tabs: `browser_tab_new` opens one and makes it current,
 `browser_tab_list` shows them with their ids, `browser_tab_switch` changes the
 current one, and `browser_tab_close` closes one. Pass `tabId` to act on a tab
-once without switching to it, or name tabs with `session` and pass that. If a
+once without switching to it — a `tabId` Chrome does not have returns
+`tab_not_found` on any tool that takes one — or name tabs with `session` and
+pass that. If a
 call says your tab was closed, list and switch — do not assume another tab is
 the same page. Close what you opened.