Files
plan2code/.readme/web-console-internals.md
T

27 KiB

The web console, inside

For people who change the console or drive it by hand: how it works, the security model, every route, and how to refresh the screenshots. Using the console? Read the web console guide instead.

How it works

Nothing is installed. The skills ship a small zero-dependency Node server (references/web-console/), and the workflow step starts it when you say yes.

agent                          server (detached)              your browser
  |                                  |                             |
  |-- open (binds the port, starts ->|                             |
  |   the server AND the browser) ---|---------------------------->|
  |<-- http://127.0.0.1:PORT/s/TOK/  |<---- the page, first state -|
  |                                  |      already inside it      |
  |-- post the first questions ----->|---- pushed to the page ---->|
  |-- wait --seconds 240 ----------->|                             |
  |   (returns every 4 minutes with  |                             |
  |    progress, then waits again)   |<---- you press Send --------|
  |<-- your answers -----------------|                             |

The server runs detached rather than as a background task of the agent, because agent background tasks get killed at various timeouts, and that would take your half-finished answers with them.

It is built to show you something fast. A browser takes most of a second to turn up after it is asked, so open binds the page's port itself and sends the browser there before the server has even finished starting; the server takes the port over a moment later, and the browser's request waits for it rather than being refused. The page arrives with the session already inside it, so it draws the real screen without asking for anything first, in your own theme and colors from the first frame. On a Windows laptop the page is in front of you in roughly the time the browser itself takes to open.

It stays up while the page is open. The page pings it every few seconds, so the idle clock never runs down while you are there. Close the tab and it shuts itself down about two minutes later; it stops after four hours unless answers you sent are still waiting for the agent, and the agent stops it outright when the session ends.

The setup session hands its tab to the agent it finds. A setup session is agent-less: nothing reads its sends, so the page's agent-silence and question rules are switched off and only the idle deadline ends it. The plan2code launcher started the session and polls it for a pick; Start with this agent posts an __start action the launcher collects, and it spawns that agent with two environment variables, PLAN2CODE_SETUP_ANNOUNCE (the setup server's address) and PLAN2CODE_SETUP_TOKEN (a per-session token). The new agent's own open then POSTs its sign-in URL to POST /handover on the setup server instead of opening a browser; the token guards the route, the setup page gets a move event on its /events stream carrying the URL, and the tab follows it onto the new session. Inside the desktop app none of this runs: open finds no setup variables (the launcher scrubs the app ones from the setup console it starts), the page tells the app agent-found instead, and the app closes the setup page and picks the agent itself.

That also means the server routinely outlives the agent. It is the agent, not the server, that reads your answers, and the two fail separately. The page tells the two apart: the ? button at the top right opens Help, whose What this page is tab says which halves are talking right now (and When something looks stuck covers what to check), and Planny stops looking busy once nothing is listening rather than spinning at you indefinitely.

State lives in three places, and none of them is your repository (the one exception being the note attachments the agent keeps for a spec, above):

Where What Survives
~/.plan2code/console/sessions/<id>/ the questions, your draft, your answers 30 days after the session was last touched
~/.plan2code/console/sessions/<id>/workspace.json, ledger.ndjson, workspace-cursor.json the workspace's folders (paths, names, descriptions — never their contents), the session meter's events, and how far the agent has been told of workspace changes. Kept beside the session, so they outlive every dashboard hop with the session
~/.plan2code/console/sessions/<id>/uploads/ images and documents attached to notes and quick questions 30 days after the session was last touched
~/.plan2code/handoffs/<id>.md, <id>.json each handoff's document, and which checkout, spec and skill it belongs to and whether it was picked up (handoffs.mjs is their one owner) 30 days after it was last touched, picked up or not
~/.plan2code/notepads/<folder-name>-<12 hex>/ your notebook for one folder: meta.json, tabs.json and, per tab, tabs/<id>/note.md and tabs/<id>/images/ (notepads.mjs is their one owner; the agent never reads them, except a tab you send) until you delete it through Cleanup, which offers it once its newest file is 30 days old
~/.plan2code/console/looks.json your role, theme, colors, sounds and card width, the Show Activities and Play activity sounds switches (hideActivities, activitySounds), the last activity picked (lastActivity), best scores (flat activityBest<Id> keys: activityBestSnake, one per Mini golf course from activityBestGolfPirate to activityBestGolfFrost, activityBestTrails, activityBestBugs, activityBestDrive, activityBestStack, activityBestBumper, activityBestRapids, activityBestFuse, activityBestHop, activityBestBounce, activityBestGhoul, activityBestFlock) and each game's memo (activityMemo<Id>: Snake's surprises found, Light Trails' furthest arena, Bug Hunt's bugs, bosses and power-ups found, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, Ghoul Rush's most stages cleared in a run, Flock Dash's furthest stage) always
~/.plan2code/console/subagents.json your Subagents switch, instruction and limit, per project folder and skill always
~/.plan2code/console/sessions/<id>/subagents-setting.json, subagents-cursor.json this session's copy of the switch, and how far the agent has been told of it with the session
~/.plan2code/agents.json your custom agent CLIs (User Preferences → Agents & models), read by the plan2code command and the desktop app always
your system temp directory the port, process id and session token until reboot

Each of the workspace and meter files has exactly one writer: the server owns workspace.json (the page changes it only through the /workspace routes under Security), and console.mjs owns ledger.ndjson and workspace-cursor.json. The meter's count is never stored; it is folded from the ledger every time (public/meter.js), so a repeated post never counts twice. The logic lives in small pure modules the tests import directly — public/workspace.js (names, the footer label, the change lines the agent reads), public/meter.js and public/mentions.js (the @name popover) — and Browse… runs the per-OS picker in picker.mjs, copied from the plan2code launcher and kept in step with it by a test.

Old sessions clean themselves up. Each time a session opens, whole session folders nobody has touched for 30 days are deleted — questions, drafts, answers, uploads and all, paused or not — along with stray scratch files (.json / .mjs) left at the top of ~/.plan2code/console/ for as long, and handoffs in ~/.plan2code/handoffs/ untouched for as long, both files each. Your looks.json and the console-dir pointer are never touched, and neither is the session being opened. Nothing of value goes with them: the page is never the record, specs/ in your project is.

Or clean up on demand. User Preferences → System → Cleanup → Find files to clean up lists, with sizes, everything in ~/.plan2code/ that is not needed: sessions untouched for 30 days (never the one you are in), anything at the top of ~/.plan2code/console/ other than sessions/, runtime/, looks.json, workspaces.json, loop-setup.json, loop-reports.json, subagents.json, pr-hosts.json, console-dir and update-check.json, and anything at the top of ~/.plan2code/ other than console/, bin/, launcher.json, install.json (what you installed, which plan2code update reads), models.json, handoffs/ (old handoffs go by age, above), notepads/, app/ and app.json (the desktop app and its settings) and agents.json (your custom agents). Each notebook whose newest file is 30 days old or more is listed as one item, Notebook for its folder, and goes whole; no automatic sweep ever removes one. It also lists each folder in the project's specs--completed/ whose newest file is more than 30 days old: archived specs Finalize moved there. Only a folder git tracks is deleted: specs--completed/ is usually gitignored, so git couldn't restore it, and Cleanup keeps it and says why instead. A stray is listed once it has sat untouched for an hour, so a lock or temp file another session is writing right now is never caught. Delete N items removes only the rows you left ticked. A console running from another home (PLAN2CODE_CONSOLE_HOME) only ever looks inside that home.


Security

It is a local dev server that reads files in your project (never writing to it) and keeps its own state in your home folder, so it is built to be boring about this:

  • Bound to 127.0.0.1 only, never 0.0.0.0. Not reachable from your network.
  • A Host header allow-list, which is what stops a website you happen to be visiting from talking to it through a DNS rebinding trick.
  • A 128-bit token in the link, swapped for an HttpOnly; SameSite=Strict cookie on first load so it leaves your address bar, your history and any screenshot.
  • A strict Content Security Policy with no inline script allowed.
  • Markdown written by the agent is turned into page elements directly and never into an HTML string, so a document that quotes a hostile README cannot run anything. It shows up as text, which is what it is.
  • Uploads are named by the server (<uuid>.jpg, or <uuid>.<ext> with the extension taken from the allow-list, via crypto.randomUUID()), never by the file name you sent, and live only under the session's own uploads/. The server checks the bytes: a JPEG header for images (4 MB cap), and for documents a %PDF- header or strict UTF-8 with no NUL byte (10 MB cap). Documents are served back only under a fixed type (application/pdf, or text/plain for text and code) with nosniff (and sandbox on text), so the Sent box can link them. A send may only point at uploads inside that session's uploads/, images in images and documents in files.

Routes

The upload routes, the send, the overview and handoff reads, the workspace and the notebook. Like every page route, they are on 127.0.0.1 behind the session cookie, and the ones that write also check the request's origin.

Route Does
POST /upload Raw bytes, original name in x-p2c-name. Content-Type: image/jpeg: writes uploads/<uuid>.jpg and answers { ok, id, kind: "image", path, url, name, size }; not a JPEG → 415, over 4 MB → 413. Content-Type: application/octet-stream: a document, its extension from the name's allow-listed extension; writes uploads/<uuid>.<ext> and answers { ok, id, kind: "file", path, name, size } with no url; not an allowed extension or contents that do not match → 415 type, over 10 MB → 413. Any other content type → 415.
GET /uploads/<id>.<ext> Serves an upload: an image as image/jpeg (the thumbnail after a reload), a document as application/pdf or text/plain; charset=utf-8 with nosniff and, on text, Content-Security-Policy: sandbox. Only <uuid>.<allowed ext> names under uploads/; anything else is 404.
DELETE /uploads/<id>.<ext> Deletes an image or document removed before sending. 204, or 404 if it is not there.
POST /submit The Send. A note may carry images and files, each [{ path, name }]: at most 5 together, images in images and documents in files, every path inside this session's uploads/, otherwise 400.
POST /chat A Quick question { text, about?, images?, files?, conversation }, or { reset: true, conversation } for New conversation. Appended to the session's chat.ndjson. 400 too-long (over 4,000 characters), image, file or bad; 409 offline, stale or limit (10 per conversation). Never refused because a card send is still uncollected.
POST /chat/decision Approve or Decline on an edit the agent proposed: { re, decision, text?, conversation }. Once per proposal; does not count toward the 10.
GET /overview?spec=specs/<name>[&file=map|draft] The Overview tab's read of <spec>/overview.md (or, with file=, the Map tab's pathfinder/map.md or the Plan draft tab's live PLAN-DRAFT-*.md), as text/markdown with cache-control: no-store and the file's spec-relative name, URL-encoded, in x-spec-file. A missing file is a 204. On the dashboard spec must be one of the scanned specs; elsewhere the session's own spec is used. The file's real path must stay inside the project, so ../, absolute paths and symlinks pointing out all get the same 204 as a missing file, as does an unscanned spec or an unknown file.
GET /agents-doc[?file=<name>] The Dashboard's AGENTS.md tab: AGENTS.md (the default) or one .agents-docs/<name>.md, as text/markdown with cache-control: no-store. A dashboard only; any other file name, a missing file or a path that leaves the project is a 204.
GET /prototypes?spec=specs/<name> The Prototypes tab's list: { files: [{ name, kind }] } (kind md or html) for the files directly in <spec>/prototypes/, or a 204 when there are none. The spec is chosen as for /overview.
GET /prototype?spec=specs/<name>&name=<file>.md One .md from <spec>/prototypes/, as text/markdown with cache-control: no-store; any other name, a missing file or a path that leaves the folder is a 204.
POST /open-prototype { spec, name }: opens one .html from <spec>/prototypes/ in the person's default browser. 404 for any other name, 500 when no browser could start.
GET /handoff?id=<id> Read it all: the handoff's .md from ~/.plan2code/handoffs/, as text/markdown with cache-control: no-store. A dashboard only, and only an id its own scan listed: a used, unknown or malformed id is 404.
POST /learning/pause Pause for me: { paused: boolean } (origin-checked; anything else is 400 bad-request, and 409 not-on unless Learning is On or Paused for you). Writes the personal pause on this machine only (pause.json under ~/.plan2code/learning/<key>/), the server's only write for Learning, and repaints the row with no agent.
GET /learning/state The Learning row's state worked out now, { state, pausedSince, waiting, oldestDays } ({} when the project's settings file is from a format it cannot read), with cache-control: no-store.
GET /learning/lessons Open the lessons, read only: { files: [{ name, title, text }] } from the project's lessons (.plan2code/lessons/, saved with the repository), general.md first, then the other .md files in name order (plain files only, at most 100 of 512 KB each), with cache-control: no-store.
GET /workspace The Workspace dialog's list: folders, missing, remote and the agent's folder issues. ?check=1 re-checks every folder on disk first.
POST /workspace/add { path, name?, description? }. The path is resolved against the folder the session started in (~ expanded) and must be a folder: 400 not-a-folder, duplicate (with its name; compared case-insensitively on Windows and macOS), bad-name, or name-taken with a suggest. Answers the new entry, nested: true when it sits inside another folder in the list.
POST /workspace/edit { id, name?, description? }. Renames or re-describes one folder: 400 bad-name / name-taken, 404 unknown.
POST /workspace/remove { id }. 400 original for the folder the session started in, 404 unknown.
POST /workspace/browse Opens the system folder picker and answers { path } or { cancelled: true }; never adds anything itself. 409 busy while one is open, 404 no-picker when the session looks remote or no picker exists.
GET /notepad[?tab=<id>] The notepad for the folder this session runs in: `{ tabs: [{ id, name, sent? }], last, tab: { id, text, savedAt, images: [{ id, url, thumb }] }
POST /notepad/text?tab=<id> { text }. Saves that tab's note.md and answers { ok, savedAt }; 400 bad, 404 no-such-tab, 413 too-long (over 1 MB).
POST /notepad/image?tab=<id> Raw image/jpeg (the page re-encodes every picture first). Writes the tab's images/<uuid>.jpg and answers { ok, id, url }; 415 not-jpeg, 413 too-large (over 4 MB), 409 too-many (200 pictures in the tab).
POST /notepad/thumb?id=<uuid>&tab=<id> Raw image/jpeg: that picture's thumbnail. 404 not-found or no-such-tab, 415 not-jpeg, 413 too-large.
POST /notepad/image/delete?tab=<id> { id }. Deletes a picture and its thumbnail; 404 not-found or no-such-tab.
POST /notepad/tab { name }. Makes a tab, which becomes the last one used, and answers { ok, id, name }; 400 bad-name, 409 duplicate-name (any case) or too-many-tabs (20).
POST /notepad/tab/rename { id, name }. Answers { ok, id, name }; 400 bad-name, 404 no-such-tab, 409 duplicate-name.
POST /notepad/tab/delete { id }. Removes the tab from the index, then its folder (text and pictures); 404 no-such-tab.
POST /notepad/tab/order { order: [id] }, every current id exactly once; 400 bad otherwise.
POST /notepad/tab/last { id }. Remembers the open tab; 404 no-such-tab.
POST /notepad/tab/sent { id, workflow, spec? }. Records that the tab was sent (workflow one of pathfinder, plan, quick-task, revise-plan, diagnose, ui-prototype; spec like specs/<name>) as sent: { workflow, spec?, at } on its tabs.json entry, shown back in GET /notepad's tabs. The page posts it only after the Send that carried the filled box; 400 bad-sent, 404 no-such-tab.
GET /notepad/images/<tab>/<uuid>.jpg, <uuid>.thumb.jpg Serves a picture or its thumbnail as image/jpeg, only by a tab id and a UUID name, a regular file (never a link) whose real path stays inside ~/.plan2code/notepads/; anything else is 404.
POST /subagents { on, instruction, max } (instruction: null for the shipped default). Saves the switch for this project and skill and answers { ok, setting }; 400 not-offered on a skill without the switch, bad, too-long (over 2,000 characters) or max (outside 1 to 20).
GET /agents The agents view's data: your custom agents and the shipped built-ins and templates, each entry merged with its lookup result { state, path, where, folder }: state is found (on PATH), outside (saved Windows PATH, npm's global folder or an install folder) or missing, and where says which search found it. Built-ins carry their install lines for the server's OS only.
POST /agents { agents, replace? }. Saves the custom-agent list to ~/.plan2code/agents.json, validated first (400 { error, index, field }); 409 while the file holds entries GET /agents could not read, unless replace: true.
POST /agents/test { command }. Where a command would run from ({ found, path }), for the form's Test button; never runs it.
POST /agents/use-path { id }. "Use it from here": saves the location the lookup found off PATH as the agent's command (a built-in becomes a new custom entry; 404 unknown, 409 not-found).
POST /handover Setup sessions only, and only with the session's setup token in x-plan2code-token: the new agent's open posts { url } here, the server broadcasts a move event with it and the setup tab follows. 409 moved once it has happened.

For maintainers

Source src/web-console/ (one row per file in the files tables of the .agents-docs/AGENTS-architecture-*.md area files; a test keeps it complete)
Ships as skills/<every skill>/references/web-console/
Wiring one additionalReferences entry per skill in install.js; the dashboard's menu lives in public/skills.js (each entry's card; SKILL_CATALOG in public/answers.js is a lookup on it)
Agent contract a card, src/web-console/console.md (read once), plus pointers: the console names a topic file (console-*.md, notes/<workflow>.md, building.md / building-review.md) in its own read output, once per session per topic, when its moment comes; console.mjs help <topic> prints any of them. A stop with no finish, or a finish while stopWarning is set, is refused with the fix; stop --session <sid> --force ends a dead page or an abandoned session anyway. Patches are one line, with lettered options and the console's own defaults filled in; a refused patch names the field and the fix. Byte budgets keep the card, the notes and a sample session's outputs from growing back (scripts/test-console-wire-budgets.mjs)
Tests node --test scripts/test-web-console-*.mjs (split by area, shared setup in scripts/web-console-test-helpers.mjs), also run by npm test
Start-up benchmark node scripts/bench-web-console.mjs (needs a local Chrome or Edge for the paint columns, driven through playwright-core from npm install; --browser-delay 900 models a real browser launch, --roundtrip times Send→agent and post→page)
Screenshots node scripts/capture-screenshots.mjs (needs a local Chrome or Edge, driven through playwright-core from npm install; `PLAN2CODE_TEST_BROWSER=chrome
Dependencies none at runtime. marked 15.0.7 (MIT) is vendored for its lexer only, and CodeMirror 6 (MIT) for the notebook's editor as one bundled file, public/vendor/codemirror.esm.js, made by the dev-only node scripts/vendor-codemirror.mjs from a pinned lock (about 500 KB, loaded only when the Notebook is first opened); the page's policy blocks the <style> element CodeMirror writes, so the editor lives in a shadow root where it adopts its rules as a constructed stylesheet (steps in the architecture doc's Notebook point)

Edit src/ only. skills/ is a committed build artifact: regenerate it with npm run build:skills and commit it with the source change, since npm test (via --verify-skills) fails when it drifts from src/.

Driving it by hand

You do not need an agent to poke at the console. Point PLAN2CODE_CONSOLE_HOME somewhere disposable first, so you never touch a real session:

export PLAN2CODE_CONSOLE_HOME=/tmp/p2c-play     # Windows: $env:PLAN2CODE_CONSOLE_HOME

cat > /tmp/payload.json <<'JSON'
{ "workflow": "pathfinder", "title": "Playing about",
  "items": [ { "id": "q1", "kind": "choice", "title": "Export format",
    "body": "Pick one.",
    "options": [ { "k": "A", "text": "CSV", "recommended": true },
                 { "k": "B", "text": "Excel" } ],
    "token": { "A": "a", "B": "b" } } ],
  "agent": { "status": "waiting" } }
JSON

node src/web-console/console.mjs open --file /tmp/payload.json   # prints the URL, opens the browser
node src/web-console/console.mjs wait --session <sid> --seconds 60
node src/web-console/console.mjs stop --all

node src/web-console/console.mjs help prints the same command summary an agent gets when it finds the binary before the docs.

wait exits 0 with the answers, 10 if nobody has finished yet, 20 if the server died, 30 on Cancel. Pick --seconds to sit under whatever your harness allows a single command: it is a poller, so killing it costs nothing, and a collected result is printed before it is marked collected, which means an interrupted handover can only repeat itself, never lose an answer. status lists sessions and flags any whose answers were submitted but never collected.

When something misbehaves, the session directory is the whole story: state.json (what the agent published), draft.json (what the person has typed but not sent), result.json (what they sent), events.ndjson (an append-only log you can cat), and server.log.

Set --idle-ms 60000 on open if you want the server to shut itself down quickly while experimenting.

Two environment variables help when the start is what you are looking at:

Variable Does
PLAN2CODE_CONSOLE_TRACE=1 open prints a timeline of its steps to stderr (roots found, server spawned, port bound, browser sent, state written, server listening).
PLAN2CODE_BROWSER The command that opens the link instead of the system default, run through the shell with the link appended, e.g. PLAN2CODE_BROWSER='firefox --new-tab'.

Every console.mjs open of an installed console (one run from a version folder under ~/.plan2code/console/) also writes its own directory to $PLAN2CODE_CONSOLE_HOME/console-dir (or ~/.plan2code/console/console-dir when the override is unset): it is how an agent finds the console on a later session without searching the skill install dirs. A console run from a source checkout leaves the pointer alone.

The vendored file is src/web-console/public/vendor/marked.esm.js, sha256 7a7d9a521ac9384e0c3a075120a7c486cbd0c3c32cc5601bbb79a23e97403690. Only marked.lexer() is used; the rendering is ours, in public/render.js, and builds DOM nodes rather than HTML so nothing needs sanitizing.

Refreshing the screenshots

The docs and the landing page show the console through the images in docs/screenshots/, one light and one dark WebP per screen. Rerun the capture after any change a person would see on the page: a new layout, a renamed button, a different color.

node scripts/capture-screenshots.mjs                     # every screen
node scripts/capture-screenshots.mjs --only dashboard    # one screen

Each screen is staged with no agent, from the payloads in scripts/screenshots/ (its README names the file behind each screen), in a throwaway sample project and console home that the script removes when it is done. It prints each file's size and warns over 300 KB.

Open every image before you commit it: the right screen, both themes, nothing cut off, and no username, home path or real project name anywhere on it.