@illuminis/comprism 0.1.5 → 0.1.6

package/out/machine/executor/shell.js

@@ -0,0 +1,582 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TIMEOUT_MS = void 0;
+exports.safeEnvironment = safeEnvironment;
+exports.keptOutput = keptOutput;
+exports.shellFor = shellFor;
+exports.runCommand = runCommand;
+exports.runProgram = runProgram;
+exports.stopForeground = stopForeground;
+exports.startBackground = startBackground;
+exports.readOutput = readOutput;
+exports.stopProcess = stopProcess;
+exports.listProcesses = listProcesses;
+exports.stopEverything = stopEverything;
+exports.guessTestCommand = guessTestCommand;
+exports.runTests = runTests;
+/**
+ * Running things on a real machine.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items D17 (run a command), D18 (run the tests), D19 to D21 (long running
+ * processes), D22 (install a dependency) and F12 (a restricted environment).
+ *
+ * ## Why the tests are their own action
+ *
+ * `run_tests` could be a shell command and deliberately is not. Its result is
+ * the grading signal the whole product is built on: it is how a job knows it is
+ * finished, and how the routing engine eventually learns whether a cheaper
+ * model actually finished the work. A result buried inside the output of a
+ * generic command is a result nobody can count.
+ *
+ * ## Why the environment is trimmed
+ *
+ * A command inherits the environment of whatever started it, and on a
+ * developer's machine that includes cloud credentials, deployment tokens and
+ * signing keys. None of that is needed to run a test suite, and all of it is
+ * available to anything the command chooses to run. The agent is not the risk
+ * here; a package in the project's own dependency tree is.
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const paths_1 = require("./paths");
+/** What a command may print back into the conversation. Beyond this it is cut,
+ *  and the cut is stated: a model that believes it saw the whole output, and
+ *  did not, draws a confident conclusion from half of it. */
+const MAX_OUTPUT_CHARS = 30_000;
+/** Environment variables never passed to a command.
+ *
+ *  Matched by pattern rather than listed by name, because the list is
+ *  unknowable: every cloud provider, CI system and package registry invents its
+ *  own, and a list of the ones we happened to think of is a list that is out of
+ *  date the day it is written. */
+const SECRET_ENV = /(^|_)(KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL|CREDENTIALS|AUTH|PRIVATE|SESSION|COOKIE)(_|$)/i;
+/** Kept regardless, because a command that cannot find its own tools is a
+ *  command that fails for a reason nobody can diagnose. */
+const ALWAYS_KEEP = new Set([
+    "PATH", "HOME", "USER", "SHELL", "LANG", "LC_ALL", "TERM", "TMPDIR", "TZ",
+    "NODE_ENV", "PWD", "PYTHONPATH", "VIRTUAL_ENV", "NVM_DIR", "JAVA_HOME",
+    "GOPATH", "GOROOT", "CARGO_HOME", "RUSTUP_HOME",
+]);
+function safeEnvironment(from = process.env) {
+    const out = {};
+    for (const [k, v] of Object.entries(from)) {
+        if (ALWAYS_KEEP.has(k) || !SECRET_ENV.test(k))
+            out[k] = v;
+    }
+    // Told, not hidden. A command that behaves differently under the agent should
+    // be able to say so, and a person debugging one should be able to see why.
+    out.ILLUMINIS_AGENT = "1";
+    return out;
+}
+/** Long output keeps its beginning and its end, where a build's first error
+ *  and a test run's summary are, and says how much of the middle was cut
+ *  (manual 5.12). */
+function clip(text) {
+    if (text.length <= MAX_OUTPUT_CHARS)
+        return text;
+    const cut = text.length - MAX_OUTPUT_CHARS;
+    const head = text.slice(0, MAX_OUTPUT_CHARS / 2);
+    const tail = text.slice(text.length - MAX_OUTPUT_CHARS / 2);
+    return (`${head}\n\n[... ${cut.toLocaleString()} characters cut from the middle. The first and ` +
+        `last parts are shown. Narrow the command, or write the output to a file and read part of it.]\n\n${tail}`);
+}
+/** The default time limit on a command (manual 5.12). */
+exports.DEFAULT_TIMEOUT_MS = 120_000;
+/** How long a command may sit silent after printing what looks like a question
+ *  before it is taken to be waiting for someone to type (manual 5.12). */
+const WAITING_MS = 8_000;
+const ASK_WORDS = /(password|passphrase|y\/n|yes\/no|continue|proceed|press (enter|any key)|enter |select|choose|overwrite|confirm)/i;
+/** A last line that reads as a question to whoever is at the keyboard. */
+function asksForInput(line) {
+    const last = line.trim();
+    if (!last)
+        return false;
+    if (/\?$/.test(last))
+        return true;
+    return /[:>\])]$/.test(last) && ASK_WORDS.test(last);
+}
+/** Every command's whole output, by its number, for `output N` in a session.
+ *  Kept in memory for this process only and never sent anywhere. */
+const outputs = new Map();
+let outputCounter = 0;
+const MAX_KEPT = 50;
+function keptOutput(n) {
+    return outputs.get(n);
+}
+function keep(command, text) {
+    outputCounter += 1;
+    outputs.set(outputCounter, { command, text });
+    if (outputs.size > MAX_KEPT)
+        outputs.delete(Math.min(...outputs.keys()));
+    return outputCounter;
+}
+function lineCount(text) {
+    if (!text)
+        return 0;
+    return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+}
+/** Run a command and wait for it.
+ *
+ *  Never throws for an ordinary failure. A command that exits non-zero is a
+ *  RESULT: it is usually the most useful thing that can happen, because it is
+ *  how the agent learns what is wrong.
+ */
+/**
+ * The shell a command runs in: the system shell on macOS and Linux, and
+ * PowerShell on Windows (manual 1.2), which is what a Windows developer types
+ * into and what the agent is told it is writing for.
+ */
+function shellFor(command) {
+    if (process.platform === "win32" && process.env.COMPRISM_WINDOWS_SHELL !== "cmd") {
+        // PowerShell 7 where it is installed, because it takes `a && b` as people
+        // write it; Windows PowerShell otherwise, which every Windows machine has.
+        return [windowsPowerShell(), ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+                "-Command", command], false];
+    }
+    return [command, [], true];
+}
+let pwshFound;
+function windowsPowerShell() {
+    if (pwshFound === undefined) {
+        pwshFound = null;
+        for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+            const candidate = path.join(dir, "pwsh.exe");
+            if (dir && fs.existsSync(candidate)) {
+                pwshFound = candidate;
+                break;
+            }
+        }
+    }
+    return pwshFound ?? "powershell.exe";
+}
+function runCommand(command, opts) {
+    const cwd = opts.cwd ? (0, paths_1.resolveInside)(opts.root, opts.cwd, true) : fs.realpathSync(opts.root);
+    if (opts.sandbox)
+        return sandboxed(command, cwd, opts);
+    return collect({ ...opts, label: opts.label ?? command }, () => {
+        // Through a shell on purpose: pipes, redirection and `&&` are how people
+        // actually write commands, and an agent told it cannot use them writes three
+        // commands where a person would write one.
+        //
+        // Running a command IS this function. It is the agent's shell tool, and a
+        // shell tool that cannot reach a shell is not a tool. What stands between a
+        // command and the machine is the approval list every command is matched
+        // against before it reaches here, plus the working directory being resolved
+        // inside the workspace root. Removing the shell would not add safety; it
+        // would move the same commands somewhere with fewer checks in front of them.
+        // The marker has to be the LAST line before the call, not the first line of
+        // the explanation: semgrep only reads the line immediately above.
+        const [file, argv, useShell] = shellFor(command);
+        // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- runs the command the person approved, which is what this tool is for
+        const child = (0, child_process_1.spawn)(file, argv, {
+            cwd, shell: useShell,
+            env: { ...safeEnvironment(), ...(opts.extraEnv ?? {}) },
+            stdio: [opts.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+            // Its own process group, so stopping it stops what the shell started as
+            // well (manual 6.7). Not on Windows, where it would open a new window.
+            detached: process.platform !== "win32",
+        });
+        if (opts.input !== undefined && child.stdin) {
+            // A command that never reads its input must not fail on it.
+            child.stdin.on("error", () => undefined);
+            child.stdin.end(opts.input);
+        }
+        return child;
+    });
+}
+/** The same command inside the sandbox, and anything it blocked said as
+ *  blocked by the sandbox (manual 4.12). */
+async function sandboxed(command, cwd, opts) {
+    const box = opts.sandbox;
+    box.takeBlocked();
+    const w = box.wrap(command, cwd);
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- the approved command, wrapped by the sandbox
+    const result = await collect({ ...opts, label: opts.label ?? command }, () => (0, child_process_1.spawn)(w.file, w.args, {
+        cwd, env: { ...safeEnvironment(), ...(opts.extraEnv ?? {}), ...w.env },
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: process.platform !== "win32",
+    }));
+    const why = box.explain(result.content, box.takeBlocked());
+    return why ? { ...result, isError: true, summary: why, content: `${why}\n\n${result.content}` } : result;
+}
+/** Run one program with its arguments as a list, and no shell in between.
+ *
+ *  For commands this tool builds itself, such as git. A shell would have to be
+ *  told how to quote each argument, and the quoting differs by shell: the POSIX
+ *  single quotes that kept a commit message whole on macOS and Linux reached
+ *  git on Windows as literal characters, so a commit read `'fix` and a branch
+ *  name no longer matched. With no shell there is nothing to quote, on any
+ *  system, and a model written message cannot become a second command. */
+function runProgram(file, args, opts) {
+    const cwd = opts.cwd ? (0, paths_1.resolveInside)(opts.root, opts.cwd, true) : fs.realpathSync(opts.root);
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- a fixed program with its arguments as a list, no shell
+    return collect(opts, () => (0, child_process_1.spawn)(file, args, {
+        cwd, env: { ...safeEnvironment(), ...(opts.extraEnv ?? {}) },
+        stdio: ["ignore", "pipe", "pipe"],
+    }));
+}
+/** Commands running in the foreground right now, so Ctrl+C can stop them
+ *  (manual 6.7). Each is marked stopped before it is killed, so its result
+ *  says so rather than reading as an ordinary exit. */
+const foreground = new Map();
+/** Stop every foreground command and everything it started. */
+function stopForeground() {
+    for (const [child, mark] of foreground) {
+        mark.stopped = true;
+        killTree(child);
+    }
+}
+function killTree(child) {
+    if (process.platform === "win32" && child.pid) {
+        // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+        (0, child_process_1.spawn)("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+        return;
+    }
+    try {
+        process.kill(-child.pid, "SIGKILL");
+    }
+    catch {
+        child.kill("SIGKILL");
+    }
+}
+function collect(opts, start) {
+    const timeoutMs = opts.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS;
+    const began = Date.now();
+    return new Promise((resolve) => {
+        let out = "";
+        let done = false;
+        const child = start();
+        const mark = { stopped: false };
+        foreground.set(child, mark);
+        let lastOutput = Date.now();
+        const collect = (chunk) => {
+            const text = chunk.toString();
+            out += text;
+            lastOutput = Date.now();
+            opts.onOutput?.(text);
+        };
+        child.stdout?.on("data", collect);
+        child.stderr?.on("data", collect);
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            clearInterval(watch);
+            foreground.delete(child);
+            const id = keep(opts.label ?? "", out);
+            resolve({ ...r, facts: { ...(r.facts ?? {}), output_id: id, lines: lineCount(out),
+                    seconds: Math.round((Date.now() - began) / 100) / 10 } });
+        };
+        const timer = setTimeout(() => {
+            // The whole process group, not just the shell. Killing the shell leaves
+            // whatever it started running, which is how a stuck job leaves a server
+            // holding a port after everybody has gone home. On Windows the tree is
+            // stopped with taskkill, since there are no process groups.
+            killTree(child);
+            const secs = Math.round(timeoutMs / 1000);
+            finish({
+                isError: true,
+                content: clip(out) +
+                    `\n\n[Timed out: stopped after ${secs}s, the time limit. If this command ` +
+                    "waits for input it will never finish; run it in a way that does not. " +
+                    "A longer limit is --timeout on the job.]",
+                summary: `timed out after ${secs}s`,
+                facts: { timed_out: 1, limit_s: secs },
+            });
+        }, timeoutMs);
+        // A command waiting for somebody to type never finishes: stdin is closed,
+        // but a program that reads the terminal directly (a password prompt) sits
+        // there until the limit. Silence after a question is taken as that.
+        const watch = setInterval(() => {
+            if (done || Date.now() - lastOutput < WAITING_MS)
+                return;
+            const last = out.trimEnd().split("\n").pop() ?? "";
+            if (!asksForInput(last))
+                return;
+            killTree(child);
+            finish({
+                isError: true,
+                content: clip(out) +
+                    "\n\n[Stopped: it was waiting for keyboard input, and nobody can type into a " +
+                    "command the agent runs. Pass the answer as an option, or run it yourself.]",
+                summary: "stopped: waiting for keyboard input",
+                facts: { waiting_input: 1 },
+            });
+        }, 1_000);
+        child.on("error", (err) => {
+            finish({ isError: true, content: `Could not run it: ${err.message}` });
+        });
+        child.on("close", (code) => {
+            const body = clip(out).trim() || "(no output)";
+            if (mark.stopped) {
+                finish({
+                    isError: true,
+                    content: `${body}\n\n[Stopped by the person. The output above is everything it printed before it was stopped.]`,
+                    summary: "stopped",
+                    facts: { stopped: 1 },
+                });
+                return;
+            }
+            finish({
+                // Non-zero is not an error in the sense that matters here. It is
+                // information, and it is usually the most useful information available.
+                isError: false,
+                content: `exit ${code}\n\n${body}`,
+                summary: code === 0 ? "exit 0" : `exit ${code}`,
+                facts: { exit: code ?? -1 },
+            });
+        });
+    });
+}
+const running = new Map();
+let counter = 0;
+/** A port a server announces in its output: "port 8765", "localhost:5173". */
+const PORT = /(?:\bport\s+|localhost:|127\.0\.0\.1:|0\.0\.0\.0:|\[::\]:|\/\/[\w.-]+:)(\d{2,5})\b/i;
+function startBackground(command, opts) {
+    const cwd = opts.cwd ? (0, paths_1.resolveInside)(opts.root, opts.cwd, true) : fs.realpathSync(opts.root);
+    const id = `p${++counter}`;
+    // The background half of the same shell tool, with the same approval list and
+    // the same workspace root in front of it. See `runCommand` above. Its own
+    // process group, so stopping it stops everything it started (manual 5.13).
+    const [file, argv, useShell] = shellFor(command);
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- runs the command the person approved, which is what this tool is for
+    const child = (0, child_process_1.spawn)(file, argv, {
+        // Unbuffered, so a Python server's "port 8765" line arrives when it is
+        // printed rather than when a buffer fills (read_output, processes).
+        cwd, shell: useShell, env: { ...safeEnvironment(), PYTHONUNBUFFERED: "1" },
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: process.platform !== "win32",
+    });
+    const entry = { child, buffer: "", read: 0, command, started: Date.now() };
+    const collect = (chunk) => {
+        const text = chunk.toString();
+        entry.buffer += text;
+        if (!entry.port) {
+            const m = PORT.exec(text);
+            if (m)
+                entry.port = Number(m[1]);
+        }
+        // Bounded. A watcher left running for an hour would otherwise hold its whole
+        // output in memory, and nobody is going to read the first hour of it.
+        if (entry.buffer.length > MAX_OUTPUT_CHARS * 4) {
+            entry.buffer = entry.buffer.slice(-MAX_OUTPUT_CHARS * 2);
+            entry.read = 0;
+        }
+    };
+    child.stdout?.on("data", collect);
+    child.stderr?.on("data", collect);
+    running.set(id, entry);
+    return {
+        content: `Started as ${id}: ${command}\nUse read_output with ${id} to see what it prints, and stop_process to end it.`,
+        summary: `started ${id}`,
+        facts: { process: counter },
+    };
+}
+function alive(entry) {
+    return entry.child.exitCode === null && entry.child.signalCode === null;
+}
+function readOutput(id) {
+    const entry = running.get(id);
+    if (!entry)
+        return { isError: true, content: `No process called ${id}. Only processes this session started can be read.` };
+    const fresh = entry.buffer.slice(entry.read);
+    entry.read = entry.buffer.length;
+    const up = alive(entry);
+    return {
+        content: (fresh.trim() || "(nothing new)") +
+            `\n\n[${id} is ${up ? "still running" : `finished, exit ${entry.child.exitCode}`}.]`,
+        summary: up ? `${id} running` : `${id} exited`,
+    };
+}
+/** Stop one process this tool started, and everything it started, by the
+ *  number it was given. Never by name or by port (manual 5.13). */
+function stopProcess(id) {
+    const entry = running.get(id);
+    if (!entry) {
+        return { isError: true, content: `No process called ${id}. The agent can stop only processes it started, by their number.` };
+    }
+    const wasUp = alive(entry);
+    if (wasUp) {
+        if (process.platform === "win32" && entry.child.pid) {
+            // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+            (0, child_process_1.spawn)("taskkill", ["/pid", String(entry.child.pid), "/T", "/F"], { stdio: "ignore" });
+        }
+        else {
+            try {
+                process.kill(-entry.child.pid, "SIGTERM");
+            }
+            catch {
+                entry.child.kill("SIGTERM");
+            }
+            // Whatever ignores the polite request is stopped a moment later.
+            const pid = entry.child.pid;
+            setTimeout(() => { try {
+                process.kill(-pid, "SIGKILL");
+            }
+            catch { /* already gone */ } }, 1500).unref();
+        }
+    }
+    running.delete(id);
+    return {
+        content: wasUp ? `Stopped ${id} (${entry.command}) and everything it started.` : `${id} had already finished.`,
+        summary: `stopped ${id}`,
+    };
+}
+/** What this session started and is still tracking, for `processes`. */
+function listProcesses() {
+    return [...running.entries()].map(([id, e]) => ({
+        id, command: e.command, running: alive(e), seconds: Math.round((Date.now() - e.started) / 1000),
+        ...(e.port ? { port: e.port } : {}),
+    }));
+}
+/** Everything still running, stopped, and what was stopped. Called when a
+ *  session ends, so a job that started a dev server does not leave it holding
+ *  a port after the person has closed the terminal (manual 5.13). */
+function stopEverything() {
+    const stopped = [];
+    for (const [id, e] of Array.from(running.entries())) {
+        if (alive(e))
+            stopped.push(`${id}  ${e.command}`);
+        stopProcess(id);
+    }
+    return stopped;
+}
+// ── the tests ───────────────────────────────────────────────────────────────
+/** How this project runs its tests, worked out from what is in it.
+ *
+ *  Ordered by how specific the evidence is. A `test` script in package.json is
+ *  a statement by the project's own authors; the presence of a pytest.ini is an
+ *  inference. Guessing wrong is cheap here because the result says what it ran.
+ */
+/** Whether this folder holds Python tests, by their conventional names.
+ *
+ *  `test_x.py` and `x_test.py` are the two names pytest collects by default, so
+ *  a folder containing either is a folder pytest can run. Deliberately shallow:
+ *  one directory read, no walk, because this is a guess made before every test
+ *  run and a recursive scan of somebody's repository is not.
+ */
+function looksLikePython(root) {
+    try {
+        return fs.readdirSync(root).some((name) => /^test_.*\.py$/.test(name) || /.*_test\.py$/.test(name));
+    }
+    catch {
+        // An unreadable project directory is a different problem, and it will be
+        // reported by whatever tries to read a file next.
+        return false;
+    }
+}
+/** The Python this machine runs: `python3` where `python` is not installed,
+ *  which is every recent Mac and most Linux. Guessing `python` there ran
+ *  nothing and cost the agent a step (exit 127). */
+function python() {
+    const dirs = (process.env.PATH ?? "").split(path.delimiter);
+    const exts = process.platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
+    const has = (name) => dirs.some((d) => exts.some((e) => {
+        try {
+            return fs.statSync(path.join(d, name + e)).isFile();
+        }
+        catch {
+            return false;
+        }
+    }));
+    return has("python") || !has("python3") ? "python" : "python3";
+}
+function guessTestCommand(root) {
+    const has = (f) => fs.existsSync(path.join(root, f));
+    const pkgPath = path.join(root, "package.json");
+    if (has("package.json")) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            if (pkg.scripts?.test) {
+                return has("pnpm-lock.yaml") ? "pnpm test"
+                    : has("yarn.lock") ? "yarn test" : "npm test";
+            }
+        }
+        catch { /* a malformed package.json is not our problem to report here */ }
+    }
+    if (has("pytest.ini") || has("pyproject.toml") || has("tests") || has("setup.cfg")) {
+        return `${python()} -m pytest -q`;
+    }
+    // A project identified by its TEST FILES rather than by a configuration file.
+    // A plain folder of `test_*.py` with no `pyproject.toml` is an entirely normal
+    // Python project and was not recognized, so `run_tests` refused and the model
+    // had to work out the command itself. It did, and it cost a step and an
+    // approval on a job that was otherwise clean. Found by watching a real run in
+    // the desktop app.
+    //
+    // One shallow directory read, and only when nothing above matched.
+    if (looksLikePython(root))
+        return `${python()} -m pytest -q`;
+    if (has("Cargo.toml"))
+        return "cargo test";
+    if (has("go.mod"))
+        return "go test ./...";
+    if (has("Gemfile"))
+        return "bundle exec rspec";
+    if (has("pom.xml"))
+        return "mvn -q test";
+    if (has("build.gradle") || has("build.gradle.kts"))
+        return "gradle test";
+    return null;
+}
+async function runTests(opts) {
+    const root = fs.realpathSync(opts.root);
+    let command = opts.command?.trim() || guessTestCommand(root) || "";
+    if (!command) {
+        return {
+            isError: true,
+            content: "I could not work out how this project runs its tests. Tell me the " +
+                "command and I will use it from now on.",
+        };
+    }
+    if (opts.path)
+        command = `${command} ${(0, paths_1.resolveInside)(root, opts.path, false)}`;
+    const result = await runCommand(command, opts);
+    const passed = /^exit 0\b/.test(result.content);
+    return {
+        ...result,
+        passed,
+        command,
+        // The verdict first, in words, before the output. This result is read by a
+        // model deciding whether it has finished, and burying "exit 1" under two
+        // hundred lines of test output is how a job declares success on a red suite.
+        content: `${passed ? "TESTS PASSED" : "TESTS FAILED"} (${command})\n\n${result.content}`,
+        summary: `${passed ? "tests passed" : "tests failed"}: ${command}`,
+    };
+}

package/out/machine/executor/toolservers.d.ts

@@ -0,0 +1,20 @@
+/** The tool servers one job started, by name. */
+export declare class ToolServers {
+    private readonly cwd;
+    private running;
+    constructor(cwd: string);
+    private server;
+    /** The server's tools, as it described them, as JSON text. */
+    list(name: string, command: string): Promise<{
+        isError: boolean;
+        content: string;
+    }>;
+    /** One call, and the text the server returned. */
+    call(name: string, command: string, tool: string, args: Record<string, unknown>): Promise<{
+        isError: boolean;
+        content: string;
+    }>;
+    /** Every server this job started, stopped. Called when the job ends. */
+    stopAll(): void;
+    get count(): number;
+}