Skip to content

2026 11 19 session pointers

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

Session Pointers Plan

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 blank session stays "your own" and is documented; the missing session://{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}/console and /network honour their query (the plain templates matched first and dropped it); upload_file reads 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).


Task 1: Pointers name the session acted in, and the missing resources exist

Audit tables 1 and 2 list every producer with file and line.

  • sessions.pointer(acted, own, path): workspace://{path} when equal, else session://{name}/{path}; the downloads form session://downloads[/…] vs session://{name}/downloads[/…].
  • Workspaces.act computes own = 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.see from act, from write(secret=…) (secrets.py) and from run_flow's report (flows/api.py total). The error note (calls.sentence, also logged by flows/engine.py) keeps workspace://… when acted is own; otherwise a nameless form naming session://{name}/… with the literal {name}.
  • Site data: save_site_data's uri; the restore report on open_session and on the first call after a reopen (set in Workspaces, the action layer knows only a Grid id); site_data on session://{name}'s body; the listing's and each row's uri when read at the new resource.
  • network_body's uri; a request view's uri (capture/views.py) and the admin request JSON say the URI they were read at.
  • New resources, each mirroring its workspace:// twin and resolved by reading (never makes a record): session://{name}/network/{id}, session://{name}/site-data, session://{name}/site-data/{site}, session://{name}/downloads/{file}. Each gets a show row (tests/test_show_inventory.py guards it) and the mirror's LINKED_FROM where binary.
  • keep_file and upload_file accept session://{name}/downloads/{file}: the session comes from the URI, and a session argument that differs is refused as _chosen refuses a name that differs from a pin. A named session's downloads listing, its entries, their keep_with, and keep_file's from all carry that form.
  • session://downloads reads resolve through reading, not session_of (WS-73: reading makes nothing, claims nothing).
  • Each sessions / others entry carries uri: 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).

Task 2: No log line names a sub-session

  • NO_SUB, _named's NotFound (resources.py), the session downloads NotFound (http/files.py), PIN_DIFFERS and the mirror's read_resource refusal drop the name.
  • network_body's and captured(kind="request")'s 400 texts, and one_site's, stop naming workspace://… alone: a nameless form that gives both workspace://… and session://{name}/….
  • QuietCallerMistakes (mcp/failures.py) masks the name in a session://<name>… URI it logs (session://downloads stays 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, by session:// resource and by the downloads resource, a bad ?level on one, and a flow step failing in one, all leave no sub-session name in any record.

Task 3: The MCP App and the admin follow the session

  • ContextView's chips (console, network, downloads) build from the view's own uri when it is session://<name>; site data uses the server's site_data.uri.
  • NetworkView opens a row at its listing's base plus /{id}; RequestView fetches the body with network_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).

Task 4: What an agent reads says where its session's state is

  • The Session argument's description: a blank value is your own; a named session's state is session://<name>/…, and workspace:// 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: lists ReadMcpResourceTool and ToolSearch.
  • The explorer agent (plugin/agents/explorer.md): ReadMcpResourceTool and ToolSearch in tools: and any tool it now needs (end_browser); it works in a session of its own, the name the main agent hands it or explorer, 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.

Clone this wiki locally