An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
docs: describe tab-bound sessions in the architecture and feature guides
Shahriar63ebd1a64f08
diff --git a/docs/architecture.md b/docs/architecture.mdindex 5b7d463..e56f846 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -116,14 +116,14 @@ but it never deletes the stored key. Only pairing again or `disconnect` replaces### Protocol version-Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **10**). A mismatch closes the socket with+Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **11**). A mismatch closes the socket withan explicit reason instead of letting two incompatible frame vocabularies talk past each other.---## 4. One registry, two bundles-There are 34 page capabilities. They are defined once, in `lib/actions/registry.ts`, and that array+There are 35 page capabilities. They are defined once, in `lib/actions/registry.ts`, and that arrayis compiled into **both** the extension and the daemon.Each action is a small module — a name, a description, a zod input schema, and an `execute()`:@@ -201,7 +201,8 @@ Details worth knowing:- **`browsentic-mcp` starts the daemon if needed.** `ensureDaemon()` reads the lockfile, checks thepid is alive and `/health` answers, and otherwise spawns a detached `daemon-main.js`, polling for- up to 8 seconds.+ up to 8 seconds. It never compares versions, so a running daemon keeps serving an old build until+ `browsentic-mcp restart` (or `stop`) — in the repo, `yarn mcp:restart` chains the rebuild with it.- **External calls are visible.** The daemon emits a `tool`/`toolResult` pair tagged`source: 'external'` on the run channel, so anything an MCP client does appears on the user'stimeline. It does **not** pass the approval gate — that gate applies to agent runs only.@@ -250,9 +251,24 @@ it is the documented escape hatch.### Tab scoping-Every action targets the active tab of the current window unless a `tabId` is threaded through — the-one caller that does is a site-mapping run, which pins itself to the tab it started in and fails-with `MAPPING_TAB_CHANGED` if that tab goes away.+A panel conversation is **bound to the tab it started in**. The background keeps a registry of tab+sessions in `browser.storage.session` under `browsentic/tabSessions`: each entry maps a `sessionId`+to its main tab, the subtabs its runs opened, the tab its next action should land on, the live tab+title, and the run currently going in it, if any.++Every frame the daemon sends for an agent run carries that run's `runId`, and the extension resolves+it to the owning session's current tab. So a run keeps working in its own tab while the user browses+somewhere else, and two sessions in two tabs act independently. A run that opens a tab with+`page.openTab` adopts it as a subtab; `page.switchTab` onto a tab another session owns is refused+with `TAB_IN_USE`, and if every tab of a session is gone its actions fail with `SESSION_TAB_CLOSED`.++Calls with no run behind them — an external MCP client, the local fast path — still target the+active tab of the current window. A site-mapping run keeps its own older pin, threading a literal+`tabId` and failing with `MAPPING_TAB_CHANGED` if that tab goes away.++Closing a tab ends its session: the run is cancelled, the transcript is flushed to history, and the+entry leaves the registry. Closing the side panel does not — the tab is the anchor, and while a run+is going its tab carries a dot on the toolbar badge and on its favicon.---@@ -289,15 +305,15 @@ sequenceDiagramparticipant K as claude -pparticipant M as browsentic-mcp (child)- S->>B: instruction + context (url, tabId, files, recordings)- B->>B: tryFastPath() — grammar- B->>D: {t:"instruct", id, text, context}+ S->>B: instruction + the tab it was typed on+ B->>B: resolve tab → session, tryFastPath() — grammar+ B->>D: {t:"instruct", id, text, context (url, tabId, sessionId, files, recordings)}D->>D: route skill, build system promptD->>K: spawn with --mcp-config {browsentic}, BROWSENTIC_AGENT_RUN=<runId>K->>M: stdio (its only MCP server)M->>D: {op:"invoke", runId, action} (control WS)D->>D: approval / mapping gate- D->>B: {t:"invoke", …}+ D->>B: {t:"invoke", runId, …} → the session's own tabB-->>D: resultD-->>M: resultM-->>K: tool result@@ -499,7 +515,11 @@ Errors are `{ ok: false, error: { code, message } }` all the way through, surfac| `DEBUGGER_UNAVAILABLE` | Extension | Chrome’s debugger could not attach — usually DevTools is open on that tab. Close it, or use `page.clickElement`. || `CAPTCHA_NOT_FOUND` | Extension | No known captcha widget on the page, so whatever is blocking the run is something else. || `DAEMON_UNREACHABLE` | RemoteBridge | The daemon died mid-call. |-| `RUN_IN_PROGRESS` | AgentSession | One instruction at a time. |+| `RUN_IN_PROGRESS` | AgentSession | One instruction at a time *per tab session*; other sessions are unaffected. |+| `RUN_LIMIT` | AgentSession | Too many sessions running at once (`maxConcurrentRuns`, default 3). |+| `SESSION_LIMIT` | Extension | Eight tab sessions are already open. |+| `SESSION_TAB_CLOSED` | Extension | Every tab this conversation was working in has been closed. |+| `TAB_IN_USE` | Extension | That tab belongs to another Browsentic conversation. || `RUN_INACTIVE` | AgentSession | The run was cancelled while a tool call was in flight. || `DECLINED` | Approval gate | The user said no. Final. || `AGENT_MISSING` | Runner | The chosen agent's binary is not on the daemon's PATH. |diff --git a/docs/features.md b/docs/features.mdindex df5d457..18098b1 100644--- a/docs/features.md+++ b/docs/features.md@@ -127,7 +127,7 @@ Local commands never reach the daemon, so they leave no trace in `browsentic-mcpexpected, not a bug. Explain any single routing decision with:```sh-yarn intent:check "take me to the checkout page"+yarn check:intent "take me to the checkout page"```---@@ -321,10 +321,36 @@ consequential.---+## One conversation per tab++Each tab gets its own conversation, and several can run at once. A conversation is bound to the tab+it started in: it keeps working there while you read something else, and its actions stay in its own+tab instead of following whichever one you are looking at.++The side panel follows the tab in front. Switch tabs and the chat switches with it — to that tab's+conversation, or to a fresh empty one if it has none. The **Sessions** strip above the chat lists+everything currently open, with each tab's live title, a pulsing dot while it is working, and how+many messages it holds. Click a row to jump to that tab and its transcript; press **×** to end that+session. The strip collapses to a single line when you want the room back.++While a conversation is working, its tab is marked in two places — a dot on the Browsentic toolbar+icon and a dot drawn onto the tab's favicon — so a run you have scrolled away from is still visible+in the tab strip. Closing the panel does not stop anything. **Closing the tab does**: the run is+cancelled and the conversation moves to **History**, where you can reopen it on any tab.++If a conversation opens a tab of its own, that tab joins the same session as a subtab and its work+belongs to the same transcript. It will not act in a tab another conversation has claimed.++Eight tab sessions can be open at once, and three can run at the same time — raise the latter with+`maxConcurrentRuns` in `~/.browsentic/config.json`.++---+## The timeline and approvalsEvery action appears as it happens, with what it targeted and what came back. Local commands carry-a ⚡; actions from an MCP client are tagged as external. Cancelling stops a run mid-flight.+a ⚡; actions from an MCP client are tagged as external. Cancelling stops the run in the conversation+you are looking at; the others keep going.Actions that change something other people can see wait for an explicit **Allow** or **Deny**. Formsubmission is gated by default, and the gate is smarter than a name match — it also catches