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: