Repository navigation
2026 11 19 session pointers
History. Drafted 2026-11-19 for #181, after the live QA of sub-sessions (#180) found that a call naming a session hands back pointers to the caller's own session. A read-only audit of every session-state URI the server emits (kept beside the build notes,
stuff/sdd/session-pointers/uri-audit.md) set the scope. Dr K's rulings: a blanksessionstays "your own" and is documented; the missingsession://{name}/…resources are added, downloads included; subagent resource access is fixed in the explorer agent and the docs, not by showing the mirror tools; the explorer works in a session of its own. Built in four tasks (2026-11-19), each reviewed, then a whole-branch review and one fix wave. Built beyond the text:session://{name}/consoleand/networkhonour their query (the plain templates matched first and dropped it);upload_filereads a named session's download from it and is never refused for it, so one session can upload another's; the explorer stops on a pinned connection; a named session's downloads, listings and keeps are scrubbed with that session's secrets.
For agentic workers: REQUIRED SUB-SKILL: Use skill://superpowers/subagent-driven-development/SKILL.md to implement this plan task by task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Whoever follows a pointer selenium-flow hands back reads the session the call acted in, and no log line names a sub-session. A subagent working in its own session is told, by every result and every description, where that session's state is.
The rule. workspace://… and session://downloads… read the caller's own session
(Workspaces.reading(caller): its pin, else the default, else its subject's own sub-session). A
pointer a call returns names workspace://<path> when the session it acted in is that own session,
and session://<name>/<path> otherwise (default is a name like any other here). Pinned
connections never change: a pin makes acted and own the same. One helper decides it, in
workspace/sessions.py.
Where names may go. A result returned to the caller may carry a sub-session's name. A log line
may not (WS-49 (3)), and FastMCP logs every tool or resource error message at WARNING, and the URI
of every failed resource read; flow step errors are logged at INFO. So error texts and error notes
never carry a sub-session's name: they use a nameless form, or the literal placeholder {name}.
Tech Stack: Python 3.11+, FastMCP, Svelte 5 + Vitest (ui/), pytest, ruff.
Spec: WS-79 (the pointer rule) and WS-80 (a blank session) in
workspaces-and-sessions.md, written for this plan; the
other rows below were brought up to date with it.
Spec rows touched: CAP-37, 41, 44, 48, 51, 53, 70 (capture.md); SITE-16, 47, 50, 52
(site-data.md); FILE-24, 25, 28, 29, 31, 48 (workspace-files.md); WS-43, 44, 45, 49, 64, 66, 72, 73,
76 (workspaces-and-sessions.md); SURF-1, 15, 16, 17, 18, 25, 26, 28, 33 (surfaces.md); ACT-40
(browser-actions.md); PLG-47, 48, 55, 60, 63 (plugin.md); ERR-16, 35 (errors-and-logging.md).
WS-44 and SURF-16 are already stale (they say session:// serves downloads only).
Audit tables 1 and 2 list every producer with file and line.
-
sessions.pointer(acted, own, path):workspace://{path}when equal, elsesession://{name}/{path}; the downloads formsession://downloads[/…]vssession://{name}/downloads[/…]. -
Workspaces.actcomputesown = self.reading(caller)only when the call named a session (an unnamed call acts in its own) and passes it to whatever builds a pointer. -
page.seefromact, fromwrite(secret=…)(secrets.py) and fromrun_flow's report (flows/api.pytotal). The error note (calls.sentence, also logged by flows/engine.py) keepsworkspace://…when acted is own; otherwise a nameless form namingsession://{name}/…with the literal{name}. - Site data:
save_site_data'suri; the restore report onopen_sessionand on the first call after a reopen (set inWorkspaces, the action layer knows only a Grid id);site_dataonsession://{name}'s body; the listing's and each row'suriwhen read at the new resource. -
network_body'suri; a request view'suri(capture/views.py) and the admin request JSON say the URI they were read at. - New resources, each mirroring its
workspace://twin and resolved byreading(never makes a record):session://{name}/network/{id},session://{name}/site-data,session://{name}/site-data/{site},session://{name}/downloads/{file}. Each gets ashowrow (tests/test_show_inventory.pyguards it) and the mirror'sLINKED_FROMwhere binary. -
keep_fileandupload_fileacceptsession://{name}/downloads/{file}: the session comes from the URI, and asessionargument that differs is refused as_chosenrefuses a name that differs from a pin. A named session's downloads listing, its entries, theirkeep_with, andkeep_file'sfromall carry that form. -
session://downloadsreads resolve throughreading, notsession_of(WS-73: reading makes nothing, claims nothing). - Each
sessions/othersentry carriesuri: session://<name>. - Tests: every producer above, through the real entry point, for a named sub-session, for an
unnamed call (unchanged
workspace://), and for a pinned connection (unchanged).
-
NO_SUB,_named's NotFound (resources.py), the session downloads NotFound (http/files.py),PIN_DIFFERSand the mirror'sread_resourcerefusal drop the name. -
network_body's andcaptured(kind="request")'s 400 texts, andone_site's, stop namingworkspace://…alone: a nameless form that gives bothworkspace://…andsession://{name}/…. -
QuietCallerMistakes(mcp/failures.py) masks the name in asession://<name>…URI it logs (session://downloadsstays as is), for failed reads and failed mirror calls alike. - The log-hygiene test covers every logger,
fastmcp.*included: a missing sub-session read by tool, bysession://resource and by the downloads resource, a bad?levelon one, and a flow step failing in one, all leave no sub-session name in any record.
- ContextView's chips (console, network, downloads) build from the view's own
uriwhen it issession://<name>; site data uses the server'ssite_data.uri. - NetworkView opens a row at its listing's base plus
/{id}; RequestView fetches the body withnetwork_body({id, session})when its URI names one, and goes back to its own listing. - The admin's capture footer and request label say
session://<name>/…for a sub-session. - Session chips: hovering a chip that is not selected takes a neutral border, so only the selected chip shows the accent (done on the branch).
- The
Sessionargument's description: a blank value is your own; a named session's state issession://<name>/…, andworkspace://is your own. - Descriptions of
open_session,network_body,save_site_data,frame,keep_file,upload_file, and of the console, network, request, site-data, session and downloads resources; the output-schema texts in core/capabilities.py and spec/schemas.py. - Server instructions: one paragraph on sessions (name it on every call; its state is
session://<name>/…;workspace://is the connection's own, the main agent's for a subagent). - The skill: SKILL.md's sub-sessions section and resource table, TROUBLESHOOTING.md,
INTERACTION.md, SITE_DATA.md, WORKSPACES.md, SECRETS.md. A Claude Code subagent reads
resources only when its
tools:listsReadMcpResourceToolandToolSearch. - The explorer agent (plugin/agents/explorer.md):
ReadMcpResourceToolandToolSearchintools:and any tool it now needs (end_browser); it works in a session of its own, the name the main agent hands it orexplorer, passed on every call, and ends that browser when done; it starts with no sign-ins of its own, so it signs in through flows; the main agent keeps its own browser meanwhile. Its description says so. - README and CHANGELOG; the spec rows above, WS-44 and SURF-16 corrected, an ERR-35 row for a sub-session's name.
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