diff --git a/packages/core/src/tool/plugin/shell.ts b/packages/core/src/tool/plugin/shell.ts index d4f8db5598f..72b51319b59 100644 --- a/packages/core/src/tool/plugin/shell.ts +++ b/packages/core/src/tool/plugin/shell.ts @@ -26,6 +26,7 @@ import { toolFailure } from "../runtime.js" export const name = "shell" export const DEFAULT_TIMEOUT_MS = 2 * 60 * 1_000 +const CODE_MODE_TIMEOUT_MS = 10 * 60 * 1_000 // How long a call the user interrupted waits for its stopped command to exit before settling with the output so far. const INTERRUPT_WAIT = "500 millis" @@ -39,7 +40,7 @@ const OS = : process.platform === "linux" ? "Linux" : process.platform -const description = (shell?: string) => +const description = (shell?: string, codeMode = false) => [ "Execute a shell command and return its output.", ...(shell ? [`Commands run on ${OS} using ${shell}.`] : []), @@ -48,33 +49,55 @@ const description = (shell?: string) => "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 still running after their timeout move to the background.", - "Background commands return immediately, and you will be notified when they complete.", + // Code Mode has no background parameter. + ...(codeMode ? [] : ["Background commands return immediately, and you will be notified when they complete."]), "The current session ID is available in the OPENCODE_SESSION_ID environment variable.", ].join(" ") +const timeoutInput = (foreground: number) => + Schema.optionalKey(NonNegativeInt).annotate({ + description: `Optional timeout in milliseconds (default ${foreground}). When it expires, a foreground command moves to the background and a background command is stopped.`, + }) + 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.`, - }), + timeout: timeoutInput(DEFAULT_TIMEOUT_MS), 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 CodeModeInput = Schema.Struct({ + ...Struct.omit(Input.fields, ["background"]), + timeout: timeoutInput(CODE_MODE_TIMEOUT_MS), +}) + const StructuredOutput = Schema.Struct({ - output: Schema.String, - exitCode: Schema.NullOr(Schema.Number), - wallTimeSeconds: Schema.Number, - outputPath: Schema.optionalKey(Schema.String), - signal: Schema.optionalKey(Schema.String), - shellID: Schema.optionalKey(Schema.String), - pid: Schema.optionalKey(NonNegativeInt), + shellID: Schema.optionalKey(Schema.String).annotate({ + description: + "Present only while the command is still running in the background. You will be notified when it exits. A result without shellID is final.", + }), + exitCode: Schema.NullOr(Schema.Number).annotate({ + description: + "The exit code once the command has exited: 0 means success. null while it is still running, or when a signal ended it.", + }), + signal: Schema.optionalKey(Schema.String).annotate({ description: "The signal that ended the command, if any" }), + output: Schema.String.annotate({ + description: + "Combined stdout and stderr as one string; there are no separate stdout or stderr fields. While shellID is present it is a notice instead, and the output streams to outputPath.", + }), + outputPath: Schema.optionalKey(Schema.String).annotate({ + description: "File with the full output, when output was truncated or the command is running in the background", + }), + pid: Schema.optionalKey(NonNegativeInt).annotate({ + description: "Process ID while the command is running in the background", + }), + wallTimeSeconds: Schema.Number.annotate({ description: "Seconds since the command started" }), }) type Output = ReturnType & { @@ -287,7 +310,6 @@ export const Plugin = { // Internal plugins are not re-run on config changes, so reload the tool transform instead. const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, ctx.tool.reload()) const flags = yield* Flag.Service - const fullCodeMode = () => flags.resolve(loaded.entries).full_codemode.enabled const prepare = Effect.fn("ShellTool.prepare")(function* (invocation: ShellCreateBefore, context: Tool.Context) { const target = yield* access.resolve({ path: invocation.cwd, kind: "directory" }) @@ -351,18 +373,22 @@ export const Plugin = { }) yield* ctx.tool - .transform((editor) => + .transform((editor) => { + const codeMode = flags.resolve(loaded.entries).full_codemode.enabled editor.add({ name, - // With full_codemode, shell is called as `tools.shell` inside `execute` instead of as a direct tool. - options: { codemode: fullCodeMode() }, - description: description(), - input: Input, + // With full_codemode, shell is called as `tools.shell` inside `execute` instead of as a direct tool, and is + // pinned so the Code Mode catalog always lists it, however many other tools there are. + options: codeMode ? { codemode: true, pinned: true } : { codemode: false }, + description: description(undefined, codeMode), + input: codeMode ? CodeModeInput : Input, output: StructuredOutput, execute: (input, context) => { + // Code Mode input has no background parameter. + const background = "background" in input && input.background === true // 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 + const foreground = input.timeout || (codeMode ? CODE_MODE_TIMEOUT_MS : DEFAULT_TIMEOUT_MS) + const timeout = background ? (input.timeout ?? 0) : foreground let finalTimeout = timeout // Uninterruptible from spawning to blocking, so an interrupt cannot orphan a started command. return Effect.uninterruptibleMask((restore) => @@ -385,7 +411,7 @@ export const Plugin = { timeout, shell: yield* compatibleShell, metadata: { sessionID: context.sessionID }, - waited: input.background !== true, + waited: !background, toolCall: { sessionID: context.sessionID, assistantMessageID: context.messageID, @@ -412,7 +438,7 @@ export const Plugin = { ), ) // A foreground timeout moves the command to the background instead of stopping it. - if (input.background !== true) invocation.timeout = 0 + if (!background) invocation.timeout = 0 }), ) yield* context.progress({ shellID: info.id }) @@ -425,7 +451,7 @@ export const Plugin = { // Stopped while the command was starting: stop it now. if (yield* Deferred.isDone(stopped)) return yield* cancelled(info, job.id) - if (input.background === true) { + if (background) { yield* jobs.background(job.id) yield* notifyWhenDone(context.sessionID, job.id, info.id, info.command, settled) return backgroundResult(info, yield* Clock.currentTimeMillis) @@ -482,14 +508,14 @@ export const Plugin = { // Shell spans, including the job that waits for a backgrounded command, name the call that started them. Effect.annotateSpans({ "gen_ai.tool.call.id": context.id, - ...(input.background === true ? { "opencode.shell.background": true } : {}), + ...(background ? { "opencode.shell.background": true } : {}), }), Effect.map((output) => toolResult(output, finalTimeout)), Effect.mapError(toolFailure(`Unable to execute command: ${input.command}`)), ) }, - }), - ) + }) + }) .pipe(Effect.orDie) const hook = (event: SessionHooks["context"]) => diff --git a/packages/core/test/tool-shell.test.ts b/packages/core/test/tool-shell.test.ts index bbc4a19ccf8..97ff4f573dd 100644 --- a/packages/core/test/tool-shell.test.ts +++ b/packages/core/test/tool-shell.test.ts @@ -12,6 +12,7 @@ import { makeGlobalNode, makeLocationNode } from "@opencode/util/effect/app-node import { filesystem } from "@opencode/util/effect/app-node-platform" import { Database } from "@opencode/core/database/database" import { Bus } from "@opencode/core/bus" +import { CodeModeCatalog } from "@opencode/core/codemode/catalog" import { Config } from "@opencode/core/config" import { Environment } from "@opencode/core/environment/index" import { FSUtil } from "@opencode/util/fs-util" @@ -177,9 +178,9 @@ const replacements = [ PersistentPty.node.replace(disabledPersistentPtyLayer), ] satisfies LayerNode.Replacements const productionIt = testEffect(AppNodeBuilder.build(nodes, replacements)) -const it = testEffect( - AppNodeBuilder.build(nodes, [...replacements, PluginSupervisor.node.replace(shellPluginSupervisor)]), -) +const shellLayer = AppNodeBuilder.build(nodes, [...replacements, PluginSupervisor.node.replace(shellPluginSupervisor)]) +const it = testEffect(shellLayer) +const codeModeIt = testEffect(shellLayer.pipe(Layer.provide(Layer.succeed(Flag.Overrides, "full_codemode")))) // On the real process daemon (when its binary is compatible; otherwise this falls back to spawning). const daemonIt = testEffect( AppNodeBuilder.build(nodes, [...daemonReplacements, PluginSupervisor.node.replace(shellPluginSupervisor)]), @@ -890,6 +891,76 @@ describe("ShellTool", () => { }), ) + codeModeIt.live("runs parallel Code Mode shells with the long default and notifies after a shorter timeout", () => + withTempDir((tmp) => { + reset() + return withSession(tmp.path, (registry) => + Effect.gen(function* () { + const snapshot = yield* registry.snapshot() + // Pinned: listed even when the catalog has no room for other tools, with the result contract in the field + // annotations. + const pinned = CodeModeCatalog.summarize(snapshot.codeModeCatalog!, { budget: 0 }).namespaces.flatMap( + (namespace) => namespace.entries, + ) + expect(pinned.map((entry) => entry.path)).toEqual(["shell"]) + expect(pinned[0]!.line).toContain("600000") + expect(pinned[0]!.line).toContain("Execute a shell command and return its output.") + // No background parameter in Code Mode. + expect(pinned[0]!.line).not.toContain("background?: boolean") + expect(pinned[0]!.line).not.toContain("Background commands return immediately") + expect(pinned[0]!.line).toContain("A result without shellID is final") + expect(pinned[0]!.line).toContain("there are no separate stdout or stderr fields") + const timeouts: number[] = [] + const hooks = yield* PluginHooks.Service + yield* hooks.register("shell", "create.before", (event) => + Effect.sync(() => { + timeouts.push(event.timeout) + }), + ) + const bus = yield* Bus.Service + const notice = 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 quick = JSON.stringify({ command: bodyExitCommand }) + const long = JSON.stringify({ command: progressOverflowCommand(6, "release"), timeout: 10 }) + const result = yield* executeTool(registry, { + sessionID, + ...toolIdentity, + call: { + type: "tool-call", + id: "call-parallel-shells", + name: "execute", + input: { code: `return await Promise.all([tools.shell(${quick}), tools.shell(${long})])` }, + }, + }).pipe(Effect.timeout("3 seconds")) + expect(result.status).toBe("completed") + const [completed, running] = JSON.parse(result.output.output) + expect(completed).toEqual({ + output: "body", + exitCode: 7, + wallTimeSeconds: expect.any(Number), + }) + expect(running).toEqual({ + output: expect.stringContaining("did not finish within its timeout of 0.01 seconds"), + exitCode: null, + shellID: expect.stringMatching(/^sh_/), + pid: expect.any(Number), + outputPath: expect.any(String), + wallTimeSeconds: expect.any(Number), + }) + expect(timeouts.toSorted((a, b) => a - b)).toEqual([10, 600_000]) + yield* Effect.promise(() => Bun.write(path.join(tmp.path, "release"), "")) + expect((yield* Fiber.join(notice)).valueOrUndefined?.data.item.payload).toMatchObject({ + text: expect.stringContaining("xxxxxx"), + metadata: { source: "shell", shellID: running.shellID, state: "completed", exit: 0 }, + }) + }), + ) + }), + ) + productionIt.live( "registers and returns real successful output from the active Location", () =>