From b80a3891a471f3e67ed35b4530a0a0ca1cadf194 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Fri, 13 Nov 2026 02:21:33 -0600 Subject: [PATCH] feat(core): move timed-out shell commands to the background by default (#63699) --- .../client/src/promise/generated/types.ts | 1 - packages/core/src/tool/plugin/shell.ts | 58 ++- packages/core/test/tool-shell.test.ts | 351 +++++++----------- packages/protocol/openapi.json | 3 - packages/schema/src/config/flag.ts | 1 - 5 files changed, 158 insertions(+), 256 deletions(-) diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index 591a8731ebc..fc8133fb489 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -2593,7 +2593,6 @@ export type ConfigEntry = media_blob?: boolean schedules?: boolean artifacts?: boolean - shell_timeout_background?: boolean console_watches?: boolean mcp_events?: boolean part_rows?: boolean diff --git a/packages/core/src/tool/plugin/shell.ts b/packages/core/src/tool/plugin/shell.ts index 12b434fc957..9357b09e8a7 100644 --- a/packages/core/src/tool/plugin/shell.ts +++ b/packages/core/src/tool/plugin/shell.ts @@ -10,7 +10,6 @@ import { Clock, Deferred, Effect, Fiber, Option, Schema, Struct } from "effect" import { Environment } from "../../environment/index.js" import { Job } from "../../job.js" import { FileAccess } from "../../file-access.js" -import { Flag } from "../../flag.js" import { Permission } from "../../permission.js" import { NonNegativeInt } from "../../schema.js" import { Session } from "../../session.js" @@ -37,7 +36,7 @@ const OS = : process.platform === "linux" ? "Linux" : process.platform -const description = (shell?: string, autoBackground = false) => +const description = (shell?: string) => [ "Execute a shell command and return its output.", ...(shell ? [`Commands run on ${OS} using ${shell}.`] : []), @@ -45,31 +44,24 @@ const description = (shell?: string, autoBackground = false) => "Prefer dedicated tools over shell commands when possible.", "When output is large, the full result is saved to a file and a truncated preview is returned.", "Rely on automatic truncation unless filtering the output is more useful.", - autoBackground - ? "Commands still running after their timeout move to the background." - : "Commands accept an optional timeout, background commands have no timeout by default.", + "Commands still running after their timeout move to the background.", "Background commands return immediately, and you will be notified when they complete.", ].join(" ") -const input = (autoBackground: boolean) => - Schema.Struct({ - command: Schema.String.annotate({ description: "Shell command string to execute" }), - workdir: Schema.optionalKey(Schema.String).annotate({ - description: - "Working directory to execute the command in. Defaults to the current working directory. When possible, avoid changing directories in the command and set the working directory here instead.", - }), - timeout: Schema.optionalKey(NonNegativeInt).annotate({ - description: autoBackground - ? `Optional timeout in milliseconds (default ${DEFAULT_TIMEOUT_MS}). When it expires, a foreground command moves to the background and a background command is stopped.` - : `Timeout in milliseconds. Set to 0 to disable the timeout. Defaults to ${DEFAULT_TIMEOUT_MS} for foreground commands. Background commands have no timeout by default.`, - }), - background: Schema.optionalKey(Schema.Boolean).annotate({ - description: - "Run the command in the background and return immediately (useful for dev servers and long-running builds). You do not need to use '&' at the end of the command when using this parameter. You will be notified when it completes. DO NOT poll for completion.", - }), - }) - -export const Input = input(false) +export const Input = Schema.Struct({ + command: Schema.String.annotate({ description: "Shell command string to execute" }), + workdir: Schema.optionalKey(Schema.String).annotate({ + description: + "Working directory to execute the command in. Defaults to the current working directory. When possible, avoid changing directories in the command and set the working directory here instead.", + }), + timeout: Schema.optionalKey(NonNegativeInt).annotate({ + description: `Optional timeout in milliseconds (default ${DEFAULT_TIMEOUT_MS}). When it expires, a foreground command moves to the background and a background command is stopped.`, + }), + background: Schema.optionalKey(Schema.Boolean).annotate({ + description: + "Run the command in the background and return immediately (useful for dev servers and long-running builds). You do not need to use '&' at the end of the command when using this parameter. You will be notified when it completes. DO NOT poll for completion.", + }), +}) const StructuredOutput = Schema.Struct({ output: Schema.String, @@ -287,7 +279,6 @@ export const Plugin = { const shellSelect = yield* ShellSelect.Service const compatibleShell = shellSelect.resolve({ priority: "compat" }) const permission = yield* Permission.Service - const autoBackground = yield* Flag.enabled("shell_timeout_background") const prepare = Effect.fn("ShellTool.prepare")(function* (invocation: ShellCreateBefore, context: Tool.Context) { const target = yield* access.resolve({ path: invocation.cwd, kind: "directory" }) @@ -355,15 +346,12 @@ export const Plugin = { editor.add({ name, options: { codemode: false }, - description: description(undefined, autoBackground), - input: input(autoBackground), + description: description(), + input: Input, output: StructuredOutput, execute: (input, context) => { - // With timeout backgrounding, a foreground timeout of 0 falls back to the default so a call can't block - // until the command exits. - const foreground = autoBackground - ? input.timeout || DEFAULT_TIMEOUT_MS - : (input.timeout ?? DEFAULT_TIMEOUT_MS) + // A foreground timeout of 0 falls back to the default, so a call can't block until the command exits. + const foreground = input.timeout || DEFAULT_TIMEOUT_MS const timeout = input.background === true ? (input.timeout ?? 0) : foreground let finalTimeout = timeout // Uninterruptible from spawning to blocking, so an interrupt cannot orphan a started command. @@ -414,7 +402,7 @@ export const Plugin = { ), ) // A foreground timeout moves the command to the background instead of stopping it. - if (autoBackground && input.background !== true) invocation.timeout = 0 + if (input.background !== true) invocation.timeout = 0 }), ) yield* context.progress({ shellID: info.id }) @@ -435,7 +423,7 @@ export const Plugin = { const waiting = jobs.block({ id: job.id, sessionID: context.sessionID }) const blocked = - autoBackground && finalTimeout > 0 + finalTimeout > 0 ? waiting.pipe( Effect.timeoutOption(finalTimeout), Effect.flatMap((result) => @@ -498,7 +486,7 @@ export const Plugin = { Effect.gen(function* () { const tool = event.tools[name] if (!tool) return - tool.description = description(ShellSelect.name(yield* compatibleShell), autoBackground) + tool.description = description(ShellSelect.name(yield* compatibleShell)) }) yield* ctx.session.hook("context", hook) yield* ctx.session.hook("compaction", hook) diff --git a/packages/core/test/tool-shell.test.ts b/packages/core/test/tool-shell.test.ts index efeadb183de..881dc514e00 100644 --- a/packages/core/test/tool-shell.test.ts +++ b/packages/core/test/tool-shell.test.ts @@ -278,19 +278,8 @@ const progressOverflowCommand = (bytes: number, release: string) => ? `[Console]::Out.Write(('x' * ${bytes})); while (!(Test-Path -LiteralPath '${release}')) { Start-Sleep -Milliseconds 50 }` : `head -c ${bytes} /dev/zero | tr '\\0' 'x'; while [ ! -e '${release}' ]; do sleep 0.05; done` -const withSession = ( - directory: string, - body: (registry: Tool.Interface) => Effect.Effect, - autoBackground?: boolean, -) => +const withSession = (directory: string, body: (registry: Tool.Interface) => Effect.Effect) => Effect.gen(function* () { - if (autoBackground !== undefined) - yield* Effect.promise(() => - Bun.write( - path.join(directory, "opencode.json"), - JSON.stringify({ experimental: { shell_timeout_background: autoBackground } }), - ), - ) const sessions = yield* Session.Service const location = Location.Ref.make({ directory: AbsolutePath.make(directory) }) yield* sessions.create({ @@ -1390,125 +1379,84 @@ describe("ShellTool", () => { { timeout: 15_000 }, ) - it.live( - "reports partial output, the timeout and the exit code when a foreground command times out", - () => - withTempDir((tmp) => { - reset() - // Long enough for the command to print before it is killed. - const timeout = isWindows ? 5_000 : 500 - return withSession(tmp.path, (registry) => - executeTool(registry, call({ command: startingCommand, timeout }, "call-foreground-timeout")), - ).pipe( - Effect.andThen((settled) => - Effect.sync(() => { - expect(settled.metadata).toMatchObject({ timeout: true }) - expect(settled.output).not.toHaveProperty("timeout") - expect(settled.output).toMatchObject({ - exitCode: settled.metadata?.exit ?? null, - }) - if (!isWindows) expect(settled.output.signal).toBe("SIGTERM") - expect(settled.content).toEqual([ - { type: "text", text: "server starting" }, - Expected.text( - expect.stringMatching( - new RegExp( - `^Command timed out after ${timeout / 1_000} seconds\\. If it needs longer and isn't waiting for input, rerun with a larger timeout\\.\\nExit code: ${timedOutExit}$`, - ), - ), - ), - ]) - }), - ), - ) - }), - { timeout: 15_000 }, - ) - it.live("moves a foreground timeout to the background and delivers its original process result once", () => withTempDir((tmp) => { reset() - return withSession( - tmp.path, - (registry) => - Effect.gen(function* () { - const bus = yield* Bus.Service - const notices = yield* Queue.unbounded() - yield* bus.subscribe(SessionEvent.InboxEnqueued).pipe( - Stream.filter((event) => event.data.sessionID === sessionID && event.data.item.type === "synthetic"), - Stream.runForEach((event) => Queue.offer(notices, event.data.item.payload)), - Effect.forkScoped({ startImmediately: true }), - ) - const result = yield* executeTool( - registry, - call({ command: progressOverflowCommand(6, "release"), timeout: 10 }, "call-auto-background"), - ) - const id = ID.make(String(result.metadata?.shellID)) - const shell = yield* Shell.Service - const info = yield* shell.get(id) - expect(result.status).toBe("completed") - expect(info.pid).toBeGreaterThan(0) - expect(result.metadata).toMatchObject({ - status: "running", - shellID: id, - pid: info.pid, - truncated: false, - }) - expect(result.output).toEqual({ - shellID: id, - pid: info.pid, - outputPath: info.file, - exitCode: null, - output: expect.any(String), - wallTimeSeconds: expect.any(Number), - }) - expect(result.output.wallTimeSeconds).toBeGreaterThanOrEqual(0.01) - expect(result.metadata).not.toHaveProperty("timeout") - expect(result.content?.[0]).toEqual({ - type: "text", - text: `Command moved to the background (shell ID: ${id}).\nPID: ${info.pid}\nOutput is streaming to: ${info.file}\n\nThe command did not finish within its timeout of 0.01 seconds and was moved to the background. Do not start another copy while it is running.`, - }) - expect(info.status).toBe("running") - expect((yield* shell.list()).map((item) => item.id)).toEqual([id]) + return withSession(tmp.path, (registry) => + Effect.gen(function* () { + const bus = yield* Bus.Service + const notices = yield* Queue.unbounded() + yield* bus.subscribe(SessionEvent.InboxEnqueued).pipe( + Stream.filter((event) => event.data.sessionID === sessionID && event.data.item.type === "synthetic"), + Stream.runForEach((event) => Queue.offer(notices, event.data.item.payload)), + Effect.forkScoped({ startImmediately: true }), + ) + const result = yield* executeTool( + registry, + call({ command: progressOverflowCommand(6, "release"), timeout: 10 }, "call-auto-background"), + ) + const id = ID.make(String(result.metadata?.shellID)) + const shell = yield* Shell.Service + const info = yield* shell.get(id) + expect(result.status).toBe("completed") + expect(info.pid).toBeGreaterThan(0) + expect(result.metadata).toMatchObject({ + status: "running", + shellID: id, + pid: info.pid, + truncated: false, + }) + expect(result.output).toEqual({ + shellID: id, + pid: info.pid, + outputPath: info.file, + exitCode: null, + output: expect.any(String), + wallTimeSeconds: expect.any(Number), + }) + expect(result.output.wallTimeSeconds).toBeGreaterThanOrEqual(0.01) + expect(result.metadata).not.toHaveProperty("timeout") + expect(result.content?.[0]).toEqual({ + type: "text", + text: `Command moved to the background (shell ID: ${id}).\nPID: ${info.pid}\nOutput is streaming to: ${info.file}\n\nThe command did not finish within its timeout of 0.01 seconds and was moved to the background. Do not start another copy while it is running.`, + }) + expect(info.status).toBe("running") + expect((yield* shell.list()).map((item) => item.id)).toEqual([id]) - yield* Effect.promise(() => Bun.write(path.join(tmp.path, "release"), "")) - const finished = yield* shell.wait(id) - expect(finished).toMatchObject({ - status: "exited", + yield* Effect.promise(() => Bun.write(path.join(tmp.path, "release"), "")) + const finished = yield* shell.wait(id) + expect(finished).toMatchObject({ + status: "exited", + exit: 0, + pid: info.pid, + }) + expect(yield* Queue.take(notices)).toMatchObject({ + text: expect.stringContaining("xxxxxx"), + metadata: { + source: "shell", + shellID: id, + state: "completed", exit: 0, - pid: info.pid, - }) - expect(yield* Queue.take(notices)).toMatchObject({ - text: expect.stringContaining("xxxxxx"), - metadata: { - source: "shell", - shellID: id, - state: "completed", - exit: 0, - }, - }) - expect(yield* Queue.size(notices)).toBe(0) - expect(yield* shell.list()).toEqual([]) - }), - true, + }, + }) + expect(yield* Queue.size(notices)).toBe(0) + expect(yield* shell.list()).toEqual([]) + }), ) }), ) - it.live("returns a fast foreground result directly with timeout backgrounding enabled", () => + it.live("returns a fast foreground result directly", () => withTempDir((tmp) => { reset() - return withSession( - tmp.path, - (registry) => - Effect.gen(function* () { - const result = yield* executeTool(registry, call({ command: helloCommand, timeout: 10_000 })) - expect(result.metadata).toMatchObject({ status: "completed", exit: 0 }) - expect(result.content).toEqual([{ type: "text", text: "hello" }]) - const jobs = yield* Job.Service - expect(yield* jobs.runningBackground).toEqual([]) - }), - true, + return withSession(tmp.path, (registry) => + Effect.gen(function* () { + const result = yield* executeTool(registry, call({ command: helloCommand, timeout: 10_000 })) + expect(result.metadata).toMatchObject({ status: "completed", exit: 0 }) + expect(result.content).toEqual([{ type: "text", text: "hello" }]) + const jobs = yield* Job.Service + expect(yield* jobs.runningBackground).toEqual([]) + }), ) }), ) @@ -1516,62 +1464,56 @@ describe("ShellTool", () => { it.live("preserves a timeout-promoted command's eventual failure", () => withTempDir((tmp) => { reset() - return withSession( - tmp.path, - (registry) => - Effect.gen(function* () { - const bus = yield* Bus.Service - const admitted = yield* bus.subscribe(SessionEvent.InboxEnqueued).pipe( - Stream.filter((event) => event.data.sessionID === sessionID && event.data.item.type === "synthetic"), - Stream.runHead, - Effect.forkScoped({ startImmediately: true }), - ) - const result = yield* executeTool( - registry, - call({ command: `${progressOverflowCommand(0, "release")}; exit 7`, timeout: 10 }), - ) - const id = ID.make(String(result.metadata?.shellID)) - yield* Effect.promise(() => Bun.write(path.join(tmp.path, "release"), "")) - const shell = yield* Shell.Service - expect(yield* shell.wait(id)).toMatchObject({ status: "exited", exit: 7 }) - expect((yield* Fiber.join(admitted)).valueOrUndefined?.data.item.payload).toMatchObject({ - text: expect.stringContaining("Exit code: 7"), - metadata: { source: "shell", shellID: id, state: "completed", exit: 7 }, - }) - }), - true, + return withSession(tmp.path, (registry) => + Effect.gen(function* () { + const bus = yield* Bus.Service + const admitted = yield* bus.subscribe(SessionEvent.InboxEnqueued).pipe( + Stream.filter((event) => event.data.sessionID === sessionID && event.data.item.type === "synthetic"), + Stream.runHead, + Effect.forkScoped({ startImmediately: true }), + ) + const result = yield* executeTool( + registry, + call({ command: `${progressOverflowCommand(0, "release")}; exit 7`, timeout: 10 }), + ) + const id = ID.make(String(result.metadata?.shellID)) + yield* Effect.promise(() => Bun.write(path.join(tmp.path, "release"), "")) + const shell = yield* Shell.Service + expect(yield* shell.wait(id)).toMatchObject({ status: "exited", exit: 7 }) + expect((yield* Fiber.join(admitted)).valueOrUndefined?.data.item.payload).toMatchObject({ + text: expect.stringContaining("Exit code: 7"), + metadata: { source: "shell", shellID: id, state: "completed", exit: 7 }, + }) + }), ) }), ) - it.effect("treats a foreground timeout of zero as the default timeout with timeout backgrounding enabled", () => + it.effect("treats a foreground timeout of zero as the default timeout", () => withTempDir((tmp) => { reset() - return withSession( - tmp.path, - (registry) => - Effect.gen(function* () { - const running = yield* executeTool( - registry, - call({ command: progressOverflowCommand(0, "release"), timeout: 0 }, "call-zero-timeout"), - ).pipe(Effect.forkScoped({ startImmediately: true })) - // The wait starts only after the command spawns, so keep advancing the clock until the call returns. - const result = yield* Fiber.join(running).pipe( - Effect.raceFirst( - Effect.forever(Effect.promise(() => Bun.sleep(20)).pipe(Effect.andThen(TestClock.adjust("2 minutes")))), - ), - ) - expect(result.content?.[0]).toMatchObject({ - type: "text", - text: expect.stringContaining("did not finish within its timeout of 120 seconds"), - }) - const id = ID.make(String(result.metadata?.shellID)) - const shell = yield* Shell.Service - expect((yield* shell.get(id)).status).toBe("running") - yield* Effect.promise(() => Bun.write(path.join(tmp.path, "release"), "")) - expect(yield* shell.wait(id)).toMatchObject({ status: "exited", exit: 0 }) - }), - true, + return withSession(tmp.path, (registry) => + Effect.gen(function* () { + const running = yield* executeTool( + registry, + call({ command: progressOverflowCommand(0, "release"), timeout: 0 }, "call-zero-timeout"), + ).pipe(Effect.forkScoped({ startImmediately: true })) + // The wait starts only after the command spawns, so keep advancing the clock until the call returns. + const result = yield* Fiber.join(running).pipe( + Effect.raceFirst( + Effect.forever(Effect.promise(() => Bun.sleep(20)).pipe(Effect.andThen(TestClock.adjust("2 minutes")))), + ), + ) + expect(result.content?.[0]).toMatchObject({ + type: "text", + text: expect.stringContaining("did not finish within its timeout of 120 seconds"), + }) + const id = ID.make(String(result.metadata?.shellID)) + const shell = yield* Shell.Service + expect((yield* shell.get(id)).status).toBe("running") + yield* Effect.promise(() => Bun.write(path.join(tmp.path, "release"), "")) + expect(yield* shell.wait(id)).toMatchObject({ status: "exited", exit: 0 }) + }), ) }), ) @@ -1579,58 +1521,35 @@ describe("ShellTool", () => { it.live("still cancels a timeout-promoted shell through its existing job handle", () => withTempDir((tmp) => { reset() - return withSession( - tmp.path, - (registry) => - Effect.gen(function* () { - const result = yield* executeTool( - registry, - call({ command: progressOverflowCommand(0, "release"), timeout: 10 }), - ) - const id = ID.make(String(result.metadata?.shellID)) - const shell = yield* Shell.Service - expect((yield* shell.get(id)).status).toBe("running") - const jobs = yield* Job.Service - expect(yield* jobs.cancel(id)).toMatchObject({ id, status: "cancelled" }) - // Cancelling stops the command and keeps it, output file included. - expect((yield* shell.wait(id)).status).toBe("killed") - expect(yield* shell.list()).toEqual([]) - }), - true, + return withSession(tmp.path, (registry) => + Effect.gen(function* () { + const result = yield* executeTool( + registry, + call({ command: progressOverflowCommand(0, "release"), timeout: 10 }), + ) + const id = ID.make(String(result.metadata?.shellID)) + const shell = yield* Shell.Service + expect((yield* shell.get(id)).status).toBe("running") + const jobs = yield* Job.Service + expect(yield* jobs.cancel(id)).toMatchObject({ id, status: "cancelled" }) + // Cancelling stops the command and keeps it, output file included. + expect((yield* shell.wait(id)).status).toBe("killed") + expect(yield* shell.list()).toEqual([]) + }), ) }), ) - it.live("preserves explicit background timeout limits with timeout backgrounding disabled", () => + it.live("stops a background command when its explicit timeout expires", () => withTempDir((tmp) => { reset() - return withSession( - tmp.path, - (registry) => - Effect.gen(function* () { - const result = yield* executeTool(registry, call({ command: idleCommand, background: true, timeout: 10 })) - const id = ID.make(String(result.metadata?.shellID)) - const shell = yield* Shell.Service - expect((yield* shell.wait(id)).status).toBe("timeout") - }), - false, - ) - }), - ) - - it.live("stops a background command when its explicit timeout expires with timeout backgrounding enabled", () => - withTempDir((tmp) => { - reset() - return withSession( - tmp.path, - (registry) => - Effect.gen(function* () { - const result = yield* executeTool(registry, call({ command: idleCommand, background: true, timeout: 50 })) - const id = ID.make(String(result.metadata?.shellID)) - const shell = yield* Shell.Service - expect((yield* shell.wait(id)).status).toBe("timeout") - }), - true, + return withSession(tmp.path, (registry) => + Effect.gen(function* () { + const result = yield* executeTool(registry, call({ command: idleCommand, background: true, timeout: 50 })) + const id = ID.make(String(result.metadata?.shellID)) + const shell = yield* Shell.Service + expect((yield* shell.wait(id)).status).toBe("timeout") + }), ) }), ) diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index 61d2670118d..8a95ff085ce 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -16671,9 +16671,6 @@ "artifacts": { "type": "boolean" }, - "shell_timeout_background": { - "type": "boolean" - }, "console_watches": { "type": "boolean" }, diff --git a/packages/schema/src/config/flag.ts b/packages/schema/src/config/flag.ts index f82cb806850..3111d6f06bf 100644 --- a/packages/schema/src/config/flag.ts +++ b/packages/schema/src/config/flag.ts @@ -15,7 +15,6 @@ export const registry = { media_blob: "Store new session media once in a deduplicated blob table instead of inline in every message row.", schedules: "Enable experimental scheduled tasks that wake a session with a prompt.", artifacts: "Enable experimental artifacts backed by pluggable providers.", - shell_timeout_background: "Move foreground shell commands to the background when their timeout expires.", console_watches: "Watch Slack threads, GitHub pull requests, issues, commits and Actions runs, and the workspace's MCP servers' events through OpenCode Console, and wake sessions when they change.", mcp_events: