refactor(core): expose shell exit code, elapsed time, and log path

packages/core/src/tool/plugin/shell.ts

@@ -6,7 +6,7 @@ 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 { Deferred, Effect, Fiber, Option, Schema } from "effect"
+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"
@@ -67,22 +67,22 @@ export const Input = Schema.Struct({
 })
 
 const StructuredOutput = Schema.Struct({
-  exit: Schema.optionalKey(Schema.Number),
+  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),
-  truncated: Schema.Boolean,
-  timeout: Schema.optionalKey(Schema.Boolean),
-  killed: Schema.optionalKey(Schema.String),
-})
-
-const Output = Schema.Struct({
-  ...StructuredOutput.fields,
-  output: Schema.String,
-  status: Schema.optionalKey(Schema.Literals(["completed", "running"])),
 })
 
-type Output = typeof Output.Type
+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)
@@ -91,8 +91,14 @@ const resultMessages = (output: Output, timeout?: number) => {
 
 const toolResult = (output: Output, timeout?: number) => {
   return {
-    output,
-    content: resultMessages(output, timeout).map((text) => ({ type: "text" as const, text })),
+    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),
@@ -102,8 +108,10 @@ const toolResult = (output: Output, timeout?: number) => {
   }
 }
 
-const backgroundResult = (info: ShellResult.Result["info"], timeout?: number) => ({
-  output: [
+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}`,
@@ -113,8 +121,13 @@ const backgroundResult = (info: ShellResult.Result["info"], timeout?: number) =>
           "",
           `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"),
+  ].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,
@@ -186,7 +199,13 @@ const startJob = Effect.fnUntraced(function* (
     run: Effect.gen(function* () {
       const result = yield* shell.result(info)
       if (!result.capture) return yield* new Shell.NotFoundError({ id: info.id })
-      return { ...ShellResult.output(result), status: "completed" as const }
+      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")),
@@ -204,15 +223,20 @@ const startJob = Effect.fnUntraced(function* (
 
 /** The tool result of a call whose command moved to the background. */
 export const backgroundToolResult = (info: ShellSchema.Info) => {
-  const result = toolResult(backgroundResult(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: result.metadata.truncated,
+    truncated: false,
     ...(info.pid === undefined ? {} : { pid: info.pid }),
   }
-  return { content: result.content, metadata }
+  return {
+    content: [backgroundText(info), BACKGROUND_INSTRUCTION].map((text) => ({
+      type: "text" as const,
+      text,
+    })),
+    metadata,
+  }
 }
 
 /**
@@ -328,7 +352,7 @@ export const Plugin = {
           options: { codemode: false },
           description: description(undefined, autoBackground),
           input: Input,
-          output: Output,
+          output: StructuredOutput,
           execute: (input, context) => {
             const timeout = input.background === true ? (input.timeout ?? 0) : (input.timeout ?? DEFAULT_TIMEOUT_MS)
             let finalTimeout = timeout
@@ -395,7 +419,7 @@ 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)
+                    return backgroundResult(info, yield* Clock.currentTimeMillis)
                   }
 
                   const waiting = jobs.block({ id: job.id, sessionID: context.sessionID })
@@ -436,7 +460,7 @@ export const Plugin = {
                     const elapsed = "timedOut" in result ? finalTimeout : undefined
                     finalTimeout = 0
                     yield* notifyWhenDone(context.sessionID, job.id, info.id, info.command, settled)
-                    return backgroundResult(info, elapsed)
+                    return backgroundResult(info, yield* Clock.currentTimeMillis, elapsed)
                   }
                   if (result?.info.status === "error")
                     return yield* Effect.fail(new Error(result.info.error ?? "Command failed"))

packages/core/test/tool-shell.test.ts

@@ -905,8 +905,8 @@ describe("ShellTool", () => {
           }).pipe(Effect.timeout("3 seconds"))
           expect(result.status).toBe("completed")
           expect(JSON.parse(result.output.output)).toEqual([
-            { output: "one", exit: 0, truncated: false, status: "completed" },
-            { output: "two", exit: 0, truncated: false, status: "completed" },
+            { output: "one", exitCode: 0, wallTimeSeconds: expect.any(Number) },
+            { output: "two", exitCode: 0, wallTimeSeconds: expect.any(Number) },
           ])
         }),
       )
@@ -1365,7 +1365,16 @@ describe("ShellTool", () => {
         ).pipe(
           Effect.andThen((settled) =>
             Effect.sync(() => {
-              expect(settled.metadata).toMatchObject({ exit: 3, truncated: true })
+              expect(settled.metadata).toMatchObject({
+                exit: 3,
+                truncated: true,
+              })
+              expect(settled.output).toEqual({
+                output: expect.stringContaining(`full output saved to ${settled.output.outputPath}]`),
+                outputPath: expect.any(String),
+                exitCode: 3,
+                wallTimeSeconds: expect.any(Number),
+              })
               expect(settled.content).toEqual([
                 Expected.text(
                   expect.stringMatching(
@@ -1394,6 +1403,11 @@ describe("ShellTool", () => {
           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(
@@ -1434,8 +1448,21 @@ describe("ShellTool", () => {
             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).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",
@@ -1445,10 +1472,20 @@ describe("ShellTool", () => {
             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 })
+            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 },
+              metadata: {
+                source: "shell",
+                shellID: id,
+                state: "completed",
+                exit: 0,
+              },
             })
             expect(yield* Queue.size(notices)).toBe(0)
             expect(yield* shell.list()).toEqual([])
@@ -1584,6 +1621,12 @@ describe("ShellTool", () => {
             )
             const id = ID.make(String(result.metadata?.shellID))
             const shell = yield* Shell.Service
+            const info = yield* shell.get(id)
+            expect(result.output).toMatchObject({
+              exitCode: null,
+              outputPath: info.file,
+              wallTimeSeconds: expect.any(Number),
+            })
             yield* TestClock.adjust("1 second")
             expect((yield* shell.get(id)).status).toBe("running")
             yield* Effect.promise(() => Bun.write(path.join(tmp.path, "release"), ""))