Repository navigation
2026 11 19 sub sessions
History. Drafted 2026-11-19 for #94 from the multiplayer design, rulings 21 to 38 and "After the review", after a builder check of the design. Built in nine tasks (2026-11-19), each reviewed, then a whole-branch review and one fix wave. Built beyond the text:
session_oftakesopening, and a read-onlyreadingresolves resources and the context; six names are reserved (current,downloads,console,network,files,site-data); a dead sub-session's page loses its query aftersession.sub_ttl; log lines name a sub-session only as "a sub-session" (sessions.logged); a listing asks the Grid once and prunes dead names fromsubs; other sessions' pages are listed without their query; admin History has a row per host and session. The Penpot Library holds the split tab bar and the workspace-only card; the Sub-sessions file keeps local copies.
For agentic workers: REQUIRED SUB-SKILL: Use skill://superpowers/subagent-driven-development/SKILL.md (recommended) or skill://superpowers/executing-plans/SKILL.md to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: A workspace keeps its one default session as today, and any call may name or pin a sub-session: its own Grid browser, settings, sign-ins, capture and live view, beside the workspace's shared files, flows, config and history.
Architecture: A session is addressed by a session key: the workspace's name for the default
session, <workspace>/<name> for a sub-session. The store already keys records by string, so
every per-browser path in Workspaces (open, act, end, settings, site data, capture, live,
monitor) runs unchanged on a session key; what the whole workspace shares (history, files, flows,
config, the flow library) is read through the key's workspace part. One function,
Workspaces.session_of(caller, named), turns a call into a session key (WS-49), and is the only
place that knows the rules. Placement (one Grid browser per session) stays where opening is
today, behind that key.
Tech Stack: Python 3.11+, FastMCP, Starlette, Redis (workspace/store.py), Selenium 4
through core/, Svelte 5 + Vitest (ui/), Penpot through the MCP, pytest, ruff.
Spec: the multiplayer design; WS-47 to WS-54, WS-59, WS-60, WS-72 to WS-75, WS-77, WS-78 in workspaces-and-sessions.md, SURF-45 and SURF-46 in surfaces.md, ACT-43 and ACT-44 in browser-actions.md, LIVE-42 in live-view-and-control.md, FLOW-50 and FLOW-51 in saved-flows.md, CAP-81 in capture.md, UI-64, UI-65 and UI-78 in admin-ui.md. Drawn in Penpot: Kubed › Selenium Flow › Sub-sessions.
- Python 3.11+:
from __future__ import annotationsin every new module;ruff check .clean. - Tests:
pytest -q tests/<file>.pyfor the task, thenpytest -qbefore each commit; the UI withnpm testinui/. The integration suite needsGRID_URLandADMIN_ORIGINand runs in CI. - Commits: stage exact paths, never
git commit -a. Every message ends withCo-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>. -
docs/is the wiki's own repository, on its branchfeat/sub-sessions. A task that editsdocs/commits there first (never onmaster), then commits thedocspointer in the same task. - A requirement's (proposed) tag comes off in the task that builds it; what it replaces (named in the row, "Replaces, when built") is rewritten in the same task. Spec text is statements only.
- No personal names, emails or hostnames anywhere. Examples use
example.com, testsexample.test. - A golden is regenerated only for a meant contract change, in a commit of its own:
GOLDEN_UPDATE=1 pytest -q tests/test_golden.py, then read the diff. - Generated wiki pages come from
python scripts/generate_wiki.py, never by hand. - A caller that never names a session behaves exactly as today: every existing test passes unchanged, except those for rows this plan replaces.
- Layers hold (
tests/test_boundaries.py). Statuses come fromerrors.status_foralone. No log line carries a Grid id, a URL, a title or a subject; log failures bytype(exc).__name__. - Use the shared doubles in
tests/fakes.pyandtests/conftest.py; extend them, never copy them. - Never edit
.github/. - Values: the default session is
default(sessions.DEFAULT).current,downloads,console,network,filesandsite-datacannot name a session (sessions.RESERVED). A sub-session's key is<workspace>/<name>(sessions.SEP = "/"). The pin is theSf-Sessionheader or the?session=parameter. A sub-session's record livessession.sub_ttlseconds after its last use (default 3600, configsession.sub_ttl, envSESSION_SUB_TTL). The default's owner is the record fieldowner(a subject, or null). Chips past five go in a+Nmenu. - Out of scope: several sessions in one browser, the hook that names a subagent's session, roles (#66), the BiDi transport (#177).
-
Secrets typed or echoed across sessions. Origins, the current frame and the turn must be the
session's, or a secret leashed to tester's site is typed from the default's page. Pinned by
test_a_secret_is_scoped_by_its_own_sessions_origin(Task 3). -
A workspace in use today strands its owner in an empty sub-session. claudecode's record has
no
owner; the first subject back must claim it, not be sent away. Pinned bytest_an_unowned_default_is_claimed_by_the_first_subjectandtest_a_caller_with_no_subject_never_claims_the_default(Task 2). -
A sub-session taken for a workspace. The admin's list, the monitor's owner lookup and the
live tunnels iterate records. Pinned by
test_workspaces_lists_no_sub_sessionandtest_owners_maps_a_sub_sessions_browser_to_its_key(Task 1). -
History lost between sessions. Sub-sessions append to the workspace's record with its
compare-and-set; a write must neither go to the hour-long record nor drop a neighbour's entry.
Pinned by
test_two_sessions_append_history_without_losing_an_entry(Task 4). -
A name that starts browsers, or a turn shared across sessions. A typo must open nothing, and
two sessions must act at once. Pinned by
test_a_call_naming_an_unknown_session_is_refused_and_opens_nothing(Task 2) andtest_two_sessions_act_at_once(Task 3).
| File | Responsibility |
|---|---|
kubed/selenium_flow/workspace/sessions.py (new) |
Session keys: DEFAULT, RESERVED, SEP, key_of, split, is_sub, valid_session_name
|
kubed/selenium_flow/workspace/store.py |
Workspace.owner, Workspace.subs; per-key TTL; records and owners by kind; forget_workspace
|
kubed/selenium_flow/config.py |
SessionSettings.sub_ttl |
kubed/selenium_flow/workspace/workspaces.py |
Caller.pinned, session_of, owner claim, others, history on the workspace record |
kubed/selenium_flow/mcp/clients.py, spec/builder.py, mcp/tools.py, routes.py, server.py
|
The pin, and session on every acting tool and route |
kubed/selenium_flow/mcp/resources.py, mcp/show.py
|
sessions in the context; session://{name} templates |
kubed/selenium_flow/flows/api.py, flows/document.py
|
run_flow(session=); save_flow refuses a step's session
|
kubed/selenium_flow/live/control.py |
Control keyed by session key |
kubed/selenium_flow/http/admin/*.py |
Workspaces only in the list, with sessions; ?session= on session routes; End all |
ui/src/admin/*, ui/src/App.svelte
|
Split bar, chips, accent edge, End name, End all, History filter, downloads by session; the MCP App names its session |
tests/test_sessions.py, tests/test_sub_sessions.py (new) |
Keys and store; resolution and acting |
Files: Create workspace/sessions.py, tests/test_sessions.py. Modify workspace/store.py,
config.py, docs/superpowers/specs/workspaces-and-sessions.md (WS-60's TTL, WS-77).
Interfaces — Produces:
-
sessions.key_of(workspace: str, name: str) -> str—workspaceforDEFAULT, elsef"{workspace}/{name}". -
sessions.split(key: str) -> tuple[str, str]—(workspace, name);("shop", "default")for"shop". -
sessions.is_sub(key: str) -> bool. -
sessions.valid_session_name(name: str) -> str—names.NAME, refusingRESERVEDwith aValueError. -
Workspace.owner: str | None = None,Workspace.subs: list[str](sub-session names, kept on the workspace's record). -
Store:
set/upsert/updateon a sub key expire aftersub_ttl, on a workspace key as today (also in a kept workspace).records()answers workspace keys only;sub_records(workspace) -> dict[str, Workspace];owners()maps every attached browser to its session key, subs included;forget_workspace(workspace)deletes the record and every sub key. -
Step 1: Write the failing tests in
tests/test_sessions.py:test_a_default_session_key_is_the_workspace_name(key_of("shop", "default") == "shop"),test_a_sub_session_key_holds_both_names(key_of("shop", "tester") == "shop/tester",splitinverts it),test_reserved_names_are_refused(current,downloads,a/braiseValueError),test_a_sub_record_expires_after_sub_ttl(MemoryStore withsub_ttl=3600: present at 3599 s, gone at 3601 s; the workspace record still there),test_a_kept_workspaces_sub_sessions_still_expire,test_workspaces_lists_no_sub_session,test_owners_maps_a_sub_sessions_browser_to_its_key,test_forgetting_a_workspace_forgets_its_sub_sessions, the same three forRedisStoreonFakeRedis. -
Step 2: Run
pytest -q tests/test_sessions.py— FAIL (no module). -
Step 3: Implement
sessions.py; the per-key TTL in both stores' expiry (_ex,_deadline); the record fields (round-trip throughto_json/from_json, absent in old records);SessionSettings.sub_ttl: int = 3600(positive). -
Step 4: Run the task's tests, then
pytest -q— PASS. -
Step 5: WS-77 and WS-60's TTL lose (proposed) (WS-60 keeps it until Task 2 builds
NoSession); commit.
Files: Modify workspace/workspaces.py (Caller, Workspaces), mcp/clients.py,
faults.py if NoSession needs a session name, principal.py (nothing consulted beyond
subject). Create tests/test_sub_sessions.py. Spec: WS-48, WS-49, WS-50, WS-78, SURF-45.
Interfaces:
-
Consumes: Task 1's
sessionsand store. -
Produces:
Caller.pinned: str(fromSf-Sessionor?session=; both, or two values, refused as two workspace names are);Workspaces.session_of(caller: Caller, named: str | None = None) -> str(a session key);Workspaces.claim(key: str, principal: Principal | None) -> None(writesowneronce). -
Step 1: Write the failing tests:
test_no_name_reaches_the_default(session_of(caller) == "shop"),test_a_name_reaches_its_sub_session(session_of(caller, "tester") == "shop/tester"once tester has a record),test_default_by_name_is_the_default,test_a_pin_wins_and_a_different_argument_is_refused(400 naming both),test_a_call_naming_an_unknown_session_is_refused_and_opens_nothing(NoSession, the Grid'sopened == 0),test_open_session_makes_a_named_sub_session,test_an_unowned_default_is_claimed_by_the_first_subject(a record with noowner; subject A's unnamed call reaches"shop"andowner == A),test_a_second_subject_gets_its_own_sub_session(owner A; subject B unnamed →"shop/<B>", its record labelled B'spreferred_username),test_a_caller_with_no_subject_never_claims_the_default(admin token: reaches"shop",ownerstays None),test_the_owner_survives_end_browser_and_a_reopen_naming_default,test_a_second_subject_naming_default_shares_it. -
Step 2: Run — FAIL.
-
Step 3: Implement the pin in
Caller.from_request(SESSION_HEADER,SESSION_PARAM;SURF-11's "read nowhere" goes) andsession_ofas WS-49's four steps; the claim inside the record's compare-and-set, so two first subjects cannot both own it. -
Step 4: Run — PASS;
pytest -q. -
Step 5: WS-48, WS-49, WS-50, WS-78, SURF-45 lose (proposed); SURF-8's table gains the pin; commit.
Files: workspace/workspaces.py (every entry taking name takes the session key from
session_of), spec/builder.py and mcp/tools.py (session on every acting tool),
routes.py/flows/api.py REST routes, core/capabilities.py if rows list arguments, goldens.
Spec: WS-47, WS-51, WS-52, WS-53, WS-59, WS-60, WS-74, WS-75, SURF-46.
Interfaces:
-
Consumes: Task 2's
session_of. -
Produces: an optional
session: str | Noneargument on every tool and route that acts on a browser, and onopen_session,end_browser,save_site_data;open_session's result gainssession,default(bool) andothers([{name, label, default, live, url}], the caller's session left out). -
Step 1: Write the failing tests:
test_a_sub_session_opens_its_own_browser_and_leaves_the_default_open(two Grid opens; the default'ssession_idunchanged),test_two_sessions_act_at_once(two threads on two keys, neither waits on the other's turn),test_two_callers_naming_one_session_take_turns(WS-53: the second call waits on the first's turn),test_a_sub_session_opens_from_config_not_from_the_defaults_settings(default firefox, tester opens chrome),test_save_site_data_saves_into_the_calling_sessions_record,test_a_reaped_sub_session_reopens_signed_in(its ownsite_datarestored),test_end_browser_ends_only_the_callers_session,test_a_secret_is_scoped_by_its_own_sessions_origin(default ona.example.test, tester onb.example.test; a secret leashed tobis typed in tester and refused in the default),test_open_session_answers_session_default_and_others,test_a_call_that_never_names_a_session_is_unchanged(one existing MCP call's result byte-equal to before). -
Step 2: Run — FAIL.
-
Step 3: Implement the key through
act,_said,open_browser,end_browser,remember,touch,reshape, the bound write and the paste;sessionin the generated schemas (it never reachesActions). -
Step 4: Run — PASS; regenerate goldens in their own commit.
-
Step 5: the rows lose (proposed); WS-13's ending step and the glossary's "at most one" are rewritten; commit.
Files: workspace/workspaces.py (history), flows/store.py and file routes (by workspace
part), core/actions.py/http/files.py (downloads per session, keep_file(session=)).
Spec: WS-54, WS-52's downloads, the Files half of UI-65.
Interfaces: history entries gain session (a name) and are written to the workspace's record
from any session; GET/DELETE /admin/workspaces/{key}/files/downloads and
session://downloads answer one session's downloads (session, default when absent).
- Step 1: Write the failing tests:
test_a_sub_sessions_visit_is_in_the_workspaces_history_tagged,test_two_sessions_append_history_without_losing_an_entry(interleaved writes throughFakeRedis.interfere; both entries kept),test_flows_files_and_config_are_the_same_from_every_session,test_each_session_has_its_own_downloads,test_keep_file_reads_the_callers_sessions_downloads. - Step 2–4: fail, implement, pass.
- Step 5: WS-54 loses (proposed); commit.
Files: mcp/resources.py, mcp/show.py, workspace/workspaces.py
(_described), capture/ callers (pass the session key). Spec: WS-72, WS-73, CAP-81 and the
rows they replace (CAP-32, CAP-37).
Interfaces: workspace://current adds session, default, sessions ([{name, label, default, live, url}], the default first) to CONTEXT_KEYS; templates session://{name},
session://{name}/console, /network, /downloads.
- Step 1: Write the failing tests:
test_the_context_lists_every_session_default_first,test_session_resource_reads_a_named_session,test_capture_is_kept_per_session(a console row in tester is absent fromworkspace://consolefor the default),test_a_sub_sessions_capture_lasts_as_its_record,test_session_name_resource_for_an_unknown_name_is_not_found. - Step 2–4: fail, implement, pass; goldens in their own commit.
- Step 5: the rows lose (proposed); commit.
Files: flows/api.py, flows/document.py, flows/engine.py, live/control.py,
http/admin/live.py. Spec: FLOW-50, FLOW-51 (and FLOW-6's exception), LIVE-42 (and LIVE-15),
ACT-43, ACT-44.
- Step 1: Write the failing tests:
test_run_flow_runs_every_step_in_its_session,test_save_flow_refuses_a_step_naming_a_session(says to set it onrun_flow),test_control_of_one_session_leaves_another_acting,test_await_control_waits_for_its_own_session. - Step 2–4: fail, implement, pass.
- Step 5: the rows lose (proposed); ACT-43 and ACT-44 lose it with no code (each session's tabs are its browser's; classic is the only transport); commit.
Files: http/admin/workspaces.py, http/admin/capture.py, http/admin/live.py,
http/admin/files.py, http/admin/signed.py.
Interfaces: the workspace list holds workspaces only, each with sessions (name, label,
default, live, browser); every session-scoped admin route (the Session row, capture, live,
site data, end browser) takes ?session=, the default when absent; POST …/end-all ends every
session's browser and answers how many ended.
- Step 1: Write the failing tests:
test_admin_lists_sub_sessions_under_their_workspace,test_admin_session_routes_take_session,test_end_all_ends_every_sessions_browser,test_an_admin_link_to_a_sub_sessions_live_view_is_scoped_to_it. - Step 2–5: fail, implement, pass, commit.
Files: ui/src/admin/Admin.svelte and the panes, ui/src/App.svelte (MCP App),
ui/src/admin/HistoryPane.svelte, FilesPane.svelte, their tests; Penpot Library. Spec: UI-64,
UI-65, UI-78 (and UI-28).
- Step 1: Write the failing tests (Vitest):
the tab order
['Session', 'Live', 'Console', 'Network', 'Site data', 'Files', 'Flows', 'History', 'Config']with a divider after Site data (replacesHistoryPane.test.ts's order),no chips with only the default session,chips: default first, then sub-sessions; past five in +N,picking a chip changes the session tabs and not Files,End tester names the picked session,History filters by its own session control, all by default,Files groups downloads by session,the workspace card carries no session state,the MCP App names a sub-session. - Step 2–4: fail, implement from the Penpot Sub-sessions boards, pass.
- Step 5: move the split tab bar and the workspace-only card into the Penpot Library and swap the Sub-sessions file's local copies for them (UI-63); the rows lose (proposed); commit.
Files: plugin/ skill docs (when to name a session; a main agent gives each subagent its own
name), README, scripts/generate_wiki.py output, CHANGELOG,
tests/integration/flows/ or an integration test: two sessions in one workspace, each signs in to
the-internet on its own, one signs out, the other is still signed in.
- Step 1: the integration test, run against the Grid.
- Step 2: docs and the generated wiki; the design's History says it is built.
- Step 3: commit.
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