toolroll 0.9.103 → 0.9.105

package/dist/server/terminals.js

@@ -1,19 +1,3 @@
-/**
- * Live terminals over the console (docs/plans/live-terminal.md): the Live page, its state, start/close/remove, and the
- * WebSocket a page attaches with.
- *
- * A terminal is shell-equivalent on this computer, so every road is the coding workspace's: a browser sign-in of an
- * installation-wide operator (codingActorAllowed), a project the coding workspace admits, and a fresh password to
- * start one. The socket is not a route-table row (an upgrade never reaches the request handler); it re-checks
- * everything the console's request path checks, and more, BEFORE the upgrade is accepted:
- *
- *   host allowlisted → HTTPS or a private path (this computer, the tailnet) → Origin exactly this page's own origin →
- *   no token or Authorization → cookie session, re-proved against the database → operator of the same generation →
- *   the terminal is theirs and its project still admitted → a viewer slot free.
- *
- * While open, the same proof runs before every input frame, before output once it is a second old, every 5 s, and at
- * once on every database change (the live bus); a failure closes the socket with 4401.
- */
 import { randomBytes } from "node:crypto";
 import { STATUS_CODES } from "node:http";
 import { dirname, join } from "node:path";
@@ -31,14 +15,11 @@ import { handlersOf } from "./handler-registry.js";
 import { respond } from "./http.js";
 import { rereadBrowser } from "./live.js";
 const TERMINAL_ID = /^\/term\/([a-f0-9]{32})(?:\/(socket|close|remove))?$/;
-/** A viewer this far behind is dropped; its page reconnects and replays the scrollback. */
 const BEHIND_BYTES = 4 * 1024 * 1024;
-/** Typed input per socket: a burst of this many bytes, refilled at this many a second. */
 const INPUT_BURST = 256 * 1024;
 const INPUT_PER_SECOND = 256 * 1024;
 const REPROVE_MS = 1_000;
 const SWEEP_MS = 5_000;
-/** The console's terminal host: on a machine that runs agents, when this install has a pty library; else why not. */
 export function terminalHostFor(store, options) {
     if (options.terminalHost !== undefined)
         return { host: options.terminalHost, problem: options.terminalHost === null ? "Terminals are off on this console." : null };
@@ -56,15 +37,9 @@ export function createTerminalHandlers(runtime, deps) {
     const transportOfRequest = (request) => transportOf({ peer: request.socket.remoteAddress, joinSource: deps.forwardedSourceOf(request),
         forwardedProto: request.headers["x-forwarded-proto"], forwarded: request.headers["forwarded"] });
     const sockets = new Set();
-    // Easy-start C2: a page offers `toolroll` and, on a protected loopback install, `toolroll.key.<key>`; only `toolroll` is
-    // ever selected, so the key is never echoed.
     const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME_BYTES, perMessageDeflate: false,
         handleProtocols: protocols => protocols.has(KEY_PROTOCOL) ? KEY_PROTOCOL : false });
-    /** An operator signed in with a browser, of the generation they signed in with; else null. */
-    const operatorOf = (who) => 
-    // Easy-start C1: never a local owner's session (a laptop's passwordless owner), for a new terminal or an existing one.
-    who?.via === "cookie" && who.authority === "full" && who.role === "approver" && !store.isDemo() && codingActorAllowed({ name: who.name, generation: who.session.generation }) ? who : null;
-    /** The project a terminal works in is one the coding workspace admits for this person, now. */
+    const operatorOf = (who) => who?.via === "cookie" && who.authority === "full" && who.role === "approver" && !store.isDemo() && codingActorAllowed({ name: who.name, generation: who.session.generation }) ? who : null;
     const projectAllowed = (name, repo) => rowVisible(liveCeiling(), repo) && store.accountCanAccess(name, repo) && codingProjectAllowed(repo);
     const owned = (who, terminal) => terminal !== null && terminal.owner === who.name && terminal.generation === who.session.generation;
     const record = (event, who, terminal) => logEvent("info", `terminal.${event}`, { actor: who, terminal: terminal.id, repo: terminal.repo, program: terminal.program });
@@ -76,7 +51,6 @@ export function createTerminalHandlers(runtime, deps) {
             return deps.problem ?? "Terminals aren't available on this install.";
         return null;
     };
-    /** The Live page: its own small document and bundle. */
     async function page(ctx) {
         const { who, url, response, request } = ctx;
         if (operatorOf(who) === null)
@@ -87,7 +61,6 @@ export function createTerminalHandlers(runtime, deps) {
         const document = html `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content"><meta name="theme-color" content="#0C0E12"><meta name="apple-mobile-web-app-capable" content="yes"><title>Terminals — Toolroll</title><link rel="icon" href="/icon.svg"><link rel="manifest" href="/manifest.webmanifest"><link rel="stylesheet" href="/assets/terminal.css"></head><body><div id="so-term"></div><div id="so-term-boot" hidden data-csrf="${who.session.csrf}" data-session="${id}" data-passwordless="${passwordlessOn(store) ? "1" : ""}"></div><script type="module" src="/assets/terminal.js" nonce="${nonce}"></script></body></html>`;
         response.writeHead(200, {
             "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", "Referrer-Policy": "no-referrer",
-            // The socket is this page's own host: named outright, since older WebKit doesn't read 'self' as ws:/wss:.
             "Content-Security-Policy": `default-src 'none'; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self'; manifest-src 'self'; script-src 'nonce-${nonce}'; connect-src 'self' ws://${host} wss://${host}; form-action 'self'; base-uri 'none'; frame-ancestors 'none'`,
         });
         response.end(htmlString(document));
@@ -117,7 +90,6 @@ export function createTerminalHandlers(runtime, deps) {
             return json(ctx, 400, { ok: false, error: "Choose Claude Code, Codex or a shell." });
         if (!runtime.consoleProjects().includes(repo) || !projectAllowed(who.name, repo))
             return json(ctx, 403, { ok: false, error: "Choose a project available to your account." });
-        // The organisation's policy decides whether this provider may run in a person's own session.
         if (program !== "shell") {
             const stopped = store.sessionPolicyRefusal(program, null, "live terminals");
             if (stopped !== null)
@@ -125,8 +97,6 @@ export function createTerminalHandlers(runtime, deps) {
         }
         if (!runtime.authenticateApprover(who, body.get("password") ?? "").ok)
             return json(ctx, 403, { ok: false, error: "Enter your Toolroll password to start a terminal." });
-        // The same session, still an operator of the same generation, and the project still theirs: asked right before the
-        // program starts (after the slow worktree work) and again once it has.
         const stillAllowed = () => {
             const again = rereadBrowser(runtime, ctx.request, who);
             if (again === null || operatorOf(again) === null)
@@ -137,7 +107,6 @@ export function createTerminalHandlers(runtime, deps) {
             const terminal = await deps.host.start({ name: who.name, generation: who.session.generation }, repo, program, undefined, stillAllowed);
             const after = stillAllowed();
             if (after !== null) {
-                // Nothing of it stays: the program is swept, then its worktree removed (a sweep that can't prove itself keeps it).
                 await deps.host.close(terminal.id);
                 await deps.host.remove(terminal.id).catch(() => { });
                 return json(ctx, 403, { ok: false, error: after });
@@ -169,28 +138,24 @@ export function createTerminalHandlers(runtime, deps) {
             return json(ctx, 409, { ok: false, error: error instanceof TerminalError ? error.message : `The terminal couldn't be ${verb === "close" ? "closed" : "removed"}.` });
         }
     };
-    /** A plain GET of the socket address: it only answers an upgrade. */
     async function socketWithoutUpgrade(ctx) {
         ctx.response.setHeader("Upgrade", "websocket");
         return respond(ctx.response, 426, "text/plain; charset=utf-8", "This address answers a WebSocket upgrade only.");
     }
-    // ---- the socket ------------------------------------------------------------------------------------------------
     const reprovers = new Set();
     const unsubscribe = deps.bus.subscribe(() => { for (const reprove of [...reprovers])
         reprove(); });
     const sweep = setInterval(() => { for (const reprove of [...reprovers])
         reprove(); }, SWEEP_MS);
     sweep.unref?.();
-    /** Answer a refused upgrade in plain HTTP and drop the connection. */
     const refuseUpgrade = (socket, status, words) => {
         const body = `${words}\n`;
         try {
             socket.end(`HTTP/1.1 ${status} ${STATUS_CODES[status] ?? ""}\r\nConnection: close\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(body)}\r\nCache-Control: no-store\r\n\r\n${body}`);
         }
-        catch { /* already gone */ }
+        catch { }
         socket.destroy();
     };
-    /** True when this request was an upgrade for a terminal (answered or refused here); false leaves it to others. */
     function upgrade(request, socket, head) {
         let url;
         try {
@@ -222,7 +187,6 @@ export function createTerminalHandlers(runtime, deps) {
             refuseUpgrade(socket, 403, "Open the console over HTTPS to use a terminal from here.");
             return true;
         }
-        // Exactly the origin of a page served at this host, over this transport (the public https origin for its host).
         const expected = deps.publicOrigin !== null && host === deps.publicOrigin.host ? deps.publicOrigin.origin : `${transport.https ? "https" : "http"}://${host}`;
         if (request.headers.origin !== expected) {
             refuseUpgrade(socket, 403, "A terminal opens only from this console's own page.");
@@ -232,14 +196,11 @@ export function createTerminalHandlers(runtime, deps) {
             refuseUpgrade(socket, 403, "Terminals open with a browser sign-in only.");
             return true;
         }
-        // Read without touching: a session ended elsewhere is never written back by being seen (round 2, finding 1).
         const who = operatorOf(runtime.identify(request, false));
         if (who === null || rereadBrowser(runtime, request, who) === null) {
             refuseUpgrade(socket, 401, "Sign in as an installation-wide operator.");
             return true;
         }
-        // Easy-start C2: typing into a terminal is a mutation: on a protected loopback install the socket offers the session's
-        // key (its protocol list), which a cookie holder on another port can't read.
         const keyed = runtime.browserKeys.check(who, request, null);
         if (keyed !== null) {
             refuseUpgrade(socket, keyed.status, keyed.message);
@@ -274,7 +235,6 @@ export function createTerminalHandlers(runtime, deps) {
             catch {
                 ws.terminate();
             }
-            // A peer that never answers the close is dropped outright.
             setTimeout(() => ws.terminate(), 2_000).unref?.();
         };
         const prove = () => {
@@ -325,7 +285,6 @@ export function createTerminalHandlers(runtime, deps) {
             if (size > budget)
                 return shut(1008, "typing faster than a terminal reads");
             budget -= size;
-            // The program isn't reading: nothing more is queued for it until it does (round 2, finding 5).
             if (!host.input(terminal.id, frame.d))
                 ws.send(JSON.stringify({ t: "input-full" }));
         });
@@ -357,8 +316,6 @@ export function createTerminalHandlers(runtime, deps) {
             "term.socket": socketWithoutUpgrade,
         }),
         upgrade,
-        /** Shutdown: no more attaches, every socket dropped, every program ended (bounded by the host's grace). The problem,
-         * when a terminal's processes couldn't be proved stopped. */
         async close() {
             unsubscribe();
             clearInterval(sweep);
@@ -369,7 +326,6 @@ export function createTerminalHandlers(runtime, deps) {
             const stopped = await deps.host?.stop();
             if (stopped !== undefined && !stopped.clean) {
                 logEvent("error", "terminal.shutdown-uncertain", {});
-                // Reported, never thrown: the server still closes, and its close callback carries this (serve.ts).
                 return new Error("A live terminal's processes could not be proved stopped. Check for them before replacing Toolroll.");
             }
             return null;

package/dist/server/welcome.js

@@ -1,12 +1,3 @@
-/**
- * The first run's own page, /welcome (src/design/KIT.md): three steps to a first result, Agent · Project · First task,
- * told by first-run.ts's one model (welcomeModel) from live facts on every render, never a stored cursor. The page
- * reads; its acts are the ones that already own each change: choosing the agent posts to Settings → Lead's own
- * turn-on (/settings/lead/on), a folder and GitHub link to Projects, and the sample project is made and added here
- * (POST /welcome/sample) the way Projects adds a folder (project-admission.ts). A first task's starter only drafts its
- * words into New task's box: nothing is filed until the person sends it. Once the first result has arrived (or for a
- * project-limited account, or in the demo) the address leads Home.
- */
 import { resolvePhaseAgent } from "../agentconfig.js";
 import { CONSOLE_FORMS, readForm } from "../contracts/console-api.js";
 import { builderReadyFor, firstRunBuilderRepo } from "../dispatch.js";
@@ -20,7 +11,6 @@ import { refuse, screen } from "./chrome.js";
 import { handlersOf } from "./handler-registry.js";
 import { redirect } from "./http.js";
 import { btn, chip, codeLine, dock, note, notice, pageHeader, settingsRecord } from "./kit.js";
-/** Why the sample project wasn't added, as a fixed key in the address (never words from it). */
 export const SAMPLE_PROBLEMS = {
     "no-root": "There's no project folder to put the sample in. Add a folder instead.",
     exists: `A folder named ${SAMPLE_PROJECT_NAME} is already there and wasn't made here, so nothing was changed.`,
@@ -32,12 +22,10 @@ const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
 const AGENT_WORDS = { "signed-in": "Signed in", "signed-out": "Not signed in", "not-installed": "Not installed", checking: "Checking…" };
 const PROJECTS_SHOWN = 3;
 const ADD_FOLDER = "/projects?return=%2Fwelcome";
-/** One step: its number and name, Done once it is, then its body. */
 function step(key, index, title, done, body) {
     return html `<section class="k-sec welcome-step" id="welcome-${key}" data-step="${key}" data-done="${done ? "1" : "0"}" aria-labelledby="welcome-${key}-h">\
 <div class="k-secthead"><h3 id="welcome-${key}-h">${index}. ${title}</h3>${done ? chip("Done", "done") : ""}</div>${body}</section>`;
 }
-/** "Use this one": Settings → Lead's own turn-on, for exactly this agent, back here. */
 const useForm = (agent, button) => postForm("/settings/lead/on", button, { hidden: { agent, return: "/welcome" } });
 function agentRow(agent, leads) {
     const sub = agent.command === null ? AGENT_WORDS[agent.state]
@@ -47,8 +35,6 @@ function agentRow(agent, leads) {
             : "";
     return settingsRecord({ title: agent.name, sub, action, attrs: { "data-agent": agent.id, "data-state": agent.state } });
 }
-/** The page body for one model, and the screen's one primary (for the phone dock). `problem`: why the sample project
- * wasn't added, from the address. `canAdd`: this person may add projects here. */
 export function welcomeBody(model, options) {
     const lead = model.next;
     let primary = null;
@@ -87,7 +73,8 @@ ${listed.length === 0 ? "" : html `<div class="welcome-rows">${listed}</div>`}${
     const taskLeads = lead === "task";
     if (taskLeads)
         primary = btn("Write a task", { variant: "primary", href: "/tasks/new" });
-    const taskBody = model.task.done ? html `<p class="k-note">Filed. Its plan waits for your approval in <a class="k-link" href="/tasks">Tasks</a>.</p>`
+    const taskBody = model.task.done ? !model.agent.done && !model.agent.checking ? html `<p class="k-note">Filed. It starts by itself once an agent is signed in (step 1).</p>`
+        : html `<p class="k-note">Filed. Its plan waits for your approval in <a class="k-link" href="/tasks">Tasks</a>.</p>`
         : !model.task.open ? html `<p class="k-note">Add a project first.</p>`
             : html `<p class="k-note">Describe a change in a sentence or two. Nothing starts until you approve its plan.</p>\
 ${model.task.starters.length === 0 ? "" : html `<div class="k-ideas" aria-label="Ideas to start from" data-starters>${model.task.starters.map(one => html `<a class="k-btn k-btn-outline k-idea" href="${one.href}">${one.label}</a>`)}</div>`}\
@@ -106,10 +93,8 @@ export function createWelcomeHandlers(runtime) {
     async function showWelcome(ctx) {
         const { who, response, now, project, url } = ctx;
         const steps = withBuilderStep(firstRunStepsNow(now), builderReadyFor(store, firstRunBuilderRepo(store, project, visible, managedRepos()), now));
-        // The first run is over (a first result, a project-limited account, the demo): the address leads Home.
         if (steps === null)
             return redirect(response, "/");
-        // The projects the sidebar lists (a sample added here included).
         const chrome = chromeFor(project, "work");
         const projects = (chrome.projects ?? []).map(one => ({ name: one.name, path: one.path }));
         const repo = project ?? projects[0]?.path ?? null;
@@ -132,8 +117,6 @@ export function createWelcomeHandlers(runtime) {
         const asked = url.searchParams.get("sample");
         return sendScreen(response, 200, welcomePage(chrome, model, { problem: isSampleProblem(asked) ? asked : null, canAdd: approver && !store.isDemo() }));
     }
-    /** Try a sample project: made in the project folder (or found again when it is ours), then added the way Projects
-     * adds a folder, and opened. A refusal comes back to the welcome as a fixed key. */
     async function addSample(ctx) {
         const { who, response, now, posted } = ctx;
         readForm(posted, CONSOLE_FORMS.welcomeSample);
@@ -145,7 +128,6 @@ export function createWelcomeHandlers(runtime) {
         const made = await createSampleProject(liveCeiling().roots[0] ?? null);
         if (!made.ok)
             return back(made.reason);
-        // Added exactly as Projects adds a folder: inside what this console serves, visible to this person, a git repository.
         const decidedOn = identities.generation();
         const canonical = await identities.resolveNow(made.path);
         if (canonical === null || canonical === "no-answer" || !(await authorizedProject(liveCeiling(), canonical)) || !visible(canonical))
@@ -154,8 +136,6 @@ export function createWelcomeHandlers(runtime) {
         const admitted = await admitProject(store, { registryFile: options.registryPath ?? null, path: canonical, actor: { label: who.name, origin: "console" }, now, stillAllowed, resolveFolder: identities.resolveNow });
         if (!admitted.ok || !stillAllowed(admitted.repo))
             return back("not-added");
-        // Its own fixed check (sample-project.ts), so the first result reads checked rather than "Checks not run": only for a
-        // sample this request just made, never one found again.
         registerSampleCheck(store, made, admitted.repo, who.name, now);
         deletedRepos.delete(admitted.repo);
         who.session.project = admitted.repo;

package/dist/server-telemetry.js

@@ -1,14 +1,11 @@
-/** Bounded, in-memory performance measurements. Never retain URLs, SQL, or identities. */
 import { monitorEventLoopDelay } from 'node:perf_hooks';
 export const TELEMETRY_WINDOW_MS = 300_000;
 const SLICE_MS = 10_000;
-/** monitorEventLoopDelay samples by sleeping this long, so every raw sample includes it. */
 const EVENT_LOOP_RESOLUTION_MS = 20;
 export const LATENCY_BUCKETS = [0.0001, 0.00025, 0.0005, 0.001, 0.0025, 0.005, 0.01, 0.015, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 15, 30, 60];
 export const ROUTE_FAMILIES = ['cli', 'mcp', 'team', 'live', 'chat', 'flows', 'tasks', 'results', 'decisions', 'sessions', 'settings', 'projects', 'assets', 'auth', 'metrics', 'health', 'console', 'other'];
 export const STREAM_FAMILIES = ['live', 'other'];
 export const QUEUE_BUCKETS = [0, 1024, 4096, 16384, 65536, 262144, 1048576];
-/** Only literals from the allowlist can become labels, including for unknown or malformed paths. */
 export function routeFamily(raw) {
     let path;
     try {
@@ -79,7 +76,6 @@ const summary = (value) => {
     };
     return { count: value.count, p50Ms: percentile(0.5), p99Ms: percentile(0.99), maxMs: value.count ? value.max * 1000 : null, totalMs: value.sum * 1000 };
 };
-/** Lifetime histogram plus a ring of ten-second slices. Cost and memory do not grow with traffic. */
 export class TimingHistogram {
     clock;
     total = counts();
@@ -165,10 +161,6 @@ export class ServerTelemetry {
         this.monitor = undefined;
         this.timer = undefined;
     }
-    /**
-     * Native nanosecond samples, folded into bounded buckets once a second, never one retained object per tick.
-     * Each raw sample includes the sampling timer's own interval, so it is subtracted: an idle loop reads near zero.
-     */
     sampleEventLoop() {
         const h = this.monitor;
         if (!h || !h.count)
@@ -220,7 +212,6 @@ export class ServerTelemetry {
         };
     }
 }
-/** SSE latency is time to opening headers; a live view's lifetime is not request work. */
 export function instrumentRequest(telemetry, request, response) {
     const family = routeFamily(request.url ?? '/'), started = telemetry.clock();
     let recorded = false;