toolroll 0.9.104 → 0.9.105

package/dist/scout-browser-lock.js

@@ -1,9 +1,3 @@
-/**
- * The scout browser helper's pinned install (scout-browser.ts ensureScoutBrowserHelper): its manifest and lockfile,
- * generated once with `npm install --package-lock-only --registry https://registry.npmjs.org/` for @playwright/mcp
- * 0.0.82. `npm ci` installs exactly this tree and refuses any tarball whose sha512 differs. Changing a version here is
- * a supply-chain change: regenerate both and review the diff.
- */
 export const SCOUT_BROWSER_MANIFEST = {
     "name": "toolroll-scout-browser",
     "private": true,

package/dist/scout-browser.js

@@ -1,23 +1,3 @@
-/**
- * The scout's browser (run 2356, review 828). Chrome's own sandbox can't start inside the agent fence (nested
- * Seatbelt: every page crashed, even example.com), and switching that sandbox off is not an option. So the browser
- * tool runs beside the agent instead of under it: the worker starts the pinned Playwright MCP itself, outside the
- * fence with Chrome's sandbox on, serving its HTTP transport on a random loopback port, and the fenced agent gets
- * only that URL. Every page still goes through the scout's public-web-only proxy, and screenshots land in the run's
- * image folder. Before research begins the browser is checked once, through that proxy, on a public page, with one
- * time limit for the whole check; a browser that can't start is said in one line and the scout researches
- * without it.
- *
- * Playwright MCP 0.0.82 has no per-client token for its HTTP transport; it answers only on 127.0.0.1, only for
- * that host name (its own host check), and only while this run's scout does.
- *
- * An explicit exception (docs/plans/sandbox-parity.md C4, owner Q-A): Toolroll can't fence this process without
- * switching Chrome's sandbox off, so its launch is held to a contract instead, and refused when any part fails
- * (`browserContractProblem`): the pinned Playwright MCP and its Chrome for Testing are installed in Toolroll's own
- * helpers folder (inside the state folder every build's fence denies) and run by Toolroll's own Node; its arguments are
- * exactly the expected ones (Chrome's sandbox on, the scout's proxy on, its image folder as its output and working
- * folder); its environment is an allowlist. The run records which exception it ran under.
- */
 import { spawn } from "node:child_process";
 import { request as httpRequest } from "node:http";
 import { connect, createServer } from "node:net";
@@ -27,18 +7,14 @@ import { dirname, join, relative, isAbsolute } from "node:path";
 import { run } from "./exec.js";
 import { SCOUT_BROWSER_LOCK, SCOUT_BROWSER_MANIFEST } from "./scout-browser-lock.js";
 import { sleep } from "./sleep.js";
-/** The public page the check opens through the scout's proxy. */
 export const PREFLIGHT_PAGE = "https://example.com/";
 const PREFLIGHT_TIMEOUT_MS = 60_000;
 const CLOSE_GRACE_MS = 5_000;
 const IMAGE = /\.(png|jpe?g)$/i;
-/** How a scout gets its browser: started for real under its launch contract, or, for a test's stub agent, a placeholder
- * that starts nothing. */
 export function starterFor(agentInjected) {
     return agentInjected ? unstarted : startContractedBrowser;
 }
 const unstarted = async () => ({ ok: true, server: { url: "http://127.0.0.1:9/mcp", close: async () => undefined } });
-/** Start the browser tool outside the fence and check it opens a public page and saves a screenshot. */
 export async function startScoutBrowser(launch, options) {
     const timeoutMs = options.timeoutMs ?? PREFLIGHT_TIMEOUT_MS;
     const deadline = Date.now() + timeoutMs;
@@ -60,7 +36,6 @@ export async function startScoutBrowser(launch, options) {
     }
     finally {
         await session.close();
-        // The check's own screenshot and page notes are not the scout's.
         for (const name of entries(options.folder))
             if (!before.has(name))
                 rmSync(join(options.folder, name), { recursive: true, force: true });
@@ -77,7 +52,6 @@ async function preflight(session) {
     }
     return { ok: true };
 }
-/** Spawn the tool with its HTTP transport on a free 127.0.0.1 port and wait until it answers there. */
 async function serveBrowser(launch, options, deadline, late) {
     const port = await freePort();
     const child = spawn(launch.command, [...launch.args, "--host", "127.0.0.1", "--port", String(port), "--allowed-hosts", `127.0.0.1:${port}`], {
@@ -97,10 +71,8 @@ async function serveBrowser(launch, options, deadline, late) {
             signal(child.pid, "SIGTERM");
             await Promise.race([exited, new Promise(done => setTimeout(done, CLOSE_GRACE_MS).unref())]);
         }
-        // Its browser and helpers go with it.
         signal(child.pid, "SIGKILL");
     };
-    // First runs download the pinned tool; it listens once it is ready.
     while (stopped === null && Date.now() < deadline && !(await answers(port)))
         await sleep(250);
     if (stopped !== null || Date.now() >= deadline) {
@@ -135,7 +107,7 @@ function signal(pid, name) {
     try {
         process.kill(process.platform === "win32" ? pid : -pid, name);
     }
-    catch { /* already gone */ }
+    catch { }
 }
 function entries(folder) {
     try {
@@ -145,7 +117,6 @@ function entries(folder) {
         return [];
     }
 }
-/** A client of the browser's HTTP transport, as the scout's own is: every step answers by `deadline`, or says why not. */
 export function openSession(url, deadline, late) {
     let session = null;
     let next = 0;
@@ -197,13 +168,11 @@ export function openSession(url, deadline, late) {
             return failed === null ? { ok: true, result: (answer.message["result"] ?? {}) } : { ok: false, reason: failed };
         },
         close: async () => {
-            // Ending the session closes its browser context.
             if (session !== null)
                 await post({}, "DELETE");
         },
     };
 }
-/** The JSON-RPC messages in an answer: a plain JSON body, or the data lines of an event stream. */
 function messages(text) {
     const bodies = text.trimStart().startsWith("{") ? [text] : text.split("\n").filter(line => line.startsWith("data:")).map(line => line.slice(5));
     return bodies.flatMap(body => {
@@ -216,7 +185,6 @@ function messages(text) {
         }
     });
 }
-/** Why a tool call failed, in one line, or null when it worked. */
 function toolFailure(answer) {
     if (answer["error"] !== undefined)
         return errorText(answer);
@@ -235,28 +203,20 @@ function lastLine(text) {
     return oneLine(text.trim().split("\n").at(-1) ?? "");
 }
 function oneLine(text) {
-    // eslint-disable-next-line no-control-regex
     return text.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim().slice(0, 200);
 }
-// ---- the launch contract (docs/plans/sandbox-parity.md C4) ----
-/** The pinned browser tool, installed once into Toolroll's helpers folder. */
 export const SCOUT_BROWSER_PACKAGE = "@playwright/mcp@0.0.82";
 const HELPER_NAME = "scout-browser-0.0.82";
-/** The names of the worker's environment the browser tool gets: an allowlist, never a denylist. */
 export const SCOUT_BROWSER_ENV = ["PATH", "HOME", "USER", "LOGNAME", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "TMPDIR",
     "HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"];
-/** What the run records of the exception it ran under. */
 export const SCOUT_BROWSER_CONTAINMENT = "Chrome's sandbox";
-/** Where the pinned browser lives under `helpers`. */
 export function scoutBrowserHelper(helpers) {
     const folder = join(helpers, HELPER_NAME);
     return { folder, cli: join(folder, "node_modules", "@playwright", "mcp", "cli.js"), browsers: join(folder, "browsers") };
 }
-/** The scout's browser tool: the pinned helper, run by Toolroll's own Node, headless, on its bundled Chrome. */
 export function scoutBrowserTool(helpers) {
     return { command: process.execPath, args: [scoutBrowserHelper(helpers).cli, "--headless", "--browser", "chromium"] };
 }
-/** A folder of Toolroll's own: a real folder (no link at it), this user's, private (0700). */
 function privateFolder(path) {
     try {
         const held = lstatSync(path);
@@ -267,13 +227,6 @@ function privateFolder(path) {
     }
 }
 const within = (child, parent) => { const rel = relative(parent, child); return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel); };
-/**
- * Why a browser launch breaks its contract, or null when it holds. Every input it trusts is the plane's: the helpers
- * folder and the proxy come from `options.contract`, never from the launch. The executable must be Toolroll's own
- * Node; the script the pinned helper's, inside a private helpers folder; the arguments exactly the expected ones (no
- * way to switch Chrome's sandbox off, point at another browser or executable, or drop the proxy); the working folder
- * the image folder; the environment only allowlisted names.
- */
 export function browserContractProblem(launch, options) {
     const contract = options.contract;
     if (contract === undefined)
@@ -303,13 +256,9 @@ export function browserContractProblem(launch, options) {
         return "the browser's environment doesn't point at the scout's proxy";
     return null;
 }
-/** The registry the helper is installed from: pinned, whatever any npm configuration says. */
 const NPM_REGISTRY = "https://registry.npmjs.org/";
 const sha256 = (text) => createHash("sha256").update(text).digest("hex");
-/** The pinned lockfile's digest, recorded when the helper is installed and checked before every use. */
 export const SCOUT_BROWSER_LOCK_DIGEST = sha256(JSON.stringify(SCOUT_BROWSER_LOCK));
-/** The npm of the Node running Toolroll (`lib/node_modules/npm/bin/npm-cli.js` beside it), run by that Node by path:
- * never an `npm` found on PATH. Null where this Node has none beside it (a bundled runtime). */
 export function ownNpm(execPath = process.execPath) {
     const cli = join(dirname(dirname(execPath)), "lib", "node_modules", "npm", "bin", "npm-cli.js");
     try {
@@ -319,15 +268,6 @@ export function ownNpm(execPath = process.execPath) {
         return null;
     }
 }
-/**
- * Install the pinned browser into the helpers folder once. The worker runs this outside every fence, so nothing a build
- * could have written may steer it: npm is Toolroll's own Node's, run by path; HOME is the staging folder and the user
- * and global npm configurations are an empty file there (no ~/.npmrc, no global npmrc, no registry, script or Node
- * option from either); the registry is pinned; install scripts never run; `npm ci` installs exactly the pinned lockfile
- * (scout-browser-lock.ts) and refuses a tarball whose integrity differs; the installed versions are checked against it
- * before ready.json is written. The npm cache and Chrome for Testing stay in the folder, never in the user's caches.
- * Residual: Chrome for Testing comes from Playwright's own download over HTTPS, without a pinned hash.
- */
 export async function ensureScoutBrowserHelper(helpers, timeoutMs = 600_000) {
     const helper = scoutBrowserHelper(helpers);
     if (helperReady(helper.folder))
@@ -338,7 +278,7 @@ export async function ensureScoutBrowserHelper(helpers, timeoutMs = 600_000) {
     try {
         mkdirSync(helpers, { recursive: true, mode: 0o700 });
     }
-    catch { /* checked next */ }
+    catch { }
     if (!privateFolder(helpers))
         return { ok: false, reason: "Toolroll's helpers folder isn't a private folder of its own" };
     const staging = mkdtempSync(join(helpers, ".install-"));
@@ -370,10 +310,7 @@ export async function ensureScoutBrowserHelper(helpers, timeoutMs = 600_000) {
         rmSync(staging, { recursive: true, force: true });
     }
 }
-/** How the helper's npm runs in `staging`: Toolroll's own npm by path, with its home, user and global configuration
- * the staging folder's own empty ones, the registry and cache pinned; the environment only these names. */
 export function helperNpm(staging, npm) {
-    // Two empty files: npm refuses to load one file as both.
     const user = join(staging, "user.npmrc"), global = join(staging, "global.npmrc");
     for (const file of [user, global])
         writeFileSync(file, "", { mode: 0o600 });
@@ -383,7 +320,6 @@ export function helperNpm(staging, npm) {
     };
     return { env, args: [npm, "--no-update-notifier", `--registry=${NPM_REGISTRY}`, "--userconfig", user, "--globalconfig", global, "--cache", join(staging, "npm-cache")] };
 }
-/** Whether a helper folder holds the pinned install: its ready note names this lockfile, and its tree still matches. */
 function helperReady(folder) {
     try {
         const ready = JSON.parse(readFileSync(join(folder, "ready.json"), "utf8"));
@@ -393,7 +329,6 @@ function helperReady(folder) {
         return false;
     }
 }
-/** What of an installed tree differs from the pinned lockfile (a package missing or at another version), or null. */
 export function lockDrift(folder) {
     for (const [path, entry] of Object.entries(SCOUT_BROWSER_LOCK.packages)) {
         if (path === "" || entry.version === undefined)
@@ -410,7 +345,6 @@ export function lockDrift(folder) {
     }
     return null;
 }
-/** The production starter: the pinned helper in place, then the launch held to its contract, then started. */
 export async function startContractedBrowser(launch, options) {
     if (options.contract === undefined)
         return { ok: false, reason: "the browser has no launch contract" };

package/dist/scout-net.js

@@ -1,20 +1,6 @@
-/**
- * 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 [
@@ -29,7 +15,6 @@ const NOT_PUBLIC = (() => {
         list.addSubnet(net, prefix, "ipv6");
     return list;
 })();
-/** An IPv6 address as its eight 16-bit groups, whatever way it was written (compressed, expanded, IPv4-tailed). */
 function ipv6Groups(address) {
     if (isIP(address) !== 6)
         return null;
@@ -48,10 +33,6 @@ function ipv6Groups(address) {
     const groups = [...left, ...Array(rest === undefined ? 0 : missing).fill("0"), ...right].map(one => parseInt(one, 16));
     return groups.length === 8 && groups.every(one => Number.isInteger(one) && one >= 0 && one <= 0xffff) ? groups : null;
 }
-/**
- * Whether an IP literal is a public internet address. IPv4 inside IPv6 (mapped, translated, compatible or NAT64) is
- * judged as IPv4, read from the address's groups so every way of writing it is caught (an expanded NAT64 form too).
- */
 export function isPublicAddress(address) {
     const bare = address.replace(/^\[|\]$/g, "").replace(/%.*$/, "");
     const family = isIP(bare);
@@ -64,7 +45,6 @@ export function isPublicAddress(address) {
         return false;
     const v4 = (high, low) => `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
     const zero = (from, to) => groups.slice(from, to).every(one => one === 0);
-    // ::ffff:a.b.c.d (mapped), ::ffff:0:a.b.c.d (translated), ::a.b.c.d (compatible), 64:ff9b::a.b.c.d (NAT64).
     if (zero(0, 5) && groups[5] === 0xffff)
         return isPublicAddress(v4(groups[6], groups[7]));
     if (zero(0, 4) && groups[4] === 0xffff && groups[5] === 0)
@@ -76,7 +56,6 @@ export function isPublicAddress(address) {
     return !NOT_PUBLIC.check(groups.map(one => one.toString(16)).join(":"), "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;
@@ -91,12 +70,7 @@ function demoTarget(demoUrl) {
         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 => {
@@ -118,15 +92,10 @@ export async function connectFirst(addresses, port, timeoutMs = CONNECT_TIMEOUT_
     }
     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;
@@ -149,7 +118,7 @@ export async function startScoutProxy(options = {}) {
         try {
             options.refused?.(target, why);
         }
-        catch { /* a listener's trouble is not the browser's */ }
+        catch { }
     };
     const server = createServer((incoming, outgoing) => {
         void (async () => {

package/dist/scout-report.js

@@ -1,10 +1,3 @@
-/**
- * The scout's terminal handoff (mate arc §10), read against the report contract (src/contracts/scout-report.ts) with
- * the 422 rule: fail closed, every problem reported at once, each naming its path (`items[0].url: must be an http or
- * https address`), stable reasons, caps and control-character rejection on every string. A report reaches the task
- * page, the ledger, the terminal, and — through leadView — the lead; and each follow-up becomes a filing's title and
- * goal at one tap, so it gets the park discipline exactly as the plan does.
- */
 import { contractProblemOf } from "./contracts/contract.js";
 import { FOLLOW_UP_TEXT_FIELDS, IMAGE_TEXT_FIELDS, ITEM_TEXT_FIELDS, readReportPayload, REPORT_LIMITS, REPORT_TEXT_FIELDS, reportPayloadBody, } from "./contracts/scout-report.js";
 import { hasForbiddenControls } from "./decision.js";
@@ -13,8 +6,6 @@ export { REPORT_IMAGE_FILE, REPORT_LIMITS, REPORT_VERSION, SCOUT_OUTPUT_JSON_SCH
 function refuse(reason, message) {
     return { ok: false, problems: [{ reason, message }] };
 }
-/** A report, checked. `stored`: one already kept as evidence, read without the length caps (a report written under
- * higher limits stays readable); every other check still holds. */
 export function parseReport(raw, options = {}) {
     const stored = options.stored === true;
     if (!stored && Buffer.byteLength(raw, "utf8") > REPORT_LIMITS.payload) {
@@ -31,7 +22,6 @@ export function parseReport(raw, options = {}) {
     if (body === null)
         return refuse("not-an-object", "payload: must be one JSON object");
     const read = readReportPayload(parsed, { stored });
-    // Every report limit counts UTF-8 bytes, including those TEXT_LIMITS names without "Bytes" (a summary, a goal).
     const issues = (read.ok ? [] : read.issues).map(issue => (issue.kind === "too-long" ? { ...issue, line: issue.line.replace(/ characters$/, " bytes") } : issue));
     const contract = issues.map(contractProblemOf);
     if (contract.some(problem => problem.reason === "newer-version" || problem.reason === "bad-version"))
@@ -58,19 +48,11 @@ export function parseReport(raw, options = {}) {
         },
     };
 }
-/**
- * The rules JSON Schema cannot state, in plain code with path-named errors: blank text, byte caps (on write only),
- * control characters, one-line fields, a one-paragraph summary, safe links, a screenshot named twice and an item
- * naming one the report doesn't have. A field the contract already refused (or one inside it) is skipped, so every
- * problem is reported once and all at once.
- */
 function reportRuleProblems(body, issues, stored) {
     const problems = [];
-    // An unknown key is about its object, not the fields beside it.
     const refused = issues.filter(issue => issue.kind !== "unknown-key").map(issue => issue.path);
     const touched = (path) => refused.some(at => at === path || path.startsWith(`${at}.`) || path.startsWith(`${at}[`) || at.startsWith(`${path}.`) || at.startsWith(`${path}[`));
     const say = (path, reason, what) => problems.push({ reason, message: `${path}: ${what}` });
-    /** One text field checked; true when it passed every rule. */
     const text = (value, path, rule) => {
         if (typeof value !== "string" || touched(path))
             return false;
@@ -100,8 +82,6 @@ function reportRuleProblems(body, issues, stored) {
             text(entry[field], at === "" ? field : `${at}.${field}`, rule);
     };
     fields(body, "", REPORT_TEXT_FIELDS);
-    // One paragraph: the summary is what the operator reads first, on a phone, in a digest line — a blank line inside
-    // it is a second paragraph.
     const summary = body["summary"];
     if (typeof summary === "string" && !problems.some(problem => problem.message.startsWith("summary:")) && !touched("summary") && /\n[ \t]*\n/.test(summary)) {
         say("summary", "summary-paragraphs", "one paragraph — no blank lines");
@@ -120,7 +100,6 @@ function reportRuleProblems(body, issues, stored) {
         else
             files.set(file, at);
     }
-    // An item's picture is checked against the images as written: one naming a screenshot the report doesn't list is refused.
     const imagesRefused = touched("images");
     for (const [entry, at] of entries("items")) {
         fields(entry, at, ITEM_TEXT_FIELDS);
@@ -131,7 +110,6 @@ function reportRuleProblems(body, issues, stored) {
     }
     return problems;
 }
-/** A cited web address: http or https, one line, no credentials. */
 function isLink(text) {
     let url = null;
     try {