Skip to content

2026 11 18 tabs design

Kelly Ferrone edited this page Nov 18, 2026 · 5 revisions

Tabs and popups

History. Drafted 2026-11-18 for issue #178, a prerequisite of sub-sessions (#94, ACT-43). Dr K's rulings are 1 to 7 below. Shipped as tab and the automatic popup follow. What it asked for now lives in ACT-45 to ACT-53 in browser-actions.md, WS-76 in workspaces-and-sessions.md and FLOW-59 in saved-flows.md. Nothing in it was overtaken; the BiDi action layer and transport setting stay with #177. The build is the tabs plan.

Brief

A browser holds tabs, and a page can open a popup, such as an SSO sign-in. selenium-flow knows one window. A popup is invisible to the agent, and the next call still acts on the window it was in. Nothing lists, opens, switches to or closes a tab, and once the current window closes, every call fails until the browser is ended. Sub-sessions (#94) assume each session can follow its own popups, so this comes first.

What the server does now

  • Every action acts on WebDriver's current window. No code reads or switches window handles.
  • Each browser has a BiDi socket, used by capture, the monitor and site data. browsingContext.getTree over it lists the top-level contexts with their URLs, without switching (monitor/monitor.py, site_data/transfer.py). WebDriver BiDi defines a classic window handle as the same string as its browsing context id.
  • One row of core.capabilities.CAPABILITIES is an MCP tool, a REST route and a flow step, and each ends in one method of core.actions.Actions (ACT-42, FLOW-7).
  • MCP and REST calls go through Workspaces.act, which holds the session's turn and notes where the result says the browser is (_arrived): secret scope follows the result's url. Flow steps call the Actions method directly, and Hooks.in_scope runs after each step, still inside the run's turn.
  • workspace://current reads in_frame and window live from the browser when it is live (WS-43), and every key it carries is listed in CONTEXT_KEYS (WS-64).

Rulings, 2026-11-18

  1. A tab tool: tab(action="list" | "open" | "switch" | "close", id=…, url=…). Every other tool acts on the current tab, as now.
  2. Popups are followed automatically. A tab that appears becomes the current tab: the newest, when several appear. When the current tab closes, the session goes back to the tab it came from, or to the newest one left when that one is gone too.
  3. A tab's id is short: t1, t2, … kept in the session's record and never reused while that browser lives. A new browser starts again at t1.
  4. Flows reach a popup without knowing its id: switch with no id goes to the newest tab, and switch with url goes to the tab whose URL contains that text.
  5. Background tabs are mentioned once, in the tool's description. Chrome stops rendering a tab that is not in front, and Firefox throttles its timers. Results carry nothing about it.
  6. The context always shows the tabs: workspace://current and workspace://current/tabs.
  7. Flows may use it. tab is a capability row, so it is a step like any other (FLOW-7). A flow follows popups within its own session only (#94's ruling).

Design

What a call sees

click(selector={"css": "#sso"})
→ {"url": "https://sso.example/login", "title": "Sign in", "tab": "t2",
   "opened": [{"tab": "t2", "url": "https://sso.example/login"}], ...}
write(...); click(...)               # the popup submits and closes itself
→ {"url": "https://shop.test/account", "title": "Account", "tab": "t1", "closed": ["t2"], ...}
tab(action="list")
→ {"tabs": [{"tab": "t1", "url": "https://shop.test/account", "title": "Account", "current": true}]}
tab(action="open", url="https://shop.test/help")
→ {"tab": "t3", "url": "https://shop.test/help", "title": "Help", ...}
tab(action="switch", id="t1")        # or url="shop.test/account", or no id: the newest
tab(action="close", id="t3")         # no id: the current tab
  • tab is in a result only when the current tab changed during the call. A tab call always carries it.
  • opened and closed are in a result only when non-empty.
  • When the session moved, the result's url and title are the new current tab's, so the origin the server notes, and secret scope with it, follow the move.

Following, at both ends of a call

Every call on the browser, whether a tool, a route or a flow step, checks the tabs before it acts and again after:

  • Before: a popup that opened after the last call, or a current tab that closed since then (by the page, or by a person in control), is caught before the call acts. The call then acts on the tab the session moved to, and its result says so.
  • After: a tab the call opened is followed, and a current tab the call closed is left.

A check is one browsingContext.getTree over BiDi (window_handles only when BiDi cannot answer), compared with the tabs the server knows for that browser. They are kept in the store under the Grid session id, beside the workspace's record and with its TTL, never inside it:

# selenium-flow:tabs:<grid session id>
next: 4                       # the next id is t4
current: t1
known:                        # in the order first seen
- {tab: t1, handle: 4F2A…, from: null}
- {tab: t3, handle: 9C11…, from: t1}

Keyed by the browser, the state starts empty for every new browser, so ids restart at t1 with no reset step and no migration of old records. It never contends with the record's own compare-and-set writes. A handle the server has not seen gets the next id, with from set to the tab that was current when it appeared. Several handles first seen together get ids in the order the browser lists them. Newest always means the highest id.

Listing

list and the context give each tab's url and title, read without switching: URLs from browsingContext.getTree, titles from one script.evaluate of document.title per tab over BiDi. When BiDi cannot answer, the current tab is read over classic and the others are left with url and title null. The order is opening order.

Edges

  • The last tab: close on it is refused, saying end_browser ends the browser.
  • Unknown id, or no tab matches url: a 400 that lists the tab ids and URLs.
  • id and url together: refused, as two selectors are (ACT-2's style).
  • A switch leaves any frame: WebDriver puts the session at the top of the new tab, so a tab result carries in_frame: false.
  • A tab closed in the middle of a call: a popup whose submit closes it is the common case. The action has already happened, so reading the page after it does not fail. The session moves (ruling 2), and the result carries the new tab's page and closed. An action that fails because its window vanished before it could act fails with a message naming the tab the session is now on. In a flow, that step fails like any other, and its onError applies.
  • What is browser-wide stays browser-wide: downloads, capture (console and network across all tabs), recording and site data. outline, screenshot and print act on the current tab only.
  • The visible tab: the live view and the recording show whichever tab is in front. The current tab must be the one in front, so a person sees what the agent acts on. It is brought there with browsingContext.activate, which keeps the session's frame. A classic switch_to.window, even to the window the session is already on, puts it back at the top page (measured on Chrome 152 and Firefox 155), so the driver switches only when it is on another window. Without BiDi, no tab is brought forward.
  • A person switching tabs in the live view does not move the session: WebDriver's current window is unchanged. The next call still acts on the session's current tab, which is then brought back to the front. This is Claude's call, and the simplest rule a person can predict.

Claude's calls

  • Checking at both ends of every call. Following only after a call would leave a late popup's first call on the wrong tab.
  • tab only on change, and opened/closed only when non-empty, to keep results short.
  • Following moves the result's url and title, because secret scope is keyed on the result's URL.
  • switch with url takes the newest matching tab.
  • Titles over BiDi, falling back to null rather than switching to read them. A switch would move the visible tab and change what Chrome renders.

After the builder check (Claude's calls)

  • Where the check runs. One method on Actions, check_tabs(session_id), reads the handles, reconciles them with the stored state, switches when following, and answers what changed. The Actions object is given the tab store when it is built. The MCP/REST bracket (_said) calls it before and after the call. The flow engine calls it around each step, since steps bypass act. tab itself is an ordinary Actions method using the same store.
  • The check runs before secret scope is read. In _said, the before-check comes before origins.current is read. A move is noted as an arrival (its URL and in_frame false). The call is then scrubbed with the origin it actually acted on. A flow step does the same.
  • Any result where the session moved carries in_frame: false, not only tab results. That way the noted frame state is corrected.
  • A popup that opens and closes within one call is never seen by either check. It gets no id and is not reported. Capture's browsingContext events could tell it later.
  • Handle equals BiDi context id is measured first, on Chrome 152 and Firefox 155 behind the Grid, and holds on both. The check lists the tabs from getTree and activates by context id, so it relies on it. Chrome holds window_handles while a popup loads a host that never answers; getTree answers at once.
  • One BiDi channel per check. A check, or a tab call, lists and activates over one channel. When BiDi will not open or answer, that browser's checks use window_handles alone for 30 s, so a route that hangs costs one call its timeout, not every call.
  • An action's own url navigates the tab that is current after the before-check. tab's url is a match text for switch and a load target for open. No shared url handling may treat it as a navigation.
  • window, the window size in the record and the context, is untouched. The context gains only tabs.

Out of scope

  • The admin UI. A tab list on the Session tab is a later round.
  • Separate windows. open makes a tab, never a new window.
  • The BiDi action layer and the transport setting, which are #177.
  • Filtering capture by tab.

Clone this wiki locally