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.mdnew file mode 100644index 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.mdindex 2ae1c0083..04116f3d6 100644--- a/docs/concepts/built-in-tools.md+++ b/docs/concepts/built-in-tools.md@@ -38,6 +38,23 @@ eve add tool/bashexport { 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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-installimport 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.tsindex 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.tsindex 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-rooimport { 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.tsindex 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,