2026 10 26 session capabilities design

Session capabilities, and named options for the ones we treat specially

Status: SETTLED 2026-10-26, issue #82 / PR #87. Rulings 1–22 were read by Dr K against the thread on #82 and found matching. Rulings 23–31 are the plan agent's calls, made checking this spec against the code on PR #87, and were read right on the pull request. Ruling 23's open question was answered there (Dr K, 10-26), and nothing is open. The plan is docs/superpowers/plans/2026-10-26-session-capabilities.md. It builds on the workspaces rename (2026-10-09-workspaces-rename-design.md) and the session monitor (2026-10-09-session-monitor-design.md). #86 (headless) and #83 (live view) build on this one. The admin UI is drawn in project-docs, design/session.md and design/README.md (Penpot file Admin UI). This spec says only what the UI needs from the server and where the design applies.

Rulings marked Dr K are settled. Rulings marked agent's call were told to Dr K on the issue or the pull request and not objected to.

Brief

open_session takes a capabilities object that is sent to the Grid as is, best effort. On top of it, the capabilities selenium-flow already treats in a specific way get promoted to named, typed options, with defaults, rules and messages that steer a model to the right choice. The raw object is the "only if you really need to" escape hatch. A server-wide default rides under every request, which is how our Grid's kubed:pool: default reaches it. The admin UI gets a Session tab with three parts: what the workspace asks for, what the Grid gave, and every capability sent with where it came from.

It came out of a Chrome 156 crash hunt, which raised three feature requests:

• #1: pick a browser version;
• #3: target one node without hijacking the Grid;
• #4: per-session browser args.

Rulings

1. Best effort (Dr K, 10-25). selenium-flow sends the caller's capabilities and reports what came back. It never refuses a request because it cannot see a node that would serve it.

2. No catalogue of node kinds (Dr K, 10-25). The Grid knows nothing about nodes scaled to zero, so a list would be static. A static list that is enforced does harm on a Grid that spawns nodes to match its queue.

3. Promote what is already special (Dr K, 10-25). Raw capabilities is for the rest.

4. Errors and results guide the model (Dr K, 10-25). A miss explains itself in words a model can act on, and points at where to look.

5. Vendor blocks merge (Dr K, 10-25). For goog:chromeOptions and moz:firefoxOptions, the caller's args are added to ours and its prefs are added too. Where both set the same thing, ours wins.

6. The named options (Dr K, 10-26) are:

   • browser and version;
   • width and height;
   • headless (#86);
   • record, capture and insecure;
   • page_load_timeout and script_timeout.

   Nothing else: no se:name, no pageLoadStrategy.

7. Store the inputs, recompute the output (Dr K, 10-26).

   • The workspace keeps the named options and the caller's raw capabilities, and carries them over.
   • The full set sent is kept with that one session, for display only, and is never reused.
   • Config changes and upgrades take effect at the next open.
   • Window size and the timeouts are WebDriver commands sent after the browser starts, not capabilities.

8. A config default capabilities (Dr K, 10-26).

9. Every capability sent has a source (Dr K, 10-26): flow, config, option or raw. A merged vendor block can have more than one.

10. The per-client layer (Dr K, 10-26). version is browser's twin, so it gets ?version= / X-Version the way browser has ?browser= / X-Browser. Raw capabilities gets none. There is no X-Capabilities: the config default carries the pool, and nobody has asked for pools per connector.

11. The idle WORKSPACE card (Dr K, 10-26) shows only what an explicit open_session() carries over, so it has no RECORD row and no CAPTURE row. The masthead's capture paused pill says the rest. design/session.md is updated; png/session-idle.png still shows the old row.

12. Wait as long as the Grid does (Dr K, 10-26), and answer with our own 503 text when it gives up. The reason: a KEDA scale-up from zero takes a minute or more, and giving up first would abandon a request the Grid may still serve. The Grid copes with that case on its own: its distributor stops a session it created after the request timed out or the client went away ("stopping it to avoid stalled browser", LocalDistributor, 4.48). Nothing here relies on it.

13. An explicit capabilities replaces the remembered object whole, and {} clears it (Dr K, 10-26). Replacing the raw object only ever touches what came from raw. Nothing raw may undo or fight a built-in setting; see Building the sent set.

14. A raw key may override a config default (Dr K, 10-26). This is how a call picks another kubed:pool, and that key's source then reads raw.

15. Owned keys are refused (Dr K, 10-26). A raw key that selenium-flow or a named option produces is a 400 naming the option, never applied quietly.

16. A node refusing the session is a 400 only when the open sent something the caller could be at fault for (Dr K, 10-26): raw keys or a version. The message quotes the node's reason and points at those raw keys or that version as the likely cause. An open that sent neither is refused because of the node itself (a starved node, Chrome failing to start), so that refusal is a 503, which a retry can act on. The queue timeout is always a 503. A refusal and a queue timeout are told apart by the Grid's error text, which this spec names and a test holds.

17. sent is what that open sent (Dr K, 10-26). A config change shows at the next open, never on a session that is already open.

18. The raw object is typed dict[str, JsonValue] (pydantic), and the owned-key list is the one below (Dr K, 10-26).

19. version="latest" clears a remembered version (agent's call), and latest is never sent. The WORKSPACE card's chrome · latest uses the same word. The Grid's own "any version" is an empty value or stable.

20. An explicit browser different from the remembered one drops a remembered version (agent's call). Otherwise Firefox inherits Chrome's 152 and waits 300 s for a node that does not exist.

21. session.version exists in config (agent's call), as browser's twin (ruling 10). Without it nothing server-wide could set a version, because browserVersion is an owned key.

22. The ENDED wording and the skill's layout are the agent's calls; Dr K delegated both. See Admin API and UI and The skill.

23. The sent set is exactly what the builder returns, and insecure owns acceptInsecureCerts (agent's call, PR #87; the insecure half is Dr K's, 10-26). Selenium's Options objects add keys of their own today, so the Capabilities section would otherwise not be the truth:

    • pageLoadStrategy: normal on both browsers. It is not sent any more. Absent, W3C's default is the same normal, and a raw pageLoadStrategy is then an ordinary raw key (ruling 6 keeps it unnamed).
    • On Firefox, acceptInsecureCerts: true and moz:debuggerAddress: true, from DesiredCapabilities.FIREFOX. So every Firefox browser accepted any certificate, whatever insecure said, and an insecure Firefox browser still got saved site data, which open_session exists to prevent. The bug was that insecure only ever sent true and left the rest to Selenium's default.
    • The fix (Dr K): insecure always sends acceptInsecureCerts explicitly, true or false, on every browser, with the source option. It is a standard W3C capability, so the option needs no per-browser translation (unlike headless). Firefox then follows insecure exactly as Chrome does, and the site-data rule holds on both. Anything browser-specific still goes through raw capabilities.
    • moz:debuggerAddress (a CDP address, which AGENTS.md rules out) is not sent.
    • A Firefox user driving a self-signed site now needs insecure=true, as on Chrome. There is one user, so there is no compatibility shim; a Fixed: changelog line says it.

24. Grid-side failures are told apart by message (agent's call, PR #87), answering the question this spec left to the plan. The router's own SessionNotCreatedException messages (checked in the 4.48.0 source): Unable to find owning node for slot, Interrupted when creating the session, An error occurred creating the session, No capabilities found in session request payload and Client has gone away. They live in one constant beside the two queue-timeout strings, a test pins all of them, and a failure carrying one stays the plain 503 it is today. Anything else SessionNotCreatedException is a node's refusal (ruling 16). Where they came from cannot be told apart: both arrive as the same HTTP 500 session not created.

25. What the 503 quotes (agent's call, PR #87): browserName, browserVersion, platformName, and every key with a : outside the never-matched prefixes (goog:, moz:, ms:, safari:, se:). Those are the keys the Grid matches on, so they are the ones that can explain a miss. A scalar value is quoted as key=value; any other value as the key alone. A vendor block, proxy and anything unmatched are never quoted, because a cloud vendor's options and a proxy URL are where credentials live.

26. A remembered raw key that an upgrade makes owned (agent's call, PR #87). Rebuilding at a reopen after a reap refuses it with the same 400, which adds: clear it with open_session(capabilities={}). Dropping it quietly would change the browser's shape, which is what a reopen must never do.

27. A raw vendor block of the wrong shape is a 400 (agent's call, PR #87), before anything ends: args that is not a list of strings, or prefs that is not an object. A merge cannot add to either, and sending it anyway would make a node's refusal out of a typo.

28. ignored lists <block>.prefs.<name> (agent's call, PR #87), and only when a config or raw value differs from the one that won. Args are never ignored: an exact duplicate is dropped, and anything else is added.

29. A named option can add a vendor arg through option_args (agent's call, PR #87): a keyword of the builder that nothing passes yet. It is what #86 needs from this change, and a test proves the merge and the option source with it.

30. The admin payload names the asked version asked_version (agent's call, PR #87). The row's version already exists and is the Grid listing's, as ran, which the list view shows.

31. The Session tab is the workspace's address (agent's call, PR #87): #/workspaces/<key> opens Session, and Files moves to #/workspaces/<key>/files. The integration flow keep-a-screenshot.yaml navigates to the new Files hash. No flow is added.

Research

Checked against the source of Selenium Grid 4.48.0, the version the cluster runs. The issue body holds the rest: KEDA's trigger matching, docker-selenium node images, and the headless table.

• DefaultSlotMatcher decides which node a request can land on.
  • An extension capability (one with : in its name) is matched only when the request carries it.
  • Capabilities starting goog:, moz:, ms:, safari: or se: are never matched.
  • A browserVersion that is null, empty or stable matches any node. Anything else is compared by SemanticVersionComparator, so 152 matches 152.0.7977.82.
• LocalDistributor.newSession answers in one of two ways.
  • When no node supports the capabilities, or none has a free slot, it raises RetrySessionRequestException and the request goes back to the front of the queue.
  • When a node is chosen and its newSession fails, the node's SessionNotCreatedException is returned at once, carrying the node's own message. startSession adds one message of its own, Unable to find owning node for slot.
• LocalNewSessionQueue times out a request still queued at sessionRequestTimeout (300 s here).
  • It fails the request with SessionNotCreatedException("New session request timed out") or ("Timed out creating session"). Its other failures are Interrupted when creating the session, An error occurred creating the session and Client has gone away.
  • That arrives as HTTP 500 with error: session not created.
  • Python raises it as SessionNotCreatedException, which errors.py already maps to 503.
• Python's ClientConfig.timeout defaults to socket.getdefaulttimeout(), which is None, and this repository sets none.
  • So Grid.open already waits the Grid's whole queue timeout (ruling 12 keeps it that way).
  • While it waits, it holds one of the 40 worker threads that FastMCP's sync tools and Starlette's routes share.
• Selenium's Python Options (read in the 4.38 source; the plan's Task 2 tests pin the result against the installed version, 4.48 or later):
  • BaseOptions.__init__ starts from default_capabilities and sets pageLoadStrategy: normal.
  • FirefoxOptions.default_capabilities is DesiredCapabilities.FIREFOX: browserName, acceptInsecureCerts: true, moz:debuggerAddress: true (ruling 23).
  • to_capabilities() rebuilds the vendor block from the object's own args, prefs and experimental options, so a vendor block set with set_capability is overwritten. The sent dict has to be what to_capabilities() returns, not something set into it key by key.
• KEDA scales a node class only for a request that carries every key in that class's trigger capabilities. Once every class carries a kubed:pool, a request without one scales nothing, which is why the config default exists.

Design

The inputs

open_session gains two arguments, on the tool (mcp/tools.py), the endpoint (POST /browser) and the action (core/actions.py):

• version: str | None: the browser version to ask for, such as 152 or 152.0.7977.82. latest clears a remembered one.
• capabilities: dict[str, JsonValue] | None: extra W3C capabilities, sent as given, best effort. {} clears a remembered object.

headless is #86's to add. What this change owes #86 is that a named option can add a vendor arg (ruling 29).

The docstring is prompt, so it presents the named options as one coherent set: what each controls, and whether it is remembered. The raw object comes last, as the escape hatch: use it only for a capability no option covers, and expect a key an option controls to be refused with the option named. The existing options are described in the same style.

What is remembered, and the cascade

Setting	Config (session.*)	Client (?param / header)	Carried to an explicit open_session()	Replayed after a reap
browser	yes	?browser / X-Browser	yes	yes
version	session.version (ruling 21)	?version / X-Version	yes; dropped when browser changes explicitly	yes
width, height, the timeouts	yes	yes, as today	yes	yes
insecure	no	no	yes, as today	yes
record, capture	no	no	no	yes, while enabled on the server
capabilities (raw)	no (session.capabilities is a separate source, below)	no	yes, whole	yes

Each setting cascades as config < client < workspace < call, through resolve in workspace/settings.py. version and capabilities join SETTINGS:

• version: (version, x-version, a stripped non-empty string). latest is kept as a value, so an explicit clear beats a remembered version.
• capabilities: (None, None, a dict coercion). {} is kept as a value, so an explicit clear beats a remembered object, the way insecure=false beats a remembered true.

Both are stored in Workspace.settings, so Workspaces.resolved() replays them after a reap with no new path. The browser switch that drops a remembered version is applied in open_browser, before resolve, to the inherited settings.

The config's session.capabilities is not a lower layer of the raw setting. It is its own source, merged under the raw object at every open (ruling 14). That way a config change reaches the next open even in a workspace that remembers a raw object.

Building the sent set

This is the one place the precedence rules live. It is a pure function with no selenium import, in core/session_caps.py, because core/capabilities.py is already the table of actions.

It takes:

• the browser kind;
• the resolved named options, and option_args (ruling 29);
• the config capabilities;
• the raw object.

It returns:

• the dict to send;
• for each top-level key, its value and its sources;
• ignored: the vendor entries where ours beat the caller's (ruling 28);
• or a ValueError for an owned key or a vendor block of the wrong shape, which is a 400.

Grid._options turns that dict into the Options object it sends, whose to_capabilities() returns exactly that dict (ruling 23). Grid.reconnect() calls _options() with no arguments for an inert ReattachDriver, and that call must stay cheap and valid.

The layers are applied in this order:

1. flow: what selenium-flow always sends.
   • unhandledPromptBehavior: ignore, se:downloadsEnabled: true and webSocketUrl: true.
   • The vendor block's args and prefs from today's _options. Chrome gets --no-sandbox, --disable-dev-shm-usage and four prefs; Firefox gets five prefs.
2. option: what a named option produces.
   • browserName from browser, always.
   • browserVersion from version, unless it is unset or latest.
   • acceptInsecureCerts from insecure, always, true or false (ruling 23).
   • se:recordVideo and se:videoName from record.
   • A vendor arg from headless, which #86 adds through option_args.
3. config: session.capabilities.
4. raw: the caller's capabilities.

Source	May override	Refused when it sets	Silently loses to
flow	nothing	nothing	nothing
option	nothing; it sets only the keys it owns	nothing	nothing (its vendor arg is added beside flow's)
config	nothing of flow's or option's	an owned key: a ConfigError at load, naming the option	raw, for the same key
raw	a config key, whose source becomes raw	an owned key: a 400 naming the option	flow and option, inside a vendor block (ruling 5); listed in ignored

Owned keys, and what a refusal names:

Key	The refusal says
unhandledPromptBehavior	selenium-flow keeps dialogs open for the dialog tool; it cannot be set
se:downloadsEnabled	the downloads folder needs it; it cannot be set
webSocketUrl	site data, capture and the monitor need it; it cannot be set
browserName	use browser=
browserVersion	use version=
acceptInsecureCerts	use insecure= (true or false)
se:recordVideo, se:videoName	use record=true
timeouts	use page_load_timeout= / script_timeout=
the headless flag in a vendor block's args	use headless=true (#86 adds this row)

A refusal is raised before the held browser is ended, like today's strict browser check in open_browser: a rejected argument must cost nothing.

The vendor block merge applies to goog:chromeOptions for Chrome and moz:firefoxOptions for Firefox.

• args are listed ours first, then option-produced, then config, then raw, with exact duplicates removed.
• prefs merge as a dict. Flow beats everything, option beats config and raw, and raw beats config.
• Any other key in the block (binary, extensions, log, mobileEmulation, …) comes from config, then raw (raw wins), unless flow sets it.
• The block's sources are every layer that contributed to it.
• A block for the other browser (a moz: block on Chrome) is sent untouched, best effort.

The function is where the unit tests live: every row of both tables gets one.

What is kept

Workspace (workspace/store.py) gains three fields. Each gets a defensive reader in from_json, like _timeout and _size, so an old or malformed record reads as none.

• sent: list[{key, value, sources[]}], what this session's open sent. remember() writes it at every open and every reopen.
• ran: {version, node, live_view}, read from driver.caps at open (browserVersion, se:containerName, se:vncEnabled).
• ended: {at, by} or None, where by is admin or caller. end_browser writes it from caller.named_by == "admin"; the admin End already passes Caller(key, "admin"). The next open clears it.

detached() keeps sent and ran, because the idle GRID SESSION card shows the last browser. A reap writes nothing here: nothing watches a plain session, so the admin view learns a browser is gone from the record still naming a browser the Grid no longer lists.

What a model is told

• open_session's result.
  • settings gains version as asked, and capabilities (the raw object) when there is one.
  • The top level gains version as it ran (ran.version).
  • The top level also gains ignored, the vendor entries ours beat, but only when it is not empty.
  • CAPABILITIES["open_session"].response in core/capabilities.py is updated with these fields.
• workspace://current (Workspaces.describe) gains version as it ran, beside browser. settings already shows what is remembered.

A model is never shown the full sent set. It belongs to the admin, and it is too long to be worth a model's context.

Errors

All of this goes in errors.py, the one place that decides what a failure means.

• An owned key, or a vendor block of the wrong shape, is a 400: a ValueError from the builder.

• The queue timed out: a SessionNotCreatedException whose message contains New session request timed out or Timed out creating session. It is a 503, with our own text, for example:

  no Grid node took this browser before the Grid gave up waiting: it asked for chrome 152, kubed:pool=headless. The Grid may have no node with these capabilities, or none free; see skill://selenium-flow/references/TROUBLESHOOTING.md

  The message quotes what ruling 25 allows, and never a vendor block. Both Grid strings live in one constant, and a test pins them.

• A Grid-side failure (ruling 24) stays the 503 it is today, with the Grid's own words.

• A node refused the session: any other SessionNotCreatedException. Its status depends on what the open sent (ruling 16):

  • 400 when the open sent raw keys (from capabilities) or a version. The message quotes the node's reason and names those keys or that version as the usual cause.
  • 503 when it sent neither. The message quotes the node's reason and says the node could not start the browser, so trying again may succeed.

  It is a new fault type, raised from the open. It carries whether the caller sent raw keys or a version, so errors.py can choose the status. Config capabilities do not count, because they are the operator's.

• The published contract. POST /browser already publishes 400 and 503; their descriptions in spec/ name the new causes.

Config

SessionSettings (config.py) gains two settings:

• capabilities: Annotated[dict[str, JsonValue], NoDecode], default {}. The env var SESSION_CAPABILITIES is JSON. An owned key is a ConfigError at load, naming the option.
• version: str | None.

FROM_CONFIG in workspace/settings.py gains version. The Settings tab shows both, since it renders every leaf. tests/test_config_load.py covers the JSON from the environment and the refusal of an owned key.

Admin API and UI

The per-workspace payload in http/admin/workspaces.py gains sent, ran, ended and asked_version (ruling 30). It already carries session_id, started and grid_timeout.

The UI is design/session.md, in four parts:

• The masthead. The summary card shrinks to the browser mark, the name, the last page and the existing pills, moved as they are. #83 renames the pills.
• The Session tab comes first, and a workspace opens on it (ruling 31).
• The two cards:
  • WORKSPACE has rows BROWSER as asked (firefox · 142, chrome · latest), WINDOW, RECORD (only when on) and CAPTURE (only while a browser is open).
  • GRID SESSION has rows BROWSER as it ran, ID, NODE, STARTED, IDLE TIMEOUT and LIVE VIEW (yes / no). On an idle workspace, ENDED takes LIVE VIEW's place. The card is not shown at all if no browser was ever opened.
• Capabilities is a section, collapsed by default.
  • Each row is a key, a value and a source pill: flow grey outline, config blue outline, option solid blue, raw solid ink.
  • A vendor block is summarised as args N · prefs N, with one pill for each source that fed it.

The ENDED wording (agent's call):

How it ended	ENDED reads
the admin's End	<local time> · ended by the admin
the caller's end_browser	<local time> · ended by the caller
the record still names a browser the Grid no longer lists	reaped after <grid_timeout> s idle, with no time, because nothing watched it
the same, with no idle timeout known	gone from the Grid

The skill

Agent's call:

• references/WORKSPACES.md gains Choosing the browser: the named options as one set, what is remembered, and version with latest.
• references/TROUBLESHOOTING.md gains three entries:
  • the raw capabilities escape hatch, as a last resort, with owned keys refused;
  • no node took this browser: the 503. Check the capabilities you sent, and look at the Grid console;
  • a node refused: the 400. A raw key is the usual cause.
• references/CONFIGURATION.md names SESSION_VERSION, SESSION_CAPABILITIES and ?version= / X-Version.
• SKILL.md gets one routing row.

It is written for a model deciding what to do next.

Out of scope

• The pools catalogue (ruling 2).
• CDP.
• Reading KEDA or Kubernetes from selenium-flow.
• The live view (#83).
• Headless (#86).
• A per-session browser log.
• Giving up on an open before the Grid does (ruling 12).

Tests and checks

Unit tests:

• every row of the builder's two tables, and rulings 23, 27, 28 and 29;
• settings.resolve for version and capabilities: the clear markers, and a browser switch dropping a remembered version;
• from_json on the three new fields;
• the error mapping, with the two queue strings and the Grid-side strings pinned, and a node refusal answered 400 with raw keys or a version sent and 503 with neither;
• config load: SESSION_CAPABILITIES as JSON, and an owned key refused;
• the open_session response shape.

These must pass unchanged in intent: tests/test_surfaces.py, test_request_schemas_are_the_tool_schemas, and tests/test_wiki.py once the pages are regenerated with scripts/generate_wiki.py.

No new integration flow (AGENTS.md: less is more). One existing flow changes its URL (ruling 31).

The checks:

• ruff check . and pytest;
• npm --prefix ui ci && npm --prefix ui run build, then test, check and lint.

One CHANGELOG line, for example: "open_session takes version and raw capabilities, and the admin UI's new Session tab shows what was sent and what the Grid gave." Ruling 23 adds a Fixed: line: "Firefox accepts a self-signed certificate only with insecure=true, like Chrome."

Open

Nothing is open. The last question, whether Firefox keeps accepting every certificate, was answered by Dr K on PR #87 (ruling 23): fix it, with insecure always sending acceptInsecureCerts.

Where the code is (checked on PR #87, 2026-10-26)

core/

• browser.py: Grid._options (lines 215–308), Grid.open (310), Grid.reconnect (323, calls _options() inert), Grid.sessions (422, reads version, node and vnc from /status).
• actions.py: open_session (220), and _set_up (308), whose applied (395) becomes settings.
• capabilities.py: the open_session row (208) and its response.

mcp/

• tools.py: open_session (357), an @own declaration whose docstring is prompt.

workspace/

• settings.py: SETTINGS (82), FROM_CONFIG (101), from_client, resolve (134).
• workspaces.py:
  • CLIENT_PARAMS / CLIENT_HEADERS (132), derived from SETTINGS;
  • describe (339);
  • resolved (485), which replays the settings after a reap through **replay, so actions.open_session must take every stored setting as a keyword;
  • open_browser (816), which makes its strict checks before end_browser (865) and does not inherit record or capture;
  • remember (957);
  • end_browser (1110), whose detached() is at 1155.
• store.py: Workspace (97) and from_json (168).

http/admin/

• workspaces.py: the per-workspace payload (501–560), and the admin End (662), which calls end_browser with Caller(key, "admin").

Elsewhere

• routes.py: opened (243) passes every SETTINGS key of the body, so the endpoint takes version and capabilities once they are settings.
• server.py: builds Grid, Actions and Workspaces (86–206).
• errors.py: UNAVAILABLE, which holds SessionNotCreatedException, and status_for.
• faults.py: the package's own exception types.
• flows/document.py: NOT_STEPS lists open_session, so flows are untouched.
• ui/src/lib/WorkspaceSummary.svelte (the masthead), ui/src/admin/WorkspaceDetail.svelte (the tabs, 311–345), ui/src/admin/router.svelte.ts (Tab, TABS, hashes), ui/src/admin/Section.svelte (opens by default), and the source pill styles scoped in ui/src/admin/SettingsPane.svelte (68–71).
• The monitor watches only the sessions it owes something (capture or a recording). A plain reap is learned at the next resolve, or from the admin list's /status join.