@illuminis/comprism 0.1.5 → 0.1.6

package/out/machine/executor/paths.js

@@ -0,0 +1,154 @@
+"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.OutsideWorkspace = void 0;
+exports.allowFolders = allowFolders;
+exports.allowedFolders = allowedFolders;
+exports.isSecret = isSecret;
+exports.resolveInside = resolveInside;
+/**
+ * The folder boundary, on a real filesystem.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md §8, register
+ * items F1 (the folder is a boundary) and F2 (shortcuts do not defeat it).
+ *
+ * The browser executor gets this property free: it walks directory handles, and
+ * a handle it was never given simply cannot be reached. A real filesystem has no
+ * such protection, so here it has to be enforced, and enforced in the one order
+ * that works.
+ *
+ * **Resolve first, then compare.** Checking the string somebody sent and then
+ * resolving it is the standard way out: `a/../../etc/passwd` passes a check for
+ * ".." at the start and becomes `/etc/passwd` afterwards. And on a real
+ * filesystem there is a second door the browser does not have, which is a
+ * symbolic link inside the project pointing outside it. `realpath` follows it;
+ * a string comparison does not.
+ *
+ * The server checks this too. Two checks is not belt and braces: the server
+ * cannot see the filesystem, so it can only reason about the path it was given,
+ * and this can see the filesystem but runs on a machine we do not control.
+ * Neither alone is the boundary.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class OutsideWorkspace extends Error {
+    attempted;
+    /** `real` is where the path actually leads, when that differs from what was
+     *  asked for: a link is refused by naming its real location (manual 2.4). */
+    constructor(attempted, real) {
+        super(`Refused: ${attempted} is outside this project` +
+            (real && real !== attempted ? ` (it leads to ${real})` : "") +
+            `. The agent works only inside the folders that were opened.`);
+        this.attempted = attempted;
+        this.name = "OutsideWorkspace";
+    }
+}
+exports.OutsideWorkspace = OutsideWorkspace;
+/**
+ * Folders the person added for this job (manual 2.3), keyed by the project's
+ * real root. Registered by the executor that owns the job, so every existing
+ * `resolveInside(root, ...)` call checks all allowed folders without each one
+ * having to carry the list. Only folders the person named reach here.
+ */
+const addedFolders = new Map();
+function allowFolders(root, added) {
+    const realRoot = fs.realpathSync(root);
+    const real = added.map((a) => fs.realpathSync(a)).filter((a) => a !== realRoot);
+    if (real.length)
+        addedFolders.set(realRoot, [...new Set(real)]);
+    else
+        addedFolders.delete(realRoot);
+}
+/** Every folder a job in `root` may touch, the project first. */
+function allowedFolders(root) {
+    const realRoot = fs.realpathSync(root);
+    return [realRoot, ...(addedFolders.get(realRoot) ?? [])];
+}
+function inside(real, folder) {
+    return real === folder || real.startsWith(folder.endsWith(path.sep) ? folder : folder + path.sep);
+}
+/** Files never read, whatever the mode. Mirrors the server's own list. */
+const SECRET = /^(\.env(\..*)?|.*\.pem|.*\.key|.*\.p12|.*\.pfx|id_rsa.*|id_ed25519.*|.*\.keystore|credentials|\.npmrc|\.netrc|\.git-credentials)$/i;
+function isSecret(p) {
+    return SECRET.test(path.basename(p));
+}
+/**
+ * An absolute path inside the workspace, or a refusal.
+ *
+ * `mustExist` is false when the caller is about to CREATE the thing. A file that
+ * does not exist yet cannot be resolved, so the check is applied to the deepest
+ * parent that does exist: creating `src/new/deep/file.ts` is inside the project
+ * exactly when `src` is, and demanding the leaf exist first would make it
+ * impossible to write a new file at all.
+ */
+function resolveInside(root, rel, mustExist = false) {
+    const realRoot = fs.realpathSync(root);
+    const asked = String(rel ?? "");
+    // An ABSOLUTE path is resolved as written, and refused if it lands outside.
+    // It used to have its leading slash stripped and be treated as relative to
+    // the project, which was safe and quietly wrong: asking to write
+    // `/tmp/notes.txt` created `<project>/tmp/notes.txt` and reported the path the
+    // caller gave. Nothing escaped, but the confirmation named a file that did not
+    // exist, so the next read failed and the model spent steps on a mystery. An
+    // absolute path inside the project still works, which is the only case anybody
+    // actually means.
+    const joined = path.isAbsolute(asked)
+        ? path.resolve(asked)
+        : path.resolve(realRoot, asked);
+    let probe = joined;
+    if (!mustExist) {
+        // Walk up to the deepest part that exists, so a path we are about to create
+        // is still checked against where it would actually land.
+        while (!fs.existsSync(probe) && path.dirname(probe) !== probe) {
+            probe = path.dirname(probe);
+        }
+    }
+    let real;
+    try {
+        real = fs.realpathSync(probe);
+    }
+    catch {
+        throw new OutsideWorkspace(rel);
+    }
+    // The comparison, with a separator on the end. Without it `/work/project-two`
+    // passes as being inside `/work/project`, because one string starts with the
+    // other. Every allowed folder is checked, and nothing else.
+    if (!allowedFolders(realRoot).some((folder) => inside(real, folder))) {
+        throw new OutsideWorkspace(rel, real);
+    }
+    // Return the requested path, not the probe: the caller wants to write to the
+    // file it named, and the probe may be an ancestor of it.
+    return mustExist ? real : joined;
+}

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

@@ -0,0 +1,40 @@
+export type SandboxSystem = "macOS" | "Linux";
+/** Which sandbox this machine offers, or why none. */
+export declare function availability(): {
+    system: SandboxSystem | null;
+    why: string;
+};
+/** Does this host match an allowed address: exact, or `*.example.com`. */
+export declare function hostAllowed(host: string, allow: string[]): boolean;
+export declare class Sandbox {
+    readonly system: SandboxSystem;
+    private readonly writable;
+    private allow;
+    private proxy;
+    private port;
+    /** Hosts refused since the last `takeBlocked`, for the result to name. */
+    private blocked;
+    constructor(system: SandboxSystem, root: string, added: string[]);
+    /** The allowed internet addresses, as the service sent them. */
+    setAllowed(allow: string[]): void;
+    /** Where the gatekeeper listens on Linux: a socket file the relay inside
+     *  the sandbox connects to, and a folder for the relay's ready marks. */
+    private socketPath;
+    private marks;
+    private calls;
+    /** Start the gatekeeper. Idempotent. */
+    start(): Promise<void>;
+    close(): void;
+    /** The hosts refused since the last call. */
+    takeBlocked(): string[];
+    private profile;
+    /** The program and arguments that run `command` inside the sandbox, and
+     *  the variables that send its web traffic to the gatekeeper. */
+    wrap(command: string, cwd: string): {
+        file: string;
+        args: string[];
+        env: Record<string, string>;
+    };
+    /** What was blocked, in the manual's words, or null (manual 4.12). */
+    explain(output: string, hosts: string[]): string | null;
+}

package/out/machine/executor/sandbox.js

@@ -0,0 +1,299 @@
+"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.Sandbox = void 0;
+exports.availability = availability;
+exports.hostAllowed = hostAllowed;
+/**
+ * Commands run inside the operating system's sandbox (manual 4.12).
+ *
+ * The service decides whether a job is sandboxed and which internet addresses
+ * are allowed; this file only adapts the facility the operating system
+ * provides, which the service cannot reach:
+ *
+ * - macOS: `sandbox-exec` with a generated profile. Writes are allowed only in
+ *   the project, the added folders and the temporary folders. The network is
+ *   closed except to this machine, where a small gatekeeper answers as the
+ *   command's web proxy and lets through only the allowed addresses.
+ * - Linux: bubblewrap (`bwrap`). The whole machine is mounted read only except
+ *   the project, the added folders and the temporary folder, and the command
+ *   gets a network of its own with nothing on it. A small relay inside that
+ *   network passes web traffic to the same gatekeeper, through a socket file,
+ *   so only the allowed addresses are reached there too.
+ *
+ * Anywhere else `--sandbox` refuses to start rather than running without it.
+ * A blocked attempt is reported as blocked by the sandbox, which is different
+ * from refused by the person or by a rule.
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
+const net = __importStar(require("net"));
+const os = __importStar(require("os"));
+const self_1 = require("../runtime/self");
+/** Which sandbox this machine offers, or why none. */
+function availability() {
+    const has = (file, args) => {
+        try {
+            (0, child_process_1.execFileSync)(file, args, { stdio: "ignore", timeout: 5000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (process.platform === "darwin") {
+        return fs.existsSync("/usr/bin/sandbox-exec")
+            ? { system: "macOS", why: "" }
+            : { system: null, why: "the macOS sandbox (sandbox-exec) is not on this machine" };
+    }
+    if (process.platform === "linux") {
+        if (!has("bwrap", ["--version"])) {
+            return { system: null, why: "bubblewrap (bwrap) is not installed; install it to use --sandbox" };
+        }
+        // A working sandbox, not merely an installed one: some systems forbid the
+        // namespaces bubblewrap needs.
+        return has("bwrap", ["--ro-bind", "/", "/", "--unshare-net", "true"])
+            ? { system: "Linux", why: "" }
+            : { system: null, why: "bubblewrap is installed but this system does not let it start" };
+    }
+    return { system: null, why: `there is no supported sandbox on ${process.platform}` };
+}
+function real(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+function quote(p) {
+    return `"${p.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** Does this host match an allowed address: exact, or `*.example.com`. */
+function hostAllowed(host, allow) {
+    const h = host.toLowerCase().replace(/\.$/, "");
+    return allow.some((raw) => {
+        const a = raw.toLowerCase().trim();
+        if (!a)
+            return false;
+        if (a === "*")
+            return true;
+        if (a.startsWith("*."))
+            return h.endsWith(a.slice(1)) || h === a.slice(2);
+        return h === a;
+    });
+}
+/** The port the relay listens on inside a Linux sandbox's own network. Any
+ *  port would do: that network holds nothing else. */
+const LINUX_RELAY_PORT = 18080;
+/** The relay, run by the same Node inside the sandbox: every connection to
+ *  its port is passed to the gatekeeper's socket file, and it marks itself
+ *  ready once listening. It decides nothing. */
+const RELAY = [
+    'const net=require("net"),fs=require("fs");',
+    "net.createServer((c)=>{const u=net.connect(process.env.COMPRISM_GATE);",
+    'c.pipe(u);u.pipe(c);u.on("error",()=>c.destroy());c.on("error",()=>u.destroy());})',
+    `.listen(${LINUX_RELAY_PORT},"127.0.0.1",()=>fs.writeFileSync(process.env.COMPRISM_READY,""));`,
+].join("");
+class Sandbox {
+    system;
+    writable;
+    allow = [];
+    proxy = null;
+    port = 0;
+    /** Hosts refused since the last `takeBlocked`, for the result to name. */
+    blocked = [];
+    constructor(system, root, added) {
+        this.system = system;
+        // This user's own temporary folder and the system one, and no wider: the
+        // parent of a user's temporary folder holds other programs' caches.
+        const tmp = [os.tmpdir(), "/tmp", "/var/tmp"];
+        this.writable = [...new Set([root, ...added, ...tmp].map(real))];
+    }
+    /** The allowed internet addresses, as the service sent them. */
+    setAllowed(allow) {
+        this.allow = allow.filter((a) => typeof a === "string" && a.trim());
+    }
+    /** Where the gatekeeper listens on Linux: a socket file the relay inside
+     *  the sandbox connects to, and a folder for the relay's ready marks. */
+    socketPath = "";
+    marks = "";
+    calls = 0;
+    /** Start the gatekeeper. Idempotent. */
+    async start() {
+        if (this.proxy)
+            return;
+        const server = http.createServer((req, res) => {
+            // A plain http:// request through the proxy.
+            let target;
+            try {
+                target = new URL(req.url ?? "");
+            }
+            catch {
+                res.writeHead(400);
+                res.end();
+                return;
+            }
+            if (!hostAllowed(target.hostname, this.allow)) {
+                this.blocked.push(target.hostname);
+                res.writeHead(403, { "content-type": "text/plain" });
+                res.end(`blocked by the sandbox: network access to ${target.hostname} is not allowed\n`);
+                return;
+            }
+            const upstream = http.request(target, { method: req.method, headers: req.headers }, (up) => {
+                res.writeHead(up.statusCode ?? 502, up.headers);
+                up.pipe(res);
+            });
+            upstream.on("error", () => { res.writeHead(502); res.end(); });
+            req.pipe(upstream);
+        });
+        server.on("connect", (req, client, head) => {
+            // https:// and anything else tunnelled with CONNECT host:port.
+            const [host, portText] = String(req.url ?? "").split(":");
+            if (!host || !hostAllowed(host, this.allow)) {
+                if (host)
+                    this.blocked.push(host);
+                client.end("HTTP/1.1 403 Forbidden\r\n\r\n");
+                return;
+            }
+            const upstream = net.connect(Number(portText) || 443, host, () => {
+                client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+                if (head.length)
+                    upstream.write(head);
+                upstream.pipe(client);
+                client.pipe(upstream);
+            });
+            upstream.on("error", () => client.destroy());
+            client.on("error", () => upstream.destroy());
+        });
+        if (this.system === "Linux") {
+            // A socket file in the temporary folder, which the sandbox can see.
+            this.marks = fs.mkdtempSync(`${real(os.tmpdir())}/comprism-gate-`);
+            this.socketPath = `${this.marks}/gate.sock`;
+            await new Promise((resolve) => server.listen(this.socketPath, () => resolve()));
+        }
+        else {
+            await new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+            this.port = server.address().port;
+        }
+        this.proxy = server;
+        server.unref();
+    }
+    close() {
+        this.proxy?.close();
+        this.proxy = null;
+        if (this.marks)
+            fs.rmSync(this.marks, { recursive: true, force: true });
+        this.marks = "";
+    }
+    /** The hosts refused since the last call. */
+    takeBlocked() {
+        const out = [...new Set(this.blocked)];
+        this.blocked = [];
+        return out;
+    }
+    profile() {
+        const writes = this.writable.map((p) => `  (subpath ${quote(p)})`).join("\n");
+        return [
+            "(version 1)",
+            "(allow default)",
+            "(deny file-write*)",
+            "(allow file-write*",
+            writes,
+            '  (literal "/dev/null") (literal "/dev/zero") (literal "/dev/stdout")',
+            '  (literal "/dev/stderr") (literal "/dev/dtracehelper")',
+            '  (regex #"^/dev/tty") (regex #"^/dev/fd/"))',
+            "(deny network*)",
+            '(allow network* (remote ip "localhost:*"))',
+            '(allow network* (local ip "localhost:*"))',
+        ].join("\n");
+    }
+    /** The program and arguments that run `command` inside the sandbox, and
+     *  the variables that send its web traffic to the gatekeeper. */
+    wrap(command, cwd) {
+        if (this.system === "macOS") {
+            const proxy = `http://127.0.0.1:${this.port}`;
+            return {
+                file: "/usr/bin/sandbox-exec",
+                args: ["-p", this.profile(), "/bin/sh", "-c", command],
+                env: {
+                    HTTP_PROXY: proxy, HTTPS_PROXY: proxy, http_proxy: proxy, https_proxy: proxy,
+                    ALL_PROXY: proxy, all_proxy: proxy, NO_PROXY: "", no_proxy: "",
+                },
+            };
+        }
+        const binds = this.writable.filter((p) => fs.existsSync(p)).flatMap((p) => ["--bind", p, p]);
+        // Inside the sandbox's own network, a relay on this port passes every
+        // connection to the gatekeeper's socket file, which decides.
+        const proxy = `http://127.0.0.1:${LINUX_RELAY_PORT}`;
+        const ready = this.marks ? `${this.marks}/ready-${++this.calls}` : "";
+        const script = this.socketPath
+            ? `${(0, self_1.isStandalone)() ? '"$COMPRISM_NODE" __relay' : '"$COMPRISM_NODE" -e "$COMPRISM_RELAY"'} & relay=$!; i=0; `
+                + `while [ ! -e "$COMPRISM_READY" ] && [ $i -lt 150 ]; do sleep 0.02; i=$((i+1)); done; `
+                + `/bin/sh -c "$COMPRISM_CMD"; rc=$?; kill $relay 2>/dev/null; exit $rc`
+            : `/bin/sh -c "$COMPRISM_CMD"`;
+        return {
+            file: "bwrap",
+            args: ["--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc", ...binds,
+                "--unshare-net", "--die-with-parent", "--chdir", cwd, "/bin/sh", "-c", script],
+            env: {
+                COMPRISM_CMD: command, COMPRISM_NODE: process.execPath, COMPRISM_RELAY: RELAY,
+                COMPRISM_GATE: this.socketPath, COMPRISM_READY: ready,
+                ...(this.socketPath ? {
+                    HTTP_PROXY: proxy, HTTPS_PROXY: proxy, http_proxy: proxy, https_proxy: proxy,
+                    ALL_PROXY: proxy, all_proxy: proxy, NO_PROXY: "", no_proxy: "",
+                } : {}),
+            },
+        };
+    }
+    /** What was blocked, in the manual's words, or null (manual 4.12). */
+    explain(output, hosts) {
+        if (hosts.length)
+            return `blocked by the sandbox: network access to ${hosts.join(", ")} is not allowed`;
+        const write = /(?:touch: |cannot touch )?'?([^'\n:]+?)'?: (?:Operation not permitted|Read-only file system)/.exec(output);
+        if (write) {
+            return `blocked by the sandbox: writing to ${write[1].trim()} is not allowed, `
+                + "only the project and temporary folders can be written";
+        }
+        const offline = /Could not resolve host: (\S+)|getaddrinfo \w+ (\S+)|Network is unreachable/.exec(output);
+        if (offline) {
+            const host = offline[1] ?? offline[2] ?? "the internet";
+            return `blocked by the sandbox: network access to ${host} is not allowed`;
+        }
+        return null;
+    }
+}
+exports.Sandbox = Sandbox;

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

@@ -0,0 +1,86 @@
+export interface RunResult {
+    content: string;
+    isError?: boolean;
+    summary?: string;
+    /** Counts the service turns into the action line: the lines read, the
+     *  matches found and how many were left out (manual 5.3, 5.4). Numbers only;
+     *  the wording is the service's. */
+    facts?: Record<string, number | string>;
+}
+export declare function safeEnvironment(from?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** The default time limit on a command (manual 5.12). */
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+export declare function keptOutput(n: number): {
+    command: string;
+    text: string;
+} | undefined;
+export interface ShellOptions {
+    root: string;
+    cwd?: string;
+    timeoutMs?: number;
+    onOutput?: (chunk: string) => void;
+    /** Extra variables for this one command.
+     *
+     *  Used by hooks, so a project's own script can read which file the agent
+     *  just touched without the agent having to rewrite the script's arguments.
+     *  Still filtered by `safeEnvironment`, so a hook cannot be handed a
+     *  credential this way either. */
+    extraEnv?: Record<string, string>;
+    /** What the command is called in `output N`. */
+    label?: string;
+    /** Written to the command's standard input, then closed. Hooks read their
+     *  details this way (manual 10.9). Absent, standard input is closed. */
+    input?: string;
+    /** The operating system's sandbox, when the service turned it on for this
+     *  job (manual 4.12). Every command then runs inside it. */
+    sandbox?: import("./sandbox").Sandbox;
+}
+/** 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.
+ */
+export declare function shellFor(command: string): [string, string[], boolean];
+export declare function runCommand(command: string, opts: ShellOptions): Promise<RunResult>;
+/** 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. */
+export declare function runProgram(file: string, args: string[], opts: ShellOptions): Promise<RunResult>;
+/** Stop every foreground command and everything it started. */
+export declare function stopForeground(): void;
+export declare function startBackground(command: string, opts: ShellOptions): RunResult;
+export declare function readOutput(id: string): RunResult;
+/** 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). */
+export declare function stopProcess(id: string): RunResult;
+/** What this session started and is still tracking, for `processes`. */
+export declare function listProcesses(): Array<{
+    id: string;
+    command: string;
+    running: boolean;
+    seconds: number;
+    port?: number;
+}>;
+/** 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). */
+export declare function stopEverything(): string[];
+export declare function guessTestCommand(root: string): string | null;
+export declare function runTests(opts: ShellOptions & {
+    command?: string;
+    path?: string;
+}): Promise<RunResult & {
+    passed?: boolean;
+    command?: string;
+}>;