Skip to content

2026 11 19 sub sessions

Kelly Ferrone edited this page Nov 19, 2026 · 4 revisions

Sub-sessions Implementation Plan

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_of takes opening, and a read-only reading resolves resources and the context; six names are reserved (current, downloads, console, network, files, site-data); a dead sub-session's page loses its query after session.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 from subs; 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.

Global Constraints

  • Python 3.11+: from __future__ import annotations in every new module; ruff check . clean.
  • Tests: pytest -q tests/<file>.py for the task, then pytest -q before each commit; the UI with npm test in ui/. The integration suite needs GRID_URL and ADMIN_ORIGIN and runs in CI.
  • Commits: stage exact paths, never git commit -a. Every message ends with Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>.
  • docs/ is the wiki's own repository, on its branch feat/sub-sessions. A task that edits docs/ commits there first (never on master), then commits the docs pointer 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, tests example.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 from errors.status_for alone. No log line carries a Grid id, a URL, a title or a subject; log failures by type(exc).__name__.
  • Use the shared doubles in tests/fakes.py and tests/conftest.py; extend them, never copy them.
  • Never edit .github/.
  • Values: the default session is default (sessions.DEFAULT). current, downloads, console, network, files and site-data cannot name a session (sessions.RESERVED). A sub-session's key is <workspace>/<name> (sessions.SEP = "/"). The pin is the Sf-Session header or the ?session= parameter. A sub-session's record lives session.sub_ttl seconds after its last use (default 3600, config session.sub_ttl, env SESSION_SUB_TTL). The default's owner is the record field owner (a subject, or null). Chips past five go in a +N menu.
  • Out of scope: several sessions in one browser, the hook that names a subagent's session, roles (#66), the BiDi transport (#177).

Review Focus

  1. 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).
  2. 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 by test_an_unowned_default_is_claimed_by_the_first_subject and test_a_caller_with_no_subject_never_claims_the_default (Task 2).
  3. 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_session and test_owners_maps_a_sub_sessions_browser_to_its_key (Task 1).
  4. 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).
  5. 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) and test_two_sessions_act_at_once (Task 3).

File Structure

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

Task 1: Session keys and the store

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 — workspace for DEFAULT, else f"{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, refusing RESERVED with a ValueError.

  • Workspace.owner: str | None = None, Workspace.subs: list[str] (sub-session names, kept on the workspace's record).

  • Store: set/upsert/update on a sub key expire after sub_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", split inverts it), test_reserved_names_are_refused (current, downloads, a/b raise ValueError), test_a_sub_record_expires_after_sub_ttl (MemoryStore with sub_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 for RedisStore on FakeRedis.

  • 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 through to_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.

Task 2: Which session a call reaches

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 sessions and store.

  • Produces: Caller.pinned: str (from Sf-Session or ?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 (writes owner once).

  • 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's opened == 0), test_open_session_makes_a_named_sub_session, test_an_unowned_default_is_claimed_by_the_first_subject (a record with no owner; subject A's unnamed call reaches "shop" and owner == A), test_a_second_subject_gets_its_own_sub_session (owner A; subject B unnamed → "shop/<B>", its record labelled B's preferred_username), test_a_caller_with_no_subject_never_claims_the_default (admin token: reaches "shop", owner stays 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) and session_of as 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.

Task 3: A call acts in its session

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 | None argument on every tool and route that acts on a browser, and on open_session, end_browser, save_site_data; open_session's result gains session, default (bool) and others ([{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's session_id unchanged), 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 own site_data restored), test_end_browser_ends_only_the_callers_session, test_a_secret_is_scoped_by_its_own_sessions_origin (default on a.example.test, tester on b.example.test; a secret leashed to b is 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; session in the generated schemas (it never reaches Actions).

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

Task 4: What the workspace shares

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 through FakeRedis.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.

Task 5: Reading a session

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 from workspace://console for 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.

Task 6: Flows and live control

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 on run_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.

Task 7: The admin API

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.

Task 8: The admin UI, the MCP App and the drawing

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 (replaces HistoryPane.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.

Task 9: The skill, the wiki and a live check

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.

Clone this wiki locally