scenescout 3.22.0 → 3.23.1

package/dist/engine/ci.js

@@ -16,6 +16,7 @@ import { markdownCell } from "./check.js";
 import { parseLimitFlag } from "./limits.js";
 import { isWorthALook, redactSecrets } from "./memory.js";
 import { SARIF_ANCHOR_FALLBACKS, checkSarifAnchor, sarifLocation } from "./sarif.js";
+import { fromRunLine, resolveFromRun } from "./from-run.js";
 // ── options ─────────────────────────────────────────────────────────────────
 export const PROVIDERS = ["anthropic", "openai"];
 /** Where each provider's key is read from. Nothing else is: no flag, no file, no input. */
@@ -93,6 +94,9 @@ export const CI_OPTION_NAMES = [
     "show",
     "compare-url",
     "dedup",
+    "from-run",
+    "from-run-mode",
+    "from-run-turns-per-page",
     "sarif-file-anchor",
 ];
 /** The longest --show description: it becomes a line of the model's prompt. */
@@ -115,7 +119,8 @@ export function checkBaseUrl(raw) {
         return { ok: true, url: u.toString().replace(/\/+$/, "") };
     return { ok: false, error: "--base-url must be https (plain http only to 127.0.0.1 or localhost): the API key is sent to it" };
 }
-export function parseCiArgs(args, cwd) {
+/** `env` is read for the earlier run alone (SCENESCOUT_FROM_RUN, SCENESCOUT_FROM_RUN_MODE), since a flag wins over it. */
+export function parseCiArgs(args, cwd, env = {}) {
     const positional = [];
     const flags = new Map();
     for (let i = 0; i < args.length; i++) {
@@ -271,6 +276,13 @@ export function parseCiArgs(args, cwd) {
     const anchor = flags.has("sarif-file-anchor") ? checkSarifAnchor(flags.get("sarif-file-anchor")) : undefined;
     if (anchor && !anchor.ok)
         return anchor;
+    const runFlags = { path: flags.get("from-run"), mode: flags.get("from-run-mode"), turnsPerPage: flags.get("from-run-turns-per-page") };
+    if (show && (runFlags.path !== undefined || runFlags.mode !== undefined || runFlags.turnsPerPage !== undefined))
+        return { ok: false, error: "--from-run starts an exploration from an earlier run, and --show explores nothing: give one or the other" };
+    // A run asked to show an element explores nothing, so an earlier run named in the environment does not apply to it.
+    const fromRun = show ? { ok: true } : resolveFromRun(runFlags, env);
+    if (!fromRun.ok)
+        return fromRun;
     const resolve = (p) => (p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) ? p : `${cwd.replace(/[\\/]$/, "")}/${p}`);
     return {
         ok: true,
@@ -296,6 +308,7 @@ export function parseCiArgs(args, cwd) {
             ...(navTimeout.value !== undefined ? { navTimeoutMs: navTimeout.value } : {}),
             dedup: dedup,
             ...(anchor ? { sarifFileAnchor: anchor.value } : {}),
+            ...(fromRun.fromRun ? { fromRun: { ...fromRun.fromRun, path: resolve(fromRun.fromRun.path), given: fromRun.fromRun.path } } : {}),
         },
     };
 }
@@ -691,6 +704,7 @@ export function ciKickoff(o) {
     return [
         `Run an exploratory test session following the method.`,
         `Target: ${o.url}`,
+        ...(o.fromRunLines ?? []),
         `Project directory (for scout_scan): ${o.projectDir}`,
         `Level: ${o.level}`,
         `Write mode: ${o.mode}`,
@@ -760,6 +774,7 @@ export function ciSummaryMarkdown(r, secrets = []) {
         `| Model | ${r.provider} ${cell(r.model, secrets)}, effort ${r.effort} |`,
         ...(r.lanes ? [`| Lanes | ${lanesCell(r.lanes, secrets)} |`] : []),
         ...(r.dedup ? [`| Finding dedup | ${dedupLine(r.dedup)} |`] : []),
+        ...(r.fromRun ? [`| Started from | ${cell(fromRunLine(r.fromRun), secrets)} |`] : []),
         `| Usage | ${usageLine(r.spend, r.model, r.endedAt, r.price)} |`,
         ``,
     ];
@@ -785,6 +800,27 @@ export function ciSummaryMarkdown(r, secrets = []) {
     lines.push(r.capture ? `The pictures are in shots/.` : `The full report, with repro steps and the gap ledger, is report.md.`, ``);
     return lines.join("\n");
 }
+/** A run record with every text a page or a person wrote in it passed through `clean`, as everything else ci.json holds is. */
+function cleanRecord(r, clean) {
+    const all = (xs) => xs.map(clean);
+    return {
+        ...r,
+        knownRoutes: all(r.knownRoutes),
+        visited: all(r.visited),
+        lanes: r.lanes.map((l) => ({ session: l.session, routes: all(l.routes) })),
+        steps: r.steps.map((s) => ({ ...s, route: clean(s.route), ...(s.target !== undefined ? { target: clean(s.target) } : {}) })),
+        left: r.left.map((l) => ({
+            ...l,
+            route: clean(l.route),
+            unexercised: all(l.unexercised),
+            forms: all(l.forms),
+            unchosen: l.unchosen.map((d) => ({ key: clean(d.key), options: all(d.options) })),
+        })),
+        gaps: all(r.gaps),
+        ...(r.assigned ? { assigned: all(r.assigned) } : {}),
+        ...(r.prefixes ? { prefixes: r.prefixes.map((n) => ({ ...n, target: clean(n.target), ...(n.why !== undefined ? { why: clean(n.why) } : {}) })) } : {}),
+    };
+}
 function lanesCell(l, secrets) {
     if (l.oneLoop)
         return `${l.asked} asked; explored in one loop: ${cell(l.oneLoop, secrets)}`;
@@ -876,6 +912,8 @@ export function ciSummaryJson(r, version, secrets = []) {
         })),
         ...(r.capture ? { capture: cleanCapture(r.capture, clean) } : {}),
         ...(r.lanes ? { lanes: lanesJson(r.lanes, clean) } : {}),
+        ...(r.fromRun ? { fromRun: { mode: r.fromRun.mode, source: clean(r.fromRun.source), runId: r.fromRun.runId, recordAt: r.fromRun.recordAt } } : {}),
+        ...(r.record ? { record: cleanRecord(r.record, clean) } : {}),
     };
 }
 /** The lanes as ci.json holds them. Module paths and lane names come from the app's routes: redacted like the rest. */

package/dist/engine/dispatch.js

@@ -98,3 +98,73 @@ export class SessionQueue {
             this.forget(key);
     }
 }
+/**
+ * The work of every tool call still running, per session.
+ *
+ * The watchdog answers a slow call, but it cannot stop the call: the work goes
+ * on in the background and can still write into the project (its action log,
+ * a frame, a debounced memory save). Left alone, those writes land after
+ * `scout_close` has answered, and after another session has attached to the
+ * same folder. So close waits for them: it closes the browser first, which
+ * makes every page-bound step of the abandoned work fail at once, then waits
+ * here for the work to finish unwinding. The wait is bounded, so work that is
+ * stuck on something other than the browser cannot hold a close forever; the
+ * caller is told how many calls were still running when it gave up.
+ */
+export class CallWork {
+    running = new Map();
+    /** Record `work` as running for `key` until it settles, whether it resolves or rejects. */
+    track(key, work) {
+        let set = this.running.get(key);
+        if (!set) {
+            set = new Set();
+            this.running.set(key, set);
+        }
+        set.add(work);
+        const done = () => {
+            const left = this.running.get(key);
+            if (!left)
+                return;
+            left.delete(work);
+            if (left.size === 0)
+                this.running.delete(key);
+        };
+        // The rejection is the call's own caller's to handle; here it only means "finished".
+        work.then(done, done);
+    }
+    /** Calls still running for `key`. */
+    count(key) {
+        return this.running.get(key)?.size ?? 0;
+    }
+    /** Wait up to `ms` for `key`'s running calls to finish; resolves with how many are still running. */
+    async settle(key, ms) {
+        return this.settleKeys([key], ms);
+    }
+    /** The same for every session (close-all). */
+    async settleAll(ms) {
+        return this.settleKeys([...this.running.keys()], ms);
+    }
+    async settleKeys(keys, ms) {
+        const work = keys.flatMap((k) => [...(this.running.get(k) ?? [])]);
+        if (work.length > 0) {
+            let timer;
+            await Promise.race([Promise.allSettled(work), new Promise((resolve) => (timer = setTimeout(resolve, ms)))]);
+            clearTimeout(timer);
+        }
+        return keys.reduce((n, k) => n + this.count(k), 0);
+    }
+}
+/**
+ * The cap on every tool call's watchdog, from SCENESCOUT_WATCHDOG_MS. Unset
+ * means each tool keeps its own limit. Anything else must be a whole number
+ * of milliseconds of at least 100, or the server refuses to start: a typo
+ * here would otherwise run with limits nobody chose.
+ */
+export function watchdogCap(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    const ms = Number(raw);
+    if (!Number.isInteger(ms) || ms < 100)
+        throw new Error(`SCENESCOUT_WATCHDOG_MS must be a whole number of milliseconds, at least 100; got "${raw}"`);
+    return ms;
+}