agent-device-lab 0.0.0-stage → 0.3.1

package/dist/core/scan.js

@@ -0,0 +1,455 @@
+import { copyFileSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { redactUrlSecrets } from './url-redact.js';
+import { join } from 'node:path';
+import { checkFilter, measureState, shot } from './checks.js';
+import { getDevice } from './devices.js';
+import { wrapHits } from './detectors.js';
+import { blockedRequest, classifyControl, orderCandidates, stateSignature } from './explore-safety.js';
+import { controlTraits, installShiftObserver, takeLayoutShifts } from './extract.js';
+import { Lab } from './lab.js';
+import { evaluatePolicy, groupFindings, matchSuppressions } from './scan-policy.js';
+import { scanReportHtml } from './scan-report.js';
+import { check, stepRequest } from './steps.js';
+import { LabError, SCHEMA_VERSION, } from './schema.js';
+const DECISIONS_MAX = 60;
+const controlKey = (c) => `${c.role}\u0000${c.name}\u0000${c.context ?? ''}`;
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'scenario';
+export async function runScan(env, opts) {
+    const cfg = env.profile.scan;
+    const t0 = Date.now();
+    const startedAt = new Date().toISOString();
+    const scenarios = selectScenarios(env.profile, opts);
+    const plan = scenarios.map((sc) => {
+        const ids = opts.devices ? (sc.devices ? sc.devices.filter((d) => opts.devices.includes(d)) : [...opts.devices]) : (sc.devices ?? cfg.devices);
+        return { sc, devices: ids.map((d) => getDevice(d, env.profile.devices)) };
+    });
+    const dir = join(env.runDir, 'scans', opts.id);
+    mkdirSync(dir, { recursive: true });
+    const exploring = (sc) => opts.explore ?? sc.explore ?? cfg.explore.enabled;
+    env.emit({
+        kind: 'scan', phase: 'start', id: opts.id, explore: scenarios.some(exploring),
+        runs: plan.flatMap(({ sc, devices }) => devices.map((d) => ({ scenario: sc.name, route: redactUrlSecrets(sc.route), device: d.id, width: d.viewport.width, height: d.viewport.height }))),
+    });
+    const runs = [];
+    const budget = { exploreMs: 0 };
+    let interrupted;
+    for (const [i, { sc, devices }] of plan.entries()) {
+        if (interrupted)
+            break;
+        // Per state label, what each device measured: compared across nearby widths when all have run.
+        const samples = new Map();
+        const scRuns = [];
+        for (const [j, device] of devices.entries()) {
+            const stop = env.checkpoint?.();
+            if (stop) {
+                // Everything not yet run is listed, never silently dropped; runs already done keep their results.
+                const skipped = [...devices.slice(j).map((d) => ({ scenario: sc.name, device: d.id })),
+                    ...plan.slice(i + 1).flatMap((p) => p.devices.map((d) => ({ scenario: p.sc.name, device: d.id })))];
+                interrupted = { ...stop, skipped };
+                break;
+            }
+            env.emit({ kind: 'scan', phase: 'run-start', id: opts.id, scenario: sc.name, device: device.id });
+            const run = await runScenario(env, opts, sc, device, join(dir, 'frames', `${i + 1}-${slug(sc.name)}`, device.id), exploring(sc), budget, samples);
+            runs.push(run);
+            scRuns.push(run);
+            env.emit({ kind: 'scan', phase: 'run-done', id: opts.id, run });
+        }
+        // Label wrapping only shows by comparing widths, so it is checked once every device has run.
+        if (checkFilter(cfg.checks, sc.checks)('text-wrap-change')) {
+            for (const [label, list] of samples) {
+                for (const { device, hit } of wrapHits(list, { ratio: cfg.wrapNearbyRatio, noWrap: cfg.noWrap, route: redactUrlSecrets(sc.route) })) {
+                    const s = list.find((x) => x.device === device);
+                    const r = env.store.recordHit(hit, { route: s.route, viewport: { width: s.width }, gen: env.gen() }, s.repro, { device, keepRefs: false, scenario: sc.name, state: label, ...(s.frame ? { frame: s.frame } : {}) });
+                    const state = s.run.states.find((st) => st.id === s.stateId);
+                    if (state && !state.findings.includes(r.finding.id))
+                        state.findings.push(r.finding.id);
+                    if (!s.run.findings.includes(r.finding.id))
+                        s.run.findings.push(r.finding.id);
+                    if (r.fresh)
+                        env.emit({ kind: 'findings', findings: [r.finding], ...(s.frame ? { frame: s.frame } : {}) });
+                }
+            }
+        }
+    }
+    const ids = new Set(runs.flatMap((r) => r.findings));
+    const findings = env.store.list().filter((f) => ids.has(f.id));
+    const today = opts.today ?? new Date().toISOString().slice(0, 10);
+    const { statuses, applied } = matchSuppressions(findings, cfg.suppressions, { today, scenarios: scenarios.map((s) => s.name), devices: [...new Set(runs.map((r) => r.device))] });
+    for (const f of findings)
+        env.store.suppress(f.id, applied.get(f.id));
+    const result = {
+        schemaVersion: SCHEMA_VERSION, id: opts.id, startedAt, ms: Date.now() - t0,
+        devices: [...new Set(plan.flatMap((p) => p.devices.map((d) => d.id)))], explore: scenarios.some(exploring),
+        runs, findings: structuredClone(findings), groups: groupFindings(findings), suppressions: statuses,
+        verdict: interruptedVerdict(evaluatePolicy(findings, runs, cfg.policy), interrupted),
+        reports: { html: join(dir, 'report.html'), json: join(dir, 'result.json') }, exploreMs: budget.exploreMs,
+        ...(interrupted ? { interrupted } : {}),
+    };
+    writeFileSync(result.reports.json, JSON.stringify(result, null, 2));
+    writeFileSync(result.reports.html, scanReportHtml(result, dir));
+    env.emit({ kind: 'scan', phase: 'done', id: opts.id, result });
+    return result;
+}
+/** An interrupted scan never claims pass or fail: only part of its plan ran. */
+function interruptedVerdict(v, i) {
+    if (!i)
+        return v;
+    const why = i.reason === 'takeover' ? 'a person took over the browser' : i.reason === 'paused' ? 'a person paused the session' : 'a person stopped the session';
+    return { ...v, result: 'incomplete', reasons: [`interrupted: ${why}; ${i.skipped.length} scenario run(s) did not run`, ...v.reasons] };
+}
+function selectScenarios(profile, opts) {
+    if (opts.route) {
+        if (!opts.route.startsWith('/'))
+            throw new LabError('invalid_request', `scan route must be a path starting with "/", got "${opts.route}"`);
+        return [{ name: `${redactUrlSecrets(opts.route)} as loaded`, route: opts.route, auth: 'session', steps: [], cleanup: [] }];
+    }
+    const declared = profile.scan.scenarios;
+    if (!declared.length)
+        return [{ name: `${profile.startPath} as loaded`, route: profile.startPath, auth: 'session', steps: [], cleanup: [] }];
+    if (!opts.scenarios?.length)
+        return declared;
+    const unknown = opts.scenarios.filter((n) => !declared.some((s) => s.name === n));
+    if (unknown.length) {
+        throw new LabError('not_found', `No scenario ${unknown.map((n) => `"${n}"`).join(', ')} in ${profile.profilePath}`, { hint: `Scenarios: ${declared.map((s) => s.name).join(', ')}` });
+    }
+    return declared.filter((s) => opts.scenarios.includes(s.name));
+}
+async function runScenario(env, opts, sc, device, dir, explore, budget, samples) {
+    const cfg = env.profile.scan;
+    const t0 = Date.now();
+    mkdirSync(dir, { recursive: true });
+    const run = {
+        scenario: sc.name, device: device.id, width: device.viewport.width, height: device.viewport.height, status: 'ok', ms: 0,
+        states: [], decisions: [], decisionsOmitted: 0, limits: [], findings: [],
+    };
+    const enabled = checkFilter(cfg.checks, sc.checks);
+    const detectors = { tapTargets: cfg.tapTargets, layoutShiftMin: cfg.layoutShiftMin, enabled };
+    const url = env.profile.app.url.replace(/\/+$/, '') + sc.route;
+    let phase = 'context';
+    const r = {};
+    // Exploration guard: while a candidate is activated, requests that could change data and
+    // navigations off the origin are blocked (and reported), whatever the control claimed to be.
+    const guard = { on: false, blocked: [] };
+    const origin = new URL(env.profile.app.url).origin;
+    let storage;
+    let prefix;
+    let beforeFrame;
+    const open = async () => {
+        const lab = await Lab.isolated({
+            browser: env.browser, profile: env.profile, device, storageState: storage, headed: env.headed, watch: env.watch,
+            sessionId: `${env.sessionId}/${opts.id}/${slug(sc.name)}/${device.id}`, runDir: dir,
+            init: {
+                scripts: enabled('layout-shift') ? [installShiftObserver] : [],
+                ...(explore ? { guard: (method, u, nav) => {
+                        if (!guard.on)
+                            return undefined;
+                        const label = blockedRequest(method, u, nav, origin);
+                        if (label)
+                            guard.blocked.push(label);
+                        return label;
+                    } } : {}),
+            },
+        });
+        if (enabled('layout-shift')) {
+            lab.onActed = async () => { beforeFrame = await shot(lab.activePage, join(dir, 'before.jpg')); };
+        }
+        return lab;
+    };
+    const describeOpen = `scan ${opts.id}: open ${redactUrlSecrets(url)} in a new ${device.id} context (${device.viewport.width}x${device.viewport.height}) ` +
+        (sc.auth === 'session' ? 'with the session\'s cookies and storage' : sc.auth === 'saved' ? 'with the saved sign-in state' : 'signed out (fresh)');
+    const setup = async (lab, adopt) => {
+        const loaded = await lab.load(sc.route, describeOpen);
+        if (!adopt)
+            return loaded.observation;
+        phase = 'setup';
+        for (const [i, step] of sc.steps.entries())
+            await runStep(lab, step, `setup step ${i + 1}`, adopt ? (f) => adoptFindings(f, 'setup') : undefined);
+        return lab.lastObservation;
+    };
+    const adoptFindings = (fs, state) => {
+        for (const f of fs) {
+            const a = env.store.adopt(f, [...prefix, ...f.reproduction], { device: device.id, keepRefs: false, scenario: sc.name, state });
+            if (!run.findings.includes(a.finding.id))
+                run.findings.push(a.finding.id);
+            if (a.fresh)
+                env.emit({ kind: 'findings', findings: [a.finding], ...(a.finding.frame ? { frame: a.finding.frame } : {}) });
+        }
+    };
+    const measure = async (st, when) => {
+        const lab = r.lab;
+        // What the state looked like right after the last input, before it settled: kept only as the
+        // "before" frame of a layout-shift finding.
+        const before = beforeFrame ? join(dir, `${st.id}-before.jpg`) : undefined;
+        if (before)
+            copyFileSync(beforeFrame, before);
+        beforeFrame = undefined;
+        const m = await measureState(lab.activePage, {
+            store: env.store, sessionId: env.sessionId, gen: env.gen(), ctx: { device: device.id, scenario: sc.name, state: st.label },
+            reproduction: [...prefix, ...lab.steps], detectors, reachLimit: 40, frameFile: (suffix) => join(dir, `${st.id}-${suffix}.jpg`),
+            observation: lab.lastObservation, shift: { when, ...(before ? { before } : {}) },
+            onFindings: (findings, frame) => env.emit({ kind: 'findings', findings, ...(frame ? { frame } : {}) }),
+        });
+        if (before && !m.findings.some((id) => env.store.get(id)?.frames?.some((f) => f.path === before)))
+            rmSync(before, { force: true });
+        const o = m.observation;
+        Object.assign(st, {
+            status: 'measured', route: o.route, ...(o.dialog ? { dialog: o.dialog } : {}), controls: o.controls.length, ...(m.frame ? { frame: m.frame } : {}), findings: m.findings,
+            budget: { controlsOmitted: o.omitted, elementsOmitted: m.omitted, reachChecked: m.reachChecked },
+        });
+        for (const id of m.findings)
+            if (!run.findings.includes(id))
+                run.findings.push(id);
+        const list = samples.get(st.label) ?? [];
+        list.push({ device: device.id, width: device.viewport.width, labels: m.labels, hiddenLabels: m.hiddenLabels, ...(m.frame ? { frame: m.frame } : {}),
+            route: o.route, repro: [...prefix, ...lab.steps], stateId: st.id, run });
+        samples.set(st.label, list);
+        env.emit({ kind: 'scan', phase: 'state', id: opts.id, scenario: sc.name, device: device.id, state: st });
+        return o;
+    };
+    try {
+        storage = sc.auth === 'session' ? await env.sessionState() : sc.auth === 'saved' ? env.savedState() : undefined;
+        prefix = sc.auth === 'session' ? [...env.sessionHistory] : [];
+        r.lab = await open();
+        phase = 'load';
+        await setup(r.lab, true);
+        phase = 'checks';
+        const s0 = { id: 's0', label: sc.steps.length ? 'after setup' : 'as loaded', path: [...sc.steps.map((s, i) => s.label ?? `setup step ${i + 1}`)], depth: 0, status: 'measured', findings: [] };
+        run.states.push(s0);
+        const o0 = await measure(s0, sc.steps.length ? 'while the page loaded and the scenario was set up' : 'while the page loaded');
+        if (explore) {
+            const t = Date.now();
+            try {
+                await exploreFrom(o0);
+            }
+            finally {
+                budget.exploreMs += Date.now() - t;
+            }
+        }
+        if (sc.cleanup.length) {
+            // Cleanup starts from the scenario's state. When exploration left the context elsewhere and it
+            // cannot be closed back, cleanup runs in a fresh context on the route as loaded (setup is not
+            // replayed: it may create data).
+            phase = 'cleanup';
+            if (r.at && r.at.depth === 0 && !(await isAt(r.at))) {
+                await r.lab?.close('fresh context for cleanup').catch(() => undefined);
+                r.lab = await open();
+                await setup(r.lab, false);
+            }
+            for (const [i, step] of sc.cleanup.entries())
+                await runStep(r.lab, step, `cleanup step ${i + 1}`);
+        }
+    }
+    catch (err) {
+        run.status = 'failed';
+        run.failedAt = phase;
+        run.error = LabError.from(err).toJSON();
+    }
+    finally {
+        await r.lab?.close('scenario finished').catch(() => undefined);
+        rmSync(join(dir, 'before.jpg'), { force: true });
+    }
+    run.ms = Date.now() - t0;
+    return run;
+    async function runStep(lab, step, label, onFindings) {
+        let result;
+        try {
+            result = await lab.act(stepRequest(lab, step));
+        }
+        catch (err) {
+            const e = LabError.from(err);
+            throw new LabError(e.code, `${label} (${step.label ?? `${step.do}${step.name ? ` "${step.name}"` : ''}`}): ${e.message}`, { ...(e.hint ? { hint: e.hint } : {}) });
+        }
+        if (result.outcome === 'error') {
+            throw new LabError(result.error.code, `${label} (${step.label ?? `${step.do}${step.name ? ` "${step.name}"` : ''}`}): ${result.error.message}`, { ...(result.error.hint ? { hint: result.error.hint } : {}) });
+        }
+        onFindings?.(result.newFindings);
+        if (step.expect) {
+            const failed = check(step.expect, lab.lastObservation, result).filter((c) => !c.ok);
+            if (failed.length)
+                throw new LabError('action_failed', `${label}: expectation failed: ${failed.map((c) => c.text).join('; ')}`, { hint: 'The scenario did not reach its state, so its checks did not run.' });
+        }
+    }
+    /** Breadth-first from the scenario's state, one safe activation at a time, within the limits. */
+    async function exploreFrom(o0) {
+        const ex = cfg.explore;
+        const decided = new Map();
+        const activated = new Set();
+        const exploreStart = Date.now();
+        const root = nodeFor('', [], 0, o0);
+        root.candidates = await candidatesAt(o0, undefined);
+        r.at = root;
+        const queue = [root];
+        let explored = 0;
+        const stop = (why) => { if (!run.limits.includes(why))
+            run.limits.push(why); };
+        for (let node = queue.shift(); node; node = queue.shift()) {
+            const pending = node.candidates.filter((c) => !activated.has(controlKey(c)));
+            if (pending.length > ex.maxActionsPerState)
+                stop(`maxActionsPerState (${ex.maxActionsPerState}): ${pending.length - ex.maxActionsPerState} candidate(s) in ${node.label || 'the scenario state'} not tried`);
+            for (const [ci, cand] of pending.slice(0, ex.maxActionsPerState).entries()) {
+                const remaining = () => pending.length - ci + queue.reduce((n, q) => n + q.candidates.length, 0);
+                if (explored >= ex.maxStates)
+                    return stop(`maxStates (${ex.maxStates}): ${remaining()} candidate(s) not explored`);
+                if (budget.exploreMs + (Date.now() - exploreStart) >= ex.maxMs)
+                    return stop(`maxMs (${ex.maxMs} ms, whole scan): ${remaining()} candidate(s) not explored`);
+                activated.add(controlKey(cand));
+                explored++;
+                const label = node.label ? `${node.label} → ${cand.label}` : cand.label;
+                const st = { id: `s${explored}`, label, path: [...run.states[0].path, ...node.path.map((p) => p.label), cand.label], depth: node.depth + 1, status: 'measured', findings: [] };
+                run.states.push(st);
+                try {
+                    await reach(node);
+                    await r.lab.activePage.evaluate(takeLayoutShifts).catch(() => undefined);
+                    guard.blocked = [];
+                    guard.on = true;
+                    let result;
+                    try {
+                        result = await r.lab.act({ action: 'click', ref: refFor(r.lab, cand) });
+                    }
+                    finally {
+                        guard.on = false;
+                    }
+                    r.at = undefined;
+                    if (guard.blocked.length) {
+                        // It tried to change data or leave: not a state to measure, and never activated again.
+                        Object.assign(st, { status: 'blocked', blocked: [...guard.blocked] });
+                        decided.set(controlKey(cand), { role: cand.role, name: cand.name, ...(cand.context ? { context: cand.context } : {}), verdict: 'skip',
+                            reason: `sent ${guard.blocked[0]} when activated; the request was blocked and the state was not measured` });
+                        env.emit({ kind: 'scan', phase: 'state', id: opts.id, scenario: sc.name, device: device.id, state: st });
+                        continue;
+                    }
+                    if (result.outcome === 'error')
+                        throw new LabError(result.error.code, result.error.message);
+                    adoptFindings(result.newFindings, label);
+                    const o = await measure(st, `after activating ${cand.label}`);
+                    // A state on another route was reached by navigating: measured, but not explored further.
+                    if (node.depth + 1 < ex.maxDepth && o.route === o0.route) {
+                        const child = nodeFor(label, [...node.path, cand], node.depth + 1, o);
+                        // Deeper states explore only what the activation revealed, not the page around it again.
+                        child.candidates = await candidatesAt(o, node.keys);
+                        if (child.candidates.length)
+                            queue.push(child);
+                    }
+                    st.restore = await restore(node, cand);
+                }
+                catch (err) {
+                    Object.assign(st, { status: 'failed', error: LabError.from(err).toJSON() });
+                    r.at = undefined;
+                    env.emit({ kind: 'scan', phase: 'state', id: opts.id, scenario: sc.name, device: device.id, state: st });
+                }
+            }
+        }
+        const all = [...decided.values()];
+        run.decisions = all.slice(0, DECISIONS_MAX);
+        run.decisionsOmitted = Math.max(0, all.length - DECISIONS_MAX);
+        async function candidatesAt(o, parentKeys) {
+            const fresh = o.controls.filter((c) => !parentKeys || !parentKeys.has(controlKey(c)));
+            const traits = await r.lab.activePage.evaluate(controlTraits, fresh.map((c) => c.ref)).catch(() => []);
+            const byRef = new Map(traits.map((t) => [t.ref, t]));
+            const out = [];
+            const counts = new Map();
+            for (const c of fresh)
+                counts.set(controlKey(c), (counts.get(controlKey(c)) ?? 0) + 1);
+            for (const [i, c] of fresh.entries()) {
+                const d = classifyControl(c, byRef.get(c.ref), ex, o.route);
+                if (!d)
+                    continue;
+                if (d.verdict === 'explore' && (counts.get(controlKey(c)) ?? 0) > 1) {
+                    d.verdict = 'skip';
+                    d.reason = 'more than one control has this role, name and context, so it cannot be targeted without guessing';
+                }
+                if (!decided.has(controlKey(c)) || d.verdict === 'skip')
+                    decided.set(controlKey(c), d);
+                if (d.verdict === 'explore')
+                    out.push({ role: c.role, name: c.name, ...(c.context ? { context: c.context } : {}), kind: d.kind, label: `${c.role} "${c.name}"`, order: i });
+            }
+            return orderCandidates(out).map(({ order: _, ...c }) => c);
+        }
+    }
+    function nodeFor(label, path, depth, o) {
+        return {
+            label, path, depth, sig: stateSignature(o), candidates: [], keys: new Set(o.controls.map(controlKey)),
+            selectedTabs: new Set(o.controls.filter((c) => c.role === 'tab' && c.selected).map(controlKey)),
+        };
+    }
+    /** Whether the context is in `node`'s state now (observing it if unsure). */
+    async function isAt(node) {
+        if (r.at === node)
+            return true;
+        const o = await r.lab.observe().catch(() => undefined);
+        if (o && stateSignature(o) === node.sig) {
+            r.at = node;
+            return true;
+        }
+        return false;
+    }
+    /** Be in `node`'s state: already there, or a fresh context with the setup and the path replayed. */
+    async function reach(node) {
+        if (await isAt(node))
+            return;
+        await r.lab?.close('fresh context for the next state').catch(() => undefined);
+        r.lab = await open();
+        await setup(r.lab, false);
+        for (const [i, s] of sc.steps.entries())
+            await runStep(r.lab, s, `setup step ${i + 1} (replayed)`);
+        for (const p of node.path) {
+            const res = await r.lab.act({ action: 'click', ref: refFor(r.lab, p) });
+            if (res.outcome === 'error')
+                throw new LabError(res.error.code, `replaying ${p.label}: ${res.error.message}`);
+        }
+        r.at = node;
+    }
+    /** Return to `node` after measuring a state: close what was opened, or press Escape, else start over. */
+    async function restore(node, cand) {
+        const lab = r.lab;
+        const back = async (req) => {
+            const res = await lab.act(req).catch(() => undefined);
+            return !!res && res.outcome === 'success' && stateSignature(lab.lastObservation) === node.sig;
+        };
+        const now = lab.lastObservation;
+        const opener = now.controls.filter((c) => controlKey(c) === controlKey(cand));
+        let how = 'fresh-context';
+        if (opener.length === 1 && (opener[0].expanded || opener[0].pressed) && await back({ action: 'click', ref: opener[0].ref }))
+            how = 'toggle';
+        else if (cand.kind === 'tab') {
+            // Switch back to the tab that was selected before (exactly one match, or not at all).
+            const was = now.controls.filter((c) => c.role === 'tab' && !c.selected && node.selectedTabs.has(controlKey(c)));
+            if (was.length === 1 && await back({ action: 'click', ref: was[0].ref }))
+                how = 'toggle';
+        }
+        if (how === 'fresh-context' && await back({ action: 'press', key: 'Escape' }))
+            how = 'escape';
+        r.at = how === 'fresh-context' ? undefined : node;
+        return how;
+    }
+}
+/** A ref for a candidate in the latest observation: exactly one control with its role, name and context, never a guess. */
+function refFor(lab, c) {
+    const matches = (lab.lastObservation?.controls ?? []).filter((x) => controlKey(x) === controlKey(c));
+    if (matches.length === 1)
+        return matches[0].ref;
+    throw new LabError(matches.length ? 'ambiguous_target' : 'not_found', `${c.label}${c.context ? ` in "${c.context}"` : ''}: ${matches.length ? `${matches.length} matching controls` : 'not in the latest observation'}`);
+}
+/**
+ * What a command returns for a scan: the verdict, each run's outcome and the problem groups, bounded.
+ * Findings are ids (details through inspect); frames and full evidence stay in the report files.
+ */
+export function scanSummary(r, maxGroups = 30) {
+    return {
+        schemaVersion: r.schemaVersion, id: r.id, ms: r.ms, explore: r.explore, exploreMs: r.exploreMs, verdict: r.verdict, reports: r.reports,
+        ...(r.interrupted ? { interrupted: r.interrupted } : {}),
+        runs: r.runs.map((x) => ({
+            scenario: x.scenario, device: x.device, status: x.status, ...(x.failedAt ? { failedAt: x.failedAt, error: x.error?.message } : {}),
+            states: x.states.length, findings: x.findings,
+            ...(x.limits.length ? { limits: x.limits } : {}),
+            ...(x.decisions.some((d) => d.verdict === 'skip') ? { skipped: x.decisions.filter((d) => d.verdict === 'skip').length } : {}),
+        })),
+        groups: r.groups.slice(0, maxGroups).map((g) => ({
+            id: g.id, title: g.title, kind: g.kind, severity: g.severity, confidence: g.confidence, route: g.route, scenarios: g.scenarios, devices: g.devices,
+            findings: g.findings, ...(g.suppressed ? { suppressed: true } : {}),
+        })),
+        groupsOmitted: Math.max(0, r.groups.length - maxGroups),
+        suppressions: r.suppressions.filter((x) => x.status !== 'applied'),
+    };
+}
+//# sourceMappingURL=scan.js.map

package/dist/core/schema.js

@@ -0,0 +1,39 @@
+// Versioned, JSON-serialisable contract shared by the CLI, the daemon and (later) the MCP adapter.
+// Anything returned to an agent must be expressible with these types.
+import { redactUrlSecrets } from './url-redact.js';
+export const SCHEMA_VERSION = 1;
+const RECOVERABLE = new Set([
+    'unknown_ref', 'stale_ref', 'not_found', 'ambiguous_target', 'not_visible', 'disabled',
+    'obstructed', 'not_fillable', 'action_failed', 'invalid_request',
+    'not_selectable', 'not_checkable', 'not_uploadable', 'upload_not_allowed', 'no_history', 'unknown_tab',
+    'session_paused', 'human_control', 'observation_required', 'invalid_control',
+]);
+export class LabError extends Error {
+    code;
+    hint;
+    details;
+    constructor(code, message, opts = {}) {
+        // A message can quote a URL (a failed navigation, a refused route): its secrets never go out.
+        super(redactUrlSecrets(message));
+        this.name = 'LabError';
+        this.code = code;
+        this.hint = opts.hint === undefined ? undefined : redactUrlSecrets(opts.hint);
+        this.details = opts.details;
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            ...(this.hint ? { hint: this.hint } : {}),
+            recoverable: RECOVERABLE.has(this.code),
+            ...(this.details ? { details: this.details } : {}),
+        };
+    }
+    static from(err) {
+        if (err instanceof LabError)
+            return err;
+        const message = err instanceof Error ? err.message : String(err);
+        return new LabError('action_failed', message.split('\n')[0] ?? message);
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/core/services.js

@@ -0,0 +1,134 @@
+import { join } from 'node:path';
+import { startOrder } from './profile.js';
+import { Service } from './project-runner.js';
+import { LabError } from './schema.js';
+/** Names of required environment variables that are unset or empty, per service. Values are never read out. */
+export function missingEnv(specs, env = process.env) {
+    return specs
+        .map((s) => ({ service: s.name, names: s.requiredEnv.filter((n) => !env[n] && !s.env[n]) }))
+        .filter((m) => m.names.length);
+}
+/**
+ * The project's services for one session. Independent services start concurrently; a service starts
+ * only when everything it depends on is ready. If a required service fails, services still starting
+ * are abandoned, and every service this group started is stopped in reverse order. Reused services
+ * are never stopped.
+ */
+export class ServiceGroup {
+    services;
+    /** In the order they became ready. */
+    constructor(services) {
+        this.services = services;
+    }
+    static async start(specs, opts) {
+        const missing = missingEnv(specs, opts.env);
+        if (missing.length) {
+            const names = [...new Set(missing.flatMap((m) => m.names))];
+            throw new LabError('missing_env', `Required environment variable${names.length > 1 ? 's' : ''} not set: ${names.join(', ')}`, {
+                hint: 'Export them in the shell (or MCP client environment) that runs agentlab. Only the names are checked and reported.',
+                details: { missing },
+            });
+        }
+        const byName = new Map(specs.map((s) => [s.name, s]));
+        const report = new Map(startOrder(specs).map((n) => [n, { name: n, status: 'pending' }]));
+        const ready = [];
+        const abort = new AbortController();
+        let failure;
+        const running = new Map();
+        const external = () => {
+            failure ??= new LabError('startup_failed', 'service start abandoned: the session is closing');
+            abort.abort();
+        };
+        if (opts.signal?.aborted)
+            external();
+        else
+            opts.signal?.addEventListener('abort', external, { once: true });
+        const run = (name) => {
+            let p = running.get(name);
+            if (p)
+                return p;
+            p = (async () => {
+                const spec = byName.get(name);
+                const deps = await Promise.all(spec.dependsOn.map(run));
+                const entry = report.get(name);
+                if (failure) {
+                    entry.status = 'skipped';
+                    entry.detail = 'not started: another service failed';
+                    return undefined;
+                }
+                const missingDep = spec.dependsOn.find((_, i) => !deps[i]);
+                if (missingDep) {
+                    entry.status = 'skipped';
+                    entry.detail = `not started: depends on "${missingDep}", which failed`;
+                    if (spec.required) {
+                        failure = new LabError('startup_failed', `service "${name}" needs optional service "${missingDep}", which failed`, { details: { service: name } });
+                        abort.abort();
+                    }
+                    return undefined;
+                }
+                try {
+                    const svc = await Service.ensure(spec, {
+                        logFile: join(opts.runDir, `${name}.log`),
+                        onLog: (line) => opts.onLog?.(name, line),
+                        signal: abort.signal,
+                        onUnexpectedExit: (exit) => opts.onUnexpectedExit?.({ ...exit, required: spec.required }),
+                    });
+                    ready.push(svc);
+                    entry.status = svc.info.owned ? 'ready' : 'reused';
+                    opts.onReady?.(svc.info);
+                    return svc;
+                }
+                catch (err) {
+                    const error = LabError.from(err);
+                    const abandoned = error.details?.aborted === true;
+                    entry.status = abandoned ? 'aborted' : 'failed';
+                    entry.detail = error.message;
+                    if (!abandoned && spec.required && !failure) {
+                        failure = error;
+                        abort.abort();
+                    }
+                    return undefined;
+                }
+            })();
+            running.set(name, p);
+            return p;
+        };
+        await Promise.all(specs.map((s) => run(s.name)));
+        opts.signal?.removeEventListener('abort', external);
+        const group = new ServiceGroup(ready);
+        if (failure) {
+            const stopped = await group.stop();
+            for (const s of stopped) {
+                const entry = report.get(s.name);
+                if (entry && s.owned)
+                    entry.stopped = s.detail;
+            }
+            throw new LabError(failure.code, failure.message, {
+                hint: failure.hint,
+                details: { ...failure.details, services: [...report.values()], stopped },
+            });
+        }
+        return group;
+    }
+    get(name) {
+        return name === undefined ? undefined : this.services.find((s) => s.spec.name === name);
+    }
+    infos() {
+        return this.services.map((s) => s.info);
+    }
+    /** Snapshot every owned process service's group members; only those whose leader is still alive can be. */
+    refreshMembers() {
+        for (const svc of this.services)
+            svc.refreshMembers();
+    }
+    /** Stop owned services, most recently ready first (dependents before what they depend on). */
+    async stop() {
+        const results = [];
+        for (const svc of [...this.services].reverse()) {
+            const r = await svc.stop();
+            results.push({ name: svc.spec.name, owned: svc.info.owned, stopped: r.stopped, detail: r.reason });
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=services.js.map