toolroll 0.9.20 → 0.9.22

package/dist/scout-net.js

@@ -0,0 +1,214 @@
+/**
+ * The scout reaches only the public web (reviews 826, 827): every request
+ * its browser and its web fetch make goes through this local proxy, which resolves the host
+ * itself and refuses anything that is not a public internet address —
+ * loopback, private, link-local, carrier-grade NAT, multicast and reserved
+ * ranges, in IPv4 and IPv6 — then connects to the very addresses it
+ * checked, each in turn until one answers, so a name that re-resolves
+ * somewhere private gets nowhere. The one
+ * exception is the project's own demo URL, when one is set, matched by its
+ * exact scheme, host and port. Redirects and a page's own requests pass
+ * through the same check; file: never reaches a proxy, and the pinned
+ * Playwright refuses to open it.
+ */
+import { createServer, request as httpRequest } from "node:http";
+import { BlockList, connect, isIP } from "node:net";
+import { lookup as dnsLookup } from "node:dns/promises";
+/** Address ranges a scout's browser may never reach. */
+const NOT_PUBLIC = (() => {
+    const list = new BlockList();
+    for (const [net, prefix] of [
+        ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8], ["169.254.0.0", 16], ["172.16.0.0", 12],
+        ["192.0.0.0", 24], ["192.0.2.0", 24], ["192.88.99.0", 24], ["192.168.0.0", 16], ["198.18.0.0", 15], ["198.51.100.0", 24],
+        ["203.0.113.0", 24], ["224.0.0.0", 4], ["240.0.0.0", 4],
+    ])
+        list.addSubnet(net, prefix, "ipv4");
+    for (const [net, prefix] of [
+        ["::", 128], ["::1", 128], ["64:ff9b:1::", 48], ["100::", 64], ["2001::", 23], ["2001:db8::", 32], ["fc00::", 7], ["fe80::", 10], ["fec0::", 10], ["ff00::", 8],
+    ])
+        list.addSubnet(net, prefix, "ipv6");
+    return list;
+})();
+/** Whether an IP literal is a public internet address. IPv4 inside IPv6 (mapped, compatible or NAT64) is judged as IPv4. */
+export function isPublicAddress(address) {
+    const bare = address.replace(/^\[|\]$/g, "").replace(/%.*$/, "");
+    const family = isIP(bare);
+    if (family === 4)
+        return !NOT_PUBLIC.check(bare, "ipv4");
+    if (family !== 6)
+        return false;
+    const embedded = /^(?:::ffff:(?:0:)?|::|64:ff9b::)(\d+\.\d+\.\d+\.\d+)$/i.exec(bare)?.[1];
+    if (embedded !== undefined)
+        return isPublicAddress(embedded);
+    const mappedHex = /^(?:::ffff:|64:ff9b::)([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(bare);
+    if (mappedHex !== null) {
+        const high = parseInt(mappedHex[1], 16);
+        const low = parseInt(mappedHex[2], 16);
+        return isPublicAddress(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`);
+    }
+    if (/^::ffff:/i.test(bare))
+        return false;
+    return !NOT_PUBLIC.check(bare, "ipv6");
+}
+const systemLookup = async (host) => (await dnsLookup(host, { all: true, verbatim: true })).map(one => one.address);
+/** The demo URL's own origin, or null when none is set or it is not an http(s) address. */
+function demoTarget(demoUrl) {
+    if (demoUrl === undefined || demoUrl === null || demoUrl === "")
+        return null;
+    try {
+        const url = new URL(demoUrl);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return null;
+        const scheme = url.protocol === "http:" ? "http" : "https";
+        return { scheme, host: url.hostname.toLowerCase(), port: Number(url.port || (scheme === "http" ? 80 : 443)) };
+    }
+    catch {
+        return null;
+    }
+}
+/** How long one address may take to answer before the next is tried. */
+const CONNECT_TIMEOUT_MS = 10_000;
+/**
+ * A connection to the first of the checked addresses that answers, tried in turn (review 827): a host whose IPv6
+ * address is unreachable from here is still reached over IPv4. Null when none answers.
+ */
+export async function connectFirst(addresses, port, timeoutMs = CONNECT_TIMEOUT_MS) {
+    for (const address of addresses) {
+        const socket = await new Promise(done => {
+            const attempt = connect({ host: address, port });
+            const give = (value) => {
+                attempt.removeAllListeners("connect").removeAllListeners("error").removeAllListeners("timeout");
+                attempt.setTimeout(0);
+                if (value === null)
+                    attempt.destroy();
+                done(value);
+            };
+            attempt.setTimeout(timeoutMs);
+            attempt.once("connect", () => give(attempt));
+            attempt.once("error", () => give(null));
+            attempt.once("timeout", () => give(null));
+        });
+        if (socket !== null)
+            return socket;
+    }
+    return null;
+}
+/**
+ * Start the scout browser's proxy on loopback. `refused` hears every request it turned away (for the live log and
+ * tests). `lookup` resolves a host name to its addresses (the system resolver unless a test supplies one).
+ */
+export async function startScoutProxy(options = {}) {
+    const lookup = options.lookup ?? systemLookup;
+    const demo = demoTarget(options.demoUrl);
+    const sockets = new Set();
+    /** The addresses this request may reach, in the resolver's order, or why it may not. */
+    const resolve = async (target) => {
+        const host = target.host.replace(/^\[|\]$/g, "").toLowerCase();
+        const isDemo = demo !== null && demo.scheme === target.scheme && demo.host.replace(/^\[|\]$/g, "") === host && demo.port === target.port;
+        let addresses;
+        try {
+            addresses = isIP(host) !== 0 ? [host] : await lookup(host);
+        }
+        catch {
+            return { ok: false, why: "the host does not resolve" };
+        }
+        if (addresses.length === 0)
+            return { ok: false, why: "the host does not resolve" };
+        if (isDemo)
+            return { ok: true, addresses };
+        if (!addresses.every(isPublicAddress))
+            return { ok: false, why: "not a public internet address" };
+        return { ok: true, addresses };
+    };
+    const refuse = (target, why) => {
+        try {
+            options.refused?.(target, why);
+        }
+        catch { /* a listener's trouble is not the browser's */ }
+    };
+    const server = createServer((incoming, outgoing) => {
+        void (async () => {
+            let url;
+            try {
+                url = new URL(incoming.url ?? "");
+            }
+            catch {
+                outgoing.writeHead(400).end();
+                return;
+            }
+            if (url.protocol !== "http:") {
+                refuse(url.protocol, "only web pages");
+                outgoing.writeHead(403, { "content-type": "text/plain" }).end("Toolroll's scout browser opens only public web pages.");
+                return;
+            }
+            const target = { scheme: "http", host: url.hostname, port: Number(url.port || 80) };
+            const reached = await resolve(target);
+            if (!reached.ok) {
+                refuse(url.origin, reached.why);
+                outgoing.writeHead(403, { "content-type": "text/plain" }).end("Toolroll's scout browser opens only public web pages.");
+                return;
+            }
+            const upstream = await connectFirst(reached.addresses, target.port);
+            if (upstream === null) {
+                outgoing.writeHead(502).end();
+                return;
+            }
+            sockets.add(upstream);
+            upstream.on("close", () => sockets.delete(upstream));
+            const headers = { ...incoming.headers };
+            delete headers["proxy-connection"];
+            delete headers["proxy-authorization"];
+            const forward = httpRequest({ createConnection: () => upstream, method: incoming.method, path: `${url.pathname}${url.search}`, headers, setHost: false }, answer => {
+                outgoing.writeHead(answer.statusCode ?? 502, answer.headers);
+                answer.pipe(outgoing);
+            });
+            forward.on("error", () => { if (!outgoing.headersSent)
+                outgoing.writeHead(502); outgoing.end(); });
+            incoming.pipe(forward);
+        })();
+    });
+    server.on("connect", (incoming, client, head) => {
+        sockets.add(client);
+        client.on("close", () => sockets.delete(client));
+        client.on("error", () => client.destroy());
+        void (async () => {
+            const match = /^(\[[0-9a-fA-F:.]+\]|[^:[\]]+):(\d{1,5})$/.exec(incoming.url ?? "");
+            const target = match === null ? null : { scheme: "https", host: match[1], port: Number(match[2]) };
+            const reached = target === null ? { ok: false, why: "not a host and port" } : await resolve(target);
+            if (!reached.ok) {
+                refuse(incoming.url ?? "", reached.why);
+                client.end("HTTP/1.1 403 Forbidden\r\nContent-Length: 0\r\n\r\n");
+                return;
+            }
+            const upstream = await connectFirst(reached.addresses, target.port);
+            if (upstream === null) {
+                if (!client.destroyed)
+                    client.end("HTTP/1.1 502 Bad Gateway\r\nContent-Length: 0\r\n\r\n");
+                return;
+            }
+            sockets.add(upstream);
+            upstream.on("close", () => { sockets.delete(upstream); client.destroy(); });
+            upstream.on("error", () => client.destroy());
+            client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            if (head.length > 0)
+                upstream.write(head);
+            upstream.pipe(client);
+            client.pipe(upstream);
+        })();
+    });
+    server.on("connection", socket => { sockets.add(socket); socket.on("close", () => sockets.delete(socket)); });
+    await new Promise((done, fail) => {
+        server.once("error", fail);
+        server.listen(0, "127.0.0.1", () => { server.off("error", fail); done(); });
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address !== null ? address.port : 0;
+    return {
+        url: `http://127.0.0.1:${port}`,
+        close: () => new Promise(done => {
+            for (const socket of sockets)
+                socket.destroy();
+            server.close(() => done());
+        }),
+    };
+}

package/dist/scout-report.d.ts

@@ -20,6 +20,24 @@ export type ParsedReport = {
         title: string;
         goal: string;
     }[];
+    /** What the scout found, as a short list later steps can read: each cites its URL, and may show one of `images`. */
+    items: ReportItem[];
+    /** Screenshots the scout saved during the run. From the scout, `file` names a file in its output folder; once
+     * stored, the runner adds the bytes' sha256 and the evidence row that holds them. */
+    images: ReportImage[];
+};
+export type ReportItem = {
+    title: string;
+    why: string;
+    url: string;
+    image: string | null;
+};
+export type ReportImage = {
+    file: string;
+    caption: string;
+    url: string;
+    sha256?: string;
+    artifact?: number;
 };
 export type ReportParseResult = {
     ok: true;
@@ -38,7 +56,15 @@ export declare const REPORT_LIMITS: {
     readonly followUps: 5;
     readonly followUpTitle: 200;
     readonly followUpGoal: 2000;
+    readonly items: 6;
+    readonly itemTitle: 200;
+    readonly itemWhy: 1000;
+    readonly url: 2000;
+    readonly images: 8;
+    readonly caption: 300;
 };
+/** A screenshot's name in the scout's output folder: one plain file name, PNG or JPEG, never a path. */
+export declare const REPORT_IMAGE_FILE: RegExp;
 /**
  * The scout's handback for Claude's `--json-schema` (run 2334's fix): plan
  * mode only lets a session write its own plan file, so a Claude scout
@@ -82,6 +108,47 @@ export declare const SCOUT_OUTPUT_JSON_SCHEMA: {
                         readonly additionalProperties: false;
                     };
                 };
+                readonly items: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly title: {
+                                readonly type: "string";
+                            };
+                            readonly why: {
+                                readonly type: "string";
+                            };
+                            readonly url: {
+                                readonly type: "string";
+                            };
+                            readonly image: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["title", "why", "url"];
+                        readonly additionalProperties: false;
+                    };
+                };
+                readonly images: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly file: {
+                                readonly type: "string";
+                            };
+                            readonly caption: {
+                                readonly type: "string";
+                            };
+                            readonly url: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["file", "caption", "url"];
+                        readonly additionalProperties: false;
+                    };
+                };
             };
             readonly required: readonly ["title", "summary", "report"];
             readonly additionalProperties: false;

package/dist/scout-report.js

@@ -17,7 +17,15 @@ export const REPORT_LIMITS = {
     followUps: 5,
     followUpTitle: 200,
     followUpGoal: 2_000,
+    items: 6,
+    itemTitle: 200,
+    itemWhy: 1_000,
+    url: 2_000,
+    images: 8,
+    caption: 300,
 };
+/** A screenshot's name in the scout's output folder: one plain file name, PNG or JPEG, never a path. */
+export const REPORT_IMAGE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}\.(?:png|jpe?g)$/i;
 const REPORT_SHAPE = {
     type: "object",
     properties: {
@@ -33,6 +41,24 @@ const REPORT_SHAPE = {
                 additionalProperties: false,
             },
         },
+        items: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { title: { type: "string" }, why: { type: "string" }, url: { type: "string" }, image: { type: "string" } },
+                required: ["title", "why", "url"],
+                additionalProperties: false,
+            },
+        },
+        images: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { file: { type: "string" }, caption: { type: "string" }, url: { type: "string" } },
+                required: ["file", "caption", "url"],
+                additionalProperties: false,
+            },
+        },
     },
     required: ["title", "summary", "report"],
     additionalProperties: false,
@@ -165,7 +191,88 @@ export function parseReport(raw) {
             }
         }
     }
+    const images = listOf(body["images"], "images", REPORT_LIMITS.images, problems, (entry, at) => {
+        // Any one line here: the runner refuses an image that isn't a plain file name in its output folder, not the report.
+        const file = prose(entry["file"], `${at}.file`, REPORT_LIMITS.caption, problems);
+        const caption = prose(entry["caption"], `${at}.caption`, REPORT_LIMITS.caption, problems);
+        const url = link(entry["url"], `${at}.url`, problems);
+        if (file !== null && /[\n\r]/.test(file))
+            problems.push({ reason: `${at}-file-multiline`, message: `${at}.file must be one line` });
+        if (caption !== null && /[\n\r]/.test(caption))
+            problems.push({ reason: `${at}-caption-multiline`, message: `${at}.caption must be one line` });
+        const sha256 = entry["sha256"];
+        if (sha256 !== undefined && (typeof sha256 !== "string" || !/^[0-9a-f]{64}$/.test(sha256)))
+            problems.push({ reason: `${at}-sha256`, message: `${at}.sha256 must be a sha256 hex digest` });
+        const artifact = entry["artifact"];
+        if (artifact !== undefined && (typeof artifact !== "number" || !Number.isSafeInteger(artifact) || artifact <= 0))
+            problems.push({ reason: `${at}-artifact`, message: `${at}.artifact must be an evidence id` });
+        if (file === null || caption === null || url === null || /[\n\r]/.test(file) || /[\n\r]/.test(caption))
+            return null;
+        return { file, caption, url, ...(typeof sha256 === "string" ? { sha256 } : {}), ...(typeof artifact === "number" ? { artifact } : {}) };
+    });
+    const files = new Set();
+    for (const one of images) {
+        if (files.has(one.file))
+            problems.push({ reason: "images-duplicate", message: `images names ${one.file} twice` });
+        files.add(one.file);
+    }
+    const items = listOf(body["items"], "items", REPORT_LIMITS.items, problems, (entry, at) => {
+        const itemTitle = prose(entry["title"], `${at}.title`, REPORT_LIMITS.itemTitle, problems);
+        const why = prose(entry["why"], `${at}.why`, REPORT_LIMITS.itemWhy, problems);
+        const url = link(entry["url"], `${at}.url`, problems);
+        const image = entry["image"] === undefined || entry["image"] === null || entry["image"] === "" ? null : entry["image"];
+        if (itemTitle !== null && /[\n\r]/.test(itemTitle))
+            problems.push({ reason: `${at}-title-multiline`, message: `${at}.title must be one line` });
+        if (image !== null && (typeof image !== "string" || !files.has(image)))
+            problems.push({ reason: `${at}-image`, message: `${at}.image must name one of images by its file` });
+        if (itemTitle === null || why === null || url === null || /[\n\r]/.test(itemTitle) || (image !== null && (typeof image !== "string" || !files.has(image))))
+            return null;
+        return { title: itemTitle, why, url, image: image };
+    });
     if (problems.length > 0)
         return { ok: false, problems };
-    return { ok: true, report: { title: title, summary: summary, report: document, followUps } };
+    return { ok: true, report: { title: title, summary: summary, report: document, followUps, items, images } };
+}
+/** An optional capped list of objects, each read by `one`; problems are reported, never thrown. */
+function listOf(value, field, cap, problems, one) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        problems.push({ reason: `bad-${field}`, message: `${field} must be an array (got ${describe(value)})` });
+        return [];
+    }
+    if (value.length > cap) {
+        problems.push({ reason: `${field}-too-many`, message: `${field} lists ${value.length} — cap is ${cap}` });
+        return [];
+    }
+    const kept = [];
+    for (const [index, entry] of value.entries()) {
+        const at = `${field}[${index}]`;
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            problems.push({ reason: `${at}-shape`, message: `${at} must be an object` });
+            continue;
+        }
+        const read = one(entry, at);
+        if (read !== null)
+            kept.push(read);
+    }
+    return kept;
+}
+/** A cited web address: http or https, one line, no credentials. */
+function link(value, field, problems) {
+    const text = prose(value, field, REPORT_LIMITS.url, problems);
+    if (text === null)
+        return null;
+    let url = null;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        url = null;
+    }
+    if (url === null || (url.protocol !== "http:" && url.protocol !== "https:") || /\s/.test(text) || url.username !== "" || url.password !== "") {
+        problems.push({ reason: `${field}-not-a-link`, message: `${field} must be an http or https address` });
+        return null;
+    }
+    return text;
 }

package/dist/scout.d.ts

@@ -2,6 +2,31 @@ import type { Store } from "./store.js";
 import { type ParsedDecision, type Problem } from "./decision.js";
 import { type ParsedReport, type ReportProblem } from "./scout-report.js";
 import type { Runner } from "./builder.js";
+import { type ToolSpec } from "./project-tools.js";
+import * as browserCheck from "./scout-browser.js";
+/** The scout's own headless browser: the pinned Playwright tool, saving its
+ * screenshots straight into the run's image folder. */
+export declare const SCOUT_BROWSER = "toolroll-browser";
+/**
+ * What a Claude scout may use without asking (`dontAsk` denies the rest):
+ * reading the checkout (always allowed), web search and fetch for research,
+ * and its browser for screenshots. Nothing that edits a file or runs a
+ * command, so the read-only posture holds by permission as well as by the
+ * clean-tree proof.
+ */
+export declare const SCOUT_ALLOWED_TOOLS: readonly string[];
+/** The scout's browser launch, or null when this install has no Playwright entry (the scout then researches without
+ * screenshots). The worker runs it outside the agent fence with Chrome's own sandbox on (run 2356, review 828:
+ * scout-browser.ts). Every request it makes goes through `proxy` (scout-net.ts), which lets only public pages and the
+ * project's own demo through; loopback is proxied too, never bypassed, and file: stays blocked. Screenshots are saved
+ * in `imageFolder`. */
+export declare function scoutBrowserLaunch(tool: Pick<ToolSpec, "command" | "args"> | null, imageFolder: string, proxy: string): browserCheck.BrowserLaunch | null;
+/** What the fenced scout gets: the running browser's loopback address, nothing it could launch itself. */
+export declare function scoutBrowser(url: string): Record<string, unknown>;
+/** The scout's environment while its proxy runs (review 827): web fetch and the provider's own traffic go through
+ * the same public-web-only proxy as its browser, so only public addresses (and the project's demo) are reachable.
+ * The one direct address is its own browser's port, when it has one (review 828): the proxy refuses loopback. */
+export declare function scoutProxyEnv(proxy: string, browserUrl?: string | null): Record<string, string>;
 export type ScoutRequest = {
     /** v105: what's left of a monthly budget this API-key work counts toward (the CLI's own cap), when one does. */
     maxBudgetUsd?: number;
@@ -35,6 +60,13 @@ export type ScoutRequest = {
         choice: string;
         note: string | null;
     }[];
+    /** Where the scout may save screenshots: outside the checkout, so the clean-tree proof still holds. Left out, a
+     * fresh temporary folder is made for this run and removed after it. */
+    outputDir?: string;
+    /** The project's own demo or dev server, the one non-public address the scout's browser may open. */
+    demoUrl?: string | null;
+    /** The browser to launch; left out, the catalog's Playwright entry. Null runs the scout without one. */
+    browserTool?: Pick<ToolSpec, "command" | "args"> | null;
 };
 export type ReportArtifact = {
     key: string;
@@ -67,3 +99,19 @@ export type ScoutOutcome = {
     problems?: (Problem | ReportProblem)[];
 };
 export declare function scout(store: Store, request: ScoutRequest): Promise<ScoutOutcome>;
+/** One screenshot from the scout's output folder: a plain file name (never a path), a regular file (never a link),
+ * at most SCREENSHOT_BYTE_CAP, and a PNG or JPEG by its signature. */
+export declare function readReportImage(folder: string, file: string): {
+    ok: true;
+    bytes: Buffer;
+    kind: "png" | "jpeg";
+} | {
+    ok: false;
+    problem: string;
+};
+/** A cited link without its secrets: credential-shaped query values and path parts become REDACTED, a fragment
+ * that carries one is dropped, and a link still showing one keeps only its origin. Unchanged when it has none. */
+export declare function scrubUrl(text: string): {
+    url: string;
+    scrubbed: boolean;
+};