scenescout 1.2.0 → 1.3.0

package/dist/engine/live.js

@@ -0,0 +1,549 @@
+/**
+ * The live view: what every session is doing right now, and what it is
+ * looking at.
+ *
+ * status.json used to hold ONE line for the whole project, last write wins. With
+ * several sessions attached that line describes whichever session happened to
+ * finish a call most recently, which is the opposite of what someone watching a
+ * multi-role run needs. The StatusBoard keeps one entry per session instead.
+ *
+ * The LiveServer puts that board, a thumbnail and an optional live stream of
+ * each session's page behind a small HTTP server. It exists for a person
+ * watching a run, and it holds to the rules in ADR 7:
+ *
+ *  - it binds 127.0.0.1 only and refuses a Host header that is not loopback,
+ *    so neither the network nor a DNS-rebinding page can reach it;
+ *  - every path starts with a random token, handed over in the scout_attach
+ *    result and, for `scenescout watch`, through a file only the owner can read;
+ *  - it answers GET and nothing else: a viewer can look, never act;
+ *  - a frame is held in memory and sent to the viewer. None is written to disk,
+ *    because the page may be showing somebody's real data.
+ *
+ * Nothing here imports Playwright. The engine is reached through LiveProvider,
+ * so the whole module is tested over real HTTP with a fake provider.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { LIVE_PAGE } from "./live-page.js";
+import { JOURNEY_END, JOURNEY_START } from "./memory.js";
+/** Holds the live view's token, next to status.json. Written owner-only; removed when the engine shuts down. */
+export const LIVE_TOKEN_FILE = "live-token";
+/** `SCENESCOUT_LIVE=off` keeps the engine from opening the live view's port at all. */
+export const LIVE_ENV = "SCENESCOUT_LIVE";
+/**
+ * One session's most recent actions, oldest first, each tagged with the
+ * journey it belonged to. The log is project-wide and interleaves every
+ * session, and a journey is delimited in it by its own `journey:start` and
+ * `journey:end` lines, so the walk goes back past the window until it finds
+ * the marker that says whether the window's first lines were inside one.
+ */
+export function feedForSession(log, session, limit, redact = (s) => s) {
+    const mine = [];
+    let i = log.length - 1;
+    for (; i >= 0 && mine.length < limit; i -= 1) {
+        const e = log[i];
+        if (e && (e.session ?? session) === session)
+            mine.push(e);
+    }
+    let objective;
+    for (; i >= 0; i -= 1) {
+        const e = log[i];
+        if (!e || (e.session ?? session) !== session)
+            continue;
+        if (e.action === JOURNEY_END)
+            break;
+        if (e.action === JOURNEY_START) {
+            objective = e.target;
+            break;
+        }
+    }
+    const lines = [];
+    for (const e of mine.reverse()) {
+        if (e.action === JOURNEY_START)
+            objective = e.target;
+        const line = { at: e.at, action: e.action, url: redact(e.url) };
+        if (e.target !== undefined)
+            line.target = e.target;
+        if (e.result !== undefined)
+            line.result = e.result;
+        if (objective !== undefined)
+            line.objective = objective;
+        lines.push(line);
+        if (e.action === JOURNEY_END)
+            objective = undefined;
+    }
+    return lines;
+}
+/** How many feed lines a status poll carries per session. Enough to read the last move at a glance; the close-up asks for more. */
+export const FEED_LINES = 6;
+/** The cap the close-up gets. A long run's log is thousands of lines and none of it needs to reach the page. */
+export const FEED_LINES_MAX = 60;
+/**
+ * How long a call may run before the session is judged wedged rather than
+ * busy, when the entry does not carry the tool's own watchdog budget (an
+ * engine from before budgets were recorded). Each tool's real budget is what
+ * `classify` uses when it is there: a healthy crawl runs for minutes.
+ */
+export const STUCK_AFTER_MS = 120_000;
+export class StatusBoard {
+    now;
+    entries = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    update(session, fields) {
+        const prev = this.entries.get(session);
+        const at = new Date(this.now()).toISOString();
+        // `since` survives repeated writes of the same phase of the same tool:
+        // that is what lets a reader tell a long-running call from a fresh one.
+        const since = prev && prev.phase === fields.phase && prev.tool === fields.tool ? prev.since : at;
+        const next = { session, ...fields, since, at };
+        this.entries.set(session, next);
+        return next;
+    }
+    remove(session) {
+        this.entries.delete(session);
+    }
+    clear() {
+        this.entries.clear();
+    }
+    has(session) {
+        return this.entries.has(session);
+    }
+    /** Sorted by name, so a poller sees a stable order rather than insertion order. */
+    list() {
+        return [...this.entries.values()].sort((a, b) => a.session.localeCompare(b.session));
+    }
+}
+export function classify(status, nowMs, stuckAfterMs = STUCK_AFTER_MS) {
+    if (status.phase !== "running")
+        return "idle";
+    // Past its own budget the watchdog should have ended the call; a call still
+    // running there has outlived the thing that was meant to stop it.
+    return nowMs - new Date(status.since).getTime() > (status.budgetMs ?? stuckAfterMs) ? "stuck" : "running";
+}
+export function formatDuration(ms) {
+    const total = Math.max(0, Math.floor(ms / 1000));
+    if (total < 60)
+        return `${total}s`;
+    const minutes = Math.floor(total / 60);
+    if (minutes < 60)
+        return `${minutes}m${String(total % 60).padStart(2, "0")}s`;
+    return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
+}
+/**
+ * A log timestamp on the reader's own clock, 24-hour. The log stores UTC, and
+ * a time sliced straight out of it reads an hour or more off the person's
+ * watch, which makes a live feed look stale.
+ */
+export function localClock(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return "";
+    return [d.getHours(), d.getMinutes(), d.getSeconds()].map((n) => String(n).padStart(2, "0")).join(":");
+}
+/** One line per session for the terminal (`scenescout status`). */
+export function formatSessionLine(status, nowMs) {
+    const state = classify(status, nowMs);
+    const held = formatDuration(nowMs - new Date(status.since).getTime());
+    const what = state === "idle" ? `· idle ${held} after ${status.tool}` : `${state === "stuck" ? "⚠ STUCK" : "⏳"} ${status.tool} for ${held}`;
+    return `${status.session} (${status.role}) ${what}${status.url ? ` — ${status.url}` : ""}`;
+}
+const statusWrites = new Map();
+/**
+ * Write status.json so that a reader never sees a torn file. Writes to one
+ * directory are queued behind each other, and each lands by rename, so two
+ * calls in the same tick cannot leave a short document with the tail of a
+ * longer one after it (which is what overlapping `writeFile`s produced).
+ * Best-effort: a failed write is dropped and the next one lands.
+ */
+export function writeStatusFile(dir, body) {
+    const file = path.join(dir, "status.json");
+    const tmp = `${file}.${process.pid}.tmp`;
+    const next = (statusWrites.get(dir) ?? Promise.resolve())
+        .then(() => fs.promises.writeFile(tmp, body))
+        .then(() => fs.promises.rename(tmp, file))
+        .catch(() => fs.promises.rm(tmp, { force: true }).catch(() => { }));
+    statusWrites.set(dir, next);
+    return next;
+}
+/** The entries of a status file that are whole enough to describe. A truncated write or an older engine can leave others. */
+export function wholeSessions(detail) {
+    return (detail ?? []).filter((e) => typeof e.session === "string" &&
+        typeof e.tool === "string" &&
+        typeof e.role === "string" &&
+        typeof e.url === "string" &&
+        (e.phase === "running" || e.phase === "idle") &&
+        typeof e.since === "string" &&
+        Number.isFinite(Date.parse(e.since)));
+}
+/**
+ * Where `scenescout watch` should send the browser, or why it cannot.
+ *
+ * status.json and the token file sit inside the project under test, so a
+ * repository can ship its own. Both values are therefore checked for shape
+ * before they are put into a URL, and the host is never read from the file.
+ */
+export function watchTarget(input) {
+    const { status, alive, token } = input;
+    if (!status)
+        return { problem: "No SceneScout engine has attached to this project yet. Start a run, then run this again." };
+    if (status === "unreadable")
+        return { problem: "The status file is unreadable or truncated: the engine was probably killed mid-write. Attach again to rewrite it." };
+    if (!alive)
+        return { problem: `The engine that last ran here (pid ${status.pid ?? "?"}) is not running. The live view exists only while a run is attached.` };
+    if (status.live?.error)
+        return { problem: `The engine could not open the live view: ${status.live.error}` };
+    const port = status.live?.port;
+    if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) {
+        return {
+            problem: `This engine is not serving a live view: it was started with ${LIVE_ENV}=off, or it is a version from before the live view existed. Restart the MCP server to pick it up.`,
+        };
+    }
+    const clean = token?.trim() ?? "";
+    if (!/^[A-Za-z0-9_-]{16,128}$/.test(clean))
+        return {
+            problem: `The live view's token file (${LIVE_TOKEN_FILE}) is missing or unreadable. It is written when a session attaches; if a run is attached and it is still missing, the engine could not write into the project directory.`,
+        };
+    return { url: `http://127.0.0.1:${port}/${clean}/` };
+}
+const LIVE_CSP = "default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; base-uri 'none'; form-action 'none'";
+const BOUNDARY = "scenescoutframe";
+/** A thumbnail younger than this is served again instead of taking a new one. */
+export const SHOT_MAX_AGE_MS = 1500;
+/** A viewer this far behind is skipped for a frame rather than buffered without bound. */
+const MAX_VIEWER_BACKLOG_BYTES = 4_000_000;
+export class LiveServer {
+    provider;
+    now;
+    server = null;
+    port = 0;
+    token = "";
+    streams = new Map();
+    shots = new Map();
+    shotsInFlight = new Map();
+    constructor(provider, now = Date.now) {
+        this.provider = provider;
+        this.now = now;
+    }
+    async start() {
+        if (this.server)
+            return { port: this.port, token: this.token };
+        this.token = crypto.randomBytes(24).toString("base64url");
+        const server = http.createServer((req, res) => {
+            this.handle(req, res).catch((err) => {
+                console.error(`[scenescout] live view ${(req.url ?? "").split("/").slice(2).join("/")} failed: ${err instanceof Error ? err.message : String(err)}`);
+                if (!res.headersSent)
+                    res.writeHead(500);
+                res.end();
+            });
+        });
+        await new Promise((resolve, reject) => {
+            // The listener stays: an 'error' with nobody listening (an accept that
+            // fails under EMFILE, say) would throw and take the whole engine down.
+            server.on("error", (err) => {
+                if (this.server === server)
+                    console.error(`[scenescout] live view server error: ${err.message}`);
+                else
+                    reject(err);
+            });
+            // Loopback, never 0.0.0.0: the page being shown may be signed in to a real account.
+            server.listen(0, "127.0.0.1", () => resolve());
+        });
+        this.server = server;
+        this.port = server.address().port;
+        return { port: this.port, token: this.token };
+    }
+    async stop() {
+        const server = this.server;
+        this.server = null;
+        const stops = [];
+        for (const entry of this.streams.values()) {
+            for (const viewer of entry.viewers.keys())
+                viewer.end();
+            if (entry.screencast.state === "live")
+                stops.push(entry.screencast.stop().catch(() => { }));
+        }
+        this.streams.clear();
+        this.shots.clear();
+        await Promise.all(stops);
+        if (server) {
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(() => resolve()));
+        }
+    }
+    get address() {
+        const addr = this.server?.address();
+        return addr ? { host: addr.address, port: addr.port } : null;
+    }
+    send(res, code, body = "", type = "text/plain; charset=utf-8", extra = {}) {
+        res.writeHead(code, {
+            "Content-Type": type,
+            "Cache-Control": "no-store",
+            "X-Content-Type-Options": "nosniff",
+            "Referrer-Policy": "no-referrer",
+            ...extra,
+        });
+        res.end(body);
+    }
+    tokenMatches(candidate) {
+        const a = Buffer.from(candidate);
+        const b = Buffer.from(this.token);
+        return a.length === b.length && crypto.timingSafeEqual(a, b);
+    }
+    async handle(req, res) {
+        // A page on another origin can point a hostname at 127.0.0.1 (DNS
+        // rebinding); it cannot make the browser send a loopback Host header.
+        const host = req.headers.host ?? "";
+        if (host !== `127.0.0.1:${this.port}` && host !== `localhost:${this.port}`)
+            return this.send(res, 403, "forbidden");
+        if (req.method !== "GET")
+            return this.send(res, 405, "the live view is read-only");
+        const parts = (req.url ?? "/").split("?")[0].split("/").slice(1);
+        // A wrong token gets the same answer as a wrong path.
+        if (!this.tokenMatches(parts[0] ?? ""))
+            return this.send(res, 404, "not found");
+        const [, route, name] = parts;
+        // The page's own requests are relative, so it has to be served from a
+        // directory. The target is this server's own token, which the request has
+        // just matched, never the request's text.
+        if (parts.length === 1) {
+            res.writeHead(302, { Location: `/${this.token}/`, "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" });
+            res.end();
+            return;
+        }
+        if (!route)
+            return this.send(res, 200, LIVE_PAGE, "text/html; charset=utf-8", { "Content-Security-Policy": LIVE_CSP });
+        if (route === "api" && name === "status") {
+            const snap = this.provider.snapshot();
+            const nowMs = this.now();
+            const body = {
+                ...snap,
+                sessions: snap.sessions.map((s) => ({ ...s, state: classify(s, nowMs), feed: this.provider.activity(s.session, FEED_LINES) })),
+            };
+            return this.send(res, 200, JSON.stringify(body), "application/json; charset=utf-8");
+        }
+        if (route === "api" && name === "activity") {
+            const session = this.param(req, "session");
+            if (session === null)
+                return this.send(res, 404, "not found");
+            if (!this.hasSession(session))
+                return this.send(res, 404, "no such session");
+            return this.send(res, 200, JSON.stringify({ session, feed: this.provider.activity(session, FEED_LINES_MAX) }), "application/json; charset=utf-8");
+        }
+        if (route === "api" && name === "report") {
+            const report = this.provider.report();
+            if (!report)
+                return this.send(res, 404, "no run attached");
+            return this.send(res, 200, JSON.stringify(report), "application/json; charset=utf-8");
+        }
+        if (route === "events" && !name) {
+            const wanted = this.param(req, "sessions");
+            if (wanted === null)
+                return this.send(res, 404, "not found");
+            const sessions = [...new Set(wanted.split(","))].filter((s) => s.length > 0 && this.hasSession(s));
+            if (sessions.length === 0)
+                return this.send(res, 404, "no such session");
+            return this.serveEvents(sessions, req, res);
+        }
+        if ((route === "shot" || route === "stream") && name) {
+            const ext = route === "shot" ? ".jpg" : ".mjpg";
+            if (!name.endsWith(ext))
+                return this.send(res, 404, "not found");
+            let session;
+            try {
+                session = decodeURIComponent(name.slice(0, -ext.length));
+            }
+            catch {
+                return this.send(res, 404, "not found");
+            }
+            if (!this.hasSession(session))
+                return this.send(res, 404, "no such session");
+            return route === "shot" ? this.serveShot(session, res) : this.serveStream(session, req, res);
+        }
+        return this.send(res, 404, "not found");
+    }
+    /** The value of this server's single query parameter, or null when its escaping is malformed. */
+    param(req, key) {
+        const raw = (req.url ?? "").split("?")[1] ?? "";
+        try {
+            return decodeURIComponent(raw.startsWith(`${key}=`) ? raw.slice(key.length + 1) : raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** A viewer may only address a session the board knows. */
+    hasSession(name) {
+        return this.provider.snapshot().sessions.some((s) => s.session === name);
+    }
+    /** One screenshot serves every poller for SHOT_MAX_AGE_MS, and concurrent requests share one capture. */
+    async takeShot(session) {
+        const cached = this.shots.get(session);
+        if (cached && this.now() - cached.at < SHOT_MAX_AGE_MS)
+            return cached.jpeg;
+        const pending = this.shotsInFlight.get(session);
+        if (pending)
+            return pending;
+        const capture = this.provider
+            .screenshot(session)
+            .catch(() => null)
+            .then((jpeg) => {
+            if (jpeg)
+                this.shots.set(session, { at: this.now(), jpeg });
+            return jpeg;
+        })
+            .finally(() => this.shotsInFlight.delete(session));
+        this.shotsInFlight.set(session, capture);
+        return capture;
+    }
+    async serveShot(session, res) {
+        const jpeg = await this.takeShot(session);
+        if (!jpeg)
+            return this.send(res, 503, "no frame available");
+        return this.send(res, 200, jpeg, "image/jpeg", { "Content-Length": jpeg.length });
+    }
+    writeFrame(res, jpeg) {
+        if (res.destroyed || res.writableLength > MAX_VIEWER_BACKLOG_BYTES)
+            return;
+        // One write per part: a part split across writes can reach the viewer half-drawn.
+        res.write(Buffer.concat([Buffer.from(`--${BOUNDARY}\r\nContent-Type: image/jpeg\r\nContent-Length: ${jpeg.length}\r\n\r\n`), jpeg, Buffer.from("\r\n")]));
+    }
+    writeEvent(res, event, data) {
+        if (res.destroyed || res.writableLength > MAX_VIEWER_BACKLOG_BYTES)
+            return;
+        res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    }
+    /**
+     * The session is gone (closed by the agent, or its page died): every viewer
+     * is told, and the screencast is stopped. A stream nobody ends would show
+     * the last frame under a LIVE badge for as long as the page stayed open.
+     */
+    dropSession(session) {
+        const stream = this.streams.get(session);
+        this.shots.delete(session);
+        if (!stream)
+            return;
+        this.streams.delete(session);
+        for (const viewer of stream.viewers.values())
+            viewer.gone();
+        stream.viewers.clear();
+        if (stream.screencast.state === "live")
+            void stream.screencast.stop().catch(() => { });
+    }
+    /**
+     * Add a viewer to a session's screencast, starting it for the first viewer.
+     * Resolves to the function that removes the viewer again, and to null when
+     * the session cannot stream. The last viewer to leave stops the screencast,
+     * so an unwatched session pays nothing.
+     */
+    async join(session, res, viewer) {
+        let stream = this.streams.get(session);
+        if (!stream) {
+            const entry = { viewers: new Map(), lastFrame: null, screencast: { state: "starting", ready: Promise.resolve(false) } };
+            entry.screencast = {
+                state: "starting",
+                ready: this.provider
+                    .startStream(session, (jpeg) => {
+                    entry.lastFrame = jpeg;
+                    for (const v of entry.viewers.values())
+                        v.frame(jpeg);
+                }, () => this.dropSession(session))
+                    .catch(() => null)
+                    .then((stop) => {
+                    if (!stop)
+                        return false;
+                    // Stopped or dropped while it was starting: nobody is left to watch, so end it now.
+                    if (this.streams.get(session) !== entry) {
+                        void stop().catch(() => { });
+                        return false;
+                    }
+                    entry.screencast = { state: "live", stop };
+                    return true;
+                }),
+            };
+            this.streams.set(session, entry);
+            stream = entry;
+        }
+        const started = stream.screencast.state === "live" ? true : await stream.screencast.ready;
+        if (!started) {
+            if (this.streams.get(session) === stream && stream.viewers.size === 0)
+                this.streams.delete(session);
+            return null;
+        }
+        const entry = stream;
+        entry.viewers.set(res, viewer);
+        return () => {
+            entry.viewers.delete(res);
+            if (entry.viewers.size > 0 || this.streams.get(session) !== entry)
+                return;
+            this.streams.delete(session);
+            if (entry.screencast.state === "live")
+                void entry.screencast.stop().catch(() => { });
+        };
+    }
+    /**
+     * MJPEG: an <img> renders it natively, so anything that shows an image can
+     * show one session live. The page itself does not use this: see serveEvents.
+     */
+    async serveStream(session, req, res) {
+        const leave = await this.join(session, res, { frame: (jpeg) => this.writeFrame(res, jpeg), gone: () => res.end() });
+        if (!leave)
+            return this.send(res, 503, "this session cannot stream");
+        if (res.destroyed || req.destroyed)
+            return leave();
+        res.writeHead(200, {
+            "Content-Type": `multipart/x-mixed-replace; boundary=${BOUNDARY}`,
+            "Cache-Control": "no-store",
+            "X-Content-Type-Options": "nosniff",
+            Connection: "close",
+        });
+        res.on("close", leave);
+        // A screencast emits on repaint, so a page that is sitting still would
+        // show a late viewer nothing at all. Give them the current picture first.
+        const first = this.streams.get(session)?.lastFrame ?? (await this.takeShot(session));
+        if (first)
+            this.writeFrame(res, first);
+    }
+    /**
+     * Every session the page is watching, over ONE connection, as server-sent
+     * events: `frame` carries a session's name and a base64 JPEG, `unavailable`
+     * names a session that cannot stream, or that has gone away since. A browser
+     * allows about six open connections to one host; with a stream per <img>,
+     * "Stream all" on six sessions used them all up and the status poll queued
+     * behind them forever, so the page froze at the moment it had the most to show.
+     */
+    async serveEvents(sessions, req, res) {
+        if (res.destroyed || req.destroyed)
+            return;
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-store",
+            "X-Content-Type-Options": "nosniff",
+        });
+        res.write("retry: 1000\n\n");
+        const leaves = [];
+        res.on("close", () => {
+            for (const leave of leaves)
+                leave();
+        });
+        for (const session of sessions) {
+            const leave = await this.join(session, res, {
+                frame: (jpeg) => this.writeEvent(res, "frame", { session, jpeg: jpeg.toString("base64") }),
+                gone: () => this.writeEvent(res, "unavailable", { session }),
+            });
+            if (!leave) {
+                this.writeEvent(res, "unavailable", { session });
+                continue;
+            }
+            if (res.destroyed)
+                return leave();
+            leaves.push(leave);
+            const first = this.streams.get(session)?.lastFrame ?? (await this.takeShot(session));
+            if (first)
+                this.writeEvent(res, "frame", { session, jpeg: first.toString("base64") });
+        }
+    }
+}

package/dist/engine/memory.js

@@ -89,6 +89,9 @@ export function redactSecrets(text) {
     }
     return hits > 0 ? `${out} [${hits} secret${hits === 1 ? "" : "s"} redacted]` : out;
 }
+/** The action-log lines that open and close a journey (scout_journey). The feed reads them to tell which goal an action served. */
+export const JOURNEY_START = "journey:start";
+export const JOURNEY_END = "journey:end";
 const EMPTY = { version: 1, states: {}, findings: [] };
 /**
  * Fold another process's memory into ours, losing nothing from either side.

package/dist/engine/report.js

@@ -305,7 +305,12 @@ export function computeGaps(memory, extras) {
         gaps.push(`single-role run (${roles.join(", ") || "no role recorded"}) — permission boundaries and role capability gaps are untested`);
     return gaps;
 }
-export function generateReport(memory, oracleLog, extras) {
+/**
+ * The report as the run stands now. `write` is what scout_report does at the
+ * end; the live view renders the same document on request without touching
+ * the disk, so someone can read it while the run is still going.
+ */
+export function generateReport(memory, oracleLog, extras, opts = {}) {
     const cov = memory.coverage();
     const findings = [...memory.findings].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
     const lines = [];
@@ -487,7 +492,8 @@ export function generateReport(memory, oracleLog, extras) {
     }
     const markdown = lines.join("\n");
     const outPath = path.join(memory.dir, "report.md");
-    fs.writeFileSync(outPath, markdown);
+    if (opts.write !== false)
+        fs.writeFileSync(outPath, markdown);
     // Bounded summary for the tool result: full reports have exceeded client
     // token limits in real runs (66–72KB observed) — the wire gets the digest,
     // the disk gets the document.