Skip to content

Specification

Dr K edited this page Nov 14, 2026 · 3 revisions

The selenium-flow spec

What the server does, one area per file. Each requirement is numbered, says one thing, and is true of the code unless it is tagged (proposed). An agent that reads every file here can rebuild the server: the requirements and use cases are in the area files, and the glossary and architecture are below.

The spec holds the present only. Why a requirement is the way it is, and what it replaced, is in the dated designs and plans in plans/, each of which opens with a History header naming the requirement ids that hold it now. How to use a feature, in plain English, is on the wiki's hand-written pages, which link here for the rules. Setting up the repo, running the tests and shipping are in CONTRIBUTING.md.

Areas

Area IDs Covers
Workspaces and sessions WS Naming a workspace, the record and its store, opening and ending a browser, reaps and reopens, the session monitor, the keep-alive, one call at a time, workspace:// and session://
Session settings SET open_session's options, where each value comes from, what a workspace remembers, raw capabilities, headless
Auth and roles AUTH The server token, OIDC on /mcp, the admin UI's sign-in, principals, signed links
Surfaces SURF The capability table, request headers, MCP tools and resources, the HTTP routes and OpenAPI document, show
Live view and control LIVE Watching a browser over VNC, a person taking control, refusals, await_control
Browser actions ACT What each action does: the recipe, selectors and waits, clicks and what received them, the pointer, keys, url=
Saved flows FLOW The flow document, parameters, running one, sites and paths, flows_here
Secrets and scope SEC The catalogue, the leash, binding a secret to a field, the scrub of every result and resource
Site data SITE Saving and restoring cookies and storage, the history, the spare tab
Capture CAP Console and network capture over BiDi, masking, the capture resources, a call's hint
Workspace files FILE Downloads, screenshots, prints, kept files, recordings, file addresses and links
Admin UI UI The admin page and its API, the tabs, the event stream, the MCP App shell
Config CFG Every setting, its three spellings, precedence, validation, the Settings tab
Plugin PLG The plugin/ folder: the embedded skill, the Skills extension, prompts, agents and the agents extension
Protocol PROT The two generations of MCP, the FastMCP stack, tasks, tool annotations, the instructions, the MCP App
Errors and logging ERR What each failure means, its status and wording, what is logged at which level and what never is
Grid GRID The contract with Selenium Grid: endpoints, socket addresses, binding to a session, timeouts, failures, the reaper, what is assumed
Runtime RUN Startup and shutdown, the probes, what survives a restart, the concurrency map, data on disk and in Redis, packaging, every limit, Chrome and Firefox

Work not built yet is in a ## Proposed: section at the end of an area file: several sessions in a workspace in WS, SURF, ACT, LIVE, FLOW, CAP and UI, and ownership and roles in AUTH and SURF.

An area file avoids the names of the wiki's top-level pages. A GitHub wiki addresses a page by its basename, ignoring case and folder, so specs/secrets.md would answer to the same address as Secrets.md.

Ids

  • An id is the area's prefix and a number: WS-12. Numbers count up within an area and are never reused. A removed requirement leaves a gap.
  • A requirement that is not built yet is written like the others and tagged (proposed). The tag comes off in the pull request that builds it. A proposed requirement that replaces a built one names it.
  • A behaviour change edits its area file in the same pull request.
  • Each rule has one owner, the area whose subject it is. Another area that needs it links the id instead of restating it, and a requirement reduced to a pointer keeps its id.
  • Requirements cite each other by id, and code by symbol name (Workspaces.act), never by line number.
  • Statements only: present tense, no dates, issue numbers or history. The repository is public, so no hostnames or personal names. The maintainer is Dr K, and examples use example.com.

Glossary

Each word below means one thing, here and in the code. The area named at a term owns its rules.

  • Workspace. The box a caller names, with ?workspace= or the Sf-Workspace header. It holds flows, files, site data, history, capture and the settings it opens browsers with. It is never deleted: it expires workspace.ttl seconds after its last use (workspaces-and-sessions.md).
  • Session. The live browser open in a workspace, at most one at a time, started by open_session and ended by end_browser, the admin's End or the Grid's reaper. It is the Grid's WebDriver session, whose id is session_id. An idle workspace has no session. Where the Grid's own session or the MCP transport session is meant, the text says so.
  • Record. What the store keeps per workspace: the session_id when a browser is open, the browser asked for, the settings a caller passed and the page it was on. It never holds a browser (WS-7).
  • Grid, node. Selenium Grid owns every browser. A node runs browsers, films them and serves their VNC (grid.md).
  • Caller. One request's who and which: the workspace name (read once, at the edge, from ?workspace= or Sf-Workspace, or stdio), how it was named, and the principal, if any. Two callers with one principal can name two workspaces.
  • Principal, door. A principal is who a verified credential says the caller is: admin (the server token) or oidc (a JWT from the configured issuer). A door decides which credentials a route accepts (auth-and-roles.md).
  • Admin, operator. Admin is an access: the principal admin, or an admin-UI sign-in holding one of oidc.admin_roles. An admin sees every workspace. The operator is the person who deploys and configures the server, its Grid and the transport that delivers recordings. The operator is a role in prose and never a credential, and the two words are not interchangeable.
  • Surface. How a call reaches an action: mcp (a tool on /mcp), http (a route, mostly under /browser) or flow (a step of a running flow) (surfaces.md).
  • Capability. A row of core/capabilities.py: one browser action with its tool name, route, annotations and response schema. Every action is a tool and an endpoint from one row. It is unrelated to WebDriver capabilities, the capabilities object open_session sends to the Grid.
  • Action, recipe. An action is a method of core.actions.Actions. The recipe (core.recipe.Recipe.run) is the road every action takes: check the arguments, reattach to the browser, go to url if one was named, wait for the element, act, report the page (browser-actions.md).
  • Selector. How an action names an element: {"xpath": ...} or {"css": ...}, one of the two.
  • Flow, library. A flow is a saved YAML document of steps, each a tool call, plus the parameters a run takes. run_flow runs every step server-side in one call. A workspace's library is the flows/ folder of its directory. The shared global library is read by every workspace and written only by the admin (saved-flows.md).
  • Place, flows_here. A flow's sites and paths say where it applies. When a call leaves the browser on a page, its result's flows_here names the flows that apply there.
  • Site data, history. Site data is the cookies, localStorage and sessionStorage a workspace keeps for the sites it used, saved by save_site_data and restored before a new browser's first page. History is the pages its browsers reached, kept with it (site-data.md).
  • Secret, leash, scrub, marker. A secret is a directory of files, one per key, or an entry in the config file. Its leash, allowed_urls, is the origins it may be typed on. An agent types one with write(secret={"name": ..., "key": ...}) and never sees a value. The scrub checks every result, error and resource for the values in scope and replaces a find with the marker [secret:<name>/<key>] (secrets-and-scope.md).
  • Capture. The console and network traffic of a browser opened with capture=true, masked and kept per workspace for capture.ttl seconds (capture.md).
  • Recording. The video of a browser opened with record=true. The Grid films it, the operator's transport drops the file in the inbox (recording.dir), and the collector files it into the workspace.
  • Files. Lowercase files is a workspace's whole set, in four sections: Downloads (the browser's, on the Grid), Screenshots, Recordings and Files. Capitalised, Files is the one section for what was kept on purpose with keep_file or print. workspace://files lists that section with the counts of the two folders and never Downloads (FILE-28). A signed link opens one file without a header (workspace-files.md).
  • Live view, control. The live view is the admin UI's Live tab: the browser's screen over the node's VNC, proxied by this server and drawn with noVNC. Control is a person in the live view taking the browser: requested, granted once the calls ahead have finished, then handed back. While it is held, calls that would change the browser are refused, and await_control waits for the hand-back (live-view-and-control.md).
  • Skill, prompt, agent. What plugin/ ships and the server serves: the skill at skill://selenium-flow/SKILL.md, prompts a person picks, and agent definitions through the agents extension (plugin.md).
  • MCP App, show. show(uri) draws one resource inside a client that can show UI, using the app shell built from ui/ (protocol.md).
  • Mirror. list_resources and read_resource, two tools that read resources for a client that cannot.
  • Reap, reopen. The Grid ends a browser idle for its node's session timeout. The next call reopens one with the stored settings at the last page, restores site data, and says so in the result's reopened (WS-19 to WS-22).
  • Keep-alive. The monitor pings a browser for session.keep_alive seconds after its last call, so a pause between calls does not lose it (WS-35 to WS-38).
  • Monitor, bus, watch, reason. The session monitor announces session.opened and session.ended on an in-process bus. A watch is its record of one session it owes something on, and a reason is one thing owed: recording, capture, control or keepalive. A reason that names BiDi events holds a connection, and the others never do (WS-26 to WS-33).
  • Turn, hold. A turn is the right to drive one browser, one call at a time per session (WS-39). Hold has three uses and is never bare: a turn is held by the call driving a browser, a BiDi connection is held for a reason, and control is held by a person.
  • Notice, note, hint. Three kinds of sentence beside an answer. A notice is about the workspace and said once: the reopen notice, carried as reopened (WS-22), and the control notice on MCP results while a person holds the browser or has just handed it back. A note is added to a failure's text after its first line, in a fixed order (ERR-16); an open's result also has a note field when a concurrent open bound first (WS-14). A hint says where to look next and is never the action's answer: the page hint of capture, the entries of flows_here, a failed run's hint, and the hint of a page state while a dialog blocks the page.

Architecture

One Python package, kubed/selenium_flow, served by FastMCP over stdio or HTTP. It holds no browser: each browser lives on the Grid, and a workspace's name leads back to it. It runs as one replica, because the MCP transport session lives in its memory, as do each browser's turn, the monitor's watches and bus, capture buffers, live-view tunnels, control episodes and background tasks. A second replica would let two calls drive one browser and would watch nothing the first opened. runtime.md has the startup order, the probes, shutdown and what survives a restart (RUN-2 to RUN-11), what runs on the event loop and what on worker threads (RUN-12 to RUN-15), and where every piece of data lives (RUN-16 to RUN-19). grid.md has everything the server says to the Grid.

Package Responsible for
server.py, main.py, config.py Loading the settings and wiring every part below into one FastMCP app
core/ The browser actions (actions.py), the recipe, the Grid client (browser.py), the capability table, element probes, the pointer, keys and the page JavaScript in js/
workspace/ Which browser a caller means (workspaces.py), the record store, session settings, the per-session turn, the call bracket (calls.py), the current origin and the secret scrub
mcp/ The MCP surface: tools, resources, the mirror, prompts, the skill and its extension, agents, show, completions, progress and long waits, and the middleware for failures, control notices and scrubbed resources
http/ The HTTP surface's shared parts: auth and doors, the one request answer, files and signed links; http/admin/ is the admin UI's page and API
routes.py, spec/ The HTTP routes for every capability and the OpenAPI document built from the same table
flows/ Flow documents, their store (which also holds the workspace's files), places, parameters, the run and its step loop, and the run's redaction
monitor/ The session monitor and its event bus
bidi/ The one WebDriver BiDi client: a connection per browser on an event loop, and the channel threads drive it through
capture/ Capture's buffers, masking, Chrome's replay alignment and the views readers get
site_data/ The site data snapshot, its BiDi transfer and the spare tab
live/ The VNC tunnels, the RFB gate, control, the pages a person reaches, and the audit line
recordings/ The collector that files each finished video from the inbox
secrets.py, binding.py, redaction.py The secret catalogue, the rule for binding a secret to a field, and every spelling of a value with the scanner that finds it
names.py, urls.py, errors.py, faults.py, principal.py Naming rules, URL and origin rules, what a failure means as a status, the package's own exceptions and messages, and the principal

bidi/, capture/, live/, recordings/ and redaction.py import no Selenium and no protocol layer; tests/test_boundaries.py holds each layer to its imports.

How a tool call travels

  1. A client sends tools/call to /mcp. The /mcp door (http/auth.py) has already accepted the token or a JWT and attached the principal.
  2. Middleware wraps the call, outermost first. It carries the caller's workspace to a background task's worker, adds the control notice while a person has the browser, and turns an exception into the one line a caller reads and the line the log writes. A resource read is scrubbed inside that last wrapper. Other middleware shapes what a client is shown at listing and handshake (surfaces.md, protocol.md).
  3. The tool's declaration (mcp/tools.py) gives its schema and description, and its body comes from its capability row. It calls Workspaces.act with the caller. A write with a secret takes the bound write (secrets.perform_write), which follows the same steps from here.
  4. Workspaces.act resolves the record to a live Grid session, reopening a browser the Grid ended (WS-19 to WS-22).
  5. It takes the browser's turn, notes the origin the call is about to reach, and begins the call. Beginning refuses it with a 409 while a person holds the browser, and asks the monitor to keep the session alive.
  6. The capability's action runs the recipe against the Grid (core/browser.py).
  7. The call ends: the monitor is told, call.finished is published and, with capture on, the result gets its page hint. The scrubber then replaces any secret value in scope with its marker.
  8. Back in Workspaces.act, the record is touched with the page reached, flows_here and reopened are added, and site data is saved when the call asked for it. The result returns through the middleware to the client.

An HTTP call takes the same road from step 3: routes.py mounts the same row, http/answer.py reads the body and maps a failure to its status (errors.status_for), and Workspaces.act runs with surface="http". A flow step runs inside run_flow's own call, through flows/engine.py, with surface="flow".

Clone this wiki locally