poltertab 1.6.0 → 1.7.0-beta.1

package/README.md

@@ -84,11 +84,12 @@ Running from a clone instead of npm? Point the client at the file directly:
 
 ## Supported MCP Tools
 
-The server exposes 23 tools to the LLM (all prefixed with `browser_`). Every
+The server exposes 27 tools to the LLM (all prefixed with `browser_`). Every
 page-facing tool also takes optional `tabId` and `session` to target a specific
-tab — omit both and PolterTab uses the last tab it navigated. The first
-`browser_navigate` of a session opens its own tab rather than commandeering the
-one you are looking at.
+tab — omit both and PolterTab uses the agent's current tab: the last one it
+navigated, opened or switched to. The first `browser_navigate` (and the first
+`browser_navigate` of each new session) opens its own tab rather than
+commandeering the one you are looking at.
 
 ### Page actions
 
@@ -192,11 +193,26 @@ next use.
 
 | Action | Parameters | Description |
 | -------- | ----------- | ------------- |
-| `browser_session_create` | `name` (required), `url` | Create a session, or bind one to the active tab |
+| `browser_session_create` | `name` (required), `url`, `tabId` | Create a session, adopt an open tab, or bind one to the active tab |
 | `browser_session_switch` | `name` (required) | Make a session active, recovering its tab if closed |
 | `browser_session_list` | — | All sessions, each `alive`, `recoverable`, or `expired` |
 | `browser_session_close` | `name` (required) | Close a session and its tab |
-| `browser_session_context` | — | Active session's tab, URL and title |
+| `browser_session_context` | — | The current tab's id, URL, title and session, or `closedTabId` |
+
+### Tabs
+
+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
+current tab is closed, untargeted calls fail with a message naming the closed
+tab instead of quietly acting on another one.
+
+| Action | Parameters | Description |
+| -------- | ----------- | ------------- |
+| `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_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
 
@@ -224,8 +240,9 @@ exists inside a web component still resolves.
 The first MCP server to bind port `7822` becomes the **primary** and owns the
 connection to the extension. Later servers find the port taken and switch
 themselves into **secondary** mode, proxying their commands through the primary,
-so concurrent agents share one browser with no extra configuration. Each
-secondary auto-injects a per-agent `session` so agents get their own tabs. Up to
+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.
 

package/mcp-server/bridge.js

@@ -301,7 +301,11 @@ function setupPrimaryWss(wss) {
         }
 
         if (msg.type === "proxy_command") {
-          const { id, action, params } = msg;
+          const { id, action } = msg;
+          // 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.
+          const params = { ...(msg.params || {}), _client: ws.nodeId };
           if (params && params.tabId) {
             ws.lastTabId = params.tabId;
             broadcastSessionState();
@@ -528,6 +532,20 @@ function awaitReply(envelope, { timedOut, sendFailed }) {
   });
 }
 
+// Build the envelope that goes to the extension. Strips reserved keys (_client,
+// id, action) from caller-supplied params so a tool argument named "_client"
+// cannot spoof the routing identity, and stamps activeNodeId as _client when
+// the caller is a promoted Secondary that still holds a node UUID.
+function _buildEnvelope(action, params, activeNodeId) {
+  const { _client: _c, id: _i, action: _a, ...safeParams } = params || {};
+  return {
+    id: crypto.randomUUID(),
+    action,
+    ...safeParams,
+    ...(activeNodeId ? { _client: activeNodeId } : {}),
+  };
+}
+
 // Helper to send command to the extension
 async function sendCommand(action, params) {
   const isConnected = await waitForConnection(5000);
@@ -537,10 +555,11 @@ async function sendCommand(action, params) {
       throw new Error("Secondary node not connected to Primary MCP server.");
     }
 
-    // Auto-inject a unique session to prevent collisions over shared tabs
-    if (!params.session) {
-      params.session = "agent_" + nodeId;
-    }
+    // No session is injected any more. It used to be ("agent_<nodeId>"), which
+    // overrode every browser_tab_switch this agent made, and an unknown session
+    // fell through to the Primary's active tab anyway. The Primary now stamps
+    // this node's id as _client and the extension keeps a current tab per
+    // client, so a Secondary's first navigate opens its own tab.
 
     return awaitReply(
       { type: "proxy_command", id: crypto.randomUUID(), action, params },
@@ -559,7 +578,7 @@ async function sendCommand(action, params) {
   }
 
   return awaitReply(
-    { id: crypto.randomUUID(), action, ...params },
+    _buildEnvelope(action, params, nodeId),
     {
       timedOut: `Command '${action}' timed out after ${COMMAND_TIMEOUT_MS / 1000} seconds.`,
       sendFailed: (e) => `Failed to send command over WebSocket: ${e.message}`,
@@ -590,4 +609,5 @@ module.exports = {
   noteActiveTab,
   isSecondary: () => isSecondary,
   extensionVersion: () => extensionVersion,
+  _buildEnvelope,
 };

package/mcp-server/tools.js

@@ -10,12 +10,13 @@
 const TARGET = {
   tabId: {
     type: "number",
-    description: "Target a specific tab. Omit to use the last tab navigated.",
+    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.",
   },
   session: {
     type: "string",
     description:
-      "Named session (tab) to run against. Created on first use by browser_navigate, so a loop can keep one tab instead of opening hundreds.",
+      "Named session (tab) to run against; it becomes the current tab. browser_navigate with a new name opens it its own tab, so a loop can keep one tab instead of opening hundreds. Other tools error on a name that does not exist yet.",
   },
 };
 
@@ -395,12 +396,17 @@ const BROWSER_TOOLS = [
   },
   {
     name: "browser_session_create",
-    description: "Create or track a named browser session (tab)",
+    description:
+      "Create or track a named browser session (tab): opens `url` in a new tab, adopts `tabId`, or with neither binds the tab the user is looking at. It becomes the current tab.",
     inputSchema: {
       type: "object",
       properties: {
         name: { type: "string" },
         url: { type: "string" },
+        tabId: {
+          type: "number",
+          description: "Adopt this already-open tab instead of opening one",
+        },
       },
       required: ["name"],
     },
@@ -438,13 +444,82 @@ const BROWSER_TOOLS = [
   },
   {
     name: "browser_session_context",
-    description: "Get context info for the current active session",
+    description:
+      "Get this agent's current tab: its id, URL, title and session name, or closedTabId if the tab it was on has been closed",
     inputSchema: {
       type: "object",
       properties: {},
       required: [],
     },
   },
+  // One agent, many tabs. Each agent (Primary or Secondary) has its own
+  // current tab; every page-facing tool without tabId/session acts there.
+  {
+    name: "browser_tab_new",
+    description:
+      "Open a new tab and make it this agent's current tab. Later calls without tabId/session act on it. Returns its tabId.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "Page to open; blank tab if omitted" },
+        session: {
+          type: "string",
+          description: "Also name the tab as a session, to come back to it by name",
+        },
+        background: {
+          type: "boolean",
+          description: "Open without stealing focus from the user's tab",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "browser_tab_list",
+    description:
+      "List the tabs this agent can work with: every tab PolterTab opened or bound to a session, marking which one is current. all: true lists every open tab in the browser (ids, URLs and titles only).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        all: { type: "boolean", description: "Include the user's other tabs" },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "browser_tab_switch",
+    description:
+      "Make another tab this agent's current tab, by tabId or session name. Does not bring it to the front unless focus: true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tabId: { type: "number" },
+        session: { type: "string" },
+        focus: {
+          type: "boolean",
+          description: "Also show the tab to the user",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "browser_tab_close",
+    description:
+      "Close a tab by tabId or session name (default: the current tab). Tabs not opened by PolterTab — including ones adopted via browser_session_create({tabId}) — require the user's permission: the tool returns code needs_user_permission with the tab's id, title and url; ask the user, then retry with force: true. A tabId that does not exist in Chrome returns tab_not_found. Closing the current tab leaves no current tab; untargeted calls then error until you switch or navigate.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tabId: { type: "number" },
+        session: { type: "string" },
+        force: {
+          type: "boolean",
+          description: "Close a tab the user opened. Only when the user asked.",
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: "browser_get_site_memory",
     description:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poltertab",
-  "version": "1.6.0",
+  "version": "1.7.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

@@ -197,14 +197,21 @@ skip the discovery entirely next time.
 
 ## Multiple tabs
 
-`browser_session_create` gives a named tab you can return to. Every page-facing
-tool takes `session` (or `tabId`).
-
-Omit both and the first `browser_navigate` opens its own tab — it does not
-commandeer the tab the user is looking at — and later calls reuse it. That is
-fine for single-track work and ambiguous the moment two flows interleave, so
-name your sessions when running more than one. Close what you opened with
-`browser_session_close`.
+You have a **current tab**; every page-facing tool without `tabId`/`session`
+acts on it. The first `browser_navigate` opens its own tab — it does not
+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
+call says your tab was closed, list and switch — do not assume another tab is
+the same page. Close what you opened.
+
+`browser_tab_close` refuses tabs that PolterTab did not open — including tabs
+adopted via `browser_session_create({tabId})` — and returns `needs_user_permission`
+with the tab's id, title and url. Ask the user for permission, then retry with
+`force: true`. Closing a tabId that Chrome does not have returns `tab_not_found`.
 
 ## Pitfalls