A session holds up to eight browsers, and every tool can name one (0.15.0)

[feder-cr]

The first slice of a bigger change: one session is going to hold up to eight browsers, and today nothing can address a second one, because every tool calls registry.ensure() with no argument and lands on the same key.

The design this belongs to is in the workbench, at docs_research/chat-ui-performance/30-PROGETTO-sessioni-e-otto-browser.md.

The machinery was already there, and unreachable

The registry has kept browsers by id all along, and not sketchily:

• a lock per id, so two callers racing to first-use one browser start one rather than two
• the configuration remembered per id, so a rebuild is the same person with the same seed, the same profile and the same exit - the comment there records that rebuilding from the environment had de-anonymised the traffic while every tool reported success
• tab numbering that does not restart across a rebuild, so an id a caller still holds never names a different page
• refusals remembered, so a failed start does not quietly become a different browser

None of it could be used, because no caller could name an id.

So the registry is untouched by this change. The key is composed instead, from a session and a browser, and everything the registry already gets right starts applying per browser, which is where it was always needed.

What changes

Every tool takes session_id and browser_id, both optional. A client that sends neither behaves exactly as before - that is the promise this slice is built around, and the first thing its tests pin.

The retry path is addressed too. Dropping and rebuilding the default key while the action was aimed at another browser would kill a browser nobody asked about and hand back the wrong one: the same class of mistake as rebuilding from the environment, in that it succeeds, at the wrong thing.

Three existing tests, and one that had stopped testing anything

Three tests set the registry up by hand under the bare default key. Two failed honestly when the tools moved to composed keys.

The third kept passing while it no longer tested anything: its answer had become "no browser is running yet", and "the proxy password is not in that string" is trivially true of a string that mentions no session at all. It now checks the answer is about the proxied session before asserting the password is absent.

The ceiling

MAX_BROWSERS_PER_SESSION = 8 is declared here with the measurement that chose it - 61 processes and 6,515 MB for eight live browsers, with the eighth taking 13.6 s to start against the first one's 6.8 - but it is not enforced yet. That is the next slice, together with the tools that open and close browsers.

Test plan

• pytest -q: 369 passed (baseline 361, +8), 3 xfailed unchanged
• mutations run and killed: one tool reverted to a bare ensure(); addressed() losing its defaults; one tool losing its address; one tool losing both parameters
• the mutation that only the structural test catches is the interesting one: no behaviour test drives browser_click, so a lost address there is invisible to everything except the test that reads the source
• check_english_only.py and check_content.py clean, both also run with --selftest
• browser_read_html trimmed back under the 1024-character truncation that mcp_tools_to_openai applies, so its new note is not cut before the model sees it