Repository navigation
workspaces and sessions
A caller names a workspace, and the server hands it the browser that name holds. The workspace lasts: a record, a flow library and files, under one name. The session is the live browser open in it, at most one, held on the Grid. Its settings are in session-settings.md, and the headers that carry them in surfaces.md.
- An agent names
?workspace=research-botin its MCP URL, callsopen_session, and after a reconnect or a week gets the same browser back at the same page. - An agent is away ten minutes and its browser waits. Away an hour, the next call reopens one where it was, and its result says the old one was replaced and why.
- An operator ends a browser from the admin UI, and the caller's next
open_session()carries on.
WS-1. A request names its workspace with the query parameter workspace or the header
Sf-Workspace. X-Workspace is an alias read as Sf-Workspace only when Sf-Workspace gives no
non-blank name, so when both are sent Sf-Workspace wins, even with a different value. Values are
trimmed and blanks dropped. named_by is header for either header. Caller.from_request reads
the request once, at the edge. Over stdio the name is stdio. Context.session_id is never a name.
WS-2. The alias counts as a header in every other rule. A header and the query parameter
together are refused with BOTH, and one place giving two distinct values is refused with "the
request names two workspaces: a, b". A refusal is raised when the name is first asked for
(Caller.name, Caller.library), so a call that needs no name runs, and listing tools and the
handshake still answer. A call that may run as a task is refused at submission (WS-5).
WS-3. A name matches names.NAME: letters, digits, dots, dashes and underscores, starting
with a letter or digit, 64 characters at most. Case is kept, so Desk and desk are two
workspaces. stdio and global are refused to a caller (RESERVED_WORKSPACES). A name is never
rewritten.
WS-4. An unnamed request is refused with UNNAMED, a 400, by anything that needs a
workspace. The flow library is the exception: an unnamed caller reads the shared global library,
which nobody may write (Caller.library). X-Session-Key and ?session= name nothing: alone they
leave the request unnamed, and beside a name they are ignored. A retired X- setting header is
refused in place of the name (SURF-10).
WS-5. A background task's worker is named only by the private header Carry wrote at
submission. See PROT-17 and PROT-18.
WS-6. No MCP tool or /browser endpoint takes or returns a Grid session id. The open's result
drops it, with what was sent and what ran (OPEN_PRIVATE). The admin API may show it.
WS-55. Nothing on the MCP surface lists workspaces. No tool or resource returns more than
the caller's own, and workspace://current is that shape. The admin's view of every workspace is
HTTP routes and the UI, never a tool or a resource: there is no grid://sessions resource and no
browser_sessions tool.
WS-56. A workspace name is an address, not a credential. A caller holding the token, or a valid JWT, who knows a name drives that workspace's browser. Sharing a browser is by name only.
WS-7. The store maps a name to one record (workspace.store.Workspace), never a browser.
A record holds session_id ("" when no session is open), opened_at, settings, set_by,
history, site_data, reopened, called_at, opened_by, grid_timeout, window_seen,
sent, ran and ended. Its page, url, is the top of history (site-data.md).
WS-8. The backend is memory or redis (workspace.store). Redis asked for and unreachable,
or its package missing, stops the boot (StoreUnavailable); it never falls back to memory.
WS-9. Every write sets the record's expiry to now plus workspace.ttl (default 86400 s).
A read never moves it. Memory treats a lapsed entry as absent and purges lapsed entries whenever
records() runs, and Redis expires them with EX. Nothing deletes a workspace: it expires, and
the next call that names it starts a new record.
WS-10. Every write is a compare-and-set against the record as it is at write time. Redis
retries under WATCH up to ten times, then raises StoreConflict. A Redis key is redis.prefix
(default selenium-flow:workspace:) plus the name. records() scans the prefix, reads with one
MGET and skips the pointer: keys.
WS-11. A stored record is read tolerantly (Workspace.from_json):
- anything but a JSON object is a miss;
- a field of the wrong type reads as empty:
grid_timeoutis read only as a positive int andcalled_atonly as a finite non-negative number that is not a bool; - a record whose
set_bydoes not name a known source for exactly its settings' keys keeps no settings and nosession_id.
WS-12. open_session (POST /browser) is the only place a browser is created. A call needing a
browser in a workspace with no session open raises faults.NoSession, a 400 telling the caller to
call open_session. A detached record reads the same as none.
WS-13. An open runs in this order:
- It is refused with
faults.Controlled(409) while a person holds the held browser (live-view-and-control.md). - Settings are resolved and checked (session-settings.md).
- An explicit
urlis checked byallowed_navigation. - The held browser is ended (WS-18).
- The new browser opens at
url, else at the remembered page unlessfresh. - The record is bound.
A rejected argument costs the held browser nothing. restore_site_data=false erases saved site
data in the bind, so a losing open erases nothing.
WS-14. The bind is one atomic create-or-update (Workspaces.remember). A record that already
names a browser other than the one this open replaced was bound by a concurrent open. That browser
is kept, this one is quit and announced ended, and its caller is answered with the kept one and
a note. A bind writes session_id, opened_at, settings, set_by, grid_timeout,
window_seen, sent and ran, clears ended and any held notice, and keeps the rest.
WS-15. grid_timeout, the node's idle timeout in whole seconds, is read at every open and
reopen by Grid.session_timeout (GRID-12, GRID-14) and stored. A failure reads as None, is
logged at info by type without the id, and never fails the open.
WS-16. Once bound, the session is announced session.opened. An open without capture
discards what the workspace captured (capture.md). The result is in SET-44.
WS-17. Workspaces.end_browser is the one place a browser is ended: the caller's end_browser
(DELETE /browser), the admin's End (DELETE /admin/workspaces/{key}/session) and an open
replacing a browser. It is refused while a person holds the browser, except the admin's End, which
releases control by ending the session.
WS-18. Workspaces.end_browser takes no turn. In order, it:
- sets the browser's ending flag (WS-40);
- sends
DELETE /session/{id}, a 404 counting as done; - detaches the record only if it still names that browser, writing
ended = {"at", "by": "caller" | "admin"}; - forgets the browser's origin and secret forms;
- announces
session.endedwith causeended, only when the quit was confirmed.
With no session open it does nothing. A detached record keeps its settings and sources, history,
site data, grid_timeout, window_seen, sent and ran, so the next open_session() carries
on. end_browser answers {"success": true, "workspace": <name>}. The admin's End answers
{"success": true, "key", "session_id"}, with session_id null when none was open.
WS-19. Every agent call resolves its browser through Workspaces.resolved: act (both
surfaces), the bound write (secrets.perform_write) and a flow run (flows/api.run_for). With a
session attached it asks Grid.is_alive, which reads any answer but invalid session id as alive
(GRID-10).
WS-20. A browser found gone is reopened in the same call:
- the stored settings are replayed with their sources (SET-17, SET-18), and a remembered capability key that has become owned is refused (SET-34);
- the browser opens at the remembered page, with saved site data restored;
- the old id is announced
ended(lost) and the new oneopenedwithreopenedtrue once bound; -
opened_byis kept, and a recorded reopen notes a new recording.
Two calls that find one browser gone leave one new browser, and both drive it (WS-14).
WS-21. The cause is judged before the reopen. The window is the longer
of grid_timeout (else 300 s) and session.keep_alive. The last activity is the later of
called_at and opened_at. Idle for the window or longer is reaped, sooner is lost. The log
line names the cause, and the bus still says lost.
WS-22. Every reopen holds a notice on the record, reopened = {"browser", "cause", "report"}, whether or not site data came back. Workspace.notice reads it only while the record
holds that browser, and one without a valid cause reads as reaped. The first successful result
from that browser carries "reopened": {"cause", "message"}, message being the fixed sentence
faults.REOPENED[cause], with site_data beside it when a report came back. The notice is then
cleared.
WS-23. A call that fails after a reopen carries the notice on its error, once, as
faults.reopen_note: the same sentence, then "Saved site data was put back for N site(s)." when N
is not zero. The order of notes on an error is ERR-16. A result that fails after its touch puts
the notice back, and its error carries it. Workspaces.failed never raises.
WS-24. A paste and a flow run's flush before a save step leave the notice held; a run says it on
its own result or error. await_control's hand-back carries reopened. open_session never
carries it, and an explicit open drops a held notice (WS-14).
WS-25. Workspaces.settle is the one record write after an action. It records the page (the
result's URL, the pages a run reached, or none when the URL is withheld), stamps called_at, and
slides the TTL whether or not a page is recorded. When the record names another browser than the one
that produced the result, it only stamps called_at. A flow step does not touch; the run does, with
every page it reached. A failed call stamps called_at too. resize stores the new width and
height in the settings as the caller's, so a reopen replays them (Workspaces.reshape).
WS-26. One monitor.Monitor and one monitor.LocalBus live in the process. The bus carries
three kinds (monitor.events.EVENTS), and every field is a str, int, float, bool or
None:
| Kind | Fields |
|---|---|
session.opened |
workspace, session_id, browser, grid_timeout, reopened, at
|
session.ended |
workspace, session_id, cause, at
|
call.finished |
workspace, session_id, browser, tool, surface, outcome, started, duration
|
WS-27. session.ended has three causes: ended (this server quit it and the Grid confirmed),
gone (the listing stopped showing it, WS-32) and lost (a call found it gone, WS-20). It is
published at most once per session_id, remembered for the last 4,096 ids.
WS-28. session.opened is published for every open and reopen, after the bind, for the browser
the workspace kept. call.finished is published once per call by Calls.end, outcome being ok,
4xx or 5xx by the error's status. Nothing subscribes to it.
WS-29. Publishing never blocks. From a worker thread an event is handed to the loop. On the
loop the handler runs after publish returns. Before start an event is delivered inline, and
after stop it is dropped. Each subscriber has a queue of 1,000, and an event that does not fit
is dropped, counted and logged once a streak. A handler that raises is logged by type once a
streak, and the others still hear. subscribe refuses an unknown kind. session.ended is heard
by the recordings collector, the live view's tunnels, the secret scrub (Workspaces.browser_ended)
and the admin page. session.opened is heard by the admin page.
WS-30. A session is watched while something is owed on it: recording, capture, control or
keepalive. A watch for an id already ended is ignored. A watch owing nothing is dropped and its
connection closed. Workspaces without a monitor announces nothing, and a monitor that raises never
fails a call (calls.told).
WS-31. The monitor's task runs only while a watch exists. Each look takes one GET /status
(Grid.listing, GRID-12) in a worker thread, shared by every watch, and refreshes each listed
watch's timeout. The next look is 30 s later, sooner for the nearest connection deadline, hold
retry or ping due, and at once on a touch or a dropped connection.
WS-32. A watched session is gone when either of these holds:
- two listings in a row, both taken after the watch began, each show a node and do not list it;
- one such listing, taken after its connection dropped.
A failed listing says nothing. A listing with no nodes says nothing until such listings have run unbroken for the watch's timeout (else 300 s) plus a tick, counted from the later of the run's first listing and the watch's start. After that each is a miss.
WS-33. A connection is held only for a reason that names BiDi events (capture, control), and
closed at the watch's deadline, its last touch plus its timeout, unless a call is in flight.
calling and called (from Calls.begin and Calls.end), an attach and Monitor.touch are
touches. What a connection carries is in capture.md and
live-view-and-control.md. Nothing in monitor/, workspace/calls.py or
Workspaces logs a Grid session id; a failure is logged by type. monitor/ imports no protocol
library and no Selenium, and gets the Grid as callables (tests/test_boundaries.py).
WS-34. The lifespan starts control, the bus, the monitor and the collector, and stops control, the collector, the tunnels, the monitor (closing every connection), the bus and the scrubber.
WS-35. session.keep_alive is how long a browser is kept alive after its last activity: 900 s
by default, 0 to 3600, 0 for off (config.md). It is never an open's default.
WS-36. With it on, the monitor owes keepalive on every session at its open and reopen
(Monitor.opened) and at the start of every call (Calls.begin), so a session opened before a
restart is kept from its next call. keepalive has no events, collector or sink and never holds a
connection; the monitor refuses to be built with any of them for it.
WS-37. A kept session is pinged with Grid.ping (GRID-11) once
max(touched, pinged) + ping_interval(timeout) has passed. For a node timeout t the interval is
max(60, min(0.8 t, t - 60)), and 240 s when the node did not say. No ping is sent past the window
(now - touched >= keep_alive), while a call on the session is in flight, or after a ping found it
gone. Pings run one at a time, inside a look.
WS-38. A ping is not a touch: it moves neither the window nor a connection's deadline. A ping
answering gone stops that watch's pings and nothing else, and only the listing announces gone. A
ping that fails is logged by type and tried at the next interval. The watch outlives the window: it
sends nothing and goes on listing until the Grid lists the session gone or it ends. A touch after
the window starts the pings again. A person in the live view touches the session
(live-view-and-control.md).
WS-57. The server runs no cleanup loop. The Grid expires an idle browser once the keep-alive stops pinging it, and the store expires a record by its TTL. The only background tasks are waits that end when nothing is owed: the admin broadcast while a page listens, the recordings collector while a recording is owed, the session monitor while a session is watched, and a Control grant's poll while a request waits.
WS-39. A call that drives a browser holds that browser's turn (locks.driving, keyed by
Grid id) from before Calls.begin to after its result is scrubbed, and a second call on it waits,
with no timeout of its own. The holders are act, the bound write, each flow step, a paste and
await_control's read. Recipe.run takes the turn again in the same thread. The turn is
reentrant and fair (each wait takes a ticket), lives only while held, waited for or under a flow
run, and is process-local.
WS-40. open_session, end_browser and reads of the record take no turn. end_browser sets
the hold's ending flag: a running assert raises cancel.Ended at its next poll, a driver failure
under an ending is answered as the ending, and a call queued before the end raises it at its turn
without touching the browser. Ended is a 404. locks.behind marks a queue without holding a
thread (live-view-and-control.md).
WS-58. A waiting call holds one of the 40 worker threads that FastMCP's sync tools and
Starlette's routes share (anyio's default limiter), and it does not notice its client giving up.
About 40 calls queued on one session stall every other workspace, end_browser and /ready. The
limit is not raised.
WS-41. core.browser.Grid is the Grid client. Its pools, retry and timeouts are GRID-4,
GRID-6 and GRID-14.
WS-42. Grid.quit is DELETE /session/{id}, a 404 being success. Grid.listing is GRID-12.
Grid.bidi_url and Grid.vnc_url are derived from grid.url, never from the session's
capabilities (GRID-5).
WS-43. workspace://current (GET /browser) answers workspace, named_by, principal,
browser, url, live, recording, capture, capturing, in_frame, window,
grid_timeout, version, store and settings, and flows_here, captured, site_data and
guidance when they apply. A workspace with no record answers live false and empty values.
- It is scrubbed as a resource is (secrets-and-scope.md).
- Reading it never opens a browser.
-
liveasksGrid.is_alivewhen a session is attached. - While live,
in_frameandwindoware read from the browser. A failure there leavesin_framenull andwindowas stored. -
grid_timeout,versionandwindowoutlive the session.
WS-44. A URI's scheme says how long its data lasts. workspace:// is the workspace's:
current, site-data, files and its folders, console and network. session:// is the
session's and serves session://downloads and session://downloads/{name} only
(workspace-files.md). A session:// read with no session open is refused with
faults.NoSession, "no session is open in this workspace; a download lives only as long as the
browser that took it", never answered empty.
WS-45. A moved URI is refused with its new spelling by names.retired_uri, in show,
read_resource, keep_file and upload_file, so a saved flow names its own fix; saved flows are
never rewritten. names.MOVED is tried in order, and the first prefix matching the URI, or the URI
followed by / or ?, answers:
| Given | Answer |
|---|---|
workspace://files/downloads[/…] |
is now session://downloads[/…]
|
session://files/downloads[/…] |
is now session://downloads[/…]
|
session://downloads[/…] |
served |
any other session://x
|
is now workspace://x
|
WS-46. The old session names are refused at boot. SESSION_STORE or SESSION_TTL set
non-blank in the environment stops it, naming WORKSPACE_STORE and WORKSPACE_TTL, and
session.store or session.ttl in the config file stops it with config.RETIRED_SESSION_KEYS.
Before anything reads the data directory, DATA_DIR/sessions/ is renamed to
DATA_DIR/workspaces/ when only the first exists. Both present, or a rename that fails, stops the
boot. A sessions folder in the flat layout (flows, files or screenshots directly in it) is a
workspace and is left alone.
Not built. The reasoning, and the questions still open, are in the multiplayer design.
WS-47. (proposed) A workspace holds several sessions at once, and an agent that joins a
workspace gets its own session. What a workspace is, how it is named (WS-1 to WS-4) and the
global library do not change. Replaces, when built, the glossary's "at most one at a time" and
the intro's "at most one".
WS-48. (proposed) A session has a name, given when it starts. open_session answers with it.
WS-49. (proposed) A call that names no session is about the workspace's default session, the
first one opened in it. There is no main session. When nobody named the first session, it takes
a generated name, such as swift-otter.
WS-50. (proposed) A session's name reaches a call one of two ways:
- pinned from outside: a header or a query parameter on the connection names the session, and no call on that connection reaches another session;
- loose: with nothing pinned, the caller names the session on the call, as the
sessionargument.
A pinned name wins over the argument, and the argument over the default (WS-49). Which header and
parameter, and what a call whose argument differs from the pinned name is told, are open. If the
parameter is ?session=, this replaces WS-4's "X-Session-Key and ?session= name nothing" for
?session=.
WS-51. (proposed) A session is a lane of windows in the workspace's one Grid browser. It starts as one window, and windows and popups its pages open join it. A window holds tabs. Sessions share that browser, and each has its own cookies and storage (WS-52). A session gets a Grid browser of its own only as an escalation. Opening a session while another is open adds a lane and ends nothing, which replaces, when built, WS-13's step that ends the held browser when the open is for a new session.
WS-52. (proposed) Each session has its own BiDi user context, so its cookies and storage are its own and it signs in on its own. One session can sign out, or sign in as another user, while another stays signed in. Callers that want to share a sign-in name the same session (WS-60).
WS-53. (proposed) Two agents in one session each get a window of it. Tabs are for one agent moving between its own pages, because a tab that is not showing does not render.
WS-54. (proposed) A workspace's files and flows are the workspace's, shared by every session in it. Site data goes with the session (WS-60). Whether History is the workspace's or each session's is open.
WS-59. (proposed) A caller that names no session gets the session named after its token's
sub. A caller with no sub gets the default session (WS-49). A sub is never tied to a session:
callers with the same credentials tell themselves apart by naming their sessions.
WS-60. (proposed) A session's cookies and saved site data go with the session, whoever calls.
Two callers that name the same session share it, whatever their sub. save_site_data saves
under the session, and a session that is reopened gets its own site data back. Replaces, when
built, the site-data area's "a workspace's record has ... site_data" (SITE-2) with one per
session. Whether a new session starts empty or is seeded from another's saved data is open.
Not built. The reasoning, and the questions still open, are in the workspace config design.
WS-61. (proposed) A workspace can have a config: one YAML or JSON file in the root of its folder. Its name and what it may hold are open. It never holds a secret's value.
WS-62. (proposed) The workspace's config is read and written while the server runs. The server's own config stays as it was read at start (config.md).
WS-63. (proposed) A workspace that has saved a config is kept, where a workspace without one expires as today. Replaces, when built, WS-9's "Nothing deletes a workspace: it expires" for a workspace with a config. What is kept is open.
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