feat(core): move timed-out shell commands to the background by default (#63699)

This commit is contained in:
Aiden Cline
2026-11-13 02:21:33 -06:00
committed by GitHub
Unverified
parent 3518013b18
commit b80a3891a4
5 changed files with 158 additions and 256 deletions
-1
View File
@@ -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
+23 -35
View File
@@ -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)
+135 -216
View File
@@ -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 = <A, E, R>(
directory: string,
body: (registry: Tool.Interface) => Effect.Effect<A, E, R>,
autoBackground?: boolean,
) =>
const withSession = <A, E, R>(directory: string, body: (registry: Tool.Interface) => Effect.Effect<A, E, R>) =>
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<unknown>()
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<unknown>()
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")
}),
)
}),
)
-3
View File
@@ -16671,9 +16671,6 @@
"artifacts": {
"type": "boolean"
},
"shell_timeout_background": {
"type": "boolean"
},
"console_watches": {
"type": "boolean"
},
-1
View File
@@ -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: