Repository navigation
2026 11 13 multiplayer sessions design
History. Drafted 2026-11-13 for issue #94 as "several sessions in a workspace, and tabs". Rulings 1 to 20 (11-12 to 11-14) designed sessions as lanes of windows in one shared browser. On 2026-11-18, rulings 21 to 36 replaced that with today's model: the workspace's own default session, plus sub-sessions, each its own Grid browser. They overtook rulings 4, 8, 13, 14, 15 (now #177), 19 and 20, and most of the Open list. Tabs and popups moved to their own issue, #178, and the BiDi action layer to #177. The requirements are (proposed) in the spec: WS-47 to WS-54, WS-59, WS-60 and WS-72 to WS-75 in workspaces-and-sessions.md, plus SURF-45, SURF-46, ACT-43, ACT-44, LIVE-42, FLOW-50, FLOW-51, CAP-81, UI-64 and UI-65. On 2026-11-19 a review before the plan added rulings 37 and 38 (the admin UI's split bar; the default session is always
default, overtaking ruling 23's name), the calls under "After the review", and WS-77, WS-78 and UI-78. The build is the sub-sessions plan, and it is built.
Status: rulings 1 to 38 are recorded; the model below is settled; the small Open list at the end is
not, and none of it blocks the build. Drawn in Penpot (Kubed › Selenium Flow › Sub-sessions): the Session tab, Live, History
and Workspaces pages, built from the Library file's session-chip, sessions / row and
sub-session / band components.
This builds on the workspaces rename (workspace is the box a caller names; session is the live browser in it) and session URIs, and revisits ruling 1 of the programme: one session per workspace. #66, ownership and roles, meets this one; its design holds the questions where they meet.
Workspaces hold more than a browser, and several agents want the same one at once: two chats in one dev environment, an Actions run beside a local chat, or a main agent and the subagents it spawns. Today they all steer the one tab and trample each other. On 2026-11-12 the agent flow ran eight issues at once, and every runner job in a repo opens the same workspace (named after the repo), so two turns that browse would share one browser.
Dr K, 11-13: "multiple agents can use a workspace; when one does it gets its own session; this means we will have more than one session per workspace now." Also: "we should also somehow support two agents working in the same session anyway and maybe they can pick a tab or even battle it out for control for the fun of it."
-
No MCP client says which agent is calling.
- The 2026-07-28 MCP specification removed
Mcp-Session-Idand the initialize handshake. - Claude Code's request to pass agent identity on MCP tool calls (anthropics/claude-code#32514) was closed as not planned.
- A Claude Code subagent shares its parent's MCP connection, so the server sees identical requests.
- The 2026-07-28 MCP specification removed
-
Claude Code's hooks do know (checked 2026-11-13 against the hooks reference).
- A
PreToolUsehook getssession_id, plusagent_idandagent_typewhen the caller is a subagent. - Its
hookSpecificOutput.updatedInputreplaces the tool's arguments before the call, MCP tools included. - So a hook can stamp every selenium-flow call with who is calling, with no help from the model or the protocol.
- A
-
Measured 2026-10-27 on the cluster Grid (4.48, Chrome 152, Firefox 155):
- BiDi commands on two browsing contexts run in parallel.
- Classic WebDriver queues commands per Grid session and has one current window.
- Chrome renders nothing in a hidden tab, and Firefox throttles hidden tabs' timers to 1 Hz. Two windows avoid both.
-
browser.createUserContextworks through the Grid.
-
Measured 2026-11-13: two windows of one Grid session (a scratch spike over BiDi
browsingContext.create {type: "window"}, one session per browser):Chrome 152 Firefox 155 2 s timer in both windows, sent together 2.01 s (parallel) 2.12 s (parallel) 1.5 s CPU loop in both windows, sent together 1.51 s (parallel) 1.55 s (parallel) rAF frames in 1 s: window, window, background tab 61, 61, 0 60, 60, 2 visibilityState: window, window, background tabvisible, visible, hidden visible, visible, hidden classic GET /titleon window A while BiDi runs 3 s in window B0.01 s 0.02 s Windows run in parallel and both render. A background tab doesn't render. Classic and BiDi mix without blocking each other. Not measured yet: BiDi
input.performActionsin two windows at once. -
What the field does (read 2026-11-13).
- One browser per agent for full isolation: browser-use, agent-browser, Browserbase, Steel, Hyperbrowser, Browserless.
-
A context per agent in a shared browser, with isolation a named opt-in:
Playwright (BrowserContext), Playwright MCP (
isolatedContext,--shared-browser-context), Chrome DevTools MCP (isolatedContext), Cloudflare. -
Every call names its target once callers share a connection. Chrome DevTools
MCP replaced its selected page with
pageIdfor that case, and Browserbase asks forsessionIdon every call. - Agents acting as one user share a live cookie jar, one tab or window per task (Kernel, Browser MCP).
- Saved profiles have one writer. Kernel warns that the last save wins.
- The hidden-tab failure is known elsewhere. NousResearch/hermes-agent#135435: 17 subagents on hidden tabs of one Chrome, 11 of which lost their page. The fix proposed there is a new window per agent.
-
Measured 2026-11-14 on the cluster Grid (Chrome 152, Firefox 155), for ruling 20: one Grid session, two BiDi user contexts (
browser.createUserContext, 11 ms each), a window in each (browsingContext.createwithuserContext), one site.- A cookie, a localStorage item and a sessionStorage item set in window A are not seen in window B or in the browser's default window, and B setting its own leaves A's alone. Both browsers.
- A second window in A's user context sees A's cookie and localStorage. So a session can hold several windows that share its sign-in.
-
storage.getCookiesandstorage.setCookiewithpartition.userContextread and write one session's jar, httpOnly cookies included. - Removing a user context closes its windows and leaves the others signed in.
-
Firefox differs in two ways.
storage.getCookieswith no partition returns every user context's cookies (Chrome returns only the default's), so a save must always name the session's user context. And classic WebDriver's cookie commands see and delete nothing in a window outside the default user context, so cookie work for a session goes over BiDi. - Classic WebDriver lists every window and can switch to any of them, in both browsers.
- Not tested: a real sign-in through an app's login form, downloads, and permissions per session.
-
The Grid's cost of a browser (2026-11-12). Each Chrome node holds one Grid session, KEDA caps nodes at 6, and a node is now limited to 8Gi after Penpot work ran it out of 4Gi seven times in a day.
-
Today's identity, for reference. The workspace is named by
?workspace=or theSf-Workspaceheader, withX-Workspaceas its alias (WS-1, SURF-9).named_bysays which. A workspace's record holds onesession_id(WS-7).?session=andX-Session-Keyare read nowhere (WS-4, SURF-11). -
How comparable UIs scope a page to one of several runs (read 2026-11-19).
- NN/g, Tabs, Used Right: one tab bar holds one kind of content; mixing in-page and navigation tabs disorients.
- PatternFly's context selector and VA's segmented button: a scope selector sits directly above the content it controls, and only that content; past about eight static options, a menu.
- Browserbase (Sessions list, then a Session Inspector with Events, Pages, Console and Network), BrowserStack Automate (a build's sessions, each with Text, Console and Network logs and video), Cloudflare Browser Run (Live Sessions, expand one for its tabs) and GitHub Actions (a run's jobs beside one job's log) all show a parent, a list of its sessions, and one session's detail. Nothing a session does not own is filtered by picking it.
-
Who is calling, checked 2026-11-14 against the Claude Code docs.
- There is no client id. Subagents share the parent's connection, and the protocol carries no session id.
- The headers helper can't name an agent: it runs once per connection with only the server's
name and URL in its environment.
${VAR}in a URL or header expands before any subagent exists. - A
PreToolUsehook getsagent_idandagent_typefor a subagent's call and can rewrite the arguments. It's the only documented way to tell two instances of one subagent apart. Whetheragent_idholds for the subagent's whole life isn't documented and needs a test. - A subagent's own inline MCP entry gets its own connection, so its own header or URL. That names the type, not the instance, and plugin-shipped agents ignore it.
- So identity has three sources, strongest first: the token's
sub(#66), a pinned name (header or URL), and a name on the call (the model, or a hook). Open 7 is how they stack.
-
Workspaces and the
globallibrary don't change (Dr K, 11-12). Multiplayer adds sessions inside a workspace. It doesn't split workspaces. -
A workspace can hold several sessions at once, and an agent that joins gets its own (Dr K, 11-13).
-
A session has a name, given when it starts.
open_sessionanswers with it (Dr K, 11-13). -
No name means the default session, which is the first one opened (Dr K, 11-13). There's no special "main" session. The first session takes a generated name if nobody named it (for example
swift-otter). -
A name can be pinned from outside (Dr K, 11-13). A header or URL param locks a connection to a named session, for example
bossfor the main agent. A known subagent whose own MCP entry (in its frontmatter) sets the header gets its own named sub-session. A call can't escape a pinned name. -
A name can also be left loose (Dr K, 11-13). With nothing pinned, the agent sets the name itself. Configuration gives us the choice per agent: pinned in the JSON settings when we want it fixed, loose when a subagent should choose.
-
Two agents in one session work on separate tabs (Dr K, 11-13). Every session can switch between tabs and follow popup windows, whether or not it's shared.
-
Agents may contend for control of a shared session (Dr K, 11-13, "for the fun of it"). This is the live view's Control (its design) extended to agents: an agent asks, waits, and gets handed control, as a person does.
-
Which tabs belong to a session, and which to the workspace (Dr K, 11-13):
- session: Session, Console, Network, Live;
- workspace: Files, Flows.
- Site data and History are Open 2.
-
The admin UI switches between sessions with a dropdown (Dr K, 11-13). It sits in the row with "← Workspaces" and appears only when the workspace has more than one session. Picking a session refocuses the session tabs on it.
-
Hooks are an option, not the mechanism (Dr K, 11-13: "hooks are an interesting idea too"). Pinned headers and the name on the call work for every client. A hook only automates the name for Claude Code subagents that have no pinned header.
-
Slow down before building (Dr K, 11-12). Talk it through and design it in Penpot first. Multiplayer use in the meantime is careful and one at a time.
-
A session is a lane of windows in the workspace's browser (proposed 11-13 from the research and measurements below; Dr K: "looks good so far").
- A session owns windows, and the windows hold tabs. It starts as one window. Popups and windows its pages open join it.
- Sessions share the workspace's one Grid browser by default.
-
isolatedgives a session its own BiDi user context. - Its own Grid browser is an escalation only.
-
Two agents in one session each get a window, not a tab (11-13). A tab that isn't showing doesn't render. Tabs are for one agent moving between its own pages.
-
BiDi is a transport, and classic stays (Dr K, 11-13: "BiDi won't totally replace; support it when we need it, and offer the choice between WebDriver and BiDi when possible"). The transport is
auto | classic | bidi. The BiDi action layer gets its own follow-up spec. -
A flow takes the options, not the tool calls (Dr K, 11-13). One run of a flow is one lane:
-
run_flowcarriessession(andtransport), and every step inherits them; - a step can't name a session, a window or a transport;
- one flow can't reach across sessions or windows.
-
-
Cookies and site data go with the session, whoever calls (Dr K, 11-14: "the cookies and site data stuff should be bound to the session even if two subs declared the same session name ... it should be loose like this since we can't really truly tell the difference"). Two callers that name the same session share it, cookies and all, whatever their
sub. One can watch what the other does, and they can take turns. Settles Open 10 (a differentsubgets nothing of its own without asking: the session's name decides) and the site-data half of Open 2. Whether it also changes ruling 13's default is Open 17. -
A
subisn't tied to a session (Dr K, 11-14: "i don't think we can force a sub to a session, if i tell an agent to spawn subagents it would have subagents using the same sub, this is where the subagents can simply name their session themselves"). Callers with the same credentials tell themselves apart by naming their session. Settles Open 7: a name, pinned or on the call, decides the session, and thesubnever overrides it. -
The
subis the default name (Dr K, 11-14: "the subs are good default names though"). A caller that names no session gets the session named after itssub. Settles Open 9, and Open 8 follows: a secondsubthat names no session gets its own. A reading, to confirm: a caller with nosub(auth off, the token, stdio) keeps ruling 4's default, the first session opened, with a generated name. -
Each session has its own cookies and site data (Dr K, 11-14, later: "it might actually be a good idea to bind the site-data stuff to the session so each one can login independently. Imagine if one was testing how to logout while another was testing some feature you need to be logged in to see, or maybe two sessions were the diff between logging into some app with different roles. One workspace is basically some app/project I am working on and that app may have these login differences"). This changes ruling 13's default: every session gets its own user context, so
isolatedis the rule and not an option. Sessions still share the workspace's one browser, as lanes of windows. Callers that want one sign-in between them name the same session (ruling 17). Settles Open 17 and the site-data half of Open 2. Opens 18.
On how this meets #66, in his words: "I feel these two issues will work together and effect each other. like two different subs in the same workspace would basically be a separate session; then whoever was first would be the first/default session; maybe roles and sessions are somewhat linked like the sub/role could be the session name by default if a name wasn't given."
- Two different
subs in one workspace are in effect two sessions. - Whoever came first holds the default session.
- The
subor a role could be the session's name when none was given.
The first and third lean away from ruling 4 (no name means the default session, which takes a generated name). Open 8 and 9.
Taken one question at a time with Dr K. Each names what it overtakes.
- One session per workspace is the default session, the workspace's own. It is today's workspace record and browser, unchanged: its settings, last page, saved site data and reopening where it left off. A user who never uses multiplayer sees nothing new (Dr K: "it just works totally fine with one workspace to one session like it does now. then the multiplayer stuff kicks when more join the party").
- Every other session is a sub-session (Dr K: "call all the session that are not the default one the sub-sessions. then we can be more intentional"). Sub-sessions show up, when one exists, as their own visibly separate thing, so it is plain which is which and who is in charge.
-
The first session opened is the default. It takes the name its open gave, else
default, anddefaultis an alias of it whatever it is called ("default is an alias to at least one of them"). Overtakes ruling 4's generated name. - A call that names no session reaches the default session, unless its token's subject differs from the subject that opened the default: then it gets a sub-session of its own, keyed by that subject and shown by the username, made on its first call. A caller with no subject (the token, stdio, auth off) always reaches the default. Narrows ruling 19.
- Callers that name the same session are one caller. Their calls queue and run in order; the server does not tell them apart. Keeping a subagent out of the boss's session is the main agent's job (Dr K: "we simply execute the flow of tools calls as if they all came from one and simply make sure they are queued correctly"). Overtakes ruling 14 (a window per agent) and ruling 8 (agents contending for control).
- Placement, for now: each session is its own Grid browser (Dr K: "generally safer to simply have one grid session per session for us too. then each agent get's their own pod even. then the windows in a session thing can come later"). One layer in the code places a session; no tool knows how. Several sessions per browser (windows in BiDi user contexts) comes later, behind that layer. Overtakes rulings 13 and 20.
- No cap. The Grid and its autoscaler decide how many browsers run. An open with no free browser waits and fails as the Grid says; the operator sizes the Grid (Dr K: "the grid limits and we shouldn't care how the queue is divvied").
- A sub-session starts empty. Nothing is seeded from another session. Settles Open 18.
-
Every session keeps a record in the store, never in
workspace.yaml. A sub-session's settings, last page and site data are its own,save_site_datasaves there, and a reaped sub-session reopens where it left off, signed in. The default session's record livesworkspace.ttl(or for ever in a kept workspace); a sub-session's livessession.sub_ttl, an hour by default, after its last use (Dr K: "make the cache ttl in the mem store just less time ... none of this stuff should be saved or persisted on the workspace config"). - Settings are each session's own. A sub-session can be Firefox while the default is Chrome.
- History is the workspace's, each entry naming its session; the History tab filters by the picked session. Settles Open 2's History half.
-
A session's data is read by its name:
session://{name}andsession://{name}/console,/networkand/downloads, since a resource read carries nosessionargument.workspace://currentdescribes the caller's resolved session and lists every session. - A person's control covers one session, its own browser; while a person holds it, that session's acting calls wait (Dr K, "the whole browser waits", which with one browser per session is that session). Sub-sessions elsewhere keep working.
-
A flow run is one session.
run_flowtakessession; no step names one. A flow may follow a popup its own page opened, within its session, once tabs exist (#178). Keeps ruling 16. -
Tabs and popups are their own issue, #178, a prerequisite: a
tabtool, popups followed and reported, the tabs in the context, and a hint when the current tab changes. Overtakes ruling 7's place here. - The transport (classic or BiDi) is its own issue, #177, with a BiDi action layer and a workspace setting. Classic takes turns; BiDi is "the streaming version". Overtakes ruling 15's place here.
From a review before the plan, with the research above.
-
The admin UI splits the workspace page by scope (Dr K picked the split bar). The workspace
card shows the workspace only: its name, whether it is kept, and its config. The session chips
sit directly above the session tabs (Session, Live, Console, Network, Site data). A divider, then
the workspace tabs (Files, Flows, History, Config), which picking a session does not change.
History has a session filter of its own. The session's state (recording, capture, its last
page) moves from the card to its Session tab, a chip's dot says whether its browser is live, and the button that ends a browser names its
session ("End tester"). With only the default session there are no chips, and the tabs are
today's in the new order. A sub-session is marked by its chip and an accent edge on the session
area, never by a line of helper text. Overtakes the drawing's single mixed bar and banner, and
ruling 10's dropdown: chips, with the ones past five in a
+Nmenu. -
The default session is always
default(Dr K). Naming or pinning any other name always means a sub-session, and a main agent reaches the workspace's session by naming nothing ordefault. Which session is the workspace's never depends on who arrives first. Overtakes ruling 23's name taken from the first open (a pinnedbossin a workspace that already had its record would have got an empty, hour-long sub-session) and ruling 5'sbossexample.
-
Keys. A sub-session's record is
<prefix><workspace>/<name>beside the workspace's own<prefix><workspace>. Names cannot hold/(WS-3), so the two never collide. One index answers which keys are workspaces, so the admin's Workspaces list, the monitor's owner lookup and the live tunnels never take a sub-session for a workspace; a workspace forgotten takes its sub-sessions with it. -
Only
open_sessionopens a browser, for every session, as today. A call naming a session with no browser getsfaults.NoSession(WS-60), so a mistyped name never starts a browser. A token subject's sub-session (WS-49, 3) is made by that subject'sopen_session. -
The default's owner (WS-50, from the builder check, read from Dr K's 11-18 words "if it's
the very first one, it's for sure the default one. However if another sub comes in then we can
actually differentiate"): the first subject that reaches the default owns it, kept once as
owneron its record. A later open, ending the browser or namingdefaultnever moves it; a new record starts unowned. An unowned record (reached only by callers with no subject, or written before this build) is claimed by the next subject, so a workspace in use today keeps its sign-ins for the subject that comes back first.Principal.opener()stays what it is, shown only. -
Downloads in the admin UI. Files stays the workspace's and lists each session's downloads
under its label; the downloads routes and
keep_filetakesession, the caller's by default. -
The MCP App's view shows the caller's session, as
workspace://currentresolves it, and names it. - The drawing had drifted from the code (no Config tab). The Sub-sessions file is redrawn to ruling 37 with local copies of the tab bar and the workspace card. The Library keeps today's until the build moves the split bar into it (UI-63).
# the server's config
workspace:
ttl: 86400 # the default session: a day after its last use
session:
sub_ttl: 3600 # a sub-session: an hour after its last use# selenium-flow:workspace:shop-app the default session: today's record, unchanged
workspace: shop-app
opened_by: {kind: admin} # or {kind: oidc, subject: 7b1e..., username: alex}
session_id: 4f1c... # its own Grid browser
settings: {browser: chrome, width: 1600, height: 1000}
url: https://shop.test/admin
site_data: {shop.test: ...}
history: # the workspace's, each entry tagged
- {session: default, url: https://shop.test/admin}
- {session: tester, url: https://shop.test/login}
subs: [tester, 7b1e4c2a-...] # the index of its sub-sessions
# selenium-flow:workspace:shop-app/tester a sub-session (lives session.sub_ttl)
workspace: shop-app
name: tester
session_id: 9b2e... # its own Grid browser
settings: {browser: firefox, width: 1280, height: 800}
url: https://shop.test/login
site_data: {shop.test: ...} # its own sign-ins
# selenium-flow:workspace:shop-app/7b1e4c2a-... made for a second token subject
name: 7b1e4c2a-... # compared by subject
label: alex # shown by username| The call | Reaches |
|---|---|
a pinned name (Sf-Session header, ?session=), else the session argument |
default reaches the default; any other name is a sub-session |
| no name, and no session open yet | opens the default session |
| no name, from a caller with no subject, or the subject that opened the default | the default session |
| no name, from another subject | that subject's sub-session, made on its first call |
open_session(url="https://shop.test/admin")
→ {"workspace": "shop-app", "session": "default", "default": true, ...}
open_session(session="tester", url="https://shop.test/login", browser="firefox")
→ {"session": "tester", "default": false,
"others": [{"session": "default", "live": true, "url": "https://shop.test/admin"}], ...}
write(session="tester", selector={"css": "#password"},
secret={"name": "shop-customer", "key": "password"}, submit=true)
save_site_data(session="tester") # tester's own record
run_flow(name="shop-login", session="tester") # every step in tester
end_browser(session="tester") # its browser quits; its record stays an hour
workspace://current → the workspace, `session` (the caller's), `sessions` (each one's
name, label, default, live, url)
session://tester → tester's context
session://tester/console → its console rows; /network and /downloads likewise
A pin, as a subagent's own MCP entry or a claude.ai connector (which controls its URL):
https://flows.example.com/mcp?workspace=shop-app&session=tester, or Sf-Session: tester.
- One placement layer hands a session its Grid browser. Everything that today reads "the workspace's browser" reads "the session's browser" through it: the turn lock (WS-39), the monitor and keep-alive (one watch per browser, as now), capture (already keyed by Grid session), secrets' origins, the current frame, recordings, downloads and the live view.
-
The store gains sub-session records under
<workspace>/<name>, with their own TTL, and an index on the workspace record. The default session's record stays where it is, so nothing moves. Whatever lists records asks the index, so a sub-session is never listed as a workspace. -
Every acting tool takes an optional
session. A caller that never names one behaves as today.
Ruling 37's split bar:
┌ claudecode ─────────────────────────── kept · config ┐
└──────────────────────────────────────────────────────┘
● default │ Sub-sessions ● tester ○ alex [End all]
┃ Session Live Console Network Site data ┃ Files Flows History Config
┃ SESSION · TESTER ● REC · capture ┃
┃ chrome 152 · 1280×800 [End tester] ┃
- The workspace card is the workspace's only. The session's state is on its chip and its tabs.
- The chips appear only when a sub-session exists: the default first, a divider, then each
sub-session by label, a filled dot when its browser is live. Past five, the rest are in
+N. - The session tabs follow the picked chip. The workspace tabs never do; History filters by its own session control, all sessions by default.
- "End tester" ends the picked session's browser; "End all" ends every session's.
- With only the default session, the page is today's with the tabs in the new order.
Settled by the rulings above: 1 (26), 2 (31; site data is each session's by 29), 3 (25: agents in one session never contend), 4 (27), 6 (34, with #178), 7 to 11 (23 to 25; ending: the admin ends any session), 12 to 15 (26: each session has its own browser, so its own frame, origin, window size, screen, downloads and turn), 17 and 18 (28, 29).
Still open:
- The hook (ruling 11, Open 5): whether selenium-flow's plugin stamps a subagent's calls with a session name. Dr K, 11-18: possibly later, with the plugin served from the server itself; not this issue.
-
?session=as the pin (Open 16): a client still sending a stale?session=starts pinning. With one user, accepted unless Dr K says otherwise. - Several sessions per browser (ruling 26's "later"): windows in BiDi user contexts behind the placement layer, with its own issue when wanted.
- Changing what a workspace is, or the
globallibrary (ruling 1). - Roles and who may join a workspace: the ownership design (#66).
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network