scenescout 3.11.1 → 3.13.0

package/dist/engine/ci.js

@@ -0,0 +1,633 @@
+/**
+ * `scenescout ci`: an exploratory run with no person and no coding agent. A
+ * model reached over an HTTP API drives the scout_* tools by the SceneScout
+ * method, and the run ends in the ordinary report. This file holds its rules,
+ * none of which needs a browser or a network: the options it accepts, which
+ * provider a run uses, the caps that end it, what may never be printed, which
+ * tools the model is given and how their results are shaped, and the files a
+ * run writes. The loop that uses them is src/ci-run.ts; the two APIs' message
+ * shapes are engine/provider.ts. Why it reports and never gates: ADR 14.
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { BROWSER_ENGINES } from "../browsers.js";
+import { markdownCell } from "./check.js";
+import { isWorthALook, redactSecrets } from "./memory.js";
+// ── options ─────────────────────────────────────────────────────────────────
+export const PROVIDERS = ["anthropic", "openai"];
+/** Where each provider's key is read from. Nothing else is: no flag, no file, no input. */
+export const KEY_ENV = { anthropic: "ANTHROPIC_API_KEY", openai: "OPENAI_API_KEY" };
+export const DEFAULT_MODEL = { anthropic: "claude-sonnet-5", openai: "gpt-6-luna" };
+/** The API root each request path is joined to. `--base-url` replaces it, for a compatible endpoint. */
+export const DEFAULT_BASE_URL = { anthropic: "https://api.anthropic.com/v1", openai: "https://api.openai.com/v1" };
+/** Reasoning effort each API accepts. The Messages API has no "none": thinking is lowered, not switched off. */
+export const EFFORTS = {
+    anthropic: ["low", "medium", "high", "xhigh", "max"],
+    openai: ["none", "low", "medium", "high", "xhigh", "max"],
+};
+export const DEFAULT_EFFORT = "low";
+/**
+ * The write policies a CI run may use. `destructive` lets the model send any
+ * request, deletes of records it did not create included, so it is taken only
+ * with `--allow-destructive` as well: a mode value alone, copied from another
+ * workflow or typed by an agent, never enables it. What CI may do is the
+ * developer's decision; the default stays read-only (ADR 14).
+ */
+export const CI_MODES = ["observe", "read-only", "safe-write", "destructive"];
+export const CI_LEVELS = ["minimal", "medium", "extensive"];
+export const DEFAULT_CAPS = { turns: 40, tokens: 1_500_000, wallMs: 20 * 60_000 };
+const CAP_BOUNDS = { turns: [1, 500], tokens: [1_000, 20_000_000], minutes: [1, 360] };
+/** Every option `scenescout ci` accepts; the ci action's inputs are these names (ci-test holds them equal). */
+export const CI_OPTION_NAMES = [
+    "provider",
+    "model",
+    "effort",
+    "base-url",
+    "max-turns",
+    "max-tokens",
+    "max-minutes",
+    "price-in",
+    "price-cached-in",
+    "price-out",
+    "mode",
+    "allow-destructive",
+    "level",
+    "focus",
+    "storage-state",
+    "browser",
+    "project",
+    "out",
+];
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
+/** A base URL a key may be sent to: https, or plain http only to this machine. */
+export function checkBaseUrl(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return { ok: false, error: `--base-url is not a URL: ${raw}` };
+    }
+    if (u.username || u.password)
+        return { ok: false, error: "--base-url must carry no credentials: the key is read from the environment" };
+    if (u.protocol === "https:")
+        return { ok: true, url: u.toString().replace(/\/+$/, "") };
+    if (u.protocol === "http:" && LOOPBACK_HOSTS.has(u.hostname))
+        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) {
+    const positional = [];
+    const flags = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith("--")) {
+            positional.push(a);
+            continue;
+        }
+        const eq = a.indexOf("=");
+        const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+        // The one switch: given bare, it takes no value, so the URL after it stays the URL.
+        if (name === "allow-destructive" && eq < 0) {
+            flags.set(name, "true");
+            continue;
+        }
+        const value = eq > 0 ? a.slice(eq + 1) : args[i + 1];
+        if (value === undefined || (eq < 0 && value.startsWith("--")))
+            return { ok: false, error: `--${name} needs a value` };
+        if (eq < 0)
+            i += 1;
+        flags.set(name, value);
+    }
+    const known = new Set(CI_OPTION_NAMES);
+    for (const name of flags.keys()) {
+        if (name === "api-key" || name === "key")
+            return { ok: false, error: `there is no --${name}: the key is read from ANTHROPIC_API_KEY or OPENAI_API_KEY only` };
+        if (!known.has(name))
+            return { ok: false, error: `unknown option --${name}` };
+    }
+    if (positional.length !== 1)
+        return { ok: false, error: "give exactly one URL to explore, e.g. scenescout ci http://127.0.0.1:3000" };
+    let url;
+    try {
+        url = new URL(positional[0]);
+    }
+    catch {
+        return { ok: false, error: `not a URL: ${positional[0]}` };
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return { ok: false, error: `only http and https URLs can be explored (got ${url.protocol})` };
+    if (url.username || url.password)
+        return { ok: false, error: "put no credentials in the URL: they would be written into the report. Sign in with --storage-state instead" };
+    const provider = flags.get("provider");
+    if (provider !== undefined && !PROVIDERS.includes(provider))
+        return { ok: false, error: `--provider must be one of ${PROVIDERS.join(", ")}` };
+    const effort = flags.get("effort");
+    if (effort !== undefined) {
+        const allowed = provider ? EFFORTS[provider] : EFFORTS.openai;
+        if (!allowed.includes(effort))
+            return { ok: false, error: `--effort must be one of ${allowed.join(", ")}${provider ? ` for ${provider}` : ""}` };
+    }
+    const model = flags.get("model");
+    if (model !== undefined && !/^[A-Za-z0-9._:/@-]{1,120}$/.test(model))
+        return { ok: false, error: "--model is not a model id" };
+    let baseUrl;
+    if (flags.has("base-url")) {
+        const b = checkBaseUrl(flags.get("base-url"));
+        if (!b.ok)
+            return b;
+        baseUrl = b.url;
+    }
+    const whole = (name, [lo, hi], fallback) => {
+        const raw = flags.get(name);
+        if (raw === undefined)
+            return fallback;
+        const n = Number(raw);
+        return Number.isInteger(n) && n >= lo && n <= hi ? n : `--${name} must be a whole number from ${lo} to ${hi}`;
+    };
+    const turns = whole("max-turns", CAP_BOUNDS.turns, DEFAULT_CAPS.turns);
+    const tokens = whole("max-tokens", CAP_BOUNDS.tokens, DEFAULT_CAPS.tokens);
+    const minutes = whole("max-minutes", CAP_BOUNDS.minutes, DEFAULT_CAPS.wallMs / 60_000);
+    for (const v of [turns, tokens, minutes])
+        if (typeof v === "string")
+            return { ok: false, error: v };
+    const price = {};
+    for (const [flag, field] of [
+        ["price-in", "input"],
+        ["price-cached-in", "cachedInput"],
+        ["price-out", "output"],
+    ]) {
+        const raw = flags.get(flag);
+        if (raw === undefined)
+            continue;
+        const v = Number(raw);
+        if (raw.trim() === "" || !Number.isFinite(v) || v < 0 || v > 1000)
+            return { ok: false, error: `--${flag} must be US dollars per million tokens, from 0 to 1000` };
+        price[field] = v;
+    }
+    const mode = flags.get("mode") ?? "read-only";
+    if (!CI_MODES.includes(mode))
+        return { ok: false, error: `--mode must be one of ${CI_MODES.join(", ")}` };
+    const allow = flags.get("allow-destructive") ?? "false";
+    if (allow !== "true" && allow !== "false")
+        return { ok: false, error: "--allow-destructive takes no value, or true or false" };
+    if (mode === "destructive" && allow !== "true")
+        return {
+            ok: false,
+            error: "--mode destructive needs --allow-destructive as well: it lets the run send any request, deleting records it did not create included",
+        };
+    const level = flags.get("level") ?? "medium";
+    if (!CI_LEVELS.includes(level))
+        return { ok: false, error: `--level must be one of ${CI_LEVELS.join(", ")}` };
+    const focus = flags.get("focus")?.trim();
+    if (focus !== undefined && focus.length > 300)
+        return { ok: false, error: "--focus is at most 300 characters" };
+    const browser = flags.get("browser");
+    if (browser !== undefined && !BROWSER_ENGINES.includes(browser))
+        return { ok: false, error: `--browser must be one of ${BROWSER_ENGINES.join(", ")}` };
+    const resolve = (p) => (p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) ? p : `${cwd.replace(/[\\/]$/, "")}/${p}`);
+    return {
+        ok: true,
+        options: {
+            url: url.toString(),
+            projectDir: resolve(flags.get("project") ?? cwd),
+            ...(flags.has("out") ? { outDir: resolve(flags.get("out")) } : {}),
+            ...(provider ? { provider: provider } : {}),
+            ...(model ? { model } : {}),
+            ...(effort ? { effort } : {}),
+            ...(baseUrl ? { baseUrl } : {}),
+            caps: { turns: turns, tokens: tokens, wallMs: minutes * 60_000 },
+            ...(Object.keys(price).length > 0 ? { price } : {}),
+            mode: mode,
+            level: level,
+            ...(focus ? { focus } : {}),
+            ...(flags.has("storage-state") ? { storageStatePath: resolve(flags.get("storage-state")) } : {}),
+            ...(browser ? { browser: browser } : {}),
+        },
+    };
+}
+const present = (env, name) => (env[name] ?? "").trim() !== "";
+/**
+ * Which provider a run uses: the one whose key is set. With both set the
+ * choice is not guessed: --provider must name it. A --provider whose key is
+ * missing is refused before anything starts, naming the variable.
+ */
+export function detectProvider(env, options) {
+    const withKey = PROVIDERS.filter((p) => present(env, KEY_ENV[p]));
+    let provider;
+    if (options.provider) {
+        if (!withKey.includes(options.provider))
+            return { ok: false, error: `--provider ${options.provider} needs ${KEY_ENV[options.provider]} set in the environment` };
+        provider = options.provider;
+    }
+    else if (withKey.length === 0) {
+        return { ok: false, error: `set ${KEY_ENV.anthropic} or ${KEY_ENV.openai} in the environment: a CI run needs a model to drive it` };
+    }
+    else if (withKey.length > 1) {
+        return { ok: false, error: `both ${KEY_ENV.anthropic} and ${KEY_ENV.openai} are set: pass --provider anthropic or --provider openai to choose` };
+    }
+    else {
+        provider = withKey[0];
+    }
+    const effort = options.effort ?? DEFAULT_EFFORT;
+    if (!EFFORTS[provider].includes(effort))
+        return { ok: false, error: `--effort must be one of ${EFFORTS[provider].join(", ")} for ${provider}` };
+    return { ok: true, resolved: { provider, model: options.model ?? DEFAULT_MODEL[provider], effort, baseUrl: options.baseUrl ?? DEFAULT_BASE_URL[provider] } };
+}
+/**
+ * The environment the MCP server and its browser are started with: this
+ * process's, without the keys. Nothing on that side needs them, and a key a
+ * process never had cannot end up in its logs or its report.
+ */
+export function childEnv(env) {
+    const out = {};
+    const drop = new Set(Object.values(KEY_ENV));
+    for (const [k, v] of Object.entries(env))
+        if (v !== undefined && !drop.has(k))
+            out[k] = v;
+    // Nobody watches a CI run: the live view would only hold a port open.
+    out.SCENESCOUT_LIVE = "off";
+    return out;
+}
+// ── never printing a key ────────────────────────────────────────────────────
+export const REDACTED_KEY = "[redacted key]";
+/** The key values set in this environment, to be removed from anything printed or written. */
+export function secretValues(env) {
+    return Object.values(KEY_ENV)
+        .map((name) => (env[name] ?? "").trim())
+        .filter((v) => v.length >= 8);
+}
+/** Key-shaped strings, for a key that reached a message from somewhere other than this environment (an echo of another). */
+const KEY_SHAPES = /\bsk-[A-Za-z0-9_-]{16,}/g;
+/**
+ * Remove every key value, and anything shaped like a provider key, from a
+ * line before it is logged or written. Longest first, so a key that contains
+ * another is not left half-printed.
+ */
+export function redactKeys(text, secrets) {
+    let out = text;
+    for (const s of [...secrets].sort((a, b) => b.length - a.length))
+        out = out.split(s).join(REDACTED_KEY);
+    return out.replace(KEY_SHAPES, REDACTED_KEY);
+}
+export const NO_USAGE = { input: 0, cachedInput: 0, cacheWrite: 0, output: 0 };
+export function addUsage(a, b) {
+    return { input: a.input + b.input, cachedInput: a.cachedInput + b.cachedInput, cacheWrite: a.cacheWrite + b.cacheWrite, output: a.output + b.output };
+}
+/**
+ * Which cap, if any, stops the run before its next model call. Checked
+ * between turns: one turn's usage is only known after it, so a run can end
+ * up to one turn over the token cap, and the report says by how much.
+ */
+export function capReached(spend, caps, now) {
+    if (now - spend.startedAt >= caps.wallMs)
+        return "time";
+    if (spend.usage.input + spend.usage.output >= caps.tokens)
+        return "tokens";
+    if (spend.turns >= caps.turns)
+        return "turns";
+    return null;
+}
+/** What is left of the time cap. No model or tool call may run longer. */
+export function wallLeftMs(spend, caps, now) {
+    return Math.max(0, caps.wallMs - (now - spend.startedAt));
+}
+export const EXIT_CI = { completed: 0, couldNotRun: 2 };
+/**
+ * A CI run reports and never gates, so its findings never set the exit code.
+ * 0: the run ran, whether the model finished or a cap ended it, and the report
+ * is written. 2: it could not run, or could not finish for a reason the
+ * workflow must fix (a key the provider refused, an app that never answered).
+ */
+export function ciExitCode(reason, reportWritten) {
+    if (!reportWritten)
+        return EXIT_CI.couldNotRun;
+    return reason === "provider-error" || reason === "could-not-start" ? EXIT_CI.couldNotRun : EXIT_CI.completed;
+}
+export function describeStop(reason, caps, detail) {
+    switch (reason) {
+        case "done":
+            return "the model finished the run";
+        case "turns":
+            return `stopped at the turn cap (${caps.turns} model calls)`;
+        case "tokens":
+            return `stopped at the token cap (${caps.tokens.toLocaleString("en-US")} tokens)`;
+        case "time":
+            return `stopped at the time cap (${Math.round(caps.wallMs / 60_000)} minutes)`;
+        case "provider-error":
+            return `stopped: the model's API failed${detail ? ` (${detail})` : ""}`;
+        case "could-not-start":
+            return `could not start${detail ? `: ${detail}` : ""}`;
+    }
+}
+export const PRICES = {
+    "gpt-6-luna": { input: 0.1, cachedInput: 0.01, output: 0.5 },
+    "gpt-5.6-luna": { input: 0.2, cachedInput: 0.02, output: 1.2 },
+    "claude-sonnet-5": { input: 2, cachedInput: 0.2, cacheWrite: 2.5, output: 10 },
+};
+/**
+ * The price a run is costed at: the table's entry for the model with any
+ * given price put over it. Null when input or output is still unknown, so a
+ * model nobody priced is never costed at a guess. Cached input given no price
+ * of its own is charged as input, which can only overstate the cost.
+ */
+export function resolvePrice(model, override = {}) {
+    const base = PRICES[model] ?? {};
+    const merged = { ...base, ...override };
+    // A cache-write price belongs to the table's input price; an overridden input price replaces it.
+    if (override.input !== undefined)
+        delete merged.cacheWrite;
+    if (merged.input === undefined || merged.output === undefined)
+        return null;
+    return {
+        input: merged.input,
+        cachedInput: merged.cachedInput ?? merged.input,
+        output: merged.output,
+        ...(merged.cacheWrite !== undefined ? { cacheWrite: merged.cacheWrite } : {}),
+    };
+}
+/** Estimated cost in dollars, or null when the model's price is not known here or given. */
+export function estimateCost(model, u, override) {
+    const p = resolvePrice(model, override);
+    if (!p)
+        return null;
+    const plain = Math.max(0, u.input - u.cachedInput - u.cacheWrite);
+    return (plain * p.input + u.cachedInput * p.cachedInput + u.cacheWrite * (p.cacheWrite ?? p.input) + u.output * p.output) / 1_000_000;
+}
+const n = (x) => x.toLocaleString("en-US");
+export function usageLine(spend, model, endedAt, override) {
+    const u = spend.usage;
+    const secs = Math.round((endedAt - spend.startedAt) / 1000);
+    const cost = estimateCost(model, u, override);
+    return (`${spend.turns} turn(s), ${n(u.input)} tokens in (${n(u.cachedInput)} cached), ${n(u.output)} out, ` +
+        `${Math.floor(secs / 60)}m ${secs % 60}s` +
+        (cost === null ? `, cost not estimated (no price known for ${model}; --price-in and --price-out give one)` : `, estimated cost $${cost.toFixed(4)}`));
+}
+// ── the tools the model is given ────────────────────────────────────────────
+/**
+ * The scout_* tools a CI model may call. An allowlist, so a tool added to the
+ * server later is not handed to an unattended model until someone decides it
+ * should be. Left out: scout_attach and scout_close (the run attaches and
+ * closes itself, so the mode and the target cannot change), scout_session,
+ * scout_playbook (the method is the system prompt), scout_screenshot (the
+ * loop is text-only), scout_resolve (scout_verify records re-tests), and the
+ * lane tools (one agent, ADR 14).
+ */
+export const CI_TOOLS = [
+    "scout_scan",
+    "scout_note",
+    "scout_crawl",
+    "scout_snapshot",
+    "scout_navigate",
+    "scout_back",
+    "scout_click",
+    "scout_type",
+    "scout_select",
+    "scout_press",
+    "scout_hover",
+    "scout_scroll",
+    "scout_upload",
+    "scout_run_plan",
+    "scout_journey",
+    "scout_request",
+    "scout_design_audit",
+    "scout_coverage",
+    "scout_finding",
+    "scout_verify",
+    "scout_report",
+];
+/**
+ * The tools as the model sees them: only the allowed ones, in a fixed order (a
+ * changing order would defeat prompt caching), each schema without `session`
+ * (one session, always the run's) or `$schema`.
+ */
+export function ciTools(listed) {
+    const byName = new Map(listed.map((t) => [t.name, t]));
+    return CI_TOOLS.filter((name) => byName.has(name)).map((name) => {
+        const t = byName.get(name);
+        const schema = { ...(t.inputSchema ?? {}) };
+        delete schema.$schema;
+        const properties = { ...(schema.properties ?? {}) };
+        delete properties.session;
+        const required = Array.isArray(schema.required) ? schema.required.filter((r) => r !== "session") : undefined;
+        const parameters = { ...schema, type: "object", properties };
+        if (required && required.length > 0)
+            parameters.required = required;
+        else
+            delete parameters.required;
+        return { name, description: t.description ?? "", parameters };
+    });
+}
+/** Arguments the model sent, as the server will get them: an object, never naming a session. */
+export function ciToolArgs(input) {
+    if (input === undefined || input === null)
+        return { ok: true, args: {} };
+    if (typeof input !== "object" || Array.isArray(input))
+        return { ok: false, error: "the arguments must be a JSON object" };
+    const args = { ...input };
+    delete args.session;
+    return { ok: true, args };
+}
+/**
+ * Arguments a tool call may not carry in a CI run. scout_scan reads a
+ * directory's files; the model may scan the run's own project and nothing
+ * else, and is given that directory when it names none.
+ */
+export function guardToolArgs(name, args, projectDir) {
+    if (name !== "scout_scan")
+        return { ok: true, args };
+    const given = args.projectPath;
+    if (given === undefined)
+        return { ok: true, args: { ...args, projectPath: path.resolve(projectDir) } };
+    if (typeof given !== "string" || path.resolve(projectDir, given) !== path.resolve(projectDir))
+        return { ok: false, error: `scout_scan may scan only this run's project directory, ${projectDir}` };
+    return { ok: true, args: { ...args, projectPath: path.resolve(projectDir) } };
+}
+/** The longest tool result handed back to the model, in characters. The report keeps everything; this only bounds the context. */
+export const TOOL_RESULT_MAX_CHARS = 16_000;
+/** One tool result as text: images named rather than sent, and the length bounded. */
+export function toolResultText(content, max = TOOL_RESULT_MAX_CHARS) {
+    const parts = (content ?? []).map((c) => (c.type === "text" ? (c.text ?? "") : `[${c.type} omitted: this run is text-only]`));
+    const text = parts.join("\n") || "(no output)";
+    return text.length <= max ? text : `${text.slice(0, max)}\n… [${n(text.length - max)} more characters cut to keep the context bounded]`;
+}
+// ── what the model is told ──────────────────────────────────────────────────
+export function ciSystemPrompt(playbook, o) {
+    return (`${playbook}\n\n---\n\n` +
+        `# Running in CI\n\n` +
+        `You are running unattended in a CI job. There is no person to ask: never ask a question or wait for an answer; decide, and say in findings and notes what you assumed.\n\n` +
+        `- The browser is already attached to the target in ${o.mode} mode, as the default session. scout_attach, scout_close, scout_session and scout_playbook are not available: the mode and the target are fixed for this run, and the method is the text above. Skip the Setup steps that choose them, and never pass \`session\`.\n` +
+        `- The level is ${o.level}. When you have met its contract, or your budget is nearly spent, call scout_report {level: "${o.level}"}. Never pass force: if the contract is unmet the run writes the report anyway, with its gap ledger.\n` +
+        `- Tool results are text only; screenshots are not available. Long results are cut: prefer calls that return less (a scout_crawl first, snapshots only where you act).\n` +
+        `- When you are finished, reply with a short summary and no tool call. That ends the run.\n`);
+}
+export function ciKickoff(o) {
+    return [
+        `Run an exploratory test session following the method.`,
+        `Target: ${o.url}`,
+        `Project directory (for scout_scan): ${o.projectDir}`,
+        `Level: ${o.level}`,
+        `Write mode: ${o.mode}`,
+        o.focus ? `Focus: ${o.focus}` : "",
+        `Budget: at most ${o.caps.turns} model turns, ${n(o.caps.tokens)} tokens and ${Math.round(o.caps.wallMs / 60_000)} minutes. Several tool calls in one turn cost one turn. The run stops at the first cap reached and writes the report as it stands.`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+// ── what a run writes ───────────────────────────────────────────────────────
+/** A finding as memory.json holds it, checked just enough to be reported. */
+export function readFindings(raw) {
+    const list = raw && typeof raw === "object" ? raw.findings : undefined;
+    if (!Array.isArray(list))
+        return [];
+    return list.filter((f) => !!f &&
+        typeof f === "object" &&
+        typeof f.id === "string" &&
+        typeof f.title === "string" &&
+        ["high", "medium", "low"].includes(f.severity) &&
+        typeof f.runs === "number");
+}
+/**
+ * The findings this run made or saw again: new ids, and ids whose run count
+ * went up. The project's memory also holds earlier runs' findings, which the
+ * report lists and this run's summary does not claim.
+ */
+export function findingsThisRun(before, after) {
+    const runsBefore = new Map(before.map((f) => [f.id, f.runs]));
+    return after.filter((f) => f.status !== "resolved" && (!runsBefore.has(f.id) || f.runs > (runsBefore.get(f.id) ?? 0)));
+}
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
+function pathOf(url) {
+    try {
+        const u = new URL(url);
+        return `${u.pathname}${u.search}`;
+    }
+    catch {
+        return url;
+    }
+}
+/** Findings summary lines are page text a model wrote: nothing that looks like a secret, nothing that breaks the table. */
+const cell = (s, secrets) => markdownCell(redactKeys(redactSecrets(s), secrets));
+/** The job summary: how the run ended, what it spent, and this run's findings. The full report is report.md. */
+export function ciSummaryMarkdown(r, secrets = []) {
+    const defects = r.findings.filter((f) => !isWorthALook(f)).sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+    const looks = r.findings.filter(isWorthALook);
+    const count = (s) => defects.filter((f) => f.severity === s).length;
+    const lines = [
+        `## SceneScout CI run`,
+        ``,
+        `**${cell(r.url, secrets)}** — ${describeStop(r.stop, r.caps, r.stopDetail && cell(r.stopDetail, secrets))}. This run reports; it does not gate.`,
+        ``,
+        `| | |`,
+        `|---|---|`,
+        `| Findings this run | ${defects.length} (${count("high")} high, ${count("medium")} medium, ${count("low")} low)${looks.length ? `, ${looks.length} worth a look` : ""} |`,
+        `| Level | ${r.level} — completion contract ${r.contractMet ? "met" : "not met (the report's gap ledger says what is missing)"} |`,
+        `| Mode | ${r.mode} |`,
+        `| Model | ${r.provider} ${cell(r.model, secrets)}, effort ${r.effort} |`,
+        `| Usage | ${usageLine(r.spend, r.model, r.endedAt, r.price)} |`,
+        ``,
+    ];
+    if (defects.length > 0) {
+        lines.push(`| Severity | Category | Finding | Page |`, `|---|---|---|---|`);
+        for (const f of defects.slice(0, 50))
+            lines.push(`| ${f.severity} | ${cell(f.category, secrets)} | ${cell(f.title, secrets)} | ${cell(pathOf(f.url), secrets)} |`);
+        if (defects.length > 50)
+            lines.push(``, `… and ${defects.length - 50} more in report.md.`);
+        lines.push(``);
+    }
+    if (looks.length > 0) {
+        lines.push(`**Worth a look** (a defect only under a convention of the project; not counted):`, ``);
+        for (const f of looks.slice(0, 20))
+            lines.push(`- ${cell(f.title, secrets)} — a defect only if your project uses ${cell(f.convention ?? "a convention", secrets)}`);
+        lines.push(``);
+    }
+    lines.push(`The full report, with repro steps and the gap ledger, is report.md.`, ``);
+    return lines.join("\n");
+}
+export function ciSummaryJson(r, version, secrets = []) {
+    const clean = (s) => redactKeys(redactSecrets(s), secrets);
+    return {
+        tool: "scenescout",
+        command: "ci",
+        version,
+        url: clean(r.url),
+        provider: r.provider,
+        model: r.model,
+        effort: r.effort,
+        mode: r.mode,
+        level: r.level,
+        caps: { turns: r.caps.turns, tokens: r.caps.tokens, minutes: Math.round(r.caps.wallMs / 60_000) },
+        stop: { reason: r.stop, ...(r.stopDetail ? { detail: clean(r.stopDetail) } : {}), text: clean(describeStop(r.stop, r.caps, r.stopDetail)) },
+        contractMet: r.contractMet,
+        usage: {
+            turns: r.spend.turns,
+            inputTokens: r.spend.usage.input,
+            cachedInputTokens: r.spend.usage.cachedInput,
+            cacheWriteTokens: r.spend.usage.cacheWrite,
+            outputTokens: r.spend.usage.output,
+            seconds: Math.round((r.endedAt - r.spend.startedAt) / 1000),
+            estimatedCostUsd: estimateCost(r.model, r.spend.usage, r.price),
+        },
+        counts: {
+            high: r.findings.filter((f) => !isWorthALook(f) && f.severity === "high").length,
+            medium: r.findings.filter((f) => !isWorthALook(f) && f.severity === "medium").length,
+            low: r.findings.filter((f) => !isWorthALook(f) && f.severity === "low").length,
+            worthALook: r.findings.filter(isWorthALook).length,
+        },
+        findings: r.findings.map((f) => ({
+            id: f.id,
+            severity: f.severity,
+            category: f.category,
+            title: clean(f.title),
+            path: clean(pathOf(f.url)),
+            ...(f.evidence ? { evidence: clean(f.evidence) } : {}),
+            ...(isWorthALook(f) ? { tier: "worth-a-look", convention: clean(f.convention ?? "") } : {}),
+        })),
+    };
+}
+const SARIF_LEVEL = { high: "error", medium: "warning", low: "note" };
+function appOrigin(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+}
+/** This run's findings as SARIF 2.1.0: one rule per category, the finding's id as its fingerprint. */
+export function ciSarif(r, version, secrets = []) {
+    const clean = (s) => redactKeys(redactSecrets(s), secrets);
+    const categories = [...new Set(r.findings.map((f) => f.category))].sort();
+    return {
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "SceneScout",
+                        version,
+                        informationUri: "https://github.com/brunoboto96/SceneScout",
+                        rules: categories.map((c) => ({ id: `finding/${c}`, name: c, shortDescription: { text: `An exploratory finding: ${c}` } })),
+                    },
+                },
+                invocations: [{ executionSuccessful: r.stop !== "provider-error" && r.stop !== "could-not-start", properties: { stop: r.stop } }],
+                originalUriBaseIds: { APP: { uri: `${appOrigin(r.url)}/` } },
+                results: r.findings.map((f) => ({
+                    ruleId: `finding/${f.category}`,
+                    level: isWorthALook(f) ? "note" : SARIF_LEVEL[f.severity],
+                    message: {
+                        text: isWorthALook(f)
+                            ? `Worth a look — ${clean(f.title)}. A defect only if your project uses ${clean(f.convention ?? "a convention")}.`
+                            : `[${f.severity}] ${clean(f.title)}${f.evidence ? ` — ${clean(f.evidence)}` : ""}`,
+                    },
+                    locations: [{ physicalLocation: { artifactLocation: { uri: clean(pathOf(f.url)).replace(/^\//, ""), uriBaseId: "APP" } } }],
+                    partialFingerprints: { "scenescoutFinding/v1": createHash("sha256").update(f.id).digest("hex").slice(0, 32) },
+                    ...(isWorthALook(f) ? { properties: { tier: "worth-a-look", convention: clean(f.convention ?? "") } } : {}),
+                })),
+            },
+        ],
+    };
+}
+/** Where a CI run writes when not told: beside the project's other SceneScout output. */
+export const CI_DIRNAME = "ci";