Repository navigation
Expand file tree
/
Copy pathshell.ts
More file actions
507 lines (481 loc) · 22.9 KB
/
Copy pathshell.ts
File metadata and controls
507 lines (481 loc) · 22.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
export * as ShellTool from "./shell.js"
import { ToolFailure } from "@opencode/ai/effect"
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 { Shell as ShellSchema } from "@opencode/schema/shell"
import type { Tool } from "@opencode/schema/tool"
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"
import { SessionMessage } from "../../session/message.js"
import { SessionSchema } from "../../session/schema.js"
import { Shell } from "../../shell.js"
import { ShellParse } from "../../shell/parse.js"
import { ShellSelect } from "../../shell/select.js"
import { ShellResult } from "../../shell/result.js"
import { toolFailure } from "../runtime.js"
export const name = "shell"
export const DEFAULT_TIMEOUT_MS = 2 * 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"
const BACKGROUND_INSTRUCTION =
"You will be notified automatically when the command finishes. The notification will include the command's output. Unless the user explicitly asks otherwise, DO NOT poll for completion, even if you need the final result to continue. Repeatedly sleeping and reading or searching the output file is polling, not useful work. You may read the current output if it lets you do useful work now, but do not repeatedly check it while waiting for the command to finish. Keep working on anything that does not depend on the result. If you have nothing else to do, end your response; you will be resumed automatically when the command finishes."
const OS =
process.platform === "darwin"
? "macOS"
: process.platform === "win32"
? "Windows"
: process.platform === "linux"
? "Linux"
: process.platform
const description = (shell?: string, autoBackground = false) =>
[
"Execute a shell command and return its output.",
...(shell ? [`Commands run on ${OS} using ${shell}.`] : []),
"Quote file paths containing spaces or special characters.",
"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.",
"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)
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),
})
type Output = ReturnType<typeof ShellResult.output> & {
status: "completed" | "running"
wallTimeSeconds: number
outputPath?: string
shellID?: string
pid?: number
}
const resultMessages = (output: Output, timeout?: number) => {
const notice = output.status === "running" ? BACKGROUND_INSTRUCTION : ShellResult.notice(output, timeout)
return [...(output.output ? [output.output] : []), ...(notice ? [notice] : [])]
}
const toolResult = (output: Output, timeout?: number) => {
return {
output: {
...Struct.omit(output, ["exit", "status", "truncated", "timeout", "killed"]),
exitCode: output.exit ?? null,
},
content: resultMessages(output, timeout).map((text) => ({
type: "text" as const,
text,
})),
metadata: {
status: output.status,
...ShellResult.metadata(output),
...(output.shellID !== undefined ? { shellID: output.shellID } : {}),
...(output.pid !== undefined ? { pid: output.pid } : {}),
},
}
}
const wallTimeSeconds = (time: ShellSchema.Time, end: number) => Math.max(0, end - time.started) / 1_000
const backgroundText = (info: ShellSchema.Info, timeout?: number) =>
[
`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")
const backgroundResult = (info: ShellSchema.Info, now: number, timeout?: number) => ({
output: backgroundText(info, timeout),
wallTimeSeconds: wallTimeSeconds(info.time, now),
shellID: info.id,
outputPath: info.file,
...(info.pid === undefined ? {} : { pid: info.pid }),
truncated: false,
status: "running" as const,
})
// Tells the session how a background command ended, once its job settles.
const notify = Effect.fnUntraced(function* (
sessions: Pick<Session.Interface, "synthetic">,
jobs: Job.Interface,
input: {
readonly sessionID: SessionSchema.ID
readonly id: string
readonly shellID: string
readonly command: string
readonly settled: Deferred.Deferred<Output>
},
) {
const info = (yield* jobs.wait({ id: input.id })).info
if (!info || info.status === "running") return
const output = info.status === "completed" ? yield* Deferred.await(input.settled) : undefined
const text = output ? (info.output ?? "") : info.status === "error" ? (info.error ?? "Command failed") : "Cancelled"
// A session deleted while its command ran has no one left to tell.
yield* sessions
.synthetic({
...(info.notificationID ? { id: info.notificationID } : {}),
sessionID: input.sessionID,
description: input.command,
...ShellResult.notification({
jobID: input.id,
shellID: input.shellID,
command: input.command,
state: info.status,
text,
output,
}),
})
.pipe(Effect.catchTag("Session.NotFoundError", () => Effect.void))
if (info.notificationID) yield* jobs.completeBackground(info.notificationID)
})
// The job that waits on a command for its call (or its session, once backgrounded).
const startJob = Effect.fnUntraced(function* (
jobs: Job.Interface,
shell: Shell.Interface,
input: {
readonly sessionID: SessionSchema.ID
readonly info: ShellSchema.Info
readonly background?: boolean
readonly notificationID?: SessionMessage.ID
readonly timeout?: () => number
},
) {
const info = input.info
const settled = yield* Deferred.make<Output>()
const job = yield* jobs.start({
// CodeMode children share a tool-call ID, but each shell must own its job.
id: info.id,
type: name,
title: info.command,
metadata: { sessionID: input.sessionID, shellID: info.id },
recovery: {
kind: "shell",
sessionID: input.sessionID,
shellID: info.id,
command: info.command,
},
...(input.notificationID ? { notificationID: input.notificationID } : {}),
background: input.background,
run: Effect.gen(function* () {
const result = yield* shell.result(info)
if (!result.capture) return yield* new Shell.NotFoundError({ id: info.id })
const completed = result.info.time.completed ?? (yield* Clock.currentTimeMillis)
return {
...ShellResult.output(result),
status: "completed" as const,
wallTimeSeconds: wallTimeSeconds(result.info.time, completed),
...(result.capture.truncated ? { outputPath: result.info.file } : {}),
}
}).pipe(
Effect.tap((output) => Deferred.succeed(settled, output)),
Effect.map((output) => resultMessages(output, input.timeout?.()).join("\n\n")),
// Interrupting the job (its registry closing) stops the command too, unless the server is handing its daemon
// over: then the command keeps running for the next server.
Effect.onInterrupt(() =>
shell.handoffPrepared() ? Effect.void : shell.stop(info.id, "killed").pipe(Effect.ignore, Effect.asVoid),
),
),
// Cancelling the job stops the command, keeping it and its output file.
cancel: shell.stop(info.id, "killed").pipe(Effect.ignore, Effect.asVoid),
})
return { job, settled }
})
/** The tool result of a call whose command moved to the background. */
export const backgroundToolResult = (info: ShellSchema.Info) => {
// Narrowed to what a backgrounded command reports, so it can be published as is.
const metadata = {
shellID: info.id,
status: "running" as const,
truncated: false,
...(info.pid === undefined ? {} : { pid: info.pid }),
}
return {
content: [backgroundText(info), BACKGROUND_INSTRUCTION].map((text) => ({
type: "text" as const,
text,
})),
metadata,
}
}
/**
* Watches a command taken over from a previous server as a background job of its session, and notifies the
* session when it finishes, as for a command the model ran in the background. A finished command's notice is
* admitted before this returns.
*/
export const reattach = Effect.fnUntraced(function* (input: {
readonly shell: Shell.Interface
readonly jobs: Job.Interface
readonly sessions: Pick<Session.Interface, "synthetic">
readonly sessionID: SessionSchema.ID
readonly info: ShellSchema.Info
// The job's existing durable row, if the previous server had backgrounded it.
readonly notificationID?: SessionMessage.ID
}) {
const { job, settled } = yield* startJob(input.jobs, input.shell, { ...input, background: true })
const notifying = notify(input.sessions, input.jobs, {
sessionID: input.sessionID,
id: job.id,
shellID: input.info.id,
command: input.info.command,
settled,
})
const current = yield* input.shell.get(input.info.id).pipe(Effect.option)
if (Option.isSome(current) && current.value.status !== "running")
return yield* notifying.pipe(
Effect.catch((error) =>
Effect.logWarning("failed to report a recovered shell command", { id: input.info.id, error }),
),
)
yield* input.shell.watch(notifying)
})
export const Plugin = {
id: "opencode.tool.shell",
effect: Effect.fn("ShellTool.Plugin")(function* (ctx: Context) {
const sessions = yield* Session.Service
const jobs = yield* Job.Service
const environment = yield* Environment.Service
const access = yield* FileAccess.Service
const shell = yield* Shell.Service
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" })
invocation.cwd = target.absolute
const timeout = invocation.timeout
const parsed = yield* ShellParse.scan(invocation.command, invocation.shell, target.absolute)
const directories = yield* Effect.forEach(parsed.directories, (directory) =>
access.resolve({
path: FileAccess.resolvePath(target.absolute, directory),
kind: "directory",
}),
)
yield* access.authorizeExternal([target, ...directories], context)
if (parsed.commands.length > 0)
yield* permission.assert({
action: name,
resources: parsed.commands.map((command) => command.resource),
save: parsed.commands.map((command) => command.save),
...Permission.invocation(context),
})
// Approval can outlive the directory, so validate immediately before spawning.
const workdir = yield* Environment.typeFollowing(environment.files, target.absolute).pipe(
Effect.catchTag("Environment.NotFound", () =>
Effect.fail(new Error(`Working directory does not exist: ${target.absolute}`)),
),
)
if (workdir !== "directory")
return yield* Effect.fail(new Error(`Working directory is not a directory: ${target.absolute}`))
return timeout
})
// Not in this Location's scope: a daemon command outlives a Location that closes while the server runs, and
// its session must still hear how it ended.
const notifyWhenDone = (
sessionID: SessionSchema.ID,
id: string,
shellID: string,
command: string,
settled: Deferred.Deferred<Output>,
) => shell.watch(notify(sessions, jobs, { sessionID, id, shellID, command, settled }))
// Stops the command of a call the user asked to stop, and fails the call with the output so far. The command
// stays observable, output file included.
const cancelled = Effect.fnUntraced(function* (info: ShellSchema.Info, jobID: string) {
yield* shell.stop(info.id, "killed").pipe(Effect.ignore)
// The stop escalates to SIGKILL on its own; the session does not wait for that to settle the call.
const result = yield* shell.result(info, { wait: INTERRUPT_WAIT })
// The stopped job settles from the same exit; this only releases it.
yield* jobs.cancel(jobID)
const stopped = ShellResult.interrupted(result)
return yield* new ToolFailure({
message: stopped.message,
// The notice ends the message; renderers show what precedes it as the output, like a finished call's.
metadata: {
interrupted: true,
truncated: result.capture?.truncated ?? false,
shellID: info.id,
notice: stopped.notice,
},
})
})
yield* ctx.tool
.transform((editor) =>
editor.add({
name,
options: { codemode: false },
description: description(undefined, autoBackground),
input: input(autoBackground),
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)
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.
return Effect.uninterruptibleMask((restore) =>
Effect.gen(function* () {
// Listens for the user's stop for the whole call, starting before the command does, so a stop always
// reaches this tool through `cancel` instead of interrupting it, even while the command starts.
const stopped = yield* Deferred.make<void>()
const listener = context.cancel
? yield* context.cancel.pipe(
Effect.andThen(Deferred.succeed(stopped, undefined)),
Effect.interruptible,
Effect.forkChild({ startImmediately: true }),
)
: undefined
return yield* Effect.gen(function* () {
const info = yield* shell.create(
{
command: input.command,
cwd: input.workdir,
timeout,
shell: yield* compatibleShell,
metadata: { sessionID: context.sessionID },
waited: input.background !== true,
toolCall: {
sessionID: context.sessionID,
assistantMessageID: context.messageID,
callID: context.id,
},
},
(invocation) =>
Effect.gen(function* () {
invocation.env.AGENT = "1"
invocation.env.OPENCODE = "1"
invocation.env.AI_AGENT ||= "opencode"
invocation.env.OPENCODE_SESSION_ID = context.sessionID
// Asking for permission can take a while; a stop then ends the call before any command starts.
finalTimeout = yield* restore(
Effect.raceFirst(
prepare(invocation, context),
Deferred.await(stopped).pipe(
Effect.andThen(
Effect.fail(
new ToolFailure({ message: "Command interrupted by the user before it started." }),
),
),
),
),
)
// A foreground timeout moves the command to the background instead of stopping it.
if (autoBackground && input.background !== true) invocation.timeout = 0
}),
)
yield* context.progress({ shellID: info.id })
const { job, settled } = yield* startJob(jobs, shell, {
sessionID: context.sessionID,
info,
timeout: () => finalTimeout,
})
// Stopped while the command was starting: stop it now.
if (yield* Deferred.isDone(stopped)) return yield* cancelled(info, job.id)
if (input.background === true) {
yield* jobs.background(job.id)
yield* notifyWhenDone(context.sessionID, job.id, info.id, info.command, settled)
return backgroundResult(info, yield* Clock.currentTimeMillis)
}
const waiting = jobs.block({ id: job.id, sessionID: context.sessionID })
const blocked =
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
// A user's stop arrives through `cancel`. Any interrupt stops the command too, unless the server is
// handing its daemon over: then the command and its job keep running, and the next server takes the
// call over and moves the command to the background.
const outcome = yield* restore(
Effect.raceFirst(
blocked.pipe(Effect.map((result) => ({ type: "settled" as const, result }))),
Deferred.await(stopped).pipe(Effect.as({ type: "cancelled" as const })),
),
).pipe(
Effect.onInterrupt(() =>
shell.handoffPrepared() ? Effect.void : jobs.cancel(job.id).pipe(Effect.ignore),
),
)
if (outcome.type === "cancelled") return yield* cancelled(info, job.id)
const result = outcome.result
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, yield* Clock.currentTimeMillis, elapsed)
}
if (result?.info.status === "error")
return yield* Effect.fail(new Error(result.info.error ?? "Command failed"))
if (result?.info.status === "cancelled") return yield* Effect.fail(new Error("Command cancelled"))
return yield* Deferred.await(settled)
}).pipe(Effect.ensuring(listener ? Fiber.interrupt(listener) : Effect.void))
}),
).pipe(
// 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 } : {}),
}),
Effect.map((output) => toolResult(output, finalTimeout)),
Effect.mapError(toolFailure(`Unable to execute command: ${input.command}`)),
)
},
}),
)
.pipe(Effect.orDie)
const hook = (event: SessionHooks["context"]) =>
Effect.gen(function* () {
const tool = event.tools[name]
if (!tool) return
tool.description = description(ShellSelect.name(yield* compatibleShell), autoBackground)
})
yield* ctx.session.hook("context", hook)
yield* ctx.session.hook("compaction", hook)
yield* ctx.session.hook("generate", hook)
}),
}