From 966168800cb80f336cb4267f0484f193a15f1292 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Tue, 10 Nov 2026 10:31:10 -0600 Subject: [PATCH] feat(core): background shell commands when their timeout expires (#63024) --- .../client/src/promise/generated/types.ts | 1 + packages/core/src/tool/plugin/shell.ts | 61 ++++-- packages/core/test/tool-shell.test.ts | 207 +++++++++++++++++- packages/protocol/openapi.json | 3 + packages/schema/src/config/flag.ts | 1 + 5 files changed, 256 insertions(+), 17 deletions(-) diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index a34feed23e8..d2a2b2d4a19 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -2552,6 +2552,7 @@ export type ConfigEntry = schedules?: boolean artifacts?: boolean codemode_vm?: boolean + shell_timeout_background?: boolean console_watches?: boolean part_rows?: boolean image_generate?: boolean | { model?: string | { providerID: string; model: string; variant?: string } } diff --git a/packages/core/src/tool/plugin/shell.ts b/packages/core/src/tool/plugin/shell.ts index 697b5754a63..2590c96be98 100644 --- a/packages/core/src/tool/plugin/shell.ts +++ b/packages/core/src/tool/plugin/shell.ts @@ -5,10 +5,11 @@ import type { Context } from "@opencode/plugin/effect/plugin" import type { SessionHooks } from "@opencode/plugin/effect/session" import type { ShellCreateBefore } from "@opencode/plugin/effect/shell" import type { Tool } from "@opencode/schema/tool" -import { Deferred, Effect, Schema, Scope } from "effect" +import { Deferred, Effect, Option, Schema, Scope } 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" @@ -31,7 +32,7 @@ const OS = : process.platform === "linux" ? "Linux" : process.platform -const description = (shell?: string) => +const description = (shell?: string, autoBackground = false) => [ "Execute a shell command and return its output.", ...(shell ? [`Commands run on ${OS} using ${shell}.`] : []), @@ -39,7 +40,9 @@ const description = (shell?: string) => "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.", - "Commands accept an optional timeout, background commands have no timeout by default.", + autoBackground + ? "Commands still running after their timeout move to the background." + : "Commands accept an optional timeout, background commands have no timeout by default.", "Background commands return immediately, and you will be notified when they complete.", ].join(" ") @@ -62,6 +65,7 @@ const StructuredOutput = Schema.Struct({ exit: Schema.optionalKey(Schema.Number), signal: Schema.optionalKey(Schema.String), shellID: Schema.optionalKey(Schema.String), + pid: Schema.optionalKey(NonNegativeInt), truncated: Schema.Boolean, timeout: Schema.optionalKey(Schema.Boolean), }) @@ -87,13 +91,25 @@ const toolResult = (output: Output, timeout?: number) => { status: output.status, ...ShellResult.metadata(output), ...(output.shellID !== undefined ? { shellID: output.shellID } : {}), + ...(output.pid !== undefined ? { pid: output.pid } : {}), }, } } -const backgroundResult = (shellID: string, file: string) => ({ - output: `Command moved to the background (shell ID: ${shellID}).\nOutput is streaming to: ${file}`, - shellID, +const backgroundResult = (info: ShellResult.Result["info"], timeout?: number) => ({ + output: [ + `Command moved to the background (shell ID: ${info.id}).`, + ...(info.pid === undefined ? [] : [`PID: ${info.pid}`]), + `Output is streaming to: ${info.file}`, + ...(timeout === undefined + ? [] + : [ + "", + `The command did not finish within its timeout of ${timeout / 1_000} seconds and was moved to the background. Do not start another copy while it is running.`, + ]), + ].join("\n"), + shellID: info.id, + ...(info.pid === undefined ? {} : { pid: info.pid }), truncated: false, status: "running" as const, }) @@ -110,6 +126,7 @@ 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" }) @@ -180,7 +197,7 @@ export const Plugin = { editor.add({ name, options: { codemode: false }, - description: description(), + description: description(undefined, autoBackground), input: Input, output: Output, execute: (input, context) => { @@ -202,6 +219,7 @@ export const Plugin = { invocation.env.AI_AGENT ||= "opencode" invocation.env.OPENCODE_SESSION_ID = context.sessionID finalTimeout = yield* prepare(invocation, context) + if (autoBackground) invocation.timeout = 0 }), ) yield* context.progress({ shellID: info.id }) @@ -234,17 +252,34 @@ export const Plugin = { if (input.background === true) { yield* jobs.background(job.id) yield* notifyWhenDone(context.sessionID, job.id, info.id, info.command, settled) - return backgroundResult(info.id, info.file) + return backgroundResult(info) } - const result = yield* jobs - .block({ id: job.id, sessionID: context.sessionID }) - .pipe(Effect.onInterrupt(() => jobs.cancel(job.id).pipe(Effect.ignore))) + const waiting = jobs.block({ id: job.id, sessionID: context.sessionID }) + const result = yield* ( + autoBackground && finalTimeout > 0 + ? waiting.pipe( + Effect.timeoutOption(finalTimeout), + Effect.flatMap((result) => + Option.isSome(result) + ? Effect.succeed(result.value) + : jobs + .background(job.id) + .pipe( + Effect.map((info) => + info ? { type: "backgrounded" as const, info, timedOut: true } : undefined, + ), + ), + ), + ) + : waiting + ).pipe(Effect.onInterrupt(() => jobs.cancel(job.id).pipe(Effect.ignore))) if (result?.type === "backgrounded") { yield* shell.timeout(info.id, 0) + const elapsed = "timedOut" in result ? finalTimeout : undefined finalTimeout = 0 yield* notifyWhenDone(context.sessionID, job.id, info.id, info.command, settled) - return backgroundResult(info.id, info.file) + return backgroundResult(info, elapsed) } if (result?.info.status === "error") return yield* Effect.fail(new Error(result.info.error ?? "Command failed")) @@ -271,7 +306,7 @@ export const Plugin = { Effect.gen(function* () { const tool = event.tools[name] if (!tool) return - tool.description = description(ShellSelect.name(yield* compatibleShell)) + tool.description = description(ShellSelect.name(yield* compatibleShell), autoBackground) }) 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 09a4ed55b33..8d1ccd0c09e 100644 --- a/packages/core/test/tool-shell.test.ts +++ b/packages/core/test/tool-shell.test.ts @@ -4,6 +4,7 @@ import os from "os" import path from "path" import { describe, expect } from "bun:test" import { Cause, Deferred, Duration, Effect, Exit, Fiber, Layer, Queue, Scope, Stream, Tracer } from "effect" +import { TestClock } from "effect/testing" import { Money } from "@opencode/schema/money" import { AppNodeBuilder } from "@opencode/core/effect/app-node-builder" import { LayerNode } from "@opencode/util/effect/layer-node" @@ -17,6 +18,7 @@ import { FSUtil } from "@opencode/util/fs-util" import { Global } from "@opencode/util/global" import { Location } from "@opencode/core/location" import { FileAccess } from "@opencode/core/file-access" +import { Flag } from "@opencode/core/flag" import { LocationServiceMap } from "@opencode/core/location-service-map" import { Model } from "@opencode/core/model" import { Provider } from "@opencode/core/provider" @@ -134,6 +136,7 @@ const shellPluginSupervisor = makeLocationNode({ Config.node, Environment.node, FileAccess.node, + Flag.node, Permission.node, Session.node, Job.node, @@ -214,8 +217,19 @@ 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) => +const withSession = ( + directory: string, + body: (registry: Tool.Interface) => Effect.Effect, + autoBackground?: boolean, +) => 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({ @@ -1179,6 +1193,7 @@ describe("ShellTool", () => { deps: [ Environment.node, FileAccess.node, + Flag.node, Permission.node, Session.node, Job.node, @@ -1334,6 +1349,187 @@ describe("ShellTool", () => { { 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).toMatchObject({ shellID: id, pid: info.pid }) + 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"), "")) + expect(yield* shell.wait(id)).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 }, + }) + expect(yield* Queue.size(notices)).toBe(0) + expect(yield* shell.list()).toEqual([]) + }), + true, + ) + }), + ) + + it.live("returns a fast foreground result directly with timeout backgrounding enabled", () => + 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, + ) + }), + ) + + 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, + ) + }), + ) + + it.live("keeps timeout zero as an unbounded foreground wait", () => + withTempDir((tmp) => { + reset() + return withSession( + tmp.path, + (registry) => + Effect.gen(function* () { + const result = yield* executeTool(registry, call({ command: bodyExitCommand, timeout: 0 })) + expect(result.metadata).toMatchObject({ status: "completed", exit: 7 }) + expect(result.metadata).not.toHaveProperty("timeout") + expect(result.content).toEqual([ + { type: "text", text: "body" }, + { type: "text", text: "Exit code: 7" }, + ]) + const jobs = yield* Job.Service + expect(yield* jobs.runningBackground).toEqual([]) + }), + true, + ) + }), + ) + + 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" }) + expect(yield* shell.list()).toEqual([]) + }), + true, + ) + }), + ) + + it.live("preserves explicit background timeout limits with timeout backgrounding disabled", () => + 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.effect("ignores explicit background timeouts with timeout backgrounding enabled", () => + withTempDir((tmp) => { + reset() + return withSession( + tmp.path, + (registry) => + Effect.gen(function* () { + const result = yield* executeTool( + registry, + call({ command: progressOverflowCommand(0, "release"), background: true, timeout: 10 }), + ) + const id = ID.make(String(result.metadata?.shellID)) + const shell = yield* Shell.Service + yield* TestClock.adjust("1 second") + 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, + ) + }), + ) + it.live( "truncates the model view and points at the saved output file when output overflows", () => @@ -1543,7 +1739,7 @@ describe("ShellTool", () => { }), ) - it.live("returns the shell id for a background command", () => + it.live("returns the shell id and PID for a background command", () => withTempDir((tmp) => { reset() return withSession(tmp.path, (registry) => @@ -1563,10 +1759,13 @@ describe("ShellTool", () => { if (!shellID) return const id = ID.make(shellID) const info = yield* shell.get(id) + expect(info.pid).toBeGreaterThan(0) + expect(settled.metadata).toMatchObject({ pid: info.pid }) + expect(settled.output).toMatchObject({ shellID, pid: info.pid }) expect(settled.content).toEqual([ { type: "text", - text: `Command moved to the background (shell ID: ${shellID}).\nOutput is streaming to: ${info.file}`, + text: `Command moved to the background (shell ID: ${shellID}).\nPID: ${info.pid}\nOutput is streaming to: ${info.file}`, }, { type: "text", @@ -1840,7 +2039,7 @@ describe("ShellTool", () => { const info = yield* shell.get(id) expect(settled.content?.[0]).toEqual({ type: "text", - text: `Command moved to the background (shell ID: ${shellID}).\nOutput is streaming to: ${info.file}`, + text: `Command moved to the background (shell ID: ${shellID}).\nPID: ${info.pid}\nOutput is streaming to: ${info.file}`, }) expect(settled.content?.[1]).toEqual({ type: "text", diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index 116829325d3..85e5c6e33a0 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -16666,6 +16666,9 @@ "codemode_vm": { "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 dc296f9c660..4c06ea3b0ca 100644 --- a/packages/schema/src/config/flag.ts +++ b/packages/schema/src/config/flag.ts @@ -16,6 +16,7 @@ export const registry = { schedules: "Enable experimental scheduled tasks that wake a session with a prompt.", artifacts: "Enable experimental artifacts backed by pluggable providers.", codemode_vm: "Run the Code Mode execute tool on the experimental bytecode VM instead of the legacy interpreter.", + 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.", } as const satisfies Record