feat(core): make shell the only Code Mode shell tool, pinned and annotated (#64335)

This commit is contained in:
James Long
2026-11-17 10:28:59 -05:00
committed by GitHub
Unverified
parent 9ca3daec38
commit 301ab45538
2 changed files with 126 additions and 29 deletions
+52 -26
View File
@@ -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<typeof ShellResult.output> & {
@@ -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"]) =>
+74 -3
View File
@@ -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",
() =>