Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): keep slow bash commands running as sandbox jobs (#4300)

Andrew Barba8582a3661cac
diff --git a/.changeset/bash-background-jobs.md b/.changeset/bash-background-jobs.md
new file mode 100644
index 000000000..db0cd4b00
--- /dev/null
+++ b/.changeset/bash-background-jobs.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+The `bash` tool no longer blocks on slow commands: a command still running after 30 seconds keeps running in the sandbox and returns `status: "running"` with its process group `pid`, its output so far, and an `outputDirectory` whose `stdout`, `stderr`, and `exit` files the model reads with later commands. Cancelling a turn now stops a command that has not yet returned. `BashToolOutput` now carries `status`, and `exitCode` is present only on `completed` results, so authored wrappers that read the output should check `status` first.
diff --git a/docs/concepts/built-in-tools.md b/docs/concepts/built-in-tools.md
index 2ae1c0083..04116f3d6 100644
--- a/docs/concepts/built-in-tools.md
+++ b/docs/concepts/built-in-tools.md
@@ -38,6 +38,23 @@ eve add tool/bash
export { default } from "eve/tools/bash";
```
+`bash` waits up to 30 seconds for a command. A command that finishes in time returns `status: "completed"` with `exitCode`, `stdout`, `stderr`, and `truncated`. A command that is still running keeps running in the sandbox as its own process group and returns `status: "running"` with:
+
+- `pid`: the process group id
+- `outputDirectory`: a directory under `/tmp/.eve/jobs/`
+- `stdout`, `stderr`, and `truncated`: the output so far
+- `message`: instructions for the model
+
+The command keeps writing to `stdout` and `stderr` files in `outputDirectory` and writes its exit code to an `exit` file when it finishes. The model checks on or stops it with ordinary shell commands in later `bash` calls, so the tool's approval policy applies to them:
+
+```sh
+tail /tmp/.eve/jobs/3f9a1c2e/stdout # latest output
+cat /tmp/.eve/jobs/3f9a1c2e/exit # exit code, once the command has finished
+kill -- -4312 # stop the command's whole process group
+```
+
+The command keeps running across turns until it exits, the model stops it, or the sandbox stops. Its output files stay in the sandbox until the sandbox stops. Cancelling a turn stops a command that has not yet returned `running`. The `just-bash` provider has no background processes, so it runs every command to completion.
+
Override its description, approval policy, or executor by wrapping the exported definition:
```ts title="agent/tools/bash.ts"
diff --git a/e2e/fixtures/agent-tools-sandbox/agent/lib/mock-responder.ts b/e2e/fixtures/agent-tools-sandbox/agent/lib/mock-responder.ts
index db69b2c13..75a3e475a 100644
--- a/e2e/fixtures/agent-tools-sandbox/agent/lib/mock-responder.ts
+++ b/e2e/fixtures/agent-tools-sandbox/agent/lib/mock-responder.ts
@@ -22,6 +22,9 @@ export function respond(request: MockModelRequest): MockModelResponse | string {
})),
};
}
+ if (message.includes("EVE_SANDBOX_BASH_JOB")) {
+ return respondToBashJob(message, request);
+ }
if (message.includes("DYNAMIC-TURN-REPLAY-START")) {
const gate = request.toolResults.find((result) => result.name === "dynamic-turn-replay-gate");
if (gate === undefined) {
@@ -77,6 +80,33 @@ export function respond(request: MockModelRequest): MockModelResponse | string {
return `Mock reply: ${message}`;
}
+/** Starts the slow command, reads its output once, stops it, then replies. */
+function respondToBashJob(message: string, request: MockModelRequest): MockModelResponse | string {
+ const outputs = request.toolResults
+ .filter((result) => result.name === "bash")
+ .map(
+ (result) => result.output as { readonly outputDirectory?: unknown; readonly pid?: unknown },
+ );
+ if (outputs.length === 0) {
+ const command = /by running: `([^`]+)`/u.exec(message)?.[1] ?? "";
+ return { toolCalls: [{ input: { command }, name: "bash" }] };
+ }
+ const { outputDirectory, pid } = outputs[0] ?? {};
+ if (typeof outputDirectory !== "string" || typeof pid !== "number") {
+ return formatOutput(outputs[0]);
+ }
+ if (outputs.length === 1) {
+ const command = `sleep 2; tail -n 1 ${outputDirectory}/stdout`;
+ return { toolCalls: [{ input: { command }, name: "bash" }] };
+ }
+ if (outputs.length === 2) {
+ const exitFile = `${outputDirectory}/exit`;
+ const command = `kill -- -${pid}; for i in 1 2 3 4 5; do [ -f ${exitFile} ] && break; sleep 1; done; cat ${exitFile}`;
+ return { toolCalls: [{ input: { command }, name: "bash" }] };
+ }
+ return "index job stopped";
+}
+
/** The `[Tasks]` note and `<task_result>` messages are eve's, not the user's. */
function isFrameworkMessage(text: string): boolean {
const trimmed = text.trim();
diff --git a/e2e/fixtures/agent-tools-sandbox/evals/sandbox/bash-background-job.eval.ts b/e2e/fixtures/agent-tools-sandbox/evals/sandbox/bash-background-job.eval.ts
new file mode 100644
index 000000000..134ba863d
--- /dev/null
+++ b/e2e/fixtures/agent-tools-sandbox/evals/sandbox/bash-background-job.eval.ts
@@ -0,0 +1,59 @@
+import type { MessageStreamEvent } from "eve/client";
+import { defineEval } from "eve/evals";
+
+const BASH_TOOL = "bash";
+const INDEX_COMMAND = "for i in $(seq 1 120); do echo indexed batch $i; sleep 1; done";
+
+interface BashOutput {
+ readonly exitCode?: number;
+ readonly status?: string;
+ readonly stdout?: string;
+}
+
+export default defineEval({
+ description:
+ "Sandbox Bash: a slow command returns running, keeps writing its output file, and stops with kill.",
+ // The first bash call waits the full 30-second yield before it reports the command.
+ timeoutMs: 150_000,
+ async test(t) {
+ const turn = await t.send(
+ [
+ "EVE_SANDBOX_BASH_JOB",
+ "Alice is rebuilding a search index that prints one progress line per second for two minutes.",
+ `Start it with the \`${BASH_TOOL}\` tool by running: \`${INDEX_COMMAND}\``,
+ "The tool will report that the command is still running, with its process group and output directory.",
+ "Check its latest progress line once with `tail`, then stop it with `kill` and read its exit code.",
+ "After it stops, reply with exactly: index job stopped",
+ ].join("\n"),
+ );
+ turn.expectOk();
+
+ t.log(JSON.stringify(bashOutputs(turn.events)));
+ turn.noFailedActions();
+ turn.eventsSatisfy("the slow command yields, keeps running, then stops with kill", (events) =>
+ jobWasObservedAndStopped(bashOutputs(events)),
+ );
+ },
+});
+
+function jobWasObservedAndStopped(outputs: readonly BashOutput[]): boolean {
+ const [started, observed, stopped] = outputs;
+ return (
+ started?.status === "running" &&
+ started.stdout?.includes("indexed batch 1") === true &&
+ observed?.status === "completed" &&
+ /indexed batch \d+/u.test(observed.stdout ?? "") &&
+ stopped?.status === "completed" &&
+ stopped.stdout?.trim() === "143"
+ );
+}
+
+function bashOutputs(events: readonly MessageStreamEvent[]): readonly BashOutput[] {
+ return events.flatMap((event) => {
+ if (event.type !== "action.result" || event.data.result.kind !== "tool-result") return [];
+ if (event.data.result.toolName !== BASH_TOOL) return [];
+ const output = event.data.result.output;
+ if (typeof output !== "object" || output === null || Array.isArray(output)) return [];
+ return [output as BashOutput];
+ });
+}
diff --git a/packages/eve/src/execution/sandbox/bash.scenario.test.ts b/packages/eve/src/execution/sandbox/bash.scenario.test.ts
new file mode 100644
index 000000000..4e5f5ea17
--- /dev/null
+++ b/packages/eve/src/execution/sandbox/bash.scenario.test.ts
@@ -0,0 +1,154 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useTemporaryDirectories } from "#internal/testing/use-temporary-app-roots.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+
+import { executeBashOnSandbox } from "./bash.js";
+import { buildSandboxSession } from "./session.js";
+
+const createScratchDirectory = useTemporaryDirectories();
+
+// Real `bash -lc` on the host stands in for a sandbox; fake timers skip the 30-second yield.
+describe("executeBashOnSandbox with a real shell", () => {
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("returns a fast command's exit code and separate streams", async () => {
+ const { sandbox } = await createHostSandbox();
+
+ const result = await executeBashOnSandbox(sandbox, {
+ command: "echo out; echo err >&2; exit 3",
+ });
+
+ expect(result).toEqual({
+ exitCode: 3,
+ status: "completed",
+ stderr: "err\n",
+ stdout: "out\n",
+ truncated: false,
+ });
+ });
+
+ it("leaves a slow command running, and kill stops its whole process group", async () => {
+ vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+ const { home, launches, sandbox } = await createHostSandbox();
+ await writeFile(join(home, ".bash_profile"), 'echo "Welcome to the sandbox"\n');
+ const pidFile = join(home, "child.pid");
+
+ const call = executeBashOnSandbox(sandbox, {
+ command: `echo first; sleep 60 & echo $! > ${pidFile}; wait`,
+ });
+ const childPid = await readPid(pidFile);
+ await vi.advanceTimersByTimeAsync(30_000);
+ const result = await call;
+
+ if (result.status !== "running") throw new Error(`expected running: ${JSON.stringify(result)}`);
+ expect(result).toMatchObject({ stderr: "", stdout: "first\n", truncated: false });
+ expect(result.message).toContain(`kill -- -${result.pid}`);
+ // The call's stream ends at the yield; only the command keeps running.
+ await launches[0];
+ expect(isProcessAlive(childPid)).toBe(true);
+
+ await runHostBash(`kill -- -${result.pid}`, home);
+
+ await vi.waitFor(() => expect(isProcessAlive(childPid)).toBe(false), { timeout: 10_000 });
+ const exitFile = join(result.outputDirectory, "exit");
+ await vi.waitFor(() => expect(readFileSync(exitFile, "utf8").trim()).toBe("143"), {
+ timeout: 10_000,
+ });
+ await rm(result.outputDirectory, { force: true, recursive: true });
+ });
+
+ it("stops the command's process group when the call is aborted", async () => {
+ const { home, sandbox } = await createHostSandbox();
+ const pidFile = join(home, "child.pid");
+ const controller = new AbortController();
+
+ const call = executeBashOnSandbox(
+ sandbox,
+ { command: `sleep 60 & echo $! > ${pidFile}; wait` },
+ { abortSignal: controller.signal },
+ );
+ const childPid = await readPid(pidFile);
+ controller.abort();
+
+ await expect(call).rejects.toThrow();
+ await vi.waitFor(() => expect(isProcessAlive(childPid)).toBe(false), { timeout: 10_000 });
+ });
+});
+
+async function createHostSandbox(): Promise<{
+ readonly home: string;
+ /** Settles when each launched process has exited and closed its output. */
+ readonly launches: Promise<unknown>[];
+ readonly sandbox: SandboxSession;
+}> {
+ const home = await createScratchDirectory("eve-bash-");
+ const launches: Promise<unknown>[] = [];
+ const unsupported = async (): Promise<never> => {
+ throw new Error("not used by the bash tool");
+ };
+ const sandbox = buildSandboxSession({
+ readFile: unsupported,
+ removePath: unsupported,
+ resolvePath: (path) => path,
+ writeFile: unsupported,
+ async spawn(options) {
+ const child = spawn("bash", ["-lc", options.command], {
+ cwd: home,
+ env: { ...process.env, HOME: home },
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ const exited = new Promise<{ exitCode: number }>((resolve, reject) => {
+ child.on("error", reject);
+ child.on("close", (code) => resolve({ exitCode: code ?? 137 }));
+ });
+ launches.push(exited);
+ // Like many providers, aborting kills only the launched process.
+ options.abortSignal?.addEventListener("abort", () => child.kill("SIGKILL"), { once: true });
+ return {
+ pid: child.pid,
+ stderr: Readable.toWeb(child.stderr) as ReadableStream<Uint8Array>,
+ stdout: Readable.toWeb(child.stdout) as ReadableStream<Uint8Array>,
+ async wait() {
+ const result = await exited;
+ options.abortSignal?.throwIfAborted();
+ return result;
+ },
+ async kill() {
+ child.kill("SIGKILL");
+ },
+ };
+ },
+ });
+ return { home, launches, sandbox };
+}
+
+async function runHostBash(command: string, home: string): Promise<void> {
+ const child = spawn("bash", ["-c", command], { cwd: home, stdio: "ignore" });
+ await new Promise((resolve) => child.on("close", resolve));
+}
+
+async function readPid(path: string): Promise<number> {
+ await vi.waitFor(
+ () => expect(existsSync(path) && readFileSync(path, "utf8").trim()).toMatch(/^\d+$/),
+ { timeout: 10_000 },
+ );
+ return Number(readFileSync(path, "utf8"));
+}
+
+function isProcessAlive(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch {
+ return false;
+ }
+}
diff --git a/packages/eve/src/execution/sandbox/bash.test.ts b/packages/eve/src/execution/sandbox/bash.test.ts
index dfab31d07..6cffaad0d 100644
--- a/packages/eve/src/execution/sandbox/bash.test.ts
+++ b/packages/eve/src/execution/sandbox/bash.test.ts
@@ -4,6 +4,7 @@ import { EVE_DEV_ENV_FLAG } from "#internal/application/optional-package-install
import type { SandboxCommandResult, SandboxSession } from "#shared/sandbox-session.js";
import { executeBashOnSandbox } from "./bash.js";
+import { bufferToStream } from "./stream-utils.js";
describe("executeBashOnSandbox", () => {
const previousDevFlag = process.env[EVE_DEV_ENV_FLAG];
@@ -30,6 +31,7 @@ describe("executeBashOnSandbox", () => {
expect(result).toEqual({
exitCode: 0,
+ status: "completed",
stderr: "",
stdout: "weather-codes.md\n",
truncated: false,
@@ -40,16 +42,22 @@ describe("executeBashOnSandbox", () => {
});
function createTestSandboxSession(result: SandboxCommandResult): SandboxSession {
+ const encoder = new TextEncoder();
return {
readBinaryFile: async () => null,
readFile: async () => null,
readTextFile: async () => null,
removePath: async () => {},
resolvePath: (path) => path,
- run: vi.fn().mockResolvedValue(result),
- spawn: async () => {
- throw new Error("spawn is not implemented in this test sandbox");
+ run: async () => {
+ throw new Error("run is not used by a command that finishes in time");
},
+ spawn: async () => ({
+ kill: async () => {},
+ stderr: bufferToStream(encoder.encode(result.stderr)),
+ stdout: bufferToStream(encoder.encode(result.stdout)),
+ wait: async () => ({ exitCode: result.exitCode }),
+ }),
writeBinaryFile: async () => {},
writeFile: async () => {},
writeTextFile: async () => {},
diff --git a/packages/eve/src/execution/sandbox/bash.ts b/packages/eve/src/execution/sandbox/bash.ts
index 6b7b98222..0e8e123a9 100644
--- a/packages/eve/src/execution/sandbox/bash.ts
+++ b/packages/eve/src/execution/sandbox/bash.ts
@@ -1,9 +1,49 @@
+import { randomUUID } from "node:crypto";
+
import type { SandboxSession } from "#shared/sandbox-session.js";
-import { truncateTail } from "#execution/sandbox/truncate-output.js";
+import { shellQuote } from "#execution/sandbox/shell-quote.js";
+import { streamToBuffer } from "#execution/sandbox/stream-utils.js";
+import { MAX_OUTPUT_BYTES, truncateTail } from "#execution/sandbox/truncate-output.js";
import { isEveDevEnvironment } from "#internal/application/dev-environment.js";
+/** How long a `bash` call waits before it leaves the command running in the background. */
+export const BASH_YIELD_SECONDS = 30;
+
+/** Where each command's output files live inside the sandbox. */
+const JOB_ROOT = "/tmp/.eve/jobs";
+
const MAX_LOG_COMMAND_LENGTH = 240;
+// The launcher runs the command in its own process group with its output in
+// files, so the command can outlive this call. If the command finishes first,
+// the launcher prints its output and exits with its code. Whichever of the
+// launcher and the yield's claim creates `claimed` first reports the command;
+// a claim also signals the launcher to exit, which ends the provider's stream
+// without touching the command. The command holds none of the launcher's file
+// descriptors, or the stream would stay open until the command exits.
+const LAUNCHER = `d=$1
+mkdir -p "$d" 2>/dev/null || { eval "$2"; exit; }
+trap 'exit 0' USR1
+echo "$$" > "$d/launcher"
+set -m
+(
+ trap : TERM INT
+ (eval "$2") > "$d/stdout" 2> "$d/stderr"
+ code=$?
+ echo "$code" > "$d/exit"
+ exit "$code"
+) < /dev/null > /dev/null 2>&1 &
+pid=$!
+set +m
+echo "$pid" > "$d/pid"
+wait "$pid" 2> /dev/null
+code=$?
+mkdir "$d/claimed" 2> /dev/null || exit 0
+cat "$d/stdout"
+cat "$d/stderr" >&2
+rm -rf "$d"
+exit "$code"`;
+
// ---------------------------------------------------------------------------
// Input shape
// ---------------------------------------------------------------------------
@@ -15,95 +55,252 @@ export interface BashInput {
readonly command: string;
}
+/**
+ * Per-call options for {@link executeBashOnSandbox}.
+ */
+export interface BashExecutionOptions {
+ /**
+ * Stops the command when aborted before the call returns. A command
+ * already returned as `running` keeps running.
+ */
+ readonly abortSignal?: AbortSignal;
+}
+
// ---------------------------------------------------------------------------
// Result shape
// ---------------------------------------------------------------------------
-/**
- * Structured result returned from {@link executeBashOnSandbox}.
- */
-interface BashResult {
- readonly exitCode: number;
+interface BashStreams {
readonly stderr: string;
readonly stdout: string;
/** True when stdout or stderr was shortened to fit within output limits. */
readonly truncated: boolean;
}
+/**
+ * Structured result returned from {@link executeBashOnSandbox}: the command
+ * finished, or it is still running in the background.
+ */
+type BashResult =
+ | (BashStreams & { readonly status: "completed"; readonly exitCode: number })
+ | (BashStreams & {
+ readonly status: "running";
+ readonly pid: number;
+ readonly outputDirectory: string;
+ readonly message: string;
+ });
+
+interface RawStreams {
+ readonly stderr: string;
+ readonly stdout: string;
+}
+
// ---------------------------------------------------------------------------
// Executor
// ---------------------------------------------------------------------------
/**
- * Executes one shell command inside the agent's sandbox via `SandboxKey`
- * on the active runtime context.
+ * Executes one shell command inside the agent's sandbox.
+ *
+ * A command that finishes within {@link BASH_YIELD_SECONDS} returns its exit
+ * code and output. A slower command keeps running in the sandbox as its own
+ * process group, writing to files the model reads with later commands, and
+ * the call returns its output so far with `status: "running"`. Sandboxes that
+ * cannot run background processes, such as `just-bash`, run every command to
+ * completion.
*
* Both stdout and stderr are tail-truncated to keep the end of the output
* (where errors and final results typically appear) within the shared
- * {@link MAX_OUTPUT_LINES} / {@link MAX_OUTPUT_BYTES} limits.
- *
- * Used by the framework `bash` tool and authored wrappers around its
- * exported definition. Centralizing the executor here keeps the error
- * messages and result shape identical across all bash-style tools.
+ * output limits.
*/
export async function executeBashOnSandbox(
sandbox: SandboxSession,
args: BashInput,
+ options: BashExecutionOptions = {},
): Promise<BashResult> {
- const raw = await runWithDevelopmentSandboxProgress(sandbox, args.command);
-
- const stdoutResult = truncateTail(raw.stdout);
- const stderrResult = truncateTail(raw.stderr);
- const truncated = stdoutResult.truncated || stderrResult.truncated;
+ const command = formatCommand(args.command);
+ logDevelopmentSandboxCommand(`eve: starting sandbox command: ${command}`);
+ const result = await withDevelopmentSandboxProgress(command, () =>
+ runCommand(sandbox, args.command, options.abortSignal),
+ );
+ logDevelopmentSandboxCommand(
+ result.status === "running"
+ ? `eve: sandbox command still running as pid ${result.pid}: ${command}`
+ : `eve: sandbox command finished (exit ${result.exitCode}): ${command}`,
+ );
+ return result;
+}
- let stdout = stdoutResult.output;
- if (stdoutResult.truncated) {
- stdout =
- `[stdout truncated: showing last ${stdoutResult.outputLines} of ${stdoutResult.totalLines} lines]\n` +
- stdout;
+async function runCommand(
+ sandbox: SandboxSession,
+ command: string,
+ signal: AbortSignal | undefined,
+): Promise<BashResult> {
+ signal?.throwIfAborted();
+ const jobId = randomUUID().slice(0, 8);
+ const directory = `${JOB_ROOT}/${jobId}`;
+ // The call's signal also aborts after the call returns, so it is linked
+ // only while the call runs; a returned `running` command must survive it.
+ const controller = new AbortController();
+ const cancel = () => {
+ controller.abort(signal?.reason);
+ // Providers may stop only the launcher, and the command runs in its own process group.
+ void Promise.resolve(
+ sandbox.run({
+ command: `kill -TERM -- -"$(cat ${shellQuote(directory)}/pid 2>/dev/null)" 2>/dev/null; rm -rf ${shellQuote(directory)}`,
+ }),
+ ).catch(() => {});
+ };
+ signal?.addEventListener("abort", cancel, { once: true });
+ try {
+ const child = await sandbox.spawn({
+ abortSignal: controller.signal,
+ command: launchCommand(command, directory),
+ });
+ const finished = Promise.all([
+ readText(child.stdout),
+ readText(child.stderr),
+ child.wait(),
+ ]).then(([stdout, stderr, { exitCode }]) => ({ exitCode, stderr, stdout }));
+ const done = await waitUpTo(finished, BASH_YIELD_SECONDS * 1000);
+ if (done !== undefined) return completed(done.exitCode, done);
+ const running = await claimRunningJob(sandbox, directory, jobId);
+ if (running === undefined) {
+ // No job to claim: the sandbox cannot run background processes, or
+ // the command finished as the yield began.
+ const result = await finished;
+ return completed(result.exitCode, result);
+ }
+ void finished.catch(() => {});
+ return running;
+ } finally {
+ signal?.removeEventListener("abort", cancel);
}
+}
- let stderr = stderrResult.output;
- if (stderrResult.truncated) {
- stderr =
- `[stderr truncated: showing last ${stderrResult.outputLines} of ${stderrResult.totalLines} lines]\n` +
- stderr;
+/**
+ * Only a real `bash` evaluates the launcher, so interpreters without
+ * background processes, such as `just-bash`, run the command directly.
+ */
+function launchCommand(command: string, directory: string): string {
+ return [
+ `if command -v bash >/dev/null 2>&1 && kill -0 "$$" 2>/dev/null; then`,
+ ` set -- ${shellQuote(directory)} ${shellQuote(command)}`,
+ ` eval ${shellQuote(LAUNCHER)}`,
+ `fi`,
+ `eval ${shellQuote(command)}`,
+ ].join("\n");
+}
+
+/** Claims a still-running command for the model and reads its output so far. */
+async function claimRunningJob(
+ sandbox: SandboxSession,
+ directory: string,
+ jobId: string,
+): Promise<BashResult | undefined> {
+ const marker = `eve-bash:${jobId}`;
+ const raw = await sandbox.run({
+ command: [
+ `cd ${shellQuote(directory)} 2>/dev/null && mkdir claimed 2>/dev/null || exit 0`,
+ `kill -USR1 "$(cat launcher)" 2>/dev/null`,
+ `printf '%s %s %s %s\\n' ${marker} "$(cat pid)" "$(($(wc -c < stdout)))" "$(($(wc -c < stderr)))"`,
+ `tail -c ${MAX_OUTPUT_BYTES} stdout`,
+ `tail -c ${MAX_OUTPUT_BYTES} stderr >&2`,
+ ].join("\n"),
+ });
+ // Output a login profile prints comes before the marker.
+ const match = new RegExp(`(?:^|\\n)${marker} (\\d+) (\\d+) (\\d+)\\n`).exec(raw.stdout);
+ if (match === null) return undefined;
+ const pid = Number(match[1]);
+ const stdout = raw.stdout.slice(match.index + match[0].length);
+ const omitted = {
+ stderr: Math.max(0, Number(match[3]) - Buffer.byteLength(raw.stderr)),
+ stdout: Math.max(0, Number(match[2]) - Buffer.byteLength(stdout)),
+ };
+ return {
+ ...formatStreams({ stderr: raw.stderr, stdout }, omitted),
+ message:
+ `The command is still running after ${BASH_YIELD_SECONDS} seconds as process group ${pid}; stdout and stderr show its output so far. ` +
+ `It keeps writing to ${directory}/stdout and ${directory}/stderr, and writes its exit code to ${directory}/exit when it finishes. ` +
+ `Check on it with later commands such as \`tail ${directory}/stdout\` or \`cat ${directory}/exit\`, and stop it with \`kill -- -${pid}\`.`,
+ outputDirectory: directory,
+ pid,
+ status: "running",
+ };
+}
+
+async function readText(stream: ReadableStream<Uint8Array>): Promise<string> {
+ return new TextDecoder().decode(await streamToBuffer(stream));
+}
+
+async function waitUpTo<T>(promise: Promise<T>, ms: number): Promise<T | undefined> {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ return await Promise.race([
+ promise,
+ new Promise<undefined>((resolve) => {
+ timer = setTimeout(() => resolve(undefined), ms);
+ }),
+ ]);
+ } finally {
+ clearTimeout(timer);
}
+}
+
+function completed(exitCode: number, streams: RawStreams): BashResult {
+ return { ...formatStreams(streams), exitCode, status: "completed" };
+}
+function formatStreams(
+ streams: RawStreams,
+ omittedBytes: { readonly stderr: number; readonly stdout: number } = { stderr: 0, stdout: 0 },
+): BashStreams {
+ const stdout = formatStream("stdout", streams.stdout, omittedBytes.stdout);
+ const stderr = formatStream("stderr", streams.stderr, omittedBytes.stderr);
return {
- exitCode: raw.exitCode,
- stderr,
- stdout,
- truncated,
+ stderr: stderr.output,
+ stdout: stdout.output,
+ truncated: stdout.truncated || stderr.truncated,
};
}
-async function runWithDevelopmentSandboxProgress(
- sandbox: SandboxSession,
+function formatStream(
+ name: "stderr" | "stdout",
+ text: string,
+ omittedBytes: number,
+): { readonly output: string; readonly truncated: boolean } {
+ const result = truncateTail(text);
+ if (!result.truncated && omittedBytes === 0) {
+ return { output: result.output, truncated: false };
+ }
+ const note =
+ omittedBytes === 0
+ ? `[${name} truncated: showing last ${result.outputLines} of ${result.totalLines} lines]`
+ : `[${name} truncated: showing last ${result.outputLines} lines; earlier output omitted]`;
+ return { output: `${note}\n${result.output}`, truncated: true };
+}
+
+async function withDevelopmentSandboxProgress<T>(
command: string,
-): Promise<Awaited<ReturnType<SandboxSession["run"]>>> {
- logDevelopmentSandboxCommand(`eve: starting sandbox command: ${formatCommand(command)}`);
+ run: () => Promise<T>,
+): Promise<T> {
if (!isEveDevEnvironment()) {
- return await sandbox.run({ command });
+ return await run();
}
const startedAt = Date.now();
const timer = setInterval(() => {
const elapsedSeconds = Math.round((Date.now() - startedAt) / 1000);
logDevelopmentSandboxCommand(
- `eve: waiting for sandbox command (${elapsedSeconds}s elapsed): ${formatCommand(command)}`,
+ `eve: waiting for sandbox command (${elapsedSeconds}s elapsed): ${command}`,
);
}, 5_000);
timer.unref?.();
try {
- const result = await sandbox.run({ command });
- logDevelopmentSandboxCommand(
- `eve: sandbox command finished (exit ${result.exitCode}): ${formatCommand(command)}`,
- );
- return result;
+ return await run();
} catch (error) {
- logDevelopmentSandboxCommand(`eve: sandbox command failed: ${formatCommand(command)}`);
+ logDevelopmentSandboxCommand(`eve: sandbox command failed: ${command}`);
throw error;
} finally {
clearInterval(timer);
diff --git a/packages/eve/src/execution/sandbox/bindings/just-bash.scenario.test.ts b/packages/eve/src/execution/sandbox/bindings/just-bash.scenario.test.ts
index 144a2c4a6..60eeed82d 100644
--- a/packages/eve/src/execution/sandbox/bindings/just-bash.scenario.test.ts
+++ b/packages/eve/src/execution/sandbox/bindings/just-bash.scenario.test.ts
@@ -9,6 +9,7 @@ import { useTemporaryDirectories } from "#internal/testing/use-temporary-app-roo
import { createJustBashSandboxProvider } from "#execution/sandbox/bindings/just-bash.js";
import { createSandboxProviderHarness } from "#internal/testing/sandbox-provider-harness.js";
import type { JustBashSandboxCreateOptions } from "#public/sandbox/just-bash-sandbox.js";
+import { executeBashOnSandbox } from "#execution/sandbox/bash.js";
import { executeGlobOnSandbox } from "#execution/sandbox/glob-tool.js";
import { executeGrepOnSandbox } from "#execution/sandbox/grep-tool.js";
@@ -174,6 +175,26 @@ describe("just-bash sandbox file API", () => {
expect(result.stdout.trim()).toBe("staging");
});
+ it("runs bash tool commands directly because just-bash cannot host background jobs", async () => {
+ const cacheDirectory = await createTemporaryCacheDirectory("bash-tool");
+ const handle = await createPrewarmedLocalHandle({
+ appRoot: cacheDirectory,
+ sandboxName: "session-bash-tool",
+ });
+
+ const result = await executeBashOnSandbox(handle.sandbox, {
+ command: "echo out; echo err >&2; exit 3",
+ });
+
+ expect(result).toEqual({
+ exitCode: 3,
+ status: "completed",
+ stderr: "err\n",
+ stdout: "out\n",
+ truncated: false,
+ });
+ });
+
it("passes env vars to a process spawned via the public session", async () => {
const cacheDirectory = await createTemporaryCacheDirectory("spawn-env");
const handle = await createPrewarmedLocalHandle({
diff --git a/packages/eve/src/tools/provided/bash.ts b/packages/eve/src/tools/provided/bash.ts
index bf6fe9ce8..6aa12d1bd 100644
--- a/packages/eve/src/tools/provided/bash.ts
+++ b/packages/eve/src/tools/provided/bash.ts
@@ -1,4 +1,8 @@
-import { executeBashOnSandbox, type BashInput } from "#execution/sandbox/bash.js";
+import {
+ BASH_YIELD_SECONDS,
+ executeBashOnSandbox,
+ type BashInput,
+} from "#execution/sandbox/bash.js";
import { toolLabel } from "#tools/tool-label.js";
import { defineTool, type ToolDefinition } from "#tools/definition.js";
import { defineJsonSchema } from "#tools/schema.js";
@@ -7,12 +11,29 @@ export interface BashToolInput {
command: string;
}
-export interface BashToolOutput {
- exitCode: number;
- stderr: string;
- stdout: string;
- truncated: boolean;
-}
+/**
+ * Output of the provided `bash` tool. A command that finishes within 30
+ * seconds is `completed`. A longer command keeps running in the sandbox as
+ * process group `pid` and returns `running` with its output so far; it keeps
+ * writing `stdout`, `stderr`, and finally `exit` files in `outputDirectory`.
+ */
+export type BashToolOutput =
+ | {
+ status: "completed";
+ exitCode: number;
+ stderr: string;
+ stdout: string;
+ truncated: boolean;
+ }
+ | {
+ status: "running";
+ pid: number;
+ outputDirectory: string;
+ message: string;
+ stderr: string;
+ stdout: string;
+ truncated: boolean;
+ };
/**
* Input schema for the provided `bash` tool.
@@ -30,15 +51,34 @@ export const BASH_INPUT_SCHEMA = defineJsonSchema<BashToolInput>({
* Output schema for the provided `bash` tool.
*/
export const BASH_OUTPUT_SCHEMA = defineJsonSchema<BashToolOutput>({
- type: "object",
- properties: {
- exitCode: { type: "number" },
- stderr: { type: "string" },
- stdout: { type: "string" },
- truncated: { type: "boolean" },
- },
- required: ["exitCode", "stderr", "stdout", "truncated"],
- additionalProperties: false,
+ oneOf: [
+ {
+ type: "object",
+ properties: {
+ status: { const: "completed" },
+ exitCode: { type: "number" },
+ stderr: { type: "string" },
+ stdout: { type: "string" },
+ truncated: { type: "boolean" },
+ },
+ required: ["status", "exitCode", "stderr", "stdout", "truncated"],
+ additionalProperties: false,
+ },
+ {
+ type: "object",
+ properties: {
+ status: { const: "running" },
+ pid: { type: "number" },
+ outputDirectory: { type: "string" },
+ message: { type: "string" },
+ stderr: { type: "string" },
+ stdout: { type: "string" },
+ truncated: { type: "boolean" },
+ },
+ required: ["status", "pid", "outputDirectory", "message", "stderr", "stdout", "truncated"],
+ additionalProperties: false,
+ },
+ ],
});
/**
@@ -51,9 +91,11 @@ export const BASH_OUTPUT_SCHEMA = defineJsonSchema<BashToolOutput>({
*/
export const bash: ToolDefinition<BashToolInput, BashToolOutput> = defineTool({
label: { start: (input) => toolLabel("Run", input.command) },
- description: "Execute a shell command in the shared workspace environment.",
+ description: `Execute a shell command in the shared workspace environment. A command still running after ${BASH_YIELD_SECONDS} seconds keeps running in the background and returns status "running" with its output so far and how to check on or stop it.`,
async execute(input, ctx) {
- return await executeBashOnSandbox(await ctx.getSandbox(), input as BashInput);
+ return await executeBashOnSandbox(await ctx.getSandbox(), input as BashInput, {
+ abortSignal: ctx.abortSignal,
+ });
},
inputSchema: BASH_INPUT_SCHEMA,
outputSchema: BASH_OUTPUT_SCHEMA,