scenescout 1.2.0 → 1.4.0

package/dist/engine/browser.js

@@ -2,13 +2,14 @@ import { chromium, firefox, webkit } from "playwright";
 import fs from "node:fs";
 import path from "node:path";
 import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./fingerprint.js";
-import { AUTH_LOSS_PREFIX, MemoryStore } from "./memory.js";
+import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore } from "./memory.js";
+import { describeInjection, newInjections, probeQueries, probeScript, probeShape, rememberProbe } from "./injection.js";
 import { AuthLossTracker } from "./authloss.js";
 import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, } from "./collector.js";
 import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
-import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, serviceWorkerPolicy, sharedWorkersAllowed } from "../browsers.js";
+import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, screencastSupport, serviceWorkerPolicy, sharedWorkersAllowed, } from "../browsers.js";
 import { revealedLines } from "./hover.js";
 import { explainLaunchFailure, isMissingBrowser } from "./launch.js";
 import { ACTION_TIMEOUT_MS, performScroll, probeFocusIndicators, probeOverlays, scrollContainer } from "./probes.js";
@@ -98,6 +99,8 @@ function actionabilityDiagnostic(message) {
  * actions by ref, runs oracles after every action, and records everything in
  * the persistent memory store. Contains no LLM calls — the MCP client is the brain.
  */
+/** A screencast whose page has been gone for this many 500 ms ticks ends and says so; a re-attach takes fewer. */
+const SCREENCAST_PAGELESS_TICKS = 20;
 export class BrowserEngine {
     browser = null;
     context = null;
@@ -182,10 +185,26 @@ export class BrowserEngine {
         return this.memory?.createdResources ?? this.localCreatedResources;
     }
     localCreatedResources = [];
+    /** Creations not yet named in a tool result. Unlike the once-per-session mutation notice, every one is reported. */
+    newlyCreated = [];
+    /**
+     * Name every record created since the last result. The mutation notice
+     * reports each endpoint once per session so a read-only run is not flooded;
+     * in safe-write that hid every creation after the first on an endpoint,
+     * so the agent could not tell from the result that it had just made one.
+     */
+    drainCreated() {
+        if (this.newlyCreated.length === 0)
+            return "";
+        const list = this.newlyCreated.splice(0);
+        return `\n(created: ${list.join(", ")} — this session may edit or delete ${list.length === 1 ? "it" : "them"})`;
+    }
     /** Design audits run this session — the report gate requires at least one. */
     designAuditCount = 0;
     /** Active task-efficiency measurement (scout_journey), if any. */
     journey = null;
+    /** The session's task, from scout_attach. Empty when the agent gave none. */
+    task = "";
     /**
      * Begin measuring a user JOURNEY — the interaction cost of completing one
      * real task ("create an order", "approve a document"). E2E suites assert
@@ -200,7 +219,7 @@ export class BrowserEngine {
             fromLog: this.memory?.actionLog.length ?? 0,
             startUrl: page.url(),
         };
-        this.logAction({ action: "journey:start", target: goal, url: page.url() });
+        this.logAction({ action: JOURNEY_START, target: goal, url: page.url() });
         return `JOURNEY STARTED — "${goal}"\nFrom: ${page.url()}\nNow perform the task the way a first-time user would (click through the UI; don't jump straight to a known deep URL, or the measurement is meaningless). Call scout_journey {action:"end"} when the task is complete or you conclude it can't be.`;
     }
     /** Close the journey and report its interaction cost + friction signals. */
@@ -225,7 +244,7 @@ export class BrowserEngine {
         catch {
             /* fact recording is best-effort */
         }
-        this.logAction({ action: "journey:end", target: j.goal, url: page.url(), result: completed ? "completed" : "abandoned" });
+        this.logAction({ action: JOURNEY_END, target: j.goal, url: page.url(), result: completed ? "completed" : "abandoned" });
         return formatJourney({ goal: j.goal, completed, seconds, note }, measured);
     }
     /** Whether the browser window is visible — headed hover results carry a physical-cursor caveat. */
@@ -244,6 +263,54 @@ export class BrowserEngine {
      * allowed POST /items that shares its prefix.
      */
     abortedByPolicy = new WeakSet();
+    /** Markup-shaped values this session typed, so every later page can be checked for them rendering as elements. */
+    probes = [];
+    /** Injections already reported, by payload and route, so a page is not reported on every snapshot. */
+    injectionsReported = new Set();
+    /**
+     * Remember a typed value when it holds an element worth watching for. What
+     * to type is the agent's choice; this only watches for the outcome. The
+     * page's current count of such elements is the baseline: shared chrome that
+     * happens to look like the payload is not an injection.
+     */
+    async noteProbe(value, field) {
+        const shape = probeShape(value);
+        if (!shape || this.probes.some((p) => p.payload === shape.payload))
+            return;
+        const page = this.page;
+        let baseline = 0;
+        if (page && !page.isClosed()) {
+            try {
+                baseline = (await page.evaluate(probeScript([shape]))).length;
+            }
+            catch {
+                // A page mid-navigation: no baseline, so a coincidence on this page would be reported. Rare, and visible.
+            }
+        }
+        this.probes = rememberProbe(this.probes, { ...shape, field, typedOn: page?.url() ?? "", baseline });
+    }
+    /**
+     * The DOM-injection oracle: has anything this session typed come back as an
+     * element on the current page? Runs wherever violations are drained, so the
+     * finding reaches the agent in the result of the action that revealed it.
+     */
+    async scanForInjections() {
+        const page = this.page;
+        if (!page || page.isClosed() || this.probes.length === 0)
+            return;
+        const url = page.url();
+        let hits;
+        try {
+            hits = (await page.evaluate(probeScript(probeQueries(this.probes))));
+        }
+        catch {
+            // A page mid-navigation has no DOM to ask; the next drain looks again.
+            return;
+        }
+        for (const found of newInjections(this.probes, hits, url, this.injectionsReported)) {
+            this.oracles.noteInjection(describeInjection(found.probe, url, found.outer), url);
+        }
+    }
     /** Raw mutation sigs of the most recent action (pre-dedup) — double-submit detection. */
     lastActionMutationSigs = [];
     /** Write-policy blocks drained by the last action — counted, so an action can know a request fired even when the policy stopped it. */
@@ -258,6 +325,7 @@ export class BrowserEngine {
             throw new Error(`storageStatePath does not exist: ${opts.storageStatePath}`);
         }
         this.mode = opts.mode ?? "read-only";
+        this.task = (opts.task ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
         this.headed = opts.headed ?? false;
         this.blockedRequests = [];
         this.pendingCreations = new Set();
@@ -636,6 +704,7 @@ export class BrowserEngine {
         const isNew = memory.visitState(fp, url, route, elements.map((el) => el.key));
         memory.recordRoleAccess(this.role, route, "reached");
         this.logAction({ action: "snapshot", url, result: fp });
+        await this.scanForInjections();
         const line = (el) => {
             const dup = el.key.match(/~(\d+)$/);
             const flags = [
@@ -793,8 +862,9 @@ export class BrowserEngine {
                 formatViolations(this.oracles.drain()));
         }
         this.logAction({ action, target, url });
+        await this.scanForInjections();
         const violations = this.oracles.drain();
-        const mutations = this.drainMutations() + this.drainBlocked();
+        const mutations = this.drainMutations() + this.drainBlocked() + this.drainCreated();
         const navigated = this.snapshotUrl !== "" && url !== this.snapshotUrl;
         if (navigated) {
             // Refs point into the previous page's DOM; invalidate so a stale ref
@@ -842,6 +912,7 @@ export class BrowserEngine {
             const desc = `${verdict.collection} id=${id}`;
             if (!this.createdResources.includes(desc)) {
                 this.createdResources.push(desc);
+                this.newlyCreated.push(desc);
                 this.logAction({ action: "created-resource", target: desc, url: this.page?.url() ?? "" });
             }
         }
@@ -1076,6 +1147,8 @@ export class BrowserEngine {
         if (refusal)
             return refusal;
         const locator = page.locator(`xpath=${el.xpath}`);
+        // Before the fill: a page that reflects input as it is typed already holds the element afterwards.
+        await this.noteProbe(text, `${el.role} "${el.name}"`);
         const fillNote = await this.fillOrAppend(locator, text, replace);
         if (pressEnter) {
             // Enter inside a form submits it — check the form's submit target, or
@@ -1609,6 +1682,7 @@ export class BrowserEngine {
             if (typeof status === "number" && status >= 400)
                 memory.markAttempted(requestedRoute, `status:${status}`, this.role);
             this.logAction({ action: "crawl", target: path, url: finalUrl });
+            await this.scanForInjections();
             const violations = this.oracles.drain();
             const deadEnd = elements.length === 0;
             const unnamed = elements.filter((el) => !el.name).length;
@@ -1681,6 +1755,9 @@ export class BrowserEngine {
             let preTestid = null;
             let preLabel = "";
             let forcedClick = false;
+            // What a type step has to say about the field it typed into; it goes on
+            // the step's own line, so it cannot read as the previous step's.
+            let note = "";
             let preState = null;
             try {
                 if (step.action === "navigate") {
@@ -1750,9 +1827,9 @@ export class BrowserEngine {
                             : `   hover revealed nothing within ${HOVER_REVEAL_WINDOW_MS / 1000}s`);
                     }
                     else if (step.action === "type") {
+                        await this.noteProbe(step.value ?? "", step.target ?? "the field");
                         const fillNote = await this.fillOrAppend(loc, step.value ?? "", step.replace ?? false);
-                        if (fillNote)
-                            transcript.push(`  ${fillNote.trim()}`);
+                        note = fillNote;
                         if (step.pressEnter) {
                             if (this.readOnly) {
                                 const submit = loc.locator("xpath=ancestor::form[1]").locator('[type="submit"], button:not([type="button"]):not([type="reset"])').first();
@@ -1821,19 +1898,20 @@ export class BrowserEngine {
                         /* coverage bookkeeping must never fail the plan */
                     }
                 }
+                await this.scanForInjections();
                 const violations = this.oracles.drain();
-                const mutations = this.drainMutations() + this.drainBlocked();
+                const mutations = this.drainMutations() + this.drainBlocked() + this.drainCreated();
                 // Abort only on NEW violations: a known-failing endpoint repeating on
                 // every navigation must not make every plan abort at step 1.
                 if (violations.some((v) => !v.repeat)) {
-                    transcript.push(`${desc} → OK, but oracle fired:${formatViolations(violations)}${mutations}`);
+                    transcript.push(`${desc} → OK${note}, but oracle fired:${formatViolations(violations)}${mutations}`);
                     transcript.push(`PLAN ABORTED at step ${i + 1} — investigate before continuing.`);
                     break;
                 }
                 const forcedNote = forcedClick
                     ? " (forced — the strict click timed out on this element's hit-test/stability check but a forced click still landed; something may render on top of it or delegate via a label, cross-check GEOMETRY overlaps before calling it a bug)"
                     : "";
-                transcript.push(`${desc} → OK (${page.url()})${mutations}${forcedNote}`);
+                transcript.push(`${desc} → OK (${page.url()})${note}${mutations}${forcedNote}`);
             }
             catch (err) {
                 const fullMsg = err instanceof Error ? err.message : String(err);
@@ -1909,6 +1987,125 @@ export class BrowserEngine {
         this.logAction({ action: "screenshot", url: page.url() });
         return { base64: buf.toString("base64"), mimeType: "image/jpeg" };
     }
+    /**
+     * What the live view shows next to a session's name. The task is what the
+     * agent said the session is for; the objective is the goal of the journey it
+     * is on right now (scout_journey). Both are the agent's own words — the
+     * engine sees tool calls, never the reasoning behind them. Neither is
+     * redacted here: the caller that writes them anywhere does that.
+     */
+    get liveDescription() {
+        return {
+            mode: this.mode,
+            browser: this.engineName,
+            headed: this.headed,
+            ...(this.task ? { task: this.task } : {}),
+            ...(this.journey ? { objective: this.journey.goal, objectiveSince: new Date(this.journey.startedAt).toISOString() } : {}),
+        };
+    }
+    /**
+     * A frame for somebody WATCHING the run, as opposed to scout_screenshot,
+     * which is the agent looking. It is not logged: the action log is the repro
+     * trace attached to findings, and a person glancing at the dashboard is not
+     * a step anyone should replay. It is also bounded, because the moment a
+     * viewer most wants a picture is when the renderer has wedged.
+     */
+    async liveShot(timeoutMs = 3000) {
+        const page = this.page;
+        if (!page || page.isClosed())
+            return null;
+        let timer;
+        // The driver's own timeout covers a slow capture; the race covers a
+        // renderer that never answers the protocol at all.
+        return Promise.race([
+            page.screenshot({ type: "jpeg", quality: 55, fullPage: false, timeout: timeoutMs }).catch(() => null),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(null), timeoutMs + 500);
+            }),
+        ]).finally(() => clearTimeout(timer));
+    }
+    /**
+     * Push frames of this session's page until the returned function is called.
+     * The stream follows the session rather than one tab: adopting a popup
+     * replaces `this.page`, and a stream left on the old tab would show a page
+     * the session is no longer driving.
+     */
+    async startScreencast(onFrame, onEnd = () => { }) {
+        if (!this.page || this.page.isClosed())
+            return null;
+        let stopped = false;
+        let bound = null;
+        let release = null;
+        // Ticks in a row with no page to take frames from: a re-attach passes
+        // through a few, a closed session never comes back.
+        let pageless = 0;
+        const bind = async (page) => {
+            if (screencastSupport(this.engineName) === "cdp") {
+                const cdp = await page.context().newCDPSession(page);
+                try {
+                    cdp.on("Page.screencastFrame", (frame) => {
+                        if (!stopped)
+                            onFrame(Buffer.from(frame.data, "base64"));
+                        void cdp.send("Page.screencastFrameAck", { sessionId: frame.sessionId }).catch(() => { });
+                    });
+                    await cdp.send("Page.startScreencast", { format: "jpeg", quality: 55, maxWidth: 1280, maxHeight: 900, everyNthFrame: 2 });
+                }
+                catch (err) {
+                    // Not bound: the timer tries this page again on its next tick.
+                    await cdp.detach().catch(() => { });
+                    throw err;
+                }
+                release = async () => {
+                    await cdp.send("Page.stopScreencast").catch(() => { });
+                    await cdp.detach().catch(() => { });
+                };
+            }
+            else {
+                release = null;
+            }
+            bound = page;
+        };
+        const stop = async () => {
+            stopped = true;
+            clearInterval(timer);
+            const current = release;
+            release = null;
+            await current?.();
+        };
+        await bind(this.page).catch(() => { });
+        // One timer does both jobs: it notices a replaced tab, and where the
+        // browser cannot push frames it is also what takes them.
+        const timer = setInterval(() => {
+            if (stopped)
+                return;
+            const page = this.page;
+            if (!page || page.isClosed()) {
+                pageless += 1;
+                if (pageless >= SCREENCAST_PAGELESS_TICKS)
+                    void stop().finally(onEnd);
+                return;
+            }
+            pageless = 0;
+            if (page !== bound) {
+                const previous = release;
+                release = null;
+                void (async () => {
+                    await previous?.();
+                    if (!stopped)
+                        await bind(page).catch(() => { });
+                })();
+                return;
+            }
+            if (screencastSupport(this.engineName) === "poll") {
+                void this.liveShot(1500).then((jpeg) => {
+                    if (jpeg && !stopped)
+                        onFrame(jpeg);
+                });
+            }
+        }, 500);
+        timer.unref();
+        return stop;
+    }
     get currentState() {
         return this.currentFingerprint;
     }

package/dist/engine/injection.js

@@ -0,0 +1,162 @@
+/**
+ * The DOM-injection oracle's rules: what a typed value has to look like to be
+ * worth watching for, how to look for it on a later page, and how to describe
+ * it when it turns up as an element.
+ *
+ * The engine never tells the agent what to type. It only remembers the shape
+ * of any markup-shaped value the agent chose to type, and checks every page it
+ * sees afterwards for an element of that shape. A value that comes back as an
+ * element rather than text means whoever opens that page runs the input:
+ * stored or reflected injection (XSS).
+ *
+ * An element counts as the typed one only when it carries exactly the
+ * payload's attributes (an app's own link has extras such as a testid; an
+ * injected one has just what was typed) and, when the payload had text, that
+ * text. A payload with neither is not watched: `<script>` or `<br>` on their
+ * own would match any page. No browser is needed for these rules, so they are
+ * table-tested; the one DOM query lives in browser.ts.
+ */
+import { normalizePath } from "./fingerprint.js";
+/** Most probes a session keeps. Every page is checked for each in one query, so the list can be generous: a fuzzing pass types many. */
+export const MAX_PROBES = 60;
+/** Text is compared on this many characters, on both sides, so a long fuzz value still matches its element. */
+export const INJECTION_TEXT_MAX = 200;
+/** Most matching elements reported per probe per page. */
+export const MAX_HITS = 20;
+const OPEN_RE = /<([a-zA-Z][a-zA-Z0-9-]*)/;
+// One attribute at a time, anchored where the last one ended: a slash between
+// attributes is the same as a space to a browser (`<svg/onload=…>`). Each
+// match consumes at least one character, so a hostile value cannot make the
+// parse backtrack.
+const ATTR_RE = /[\s/]*([^\s=>/]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/y;
+const CLOSE_RE = /[\s/]*>/y;
+/** Values longer than this are cut before parsing; no payload needs more. */
+const MAX_VALUE_LENGTH = 2000;
+/** Attribute names that can go into a selector as they are. Anything else is dropped rather than escaped. */
+const ATTR_NAME_RE = /^[A-Za-z_][-A-Za-z0-9_]*$/;
+function cssValue(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\a ").replace(/\r/g, "\\d ");
+}
+function routeOf(url) {
+    try {
+        return normalizePath(new URL(url).pathname);
+    }
+    catch {
+        return url || "?";
+    }
+}
+/**
+ * The shape for a typed value, or null when the value holds no element worth
+ * watching: plain text, an email, a URL, a stray `<`, and an element with
+ * nothing to tell it apart by (`<script>`, `<br>`) are none of the oracle's
+ * business.
+ */
+export function probeShape(raw) {
+    const value = raw.slice(0, MAX_VALUE_LENGTH);
+    const open = OPEN_RE.exec(value);
+    if (!open)
+        return null;
+    const tag = open[1].toLowerCase();
+    const attrs = [];
+    let pos = open.index + open[0].length;
+    for (;;) {
+        CLOSE_RE.lastIndex = pos;
+        const close = CLOSE_RE.exec(value);
+        if (close) {
+            pos += close[0].length;
+            break;
+        }
+        ATTR_RE.lastIndex = pos;
+        const a = ATTR_RE.exec(value);
+        // Neither an attribute nor the end of the tag: not an element, just a "<".
+        if (!a)
+            return null;
+        pos += a[0].length;
+        const name = a[1].toLowerCase();
+        if (!ATTR_NAME_RE.test(name))
+            continue;
+        attrs.push([name, a[2] ?? a[3] ?? a[4] ?? ""]);
+    }
+    const rest = value.slice(pos);
+    const close = rest.toLowerCase().indexOf(`</${tag}`);
+    const inner = (close >= 0 ? rest.slice(0, close) : rest).trim();
+    const text = inner ? inner.slice(0, INJECTION_TEXT_MAX) : null;
+    if (attrs.length === 0 && text === null)
+        return null;
+    return {
+        payload: value.slice(0, 200),
+        tag,
+        attrs,
+        text,
+        selector: tag + attrs.map(([name, v]) => `[${name}="${cssValue(v)}"]`).join(""),
+    };
+}
+export function injectionProbe(value, field, typedOn, baseline = 0) {
+    const shape = probeShape(value);
+    return shape ? { ...shape, field, typedOn, baseline } : null;
+}
+/**
+ * The session's probe list with one more: a payload already on it is kept as
+ * first seen (its baseline came from where it was first typed), and past the
+ * cap the oldest goes. Returns the list to keep, so the rule is testable.
+ */
+export function rememberProbe(probes, probe) {
+    if (probes.some((p) => p.payload === probe.payload))
+        return [...probes];
+    const kept = probes.length >= MAX_PROBES ? probes.slice(probes.length - MAX_PROBES + 1) : [...probes];
+    return [...kept, probe];
+}
+export function probeQueries(probes) {
+    return probes.map((p) => ({ selector: p.selector, attrs: p.attrs, text: p.text }));
+}
+/**
+ * The script the page runs to find matching elements: the same rules as
+ * matchesElement, applied in the page so the cap counts matches, not
+ * candidates. Returns [{ index, outer }] with at most MAX_HITS per probe.
+ */
+export function probeScript(queries) {
+    return (`(() => { const queries = ${JSON.stringify(queries)}; const max = ${MAX_HITS}; const textMax = ${INJECTION_TEXT_MAX}; const out = []; ` +
+        `queries.forEach((q, index) => { let els; try { els = document.querySelectorAll(q.selector); } catch { return; } let n = 0; ` +
+        `for (const el of els) { if (n >= max) break; if (el.attributes.length !== q.attrs.length) continue; ` +
+        `if (!q.attrs.every(([name, value]) => el.getAttribute(name) === value)) continue; ` +
+        `if (q.text !== null && (el.textContent || '').trim().slice(0, textMax) !== q.text) continue; ` +
+        `out.push({ index, outer: el.outerHTML.slice(0, 200) }); n += 1; } }); return out; })()`);
+}
+/** The rule the script applies, in one place a test can reach. */
+export function matchesElement(query, el) {
+    if (Object.keys(el.attrs).length !== query.attrs.length)
+        return false;
+    if (!query.attrs.every(([name, value]) => el.attrs[name] === value))
+        return false;
+    return query.text === null || el.text.trim().slice(0, INJECTION_TEXT_MAX) === query.text;
+}
+/**
+ * Which hits on a page are injections to report: more matching elements than
+ * the page the value was typed on already held (shared chrome such as a nav
+ * link is the same on every page), and not reported for this route before.
+ */
+export function newInjections(probes, hits, url, reported) {
+    const out = [];
+    const route = routeOf(url);
+    probes.forEach((probe, index) => {
+        const mine = hits.filter((h) => h.index === index);
+        if (mine.length <= probe.baseline)
+            return;
+        const key = `${probe.payload}|${route}`;
+        if (reported.has(key))
+            return;
+        reported.add(key);
+        out.push({ probe, outer: mine[mine.length - 1]?.outer ?? "", key });
+    });
+    return out;
+}
+/**
+ * The violation's detail: what it became, where it fired, and where it was
+ * typed. The element comes first because the oracle log signs a violation on
+ * the first characters of its detail: two payloads that fired on one page
+ * must not read as one.
+ */
+export function describeInjection(probe, url, outerHtml) {
+    return (`${outerHtml.slice(0, 160)} on ${routeOf(url)} is a value typed into ${probe.field} on ${routeOf(probe.typedOn)}, come back as markup — ` +
+        `whoever opens this page runs what was typed there (stored or reflected injection, XSS)`);
+}