toolroll 0.9.19 → 0.9.21

package/dist/result-shots.js

@@ -15,11 +15,11 @@
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { imageDimensions, readVerifiedProofForRun, RETENTION_NOTE } from "./evidence.js";
+import { imageDimensions, readVerifiedProofForRun, readVerifiedReport, RETENTION_NOTE } from "./evidence.js";
 import { resultImageFileName, verifyResultImage } from "./chat-evidence.js";
 import { publicChatText } from "./chat-display.js";
 import { chatTitle } from "./chat-voice.js";
-import { RESULT_SHOTS_KIND } from "./store.js";
+import { FLOW_SHOTS_KIND, RESULT_SHOTS_KIND } from "./store.js";
 /** "Up to 4": the most screenshots one result ever sends. */
 export const RESULT_SHOTS_MAX = 4;
 /** The choices in the order Settings and the CLI show them. */
@@ -45,6 +45,19 @@ function ownCaptions(store, root, run) {
     }
     return captions;
 }
+/** A scout's screenshots keep the captions its report gave them, by evidence id. */
+function reportCaptions(store, root, taskRef, run) {
+    const captions = new Map();
+    const view = readVerifiedReport(store, root, taskRef);
+    if (view === null || !view.ok || view.run !== run)
+        return captions;
+    for (const image of view.report.images) {
+        const words = publicChatText(image.caption, 200).trim();
+        if (image.artifact !== undefined && words !== "" && !words.includes("[sensitive text hidden]"))
+            captions.set(image.artifact, words);
+    }
+    return captions;
+}
 function isPhoto(bytes, format) {
     const size = imageDimensions(bytes, format);
     if (size === null || size.width === 0 || size.height === 0)
@@ -59,9 +72,10 @@ function isPhoto(bytes, format) {
  * no wait in between, or asks again.
  */
 export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()) {
-    if (row.kind !== RESULT_SHOTS_KIND || row.recipient === null || row.taskId === null || row.taskRef === null || row.run === null)
+    if (!isShotsKind(row.kind) || row.recipient === null || row.taskId === null || row.taskRef === null || row.run === null)
         return { kind: "none", why: "none" };
-    const limit = resultShotLimit(store.notificationPreference(row.recipient).screenshots);
+    // A flow's "Send to me" or "Person chooses" asked for them: up to four, whatever the person chose for results.
+    const limit = row.kind === FLOW_SHOTS_KIND ? RESULT_SHOTS_MAX : resultShotLimit(store.notificationPreference(row.recipient).screenshots);
     if (limit === 0)
         return { kind: "none", why: "off" };
     const title = chatTitle(store, row.taskId);
@@ -82,6 +96,7 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
     if (chosen.length === 0)
         return { kind: "none", why: "none" };
     const captions = ownCaptions(store, evidenceRoot, row.run);
+    const reported = latest.role === "scout" ? reportCaptions(store, evidenceRoot, row.taskRef, row.run) : new Map();
     const shots = [];
     for (const [index, artifact] of chosen.entries()) {
         const verified = verifyResultImage(store, evidenceRoot, repos, { taskId: row.taskId, run: row.run, artifact: artifact.id, sha256: artifact.sha256 });
@@ -91,7 +106,7 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
                 return { kind: "none", why: "pruned" };
             return line(verified.problem);
         }
-        const own = captions.get(SCREENSHOT_CAPTURE.exec(artifact.capture)?.[1] ?? "") ?? null;
+        const own = captions.get(SCREENSHOT_CAPTURE.exec(artifact.capture)?.[1] ?? "") ?? reported.get(artifact.id) ?? null;
         shots.push({
             artifact: artifact.id, sha256: artifact.sha256, bytes: verified.bytes, format: verified.format,
             fileName: resultImageFileName(row.taskId, row.run, artifact.id, verified.format),
@@ -102,6 +117,10 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
     const remaining = shots.filter(one => !sent.has(one.artifact));
     return remaining.length === 0 ? { kind: "none", why: "sent" } : { kind: "send", taskId: row.taskId, run: row.run, shots: remaining };
 }
+/** A row that carries a result's screenshots: one a person asked for with results, or one a flow sends them. */
+export function isShotsKind(kind) {
+    return kind === RESULT_SHOTS_KIND || kind === FLOW_SHOTS_KIND;
+}
 /** A screenshot whose result message is not posted yet waits for that message's own next try (at least a second). */
 export function shotWaitsUntil(resultNextAt, now) {
     const soonest = new Date(now.getTime() + 1_000).toISOString();

package/dist/scout-net.d.ts

@@ -0,0 +1,22 @@
+import { type Socket } from "node:net";
+/** Whether an IP literal is a public internet address. IPv4 inside IPv6 (mapped, compatible or NAT64) is judged as IPv4. */
+export declare function isPublicAddress(address: string): boolean;
+export type Lookup = (host: string) => Promise<readonly string[]>;
+/**
+ * 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 declare function connectFirst(addresses: readonly string[], port: number, timeoutMs?: number): Promise<Socket | null>;
+export type ScoutProxy = {
+    url: string;
+    close: () => Promise<void>;
+};
+/**
+ * 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 declare function startScoutProxy(options?: {
+    demoUrl?: string | null;
+    lookup?: Lookup;
+    refused?: (target: string, why: string) => void;
+}): Promise<ScoutProxy>;

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,5 +56,147 @@ 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
+ * returns a report — or a question for the operator — as structured output
+ * on the terminal result event. Shape only, never the validator: byte caps,
+ * one-line titles and control characters stay `parseReport`'s and
+ * `parseDecision`'s, applied to the re-serialized body.
+ */
+export declare const SCOUT_OUTPUT_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly kind: {
+            readonly type: "string";
+            readonly enum: readonly ["report", "question"];
+        };
+        readonly report: {
+            readonly type: "object";
+            readonly properties: {
+                readonly title: {
+                    readonly type: "string";
+                };
+                readonly summary: {
+                    readonly type: "string";
+                };
+                readonly report: {
+                    readonly type: "string";
+                };
+                readonly followUps: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly title: {
+                                readonly type: "string";
+                            };
+                            readonly goal: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["title", "goal"];
+                        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;
+        };
+        readonly decision: {
+            readonly type: "object";
+            readonly properties: {
+                readonly urgency: {
+                    readonly type: "string";
+                    readonly enum: readonly ["blocking"];
+                };
+                readonly recap: {
+                    readonly type: "string";
+                };
+                readonly question: {
+                    readonly type: "string";
+                };
+                readonly options: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly label: {
+                                readonly type: "string";
+                            };
+                            readonly consequence: {
+                                readonly type: "string";
+                            };
+                            readonly reversible: {
+                                readonly type: "boolean";
+                            };
+                        };
+                        readonly required: readonly ["id", "label", "consequence", "reversible"];
+                        readonly additionalProperties: false;
+                    };
+                };
+                readonly recommendation: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["urgency", "recap", "question", "options", "recommendation"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly required: readonly ["kind"];
+    readonly additionalProperties: false;
 };
 export declare function parseReport(raw: string): ReportParseResult;

package/dist/scout-report.js

@@ -17,6 +17,95 @@ 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: {
+        title: { type: "string" },
+        summary: { type: "string" },
+        report: { type: "string" },
+        followUps: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { title: { type: "string" }, goal: { type: "string" } },
+                required: ["title", "goal"],
+                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,
+};
+/** The park mailbox's decision, the same fields `parseDecision` reads. */
+const DECISION_SHAPE = {
+    type: "object",
+    properties: {
+        urgency: { type: "string", enum: ["blocking"] },
+        recap: { type: "string" },
+        question: { type: "string" },
+        options: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    label: { type: "string" },
+                    consequence: { type: "string" },
+                    reversible: { type: "boolean" },
+                },
+                required: ["id", "label", "consequence", "reversible"],
+                additionalProperties: false,
+            },
+        },
+        recommendation: { type: "string" },
+    },
+    required: ["urgency", "recap", "question", "options", "recommendation"],
+    additionalProperties: false,
+};
+/**
+ * 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
+ * returns a report — or a question for the operator — as structured output
+ * on the terminal result event. Shape only, never the validator: byte caps,
+ * one-line titles and control characters stay `parseReport`'s and
+ * `parseDecision`'s, applied to the re-serialized body.
+ */
+export const SCOUT_OUTPUT_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        kind: { type: "string", enum: ["report", "question"] },
+        report: REPORT_SHAPE,
+        decision: DECISION_SHAPE,
+    },
+    required: ["kind"],
+    additionalProperties: false,
 };
 function refuse(reason, message) {
     return { ok: false, problems: [{ reason, message }] };
@@ -102,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;
 }