sakura-agent 0.1.0 → 0.1.2

package/dist/packages/env/src/connect-ssh.js

@@ -0,0 +1,242 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { createRemoteEnvironment, RemoteConnectionError } from "./remote.js";
+/** Output kept from one command, as for a local one. */
+const MAX_OUTPUT_CHARS = 20_000_000;
+const quote = (text) => `'${text.replace(/'/g, `'\\''`)}'`;
+/** Runs ssh on this machine and collects what it prints. */
+function runSsh(program, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(program, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let output = "";
+        let stderr = "";
+        let timedOut = false;
+        const keep = (chunk, target) => {
+            const text = chunk.toString("utf8");
+            output += text;
+            if (output.length > MAX_OUTPUT_CHARS)
+                output = output.slice(output.length - MAX_OUTPUT_CHARS);
+            if (target === "stderr")
+                stderr += text;
+        };
+        child.stdout.on("data", (chunk) => keep(chunk, "both"));
+        child.stderr.on("data", (chunk) => keep(chunk, "stderr"));
+        const stop = () => {
+            child.kill("SIGTERM");
+            setTimeout(() => child.kill("SIGKILL"), 1000).unref();
+        };
+        const timer = options.timeoutMs !== undefined
+            ? setTimeout(() => {
+                timedOut = true;
+                stop();
+            }, options.timeoutMs)
+            : undefined;
+        if (options.signal?.aborted)
+            stop();
+        options.signal?.addEventListener("abort", stop, { once: true });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            reject(new RemoteConnectionError(`could not run ${program}: ${error.message}`));
+        });
+        const finish = (code) => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", stop);
+            resolve({ exitCode: code, output, timedOut, stderr });
+        };
+        child.on("close", finish);
+        // An ssh that makes the connection leaves a copy of itself behind in the background (the first one does, and so does one that has to make it again), and
+        // that copy may keep our pipes open for as long as it lives. So the answer is the ssh we started exiting, with a moment for what it wrote to arrive.
+        child.on("exit", (code) => setTimeout(() => {
+            child.stdout.destroy();
+            child.stderr.destroy();
+            finish(code);
+        }, 100));
+    });
+}
+/** Runs ssh on this machine and passes on what it prints as it prints it. What ssh itself says (its stderr) is kept apart from the command's output. */
+function streamSsh(program, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(program, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (text) => options.onData(text));
+        child.stderr.on("data", (chunk) => {
+            stderr = (stderr + chunk.toString("utf8")).slice(-4000);
+        });
+        const stop = () => {
+            child.kill("SIGTERM");
+            setTimeout(() => child.kill("SIGKILL"), 1000).unref();
+        };
+        if (options.signal?.aborted)
+            stop();
+        options.signal?.addEventListener("abort", stop, { once: true });
+        child.on("error", (error) => reject(new RemoteConnectionError(`could not run ${program}: ${error.message}`)));
+        // "close" comes after the last byte of both pipes was read, so nothing the command printed is lost
+        child.on("close", (code) => {
+            options.signal?.removeEventListener("abort", stop);
+            resolve({ exitCode: code, stderr });
+        });
+    });
+}
+/** How long a command waits for a free place before it is given up with an error. */
+const SESSION_WAIT_MS = 60_000;
+/** A fixed number of places, handed out in the order they were asked for. `take` resolves with the function that gives the place back. */
+function createPlaces(count) {
+    let free = count;
+    const waiting = [];
+    const giveBack = () => {
+        const next = waiting.shift();
+        if (next)
+            next.grant();
+        else
+            free++;
+    };
+    const release = () => {
+        let given = false;
+        return () => {
+            if (given)
+                return;
+            given = true;
+            giveBack();
+        };
+    };
+    return {
+        take(waitMs, tooLong) {
+            if (free > 0) {
+                free--;
+                return Promise.resolve(release());
+            }
+            return new Promise((resolve, reject) => {
+                const entry = {
+                    grant: () => {
+                        clearTimeout(timer);
+                        resolve(release());
+                    },
+                };
+                const timer = setTimeout(() => {
+                    waiting.splice(waiting.indexOf(entry), 1);
+                    reject(tooLong());
+                }, waitMs);
+                waiting.push(entry);
+            });
+        },
+    };
+}
+/** How often an idle connection is touched, so that it is not given up by ControlPersist while the session is still there (the master is meant to live as long as we do). */
+const KEEP_ALIVE_MS = 4 * 60_000;
+/**
+ * Opens one connection to the machine and runs every command over it. The first ssh logs in (once) and stays in the background; each later ssh finds it
+ * through a socket in a directory of ours and only starts a new process on the other side, so a command costs milliseconds and not a login. If the
+ * connection dies it is NOT made again: commands are run with ControlMaster=no and ProxyCommand=false, so an ssh that finds no live master has nowhere to
+ * go and fails at once (by default, ssh_config(5) says, a client that cannot use the socket makes a connection of its own, silently and with a new login).
+ * The result is a RemoteConnectionError that tells the caller to stop and report it.
+ */
+export async function connectSsh(options) {
+    const program = options.ssh ?? "ssh";
+    // sockets have a short length limit (104 characters on macOS), so the directory is under /tmp and the name is a hash
+    const directory = await mkdtemp("/tmp/sk-ssh-");
+    const control = `${directory}/%C`;
+    const common = [
+        "-o",
+        `ControlPath=${control}`,
+        "-o",
+        "BatchMode=yes",
+        "-o",
+        `ConnectTimeout=${options.connectTimeoutSec ?? 15}`,
+        "-o",
+        "ServerAliveInterval=15",
+        "-o",
+        "ServerAliveCountMax=3",
+        ...(options.port !== undefined ? ["-p", String(options.port)] : []),
+        ...(options.identityFile !== undefined ? ["-i", options.identityFile] : []),
+        ...Object.entries(options.options ?? {}).flatMap(([name, value]) => ["-o", `${name}=${value}`]),
+    ];
+    let closed = false;
+    const cleanup = () => rm(directory, { recursive: true, force: true });
+    try {
+        // log in now, so a wrong host or key shows up here and not in the middle of a task
+        const opened = await runSsh(program, [...common, "-o", "ControlMaster=yes", "-o", "ControlPersist=10m", "-N", options.host], {});
+        if (opened.exitCode !== 0)
+            throw new RemoteConnectionError(`could not connect to ${options.host}: ${opened.stderr.trim() || `ssh exited with ${opened.exitCode}`}`);
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+    /** Arguments for one command: through the master or nowhere. Ours come first because with ssh the first value of an option wins over later ones. */
+    const throughMaster = (remote) => ["-o", "ControlMaster=no", "-o", "ProxyCommand=false", ...common, options.host, remote];
+    const goneBecause = (detail) => new RemoteConnectionError(`the connection to ${options.host} is gone and is not made again by itself: ${detail || "ssh exited with code 255"}`);
+    const remoteCommand = (command, cwd) => `${cwd !== undefined ? `cd ${quote(cwd)} && ` : ""}bash -c ${quote(command)}`;
+    // Two places stay for short jobs (files, stopping a command), so that commands that run for long cannot keep a command from being stopped.
+    const SHORT_PLACES = 2;
+    const maxSessions = Math.max(SHORT_PLACES + 1, options.maxSessions ?? 8);
+    const commandPlaces = createPlaces(maxSessions - SHORT_PLACES);
+    const shortPlaces = createPlaces(SHORT_PLACES);
+    const waitForPlace = (places, limit) => places.take(SESSION_WAIT_MS, () => new RemoteConnectionError(`too many commands are running at once over the connection to ${options.host} (at most ${limit}); none ended within ${SESSION_WAIT_MS / 1000} seconds. Wait for one to finish or stop one, then try again.`));
+    const run = async (command, runOptions) => {
+        if (closed)
+            throw new RemoteConnectionError("the connection was closed");
+        const giveBack = await waitForPlace(shortPlaces, SHORT_PLACES);
+        try {
+            const result = await runSsh(program, throughMaster(remoteCommand(command, runOptions.cwd)), { timeoutMs: runOptions.timeoutMs, signal: runOptions.signal });
+            // ssh itself exits with 255 when it could not reach the machine; a command that exits with 255 on its own is taken for that too
+            if (result.exitCode === 255 && !result.timedOut && !runOptions.signal?.aborted) {
+                throw new RemoteConnectionError(`${goneBecause(result.stderr.trim()).message}. The command may or may not have run. Stop here and tell the user that the connection was lost.`);
+            }
+            return { exitCode: result.exitCode, output: result.output, timedOut: result.timedOut };
+        }
+        finally {
+            giveBack();
+        }
+    };
+    const stream = async (command, streamOptions) => {
+        if (closed)
+            throw new RemoteConnectionError("the connection was closed");
+        const giveBack = await waitForPlace(commandPlaces, maxSessions - SHORT_PLACES);
+        try {
+            const outcome = await streamSsh(program, throughMaster(remoteCommand(command, streamOptions.cwd)), { signal: streamOptions.signal, onData: streamOptions.onData });
+            // the command's own code travels in its output; the child itself ends with 255 only when ssh could not do its job
+            if (outcome.exitCode === 255 && !streamOptions.signal?.aborted)
+                throw goneBecause(outcome.stderr.trim());
+            return outcome;
+        }
+        finally {
+            giveBack();
+        }
+    };
+    const keepAlive = setInterval(() => void run("true", {}).catch(() => undefined), KEEP_ALIVE_MS);
+    keepAlive.unref();
+    return {
+        run,
+        stream,
+        socketDirectory: directory,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            clearInterval(keepAlive);
+            await runSsh(program, [...common, "-O", "exit", options.host], {}).catch(() => undefined);
+            await cleanup();
+        },
+    };
+}
+/** What the model is told about where its tools run, over ssh. */
+export function describeSsh(host, cwd) {
+    return (`a remote machine (${host}), not the computer that runs you. Every command is sent over an SSH connection and starts fresh in ${cwd}: cd and export do not carry over to the next command. ` +
+        "The connection can be slow or drop, and a command can fail for reasons that have nothing to do with it, so results are not guaranteed to be repeatable. " +
+        "If a tool says the connection failed, the command may or may not have run: look at the current state (list the files, read the output file) before you repeat anything that changes something. " +
+        "A lost connection is not made again by itself: when a tool says it was lost, stop and tell the user. " +
+        "Files are on the remote machine.");
+}
+/** An environment whose tools run on another machine over ssh. Close it (or dispose of the agent) to hang up. */
+export async function createSshEnvironment(options) {
+    const connection = await connectSsh(options);
+    return createRemoteEnvironment({
+        cwd: options.cwd,
+        run: connection.run,
+        stream: connection.stream,
+        close: connection.close,
+        description: describeSsh(options.host, options.cwd),
+        ...(options.workDir !== undefined ? { workDir: options.workDir } : {}),
+    });
+}

package/dist/packages/env/src/index.d.ts

@@ -1,3 +1,8 @@
 export { createLocalEnvironment } from "./local.js";
-export { createRemoteEnvironment } from "./remote.js";
+export type { LocalOptions } from "./local.js";
+export { OutsideDirectoryError } from "./confine.js";
+export { createRemoteEnvironment, RemoteConnectionError } from "./remote.js";
 export type { RemoteRunner } from "./remote.js";
+export type { RemoteStreamer } from "./remote-stream.js";
+export { connectSsh, createSshEnvironment } from "./connect-ssh.js";
+export type { SshConnection, SshOptions } from "./connect-ssh.js";

package/dist/packages/env/src/index.js

@@ -1,2 +1,4 @@
 export { createLocalEnvironment } from "./local.js";
-export { createRemoteEnvironment } from "./remote.js";
+export { OutsideDirectoryError } from "./confine.js";
+export { createRemoteEnvironment, RemoteConnectionError } from "./remote.js";
+export { connectSsh, createSshEnvironment } from "./connect-ssh.js";

package/dist/packages/env/src/local.d.ts

@@ -1,3 +1,12 @@
 import type { Environment } from "../../kernel/src/index.js";
-/** The environment tools run in when there is no sandbox: the local machine. */
-export declare function createLocalEnvironment(cwd: string): Environment;
+export interface LocalOptions {
+    /**
+     * Keep every file operation inside the working directory: reading, writing, listing and the directory of a command are refused (OutsideDirectoryError)
+     * for a path outside it, however it is written (absolute, with .., through a link). This is a boundary for the file tools. It is not a sandbox: a shell
+     * command can still reach anything this process can, so with a shell tool use it together with the review, or without a shell tool at all.
+     * It guards against honest mistakes and a model that wanders, not against a program that races the check.
+     */
+    confine?: boolean;
+}
+/** The environment tools run in by default: this machine, with the permissions of this process. It confines nothing unless `confine` is set. */
+export declare function createLocalEnvironment(cwd: string, options?: LocalOptions): Environment;

package/dist/packages/env/src/local.js

@@ -1,8 +1,9 @@
 import { spawn as spawnProcess } from "node:child_process";
 import { createWriteStream } from "node:fs";
-import { mkdir, mkdtemp, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { isInside, OutsideDirectoryError, realLocation } from "./confine.js";
 const MAX_OUTPUT_CHARS = 20_000_000;
 const KILL_GRACE_MS = 1500;
 function killGroup(pid, signal) {
@@ -15,7 +16,9 @@ function killGroup(pid, signal) {
         // the group is already gone
     }
 }
-// Commands run in their own process group, so they would outlive a host process that is stopped without closing the environment
+// Commands run in their own process group, so that stopping one stops everything it started. (A command that starts a session of its own, with
+// setsid for example, leaves the group and is not reached by that; to stop everything, run the commands in a container.)
+// They would also outlive a host process that is stopped without closing the environment
 // (Ctrl-C, process.exit, a script that ends while a background command still runs). Every group still running is stopped when the host exits.
 const liveGroups = new Set();
 let exitHooked = false;
@@ -39,15 +42,43 @@ function hookExit() {
         process.on(signal, onSignal);
     }
 }
-/** The environment tools run in when there is no sandbox: the local machine. */
-export function createLocalEnvironment(cwd) {
+/** The environment tools run in by default: this machine, with the permissions of this process. It confines nothing unless `confine` is set. */
+export function createLocalEnvironment(cwd, options = {}) {
     const root = resolve(cwd);
-    const resolvePath = (path) => (isAbsolute(path) ? resolve(path) : resolve(root, path));
+    const confine = options.confine === true;
+    /** Where the output files of the commands of this environment are: outside the working directory, and the model is told to read them. */
+    let outputRoot;
+    const inOutputRoot = (absolute) => outputRoot !== undefined && isInside(outputRoot, absolute);
+    const resolvePath = (path) => {
+        const absolute = isAbsolute(path) ? resolve(path) : resolve(root, path);
+        if (confine && !isInside(root, absolute) && !inOutputRoot(absolute))
+            throw new OutsideDirectoryError(absolute, root);
+        return absolute;
+    };
+    let realRoot;
+    /** For file operations: the text check of resolvePath, and then where the path really is, because a link inside the folder can lead out of it. */
+    const checked = async (path, forWriting = false) => {
+        const absolute = resolvePath(path);
+        if (confine && inOutputRoot(absolute)) {
+            if (forWriting)
+                throw new OutsideDirectoryError(absolute, root); // the output files may be read, not written
+            return absolute;
+        }
+        if (confine) {
+            realRoot ??= realpath(root);
+            if (!isInside(await realRoot, await realLocation(absolute, root)))
+                throw new OutsideDirectoryError(absolute, root);
+        }
+        return absolute;
+    };
     const running = new Set();
     let outputDir;
     let counter = 0;
     const nextOutputFile = async () => {
-        outputDir ??= mkdtemp(join(tmpdir(), "sakura-env-"));
+        outputDir ??= mkdtemp(join(tmpdir(), "sakura-env-")).then((directory) => {
+            outputRoot = resolve(directory);
+            return directory;
+        });
         return join(await outputDir, `command-${++counter}.log`);
     };
     function start(command, options) {
@@ -129,16 +160,17 @@ export function createLocalEnvironment(cwd) {
     }
     return {
         cwd: root,
+        ...(confine ? { description: `this machine (${process.platform}). The file tools work only inside ${root}; a path outside it is refused.` } : {}),
         resolve: resolvePath,
-        readFile: async (path) => new Uint8Array(await readFile(resolvePath(path))),
+        readFile: async (path) => new Uint8Array(await readFile(await checked(path))),
         async writeFile(path, data) {
-            const target = resolvePath(path);
+            const target = await checked(path, true);
             await mkdir(dirname(target), { recursive: true });
             await writeFile(target, data);
         },
         async stat(path) {
             try {
-                const info = await stat(resolvePath(path));
+                const info = await stat(await checked(path));
                 return { isFile: info.isFile(), isDirectory: info.isDirectory(), size: info.size };
             }
             catch (error) {
@@ -148,7 +180,7 @@ export function createLocalEnvironment(cwd) {
             }
         },
         async list(path) {
-            return (await readdir(resolvePath(path))).sort();
+            return (await readdir(await checked(path))).sort();
         },
         spawn: start,
         async exec(command, options) {

package/dist/packages/env/src/remote-stream.d.ts

@@ -0,0 +1,48 @@
+import type { ProcessHandle } from "../../kernel/src/index.js";
+import type { RemoteRunner } from "./remote-types.js";
+/**
+ * Runs one command on the other side as a child that lives as long as the command is watched, and hands over what it prints as it is printed. Resolves
+ * with the exit code of that child (null when it was stopped by a signal) and what it wrote to its own error stream, which is the transport's talk (ssh
+ * says why it could not connect) and never the command's. Rejects with a RemoteConnectionError when the child could not be started at all.
+ */
+export type RemoteStreamer = (command: string, options: {
+    cwd?: string;
+    signal?: AbortSignal;
+    onData(text: string): void;
+}) => Promise<{
+    exitCode: number | null;
+    stderr: string;
+}>;
+export interface StreamedSpawnDependencies {
+    stream: RemoteStreamer;
+    /** One short command over the same connection (used to stop a command). */
+    run: RemoteRunner;
+    root: string;
+    workDir: string;
+    resolvePath(path: string): string;
+    nextId(): string;
+    running: Set<ProcessHandle>;
+    killing: Map<ProcessHandle, Promise<void>>;
+}
+/**
+ * The shell text one streamed command is sent as. It writes the script, starts it detached (own session, output into a log file, so it survives the
+ * connection and the log can be read afterwards), prints the process group id, then copies the log to its own output as the log grows. When the command
+ * has ended and the log is copied to the last byte, it prints the exit code after a marker. `wait` gives the exit code without anyone looking for it.
+ */
+export declare function launcherFor(options: {
+    id: string;
+    command: string;
+    cwd: string;
+    workDir: string;
+}): string;
+/** `kill` text for the group of a command: ask nicely, then insist. */
+export declare const stopCommand: (pid: number) => string;
+/**
+ * `spawn` for an environment that has a streamer. Each command is one child of the connection; the exit code is the end of that child's script, no
+ * file is looked at to find it; stopping a command stops its process group on the other side. When the connection is lost the command is NOT followed:
+ * it keeps running there (it is detached), and the error says that, where its output is, and that the model must stop and report it.
+ */
+export declare function createStreamedSpawn(deps: StreamedSpawnDependencies): (command: string, options: {
+    cwd?: string;
+    signal?: AbortSignal;
+}) => ProcessHandle;

package/dist/packages/env/src/remote-stream.js

@@ -0,0 +1,143 @@
+import { posix } from "node:path";
+import { RemoteConnectionError } from "./remote-types.js";
+const quote = (text) => `'${text.replace(/'/g, `'\\''`)}'`;
+/** Output kept from one command, as for a local one. */
+const MAX_OUTPUT_CHARS = 20_000_000;
+/** After a stop was asked for, how long the connection gets to report the end before the local child is killed. */
+const STOP_GRACE_MS = 4000;
+/** What the model sees of a command that was lost in the middle. */
+const TAIL_LINES = 20;
+/**
+ * The shell text one streamed command is sent as. It writes the script, starts it detached (own session, output into a log file, so it survives the
+ * connection and the log can be read afterwards), prints the process group id, then copies the log to its own output as the log grows. When the command
+ * has ended and the log is copied to the last byte, it prints the exit code after a marker. `wait` gives the exit code without anyone looking for it.
+ */
+export function launcherFor(options) {
+    const { id, workDir } = options;
+    const script = posix.join(workDir, `${id}.sh`);
+    const log = posix.join(workDir, `${id}.log`);
+    const stop = posix.join(workDir, `${id}.stop`);
+    const body = `cd ${quote(options.cwd)} || exit 1\n${options.command}\n`;
+    const detached = `bash ${quote(script)} > ${quote(log)} 2>&1; code=$?; exit $code`;
+    return [
+        `mkdir -p ${quote(workDir)} && echo ${Buffer.from(body).toString("base64")} | base64 -d > ${quote(script)} && : > ${quote(log)} && rm -f ${quote(stop)} || exit 126`,
+        `setsid bash -c ${quote(detached)} < /dev/null > /dev/null 2>&1 &`,
+        "main=$$ job=$!",
+        `printf '@@${id}-pid %s\\n' "$job"`,
+        // copy the log as it grows; the end is known when the stop file exists (or the shell that started this is gone) AND nothing more was written after that was seen
+        `( sent=0; while :; do ended=0; [ -e ${quote(stop)} ] && ended=1; kill -0 "$main" 2>/dev/null || ended=1; size=$(wc -c < ${quote(log)}); if [ "$size" -gt "$sent" ]; then tail -c +$((sent+1)) ${quote(log)} | head -c $((size-sent)); sent=$size; continue; fi; [ $ended = 1 ] && break; sleep 0.05; done ) &`,
+        "follower=$!",
+        'wait "$job"; code=$?',
+        `: > ${quote(stop)}`,
+        'wait "$follower"',
+        `printf '\\n@@${id}-exit %s\\n' "$code"`,
+        // the command's own code is in the line above; the child ends with 0, so that an ssh that ends with 255 can only mean that the connection failed
+        "exit 0",
+    ].join("\n");
+}
+/** `kill` text for the group of a command: ask nicely, then insist. */
+export const stopCommand = (pid) => `kill -TERM -- -${pid} 2>/dev/null; sleep 1; kill -KILL -- -${pid} 2>/dev/null; true`;
+const lastLines = (text) => text.trimEnd().split("\n").slice(-TAIL_LINES).join("\n");
+/**
+ * `spawn` for an environment that has a streamer. Each command is one child of the connection; the exit code is the end of that child's script, no
+ * file is looked at to find it; stopping a command stops its process group on the other side. When the connection is lost the command is NOT followed:
+ * it keeps running there (it is detached), and the error says that, where its output is, and that the model must stop and report it.
+ */
+export function createStreamedSpawn(deps) {
+    return (command, spawnOptions) => {
+        const id = deps.nextId();
+        const log = posix.join(deps.workDir, `${id}.log`);
+        const pidMarker = `@@${id}-pid `;
+        const exitMarker = `\n@@${id}-exit `;
+        const local = new AbortController();
+        let pid = 0;
+        let finished = false;
+        let stopRequested = false;
+        let received = "";
+        let pidSeen;
+        const pidKnown = new Promise((resolve) => {
+            pidSeen = resolve;
+        });
+        const launcher = launcherFor({ id, command, cwd: spawnOptions.cwd ? deps.resolvePath(spawnOptions.cwd) : deps.root, workDir: deps.workDir });
+        const kill = () => {
+            if (deps.killing.has(handle))
+                return;
+            stopRequested = true;
+            deps.killing.set(handle, (async () => {
+                const ended = new Promise((resolve) => void done.then(() => resolve(), () => resolve()));
+                await Promise.race([pidKnown, ended]);
+                if (pid > 0 && !finished)
+                    await deps.run(stopCommand(pid), { cwd: deps.root }).catch(() => undefined);
+                // the connection normally reports the end now; if it does not, the local child is stopped so that nobody waits for ever
+                const timer = setTimeout(() => local.abort(), STOP_GRACE_MS);
+                await ended;
+                clearTimeout(timer);
+            })());
+        };
+        spawnOptions.signal?.addEventListener("abort", kill, { once: true });
+        if (spawnOptions.signal?.aborted)
+            queueMicrotask(kill);
+        const lostMessage = (reason) => `The connection to the remote machine was lost while the command was running (${reason}). The command may still be running or may have finished; its output is being written to ${log} on the remote machine. ` +
+            "Stop here and tell the user that the connection was lost, and where that output file is. Do not reconnect or run the command again yourself." +
+            (received.trim() !== "" ? `\nLast output received:\n${lastLines(received)}` : "");
+        const handle = {
+            get pid() {
+                return pid;
+            },
+            outputFile: log,
+            wait: () => done,
+            kill,
+            get finished() {
+                return finished;
+            },
+        };
+        const done = (async () => {
+            const end = () => {
+                finished = true;
+                deps.running.delete(handle);
+            };
+            let outcome;
+            try {
+                outcome = await deps.stream(launcher, {
+                    cwd: deps.root,
+                    signal: local.signal,
+                    onData: (text) => {
+                        received += text;
+                        if (received.length > MAX_OUTPUT_CHARS)
+                            received = received.slice(received.length - MAX_OUTPUT_CHARS);
+                        if (pid === 0 && received.startsWith(pidMarker) && received.includes("\n")) {
+                            pid = Number.parseInt(received.slice(pidMarker.length, received.indexOf("\n")), 10) || 0;
+                            received = received.slice(received.indexOf("\n") + 1);
+                            pidSeen();
+                        }
+                    },
+                });
+            }
+            catch (error) {
+                end();
+                pidSeen();
+                if (!(error instanceof RemoteConnectionError))
+                    throw error;
+                throw new RemoteConnectionError(pid === 0
+                    ? `The connection to the remote machine failed while the command was being started, so it may or may not be running (${error.message}). If it is, its output is being written to ${log} on the remote machine. Stop here and tell the user.`
+                    : lostMessage(error.message));
+            }
+            end();
+            pidSeen();
+            const at = received.lastIndexOf(exitMarker);
+            const trailer = at === -1 ? undefined : /^(\d+)\n$/.exec(received.slice(at + exitMarker.length));
+            if (at !== -1 && trailer) {
+                const code = Number(trailer[1]);
+                const output = received.slice(0, at);
+                // stopped on request: the number says which signal ended it, which nobody asked about
+                return { exitCode: stopRequested && code > 128 ? null : code, output: output.length > MAX_OUTPUT_CHARS ? output.slice(output.length - MAX_OUTPUT_CHARS) : output, timedOut: false };
+            }
+            if (pid === 0)
+                return { exitCode: null, output: `the command could not be started${outcome.stderr.trim() ? `: ${outcome.stderr.trim()}` : ""}`, timedOut: false };
+            throw new RemoteConnectionError(lostMessage(outcome.stderr.trim() || `the connection ended with ${outcome.exitCode === null ? "a signal" : `exit code ${outcome.exitCode}`}`));
+        })();
+        done.catch(() => undefined); // a caller that never waits must not cause an unhandled rejection
+        deps.running.add(handle);
+        return handle;
+    };
+}

package/dist/packages/env/src/remote-types.d.ts

@@ -0,0 +1,17 @@
+import type { ExecResult } from "../../kernel/src/index.js";
+/**
+ * Thrown by a runner when it could not reach the other side, so nothing is known about whether the command ran. A command that did run and failed
+ * is not this: it is a result with its own exit code. Whoever writes a runner translates its transport's failures (ssh exits with 255, for example) into this.
+ */
+export declare class RemoteConnectionError extends Error {
+    constructor(message: string);
+}
+/**
+ * The one thing a remote environment needs: a way to run a shell command somewhere else and get its output back.
+ * It resolves with the result of a command that ran, whatever its exit code, and rejects with a RemoteConnectionError when it could not reach the other side.
+ */
+export type RemoteRunner = (command: string, options: {
+    cwd?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}) => Promise<ExecResult>;

package/dist/packages/env/src/remote-types.js

@@ -0,0 +1,10 @@
+/**
+ * Thrown by a runner when it could not reach the other side, so nothing is known about whether the command ran. A command that did run and failed
+ * is not this: it is a result with its own exit code. Whoever writes a runner translates its transport's failures (ssh exits with 255, for example) into this.
+ */
+export class RemoteConnectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RemoteConnectionError";
+    }
+}

package/dist/packages/env/src/remote.d.ts

@@ -1,10 +1,8 @@
-import type { Environment, ExecResult } from "../../kernel/src/index.js";
-/** The one thing a remote environment needs: a way to run a shell command somewhere else and get its output back. */
-export type RemoteRunner = (command: string, options: {
-    cwd?: string;
-    timeoutMs?: number;
-    signal?: AbortSignal;
-}) => Promise<ExecResult>;
+import type { Environment } from "../../kernel/src/index.js";
+import type { RemoteRunner } from "./remote-types.js";
+import type { RemoteStreamer } from "./remote-stream.js";
+export { RemoteConnectionError } from "./remote-types.js";
+export type { RemoteRunner } from "./remote-types.js";
 /**
  * An environment on another machine (a container, say) reached only through `run`. Files are read and written
  * with base64 over the shell, and long commands are started detached so they can outlive a single call.
@@ -12,4 +10,15 @@ export type RemoteRunner = (command: string, options: {
 export declare function createRemoteEnvironment(options: {
     cwd: string;
     run: RemoteRunner;
+    /**
+     * Optional. With it, every command (`spawn` and `exec`) is one streamed child of the connection and its end is the end of that child; without it the
+     * environment starts commands detached through `run` and looks for their exit code from time to time, which is all a runner without a live channel can do.
+     */
+    stream?: RemoteStreamer;
+    /** Called once when the environment is disposed, after its commands were stopped: close the connection the runner uses. */
+    close?: () => Promise<void>;
+    /** What the model is told about where its tools run (see Environment.description). */
+    description?: string;
+    /** Where the scripts and logs of started commands are kept on the other machine, and where a background command's output file is. Default /tmp/.sakura-remote, so the working directory is left as the task has it. */
+    workDir?: string;
 }): Environment;