#!/usr/bin/env node // Plan2Code Web Console - the HTTP server. // // Spawned DETACHED by console.mjs, never as a harness-managed background task: // those get killed on compaction, on a new prompt, and at assorted timeouts, // which would take the human's half-finished answers with them. // // It owns no durable state of its own. Everything lives in the session // directory, which is what makes the console survivable: the human can finish // the form even if the agent session died, and a fresh agent picks the result up. // // This file is start-up and lifecycle: reading the handle and binding through // the handover, the cached reads the page's frame is built from, SSE, the // update check, state watching, the heartbeat, the idle deadline and listen. // Every request goes to routes.mjs, which lists every URL; the page's own // files are served by static.mjs, and the Workspace and Subagents helpers // live in workspace.mjs and settings.mjs. // // Node built-ins only. import fs from "node:fs"; import http from "node:http"; import path from "node:path"; import { HERE, UPDATE_CHECK_FILE, appendEvent, ensureDir, fileStamp, nowIso, parseArgs, readJson, writeJsonAtomic, } from "./files.mjs"; import { LEDGER_FILE, SERVER_MAX_LIFE_MS, handleFile, readLedger } from "./sessions.mjs"; import { CHAT_CURSOR_FILE, CHAT_FILE, appendChat, chatForFrame, currentConversation, readChat, readCursor, } from "./inbox.mjs"; import { serverWorkspace } from "./workspace.mjs"; import { serverSubagents } from "./settings.mjs"; import { inAppSignal } from "./in-app.mjs"; import { chatAnswering, chatOffline } from "./public/chat.js"; import { isAgentless } from "./public/skills.js"; import { meterView } from "./public/meter.js"; import { SERVABLE, asset } from "./static.mjs"; import { handle } from "./routes.mjs"; import { checkForUpdate } from "./update-check.mjs"; const args = parseArgs(process.argv.slice(2)); // Canonicalize before anything derives a path from it: a session dir reached // through a junction or a subst'd drive is watched under the wrong spelling, // which is the libuv assert described below. The native realpath resolves // those AND expands 8.3 short names, which lets the watcher run in a TEMP // spelled C:\Users\JUSTIN~1.PAR; the JS one is the fallback, and the watcher // still checks what it was given. const DIR = (() => { for (const real of [fs.realpathSync.native, fs.realpathSync]) { try { return real(args.session); } catch {} } return args.session; })(); if (!DIR) { process.stderr.write("server: --session is required\n"); process.exit(2); } const SID = path.basename(DIR); // The session token. `open` leaves it in a one-shot file in the session // folder (`--token-file=`, a bare name inside DIR) so it never appears // on this process's command line; it is read once and the file deleted at // once. `--token=` is kept for a server started by hand or by a test. // No token, no server: authed() waves everything through on an empty one. A // bare `--token` (or one whose value parseArgs took for a flag) arrives as // `true`, so anything but a non-empty string is refused here, at boot. const TOKEN = (() => { const name = args["token-file"]; if (typeof name === "string" && name && path.basename(name) === name) { const file = path.join(DIR, name); let text = ""; try { text = fs.readFileSync(file, "utf8").trim(); } catch {} try { fs.rmSync(file, { force: true }); } catch {} return text; } return typeof args.token === "string" ? args.token : ""; })(); if (!TOKEN) { process.stderr.write("server: a token is required: --token-file= or --token= (a non-empty string)\n"); process.exit(2); } const PROJECT = args.project || process.cwd(); // The checkout this session runs in, from `open`. PROJECT is the folder that // holds .git, which for a linked worktree is the MAIN checkout: the wrong // folder to seed the workspace with or resolve a typed path against. A fresh // `open` starts this server before it writes the state, so until the state is // there this is the only place the worktree can come from. const WORKTREE = typeof args.worktree === "string" ? args.worktree : ""; const IDLE_MS = Number(args["idle-ms"] || 30 * 60 * 1000); const MAX_LIFE_MS = Number(args["max-life-ms"] || SERVER_MAX_LIFE_MS); const STATE_FILE = path.join(DIR, "state.json"); const DRAFT_FILE = path.join(DIR, "draft.json"); const RESULT_FILE = path.join(DIR, "result.json"); const CHAT_PATH = path.join(DIR, CHAT_FILE); const CURSOR_PATH = path.join(DIR, CHAT_CURSOR_FILE); const STARTED = Date.now(); let lastContact = Date.now(); let browsers = 0; let rev = 0; let seq = 0; /* -------------------------------------------------------------- helpers */ // The state as last read, re-read only when its file has changed. Every // request, every SSE frame and the one-second poll used to read and parse // state.json afresh, and the state grows with the session (whole documents // live in it). A stat says whether anything moved; refreshing through // checkState also means a request that sees a new state first still counts // it as a new revision and tells every other tab. Callers must not mutate // what this returns -- /submit edits a fresh read of its own, under the lock. function readState() { checkState(); return stateNow; } // Both facts about result.json from one read, cached the same way. The page's // heartbeat, every state frame and /submit's guard each asked for them, and // each used to read and parse the file twice. // // An answered-but-not-yet-collected result: while one exists the session is // mid-handoff, and the page must not send again and must say why. // A stop the person asked for that nothing has collected yet. Reported from // here rather than remembered by the page, because the page's memory is per // origin and a resumed session comes back on a new port: the one place that // still knows a stop is on its way is the result sitting on this disk. let resultSeen = { stamp: null, pending: false, stop: false }; function resultFlags() { const stamp = fileStamp(RESULT_FILE); if (stamp !== resultSeen.stamp) { let text = null; try { text = stamp ? fs.readFileSync(RESULT_FILE, "utf8") : null; } catch (err) { // There but unreadable for now (an antivirus lock, say). Never cached, // so the next call reads it again, and meanwhile it counts as pending: // a result nobody could read is exactly the one /submit must not // overwrite. if (err.code !== "ENOENT") return { ...resultSeen, pending: true }; } let r = null; try { r = text ? JSON.parse(text) : null; } catch {} const pending = Boolean(r && !r.consumedAt); resultSeen = { stamp, pending, stop: pending && Array.isArray(r.actions) && r.actions.some((a) => a && a.type === "stop"), }; } return resultSeen; } // The chat inbox as last parsed, re-read only when the file has moved: every // frame carries the conversation, and frames go out on every change. let chatSeen = { stamp: null, entries: [] }; function chatEntries() { const stamp = fileStamp(CHAT_PATH); if (stamp !== chatSeen.stamp) chatSeen = { stamp, entries: readChat(DIR) }; return chatSeen.entries; } // How far the agent has collected the inbox. console.mjs writes the cursor // when it hands entries over, so this is the "picked up, answering" signal the // Ask pane shows a spinner for. let cursorSeen = { stamp: null, seq: 0 }; function chatPickedUp() { const stamp = fileStamp(CURSOR_PATH); if (stamp !== cursorSeen.stamp) cursorSeen = { stamp, seq: readCursor(DIR) }; return cursorSeen.seq; } // The frame's chat block without `offline`. A caller that already built it // (stateFrame) passes it in rather than building it twice. const chatNow = (state) => ({ ...chatForFrame(chatEntries(), state), pickedUp: chatPickedUp() }); function chatOfflineNow(state, chat = chatNow(state)) { return chatOffline({ finish: state && state.finish, agent: state && state.agent, agentLastSeenMs: agentSeenAt, now: Date.now(), answering: chatAnswering(chat), agentless: isAgentless(state && state.workflow), }); } /* ------------------------------------------------------------ workspace */ // ledger.ndjson has one writer, console.mjs; re-read only when it has moved. const LEDGER_PATH = path.join(DIR, LEDGER_FILE); let ledgerSeen = { stamp: null, entries: [], launches: 0 }; function ledgerEntries() { const stamp = fileStamp(LEDGER_PATH); if (stamp !== ledgerSeen.stamp) { const entries = readLedger(DIR); ledgerSeen = { stamp, entries, launches: entries.filter((e) => e.kind === "launch").length }; } return ledgerSeen.entries; } // The folder the session runs in: the state's own once it is written, else // the one `open` passed on the command line. Null while neither is known. const sessionWorktree = () => stateNow?.worktree || WORKTREE || null; // The Workspace, kept by workspace.mjs: workspace.json has one writer, this server. const workspace = serverWorkspace({ dir: DIR, project: PROJECT, worktree: sessionWorktree, state: () => stateNow, ledger: ledgerEntries, pushState: () => pushState(), }); /** * Open a conversation when there is none. A hop to another skill keeps it: * the person is still talking to the same agent, and switchWorkflow() carries * the agent's replies across, so only New conversation starts a new one. */ function ensureConversation(state) { if (!state) return; if (currentConversation(readChat(DIR)).conversation) return; const entry = appendChat(DIR, { kind: "reset", conversation: 1, workflow: state.workflow, reason: "start" }); appendEvent(DIR, { type: "chat-reset", reason: entry.reason }); } /* ------------------------------------------------------------ subagents */ // The Subagents switch, kept by settings.mjs: subagents-setting.json has one // writer, this server. const subagents = serverSubagents({ dir: DIR, worktree: sessionWorktree }); // Whether the agent driving this session is the desktop app: fixed for the // process's whole life (the env var that says so is set once, at spawn), so // read once rather than on every frame. The page uses it to drop advice that // only makes sense in a plain terminal (a command to copy into a new // conversation) in favor of the app's own Restart and Update skills buttons. const IN_APP = Boolean(inAppSignal()); // What the page needs to draw itself, in the shape of the SSE state frame. // `have` names that exact view, for the page to hand back when it opens its // stream (see /events). function stateFrame(state) { const { pending, stop } = resultFlags(); const chat = chatNow(state); return { rev, // The setup hand-over token is for the launcher only: the page gets // forCli, which is all the setup screen reads. state: state.setup ? { ...state, setup: { forCli: state.setup.forCli || null } } : state, agentLastSeen: agentLastSeen(), pendingResult: pending, pendingStop: stop, chat: { ...chat, offline: chatOfflineNow(state, chat) }, workspace: workspace.workspaceView(), meter: meterView(ledgerEntries()), subagents: subagents.view(state), inApp: IN_APP, ...(updateInfo ? { update: updateInfo } : {}), have: haveKey(), }; } function haveKey() { const { pending, stop } = resultFlags(); chatEntries(); chatPickedUp(); workspace.workspaceNow(); ledgerEntries(); subagents.settingNow(); subagents.capsNow(); return ( `${STARTED}.${rev}.${pending ? 1 : 0}${stop ? 1 : 0}.${chatSeen.stamp || ""}.${cursorSeen.stamp || ""}` + `.${workspace.stamp() || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}` + `.${subagents.stamps()}` ); } function touch() { lastContact = Date.now(); } // A tab closing: with no page left, the server stops two minutes from now // rather than at the end of the idle window. function closedTab() { if (clients.size === 0) lastContact = Date.now() - (IDLE_MS - 2 * 60 * 1000); } /* ------------------------------------------------------------------ SSE */ // Exactly one stream per page. Browsers cap HTTP/1.1 at ~6 connections per // origin, and an open stream holds one permanently; a second stream per tab // across three tabs wedges the origin with no error and no timeout. Everything // is multiplexed through this one channel with a `type` field. const clients = new Set(); function broadcast(type, data) { seq++; const payload = `id: ${seq}\nevent: ${type}\ndata: ${JSON.stringify(data)}\n\n`; for (const res of clients) { try { res.write(payload); } catch { clients.delete(res); } } } function pushState() { if (stateNow) broadcast("state", stateFrame(stateNow)); } /* --------------------------------------------------------- update check */ // The version this console was installed as: install.js writes version.json // beside console.mjs; a dev checkout falls back to the repo root's. function installedVersion() { for (const file of [path.join(HERE, "version.json"), path.join(HERE, "..", "..", "version.json")]) { const version = readJson(file, {}).version; if (typeof version === "string" && version) return version; } return null; } // Filled in once the boot-time check answers; until then, and whenever it // fails, the frame carries no `update` and the page shows no banner. let updateInfo = null; let updateLatest = null; // Started at boot and never awaited: git may take up to its 10 s limit, and // nothing the person sees waits on it. The catch is not optional: a throw in // pushState() would otherwise be an unhandled rejection, which ends the server. function startUpdateCheck() { const installed = installedVersion(); if (!installed) return; checkForUpdate({ installed, cacheFile: UPDATE_CHECK_FILE }) .then((result) => { updateLatest = result?.latest ?? null; updateInfo = result?.updateAvailable ? { installed: result.installed, latest: result.latest } : null; if (updateInfo) pushState(); }) .catch(() => {}); } let agentSeenAt = Date.now(); function agentLastSeen() { return new Date(agentSeenAt).toISOString(); } /* --------------------------------------------------------------- routes */ // The port this server answers on. Known before the server is: a handed-over // socket was bound by console.mjs, so `server.address()` has nothing to say. let PORT = 0; // What routes.mjs reads from this server. Getters and setters where the // value moves, so a handler always sees the live one. const ctx = { sid: SID, token: TOKEN, dir: DIR, project: PROJECT, files: { state: STATE_FILE, draft: DRAFT_FILE, result: RESULT_FILE }, port: () => PORT, get rev() { return rev; }, set rev(n) { rev = n; }, get browsers() { return browsers; }, set browsers(n) { browsers = n; }, clients, touch, closedTab, sawAgent: () => { agentSeenAt = Date.now(); }, agentLastSeen, readState, resultFlags, stateText: () => lastStateText, adoptStateText, stateFrame, haveKey, pushState, broadcast, chatEntries, chatOffline: chatOfflineNow, ensureConversation, worktree: sessionWorktree, workspace, subagents, installedVersion, updateLatest: () => updateLatest, }; const server = http.createServer((req, res) => handle(req, res, ctx)); /* ------------------------------------------------------- state watching */ // The agent writes state.json through `console.mjs post`, and the server only // through /submit; both under the state lock (updateState() in files.mjs), so // neither can write back a state read before the other's. Watch the DIRECTORY, // not the file: on Windows a watch on a file breaks the moment that file is // replaced by rename, which is exactly what an atomic write does. let watchTimer = null; let lastStateText = ""; let lastStateStamp = null; let stateNow = null; // A stat first, and a read only when the file has moved. The one-second poll // used to read and compare the whole file every second for the whole session. function checkState() { const stamp = fileStamp(STATE_FILE); if (stamp === lastStateStamp) return; try { const text = fs.readFileSync(STATE_FILE, "utf8"); if (text !== lastStateText) { const parsed = JSON.parse(text); // ignore a torn read; we will catch it on the next tick lastStateText = text; stateNow = parsed; rev++; agentSeenAt = Date.now(); try { ensureConversation(parsed); } catch {} try { subagents.sync(parsed); } catch {} try { workspace.followSpecDir(parsed); } catch {} pushState(); } lastStateStamp = stamp; } catch {} } function adoptStateText(text, state) { lastStateText = text; lastStateStamp = fileStamp(STATE_FILE); stateNow = state; } // On Windows, fs.watch can ABORT the process outright: libuv asserts that the // name a change is reported under starts with the dir it was asked to watch, // and a dir spelled with an 8.3 short name (a TEMP like C:\Users\JUSTIN~1.PAR) // reports the long form instead. An assert is not a JS exception -- no catch // reaches it -- so the only safe move is not to watch such a path. The 1s // poll below keeps the page current regardless; the watch only saves a beat. // A segment that merely looks like ~N costs nothing: we poll instead. const WIN_SHORT_NAME = /(^|[\\/])[^\\/]*~\d/; if (process.platform !== "win32" || !WIN_SHORT_NAME.test(DIR)) { try { fs.watch(DIR, { persistent: false }, (_e, name) => { if (name === "state.json") { clearTimeout(watchTimer); watchTimer = setTimeout(checkState, 25); } }); } catch {} } // The cursor has no watcher of its own: the next poll tick pushes a pickup. function checkCursor() { const before = cursorSeen.stamp; chatPickedUp(); if (cursorSeen.stamp !== before) pushState(); } // The ledger likewise: a moved stamp is a new meter count or folder issue, and // a new launch is a new skill run, which re-checks that every folder is there. // Measured against what this check last handled, not against the read cache: // every frame refreshes that cache, and `open` writes state.json just before // it appends the launch, so the frame that change pushes has usually read the // launch already. let ledgerChecked = { stamp: null, launches: 0 }; function checkLedger() { ledgerEntries(); if (ledgerSeen.stamp === ledgerChecked.stamp) return; const newLaunch = ledgerSeen.launches > ledgerChecked.launches; ledgerChecked = { stamp: ledgerSeen.stamp, launches: ledgerSeen.launches }; if (newLaunch) workspace.checkFolders(workspace.workspaceNow()); pushState(); } setInterval(() => { checkState(); checkCursor(); try { checkLedger(); } catch {} }, 1000).unref(); /* ------------------------------------------------------------ heartbeat */ setInterval(() => { for (const res of clients) { try { res.write(": keepalive\n\n"); } catch { clients.delete(res); } } browsers = clients.size; }, 15000).unref(); /* ------------------------------------------------------- idle deadline */ // This is the mechanism, not a nicety. // // Windows has no real SIGTERM, Node only synthesizes SIGINT for Ctrl+C on an // attached console, and this process is detached with no console at all. // taskkill /F and Task Manager give zero cleanup opportunity. A Job Object with // KILL_ON_JOB_CLOSE would be the proper fix and needs native code, which is out // under zero-dependencies. So the only thing that reliably stops an orphan is // the server deciding to stop. Do not "optimize" this away. setInterval(() => { const idle = Date.now() - lastContact; // Answers nobody has collected yet keep the server up, past the idle limit // and past MAX_LIFE_MS alike: exiting would strand the tab and the send it // holds. Once a `wait` collects them (consumedAt) both limits apply again. const pending = resultFlags().pending; if (idle > IDLE_MS && !pending) { // The log is advisory: a failed append must never keep an orphan server alive. try { appendEvent(DIR, { type: "exit", reason: "idle", idleMs: idle }); } catch {} process.exit(0); } if (Date.now() - STARTED > MAX_LIFE_MS && !pending) { try { appendEvent(DIR, { type: "exit", reason: "max-life" }); } catch {} process.exit(0); } }, 20000).unref(); for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) { try { process.on(sig, () => process.exit(0)); } catch {} } // A throw inside a request callback (a read or write failing on a locked file) // must not end the detached server: note it and carry on. The page retries. process.on("uncaughtException", (e) => { try { appendEvent(DIR, { type: "error", message: String(e?.message || e).slice(0, 200) }); } catch {} }); // Every exit that gets to run code takes its handle file with it, so a pid // left behind in the runtime dir cannot later be mistaken for this server once // the number is reused. Only while the file still names THIS process: a // resume may already have started a replacement that wrote its own handle. // A hard kill skips this, and reapHandles() plus stop's /health check cover it. process.on("exit", () => { try { const file = handleFile(PROJECT, SID); if (readJson(file)?.pid === process.pid) fs.rmSync(file, { force: true }); } catch {} }); /* --------------------------------------------------------------- listen */ server.on("error", (err) => { process.stderr.write(`server: ${err.message}\n`); process.exit(1); }); // Node's default keep-alive is 5s, which is exactly the page's ping interval. // A client that reuses a socket the server just closed gets an ECONNRESET, so // hold idle sockets open comfortably longer than any interval we run. // headersTimeout must stay above keepAliveTimeout or Node closes them anyway. server.keepAliveTimeout = 65000; server.headersTimeout = 70000; // No response timeout: the SSE stream is meant to stay open indefinitely. server.timeout = 0; // Ephemeral port from the OS (RFC 8252 section 7.3, and Jupyter's pattern). // A fixed port would be silently wrong the moment two worktrees of one repo // run a session at the same time. // // Usually the port is already chosen by the time this runs. `open` binds the // socket itself and hands it over the IPC channel (--handoff), so it can send // the browser on its way before this process has even booted: the browser // takes most of a second to show up, and its request simply waits in the // socket's queue until this server takes the socket. A connection that // reached `open` before the handover arrives here as a socket of its own. // With no channel, or no socket within a few seconds, it picks its own port, // and `open` sees the different port in the handle and says so. let listening = false; function onListening(port) { if (listening) return; listening = true; PORT = port; const url = TOKEN ? `http://127.0.0.1:${port}/s/${TOKEN}/` : `http://127.0.0.1:${port}/`; const handle = { v: 1, sid: SID, pid: process.pid, port, token: TOKEN, url, project: PROJECT, stateDir: DIR, startedAt: nowIso(), }; // The handle holds the session token: private to this user on a shared /tmp. ensureDir(path.dirname(handleFile(PROJECT, SID)), 0o700); writeJsonAtomic(handleFile(PROJECT, SID), handle, 0o600); appendEvent(DIR, { type: "listening", port, pid: process.pid }); checkState(); // A resume through a fresh server still starts a new conversation on a hop. try { ensureConversation(readState()); } catch {} try { workspace.bootWorkspace(); } catch {} try { subagents.sync(readState()); } catch {} // stdout is server.log (`open` points it there), so the ready line names // the server without the token segment: the log is not a place for it. The // full link lives only in the handle file, which is private to this user. process.stdout.write(JSON.stringify({ type: "ready", url: `http://127.0.0.1:${port}/`, port, sid: SID }) + "\n"); try { startUpdateCheck(); } catch {} try { process.send?.({ type: "listening", port }); } catch {} // Warm the asset cache while the browser is still on its way. Not with a // game's songs: megabytes read for a game that may never be played. setImmediate(() => { for (const rel of SERVABLE) { if (rel.startsWith("activities/") && rel.endsWith(".mp3")) continue; try { asset(rel); } catch {} } }); } function listenOwn() { if (listening) return; server.listen(0, "127.0.0.1", () => onListening(server.address().port)); } if (args.handoff && typeof process.send === "function") { const fallback = setTimeout(listenOwn, 3000); process.on("message", (msg, handle) => { if (msg && msg.type === "own") { clearTimeout(fallback); return listenOwn(); } if (!msg || !handle) return; if (msg.type === "listen" && !listening) { clearTimeout(fallback); server.listen(handle, () => onListening(Number(msg.port) || handle.address().port)); } else if (msg.type === "conn") { server.emit("connection", handle); handle.resume(); // `open` waits for this before it lets go of the channel. try { process.send({ type: "conn-held" }); } catch {} } }); // `open` lets go of the channel once the handover is done. That is the end // of the conversation, not of this server. process.on("disconnect", () => {}); process.channel?.unref?.(); } else { listenOwn(); }