Skip to content

workspaces and sessions

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

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.

Use cases

  • An agent names ?workspace=research-bot in its MCP URL, calls open_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.

Naming a workspace

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.

The record and its store

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_timeout is read only as a positive int and called_at only as a finite non-negative number that is not a bool;
  • a record whose set_by does not name a known source for exactly its settings' keys keeps no settings and no session_id.

Opening a session

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:

  1. It is refused with faults.Controlled (409) while a person holds the held browser (live-view-and-control.md).
  2. Settings are resolved and checked (session-settings.md).
  3. An explicit url is checked by allowed_navigation.
  4. The held browser is ended (WS-18).
  5. The new browser opens at url, else at the remembered page unless fresh.
  6. 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.

Ending a session

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:

  1. sets the browser's ending flag (WS-40);
  2. sends DELETE /session/{id}, a 404 counting as done;
  3. detaches the record only if it still names that browser, writing ended = {"at", "by": "caller" | "admin"};
  4. forgets the browser's origin and secret forms;
  5. announces session.ended with cause ended, 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.

Reaps and reopens

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 one opened with reopened true once bound;
  • opened_by is 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).

After a call

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).

The session monitor and its bus

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.

The keep-alive

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.

One call at a time

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.

The Grid client

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).

workspace://current

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.
  • live asks Grid.is_alive when a session is attached.
  • While live, in_frame and window are read from the browser. A failure there leaves in_frame null and window as stored.
  • grid_timeout, version and window outlive the session.

The two schemes

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

Retired names

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.

Proposed: several sessions in a workspace

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 session argument.

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.

Proposed: a config for each workspace

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.

Clone this wiki locally