feat: background blocking tools

Author: thdxr

packages/client/src/generated-effect/client.ts

@@ -237,12 +237,17 @@ type Endpoint4_18Input = { readonly sessionID: Endpoint4_18Request["params"]["se
 const Endpoint4_18 = (raw: RawClient["server.session"]) => (input: Endpoint4_18Input) =>
   raw["session.interrupt"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
 
-type Endpoint4_19Request = Parameters<RawClient["server.session"]["session.message"]>[0]
-type Endpoint4_19Input = {
-  readonly sessionID: Endpoint4_19Request["params"]["sessionID"]
-  readonly messageID: Endpoint4_19Request["params"]["messageID"]
-}
+type Endpoint4_19Request = Parameters<RawClient["server.session"]["session.background"]>[0]
+type Endpoint4_19Input = { readonly sessionID: Endpoint4_19Request["params"]["sessionID"] }
 const Endpoint4_19 = (raw: RawClient["server.session"]) => (input: Endpoint4_19Input) =>
+  raw["session.background"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
+
+type Endpoint4_20Request = Parameters<RawClient["server.session"]["session.message"]>[0]
+type Endpoint4_20Input = {
+  readonly sessionID: Endpoint4_20Request["params"]["sessionID"]
+  readonly messageID: Endpoint4_20Request["params"]["messageID"]
+}
+const Endpoint4_20 = (raw: RawClient["server.session"]) => (input: Endpoint4_20Input) =>
   raw["session.message"]({ params: { sessionID: input["sessionID"], messageID: input["messageID"] } }).pipe(
     Effect.mapError(mapClientError),
     Effect.map((value) => value.data),
@@ -268,7 +273,8 @@ const adaptGroup4 = (raw: RawClient["server.session"]) => ({
   history: Endpoint4_16(raw),
   events: Endpoint4_17(raw),
   interrupt: Endpoint4_18(raw),
-  message: Endpoint4_19(raw),
+  background: Endpoint4_19(raw),
+  message: Endpoint4_20(raw),
 })
 
 type Endpoint5_0Request = Parameters<RawClient["server.message"]["session.messages"]>[0]

packages/client/src/generated/client.ts

@@ -43,6 +43,8 @@ import type {
   SessionEventsOutput,
   SessionInterruptInput,
   SessionInterruptOutput,
+  SessionBackgroundInput,
+  SessionBackgroundOutput,
   SessionMessageInput,
   SessionMessageOutput,
   MessageListInput,
@@ -561,6 +563,17 @@ export function make(options: ClientOptions) {
           },
           requestOptions,
         ),
+      background: (input: SessionBackgroundInput, requestOptions?: RequestOptions) =>
+        request<SessionBackgroundOutput>(
+          {
+            method: "POST",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/background`,
+            successStatus: 204,
+            declaredStatuses: [404, 400, 401],
+            empty: true,
+          },
+          requestOptions,
+        ),
       message: (input: SessionMessageInput, requestOptions?: RequestOptions) =>
         request<{ readonly data: SessionMessageOutput }>(
           {

packages/client/src/generated/types.ts

@@ -1775,6 +1775,10 @@ export type SessionInterruptInput = { readonly sessionID: { readonly sessionID:
 
 export type SessionInterruptOutput = void
 
+export type SessionBackgroundInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
+
+export type SessionBackgroundOutput = void
+
 export type SessionMessageInput = {
   readonly sessionID: { readonly sessionID: string; readonly messageID: string }["sessionID"]
   readonly messageID: { readonly sessionID: string; readonly messageID: string }["messageID"]

packages/core/src/tool/shell.ts

@@ -19,7 +19,7 @@ export const MAX_TIMEOUT_MS = 10 * 60 * 1_000
 export const MAX_CAPTURE_BYTES = 1024 * 1024
 
 const BACKGROUND_STARTED =
-  "The command is running in the background. You will be notified automatically when it completes. DO NOT sleep, poll, or proactively check on its progress."
+  "The command has not completed; it is now running in the background."
 
 export const Input = Schema.Struct({
   command: Schema.String.annotate({ description: "Shell command string to execute" }),
@@ -185,75 +185,80 @@ export const Plugin = {
                 return yield* Effect.fail(new Error(`Working directory is not a directory: ${target.canonical}`))
 
               const timeout = input.timeout ?? DEFAULT_TIMEOUT_MS
+              const info = yield* shell.create({
+                command: input.command,
+                cwd: target.canonical,
+                timeout,
+                metadata: { sessionID: context.sessionID },
+              })
 
-              if (input.background === true) {
-                const background = yield* shell.create({
-                  command: input.command,
-                  cwd: target.canonical,
-                  timeout,
-                  metadata: { sessionID: context.sessionID },
-                })
-                const run = Effect.fn("ShellTool.run")(function* () {
-                  return yield* Effect.gen(function* () {
-                    const final = yield* shell.wait(background.id)
-                    const page = yield* shell.output(background.id, { limit: MAX_CAPTURE_BYTES })
+              const settleShell = Effect.fn("ShellTool.settleShell")(function* () {
+                const final = yield* shell.wait(info.id)
+                const page = yield* shell.output(info.id, { limit: MAX_CAPTURE_BYTES })
 
-                    if (final.status === "timeout")
-                      return `Command exceeded timeout of ${timeout} ms. Retry with a larger timeout if the command is expected to take longer.`
+                if (final.status === "timeout") {
+                  return {
+                    exit: final.exit,
+                    output: `Command exceeded timeout of ${timeout} ms. Retry with a larger timeout if the command is expected to take longer.`,
+                    truncated: false,
+                    timeout: true,
+                    status: "completed" as const,
+                  }
+                }
 
-                    const truncated = page.size > page.cursor
-                    const body = page.output || "(no output)"
-                    const notice = truncated ? `\n\n[output truncated; full output saved to: ${final.file}]` : ""
-                    return `${body}${notice}`
-                  }).pipe(Effect.onInterrupt(() => shell.remove(background.id).pipe(Effect.ignore)))
-                })
+                const truncated = page.size > page.cursor
+                const body = page.output || "(no output)"
+                const notice = truncated ? `\n\n[output truncated; full output saved to: ${final.file}]` : ""
+                return {
+                  exit: final.exit,
+                  output: `${body}${notice}`,
+                  truncated,
+                  status: "completed" as const,
+                }
+              })
 
-                const info = yield* runtime.job.start({
-                  id: context.toolCallID,
-                  type: name,
-                  title: input.command,
-                  metadata: { sessionID: context.sessionID },
-                  run: run(),
-                })
-                yield* runtime.job.background(info.id)
+              const run = settleShell().pipe(
+                Effect.map((output) => output.output),
+                Effect.onInterrupt(() => shell.remove(info.id).pipe(Effect.ignore)),
+              )
+              const job = yield* runtime.job.start({
+                id: context.toolCallID,
+                type: name,
+                title: input.command,
+                metadata: { sessionID: context.sessionID, shellID: info.id },
+                run,
+              })
+
+              if (input.background === true) {
+                yield* runtime.job.background(job.id)
                 yield* notifyWhenDone(context.sessionID, context.toolCallID, input.command)
                 return {
                   output: BACKGROUND_STARTED,
-                  shellID: background.id,
+                  shellID: info.id,
                   truncated: false,
                   status: "running" as const,
                   ...(warnings.length ? { warnings } : {}),
                 }
               }
 
-              const info = yield* shell.create({
-                command: input.command,
-                cwd: target.canonical,
-                timeout,
-                metadata: { sessionID: context.sessionID },
-              })
-              const final = yield* shell.wait(info.id)
-              const page = yield* shell.output(info.id, { limit: MAX_CAPTURE_BYTES })
-
-              if (final.status === "timeout") {
+              const result = yield* runtime.job.block({ id: job.id, sessionID: context.sessionID }).pipe(
+                Effect.onInterrupt(() => runtime.job.cancel(job.id).pipe(Effect.ignore)),
+              )
+              if (result?.type === "backgrounded") {
+                yield* notifyWhenDone(context.sessionID, context.toolCallID, input.command)
                 return {
-                  exit: final.exit,
-                  output: `Command exceeded timeout of ${timeout} ms. Retry with a larger timeout if the command is expected to take longer.`,
+                  output: BACKGROUND_STARTED,
+                  shellID: info.id,
                   truncated: false,
-                  timeout: true,
-                  status: "completed" as const,
+                  status: "running" as const,
                   ...(warnings.length ? { warnings } : {}),
                 }
               }
+              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"))
 
-              const truncated = page.size > page.cursor
-              const body = page.output || "(no output)"
-              const notice = truncated ? `\n\n[output truncated; full output saved to: ${final.file}]` : ""
               return {
-                exit: final.exit,
-                output: `${body}${notice}`,
-                truncated,
-                status: "completed" as const,
+                ...(yield* settleShell()),
                 ...(warnings.length ? { warnings } : {}),
               }
             }).pipe(Effect.mapError(() => new ToolFailure({ message: `Unable to execute command: ${input.command}` }))),

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

@@ -2,7 +2,7 @@ import fs from "fs/promises"
 import { realpathSync } from "node:fs"
 import path from "path"
 import { describe, expect, test } from "bun:test"
-import { DateTime, Effect, Layer } from "effect"
+import { DateTime, Effect, Fiber, Layer, Scope } from "effect"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { makeGlobalNode } from "@opencode-ai/core/effect/app-node"
@@ -454,6 +454,51 @@ describe("ShellTool", () => {
       (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]().then(() => undefined)),
     ),
   )
+
+  it.live("backgrounds a foreground command when the session is signaled", () =>
+    Effect.acquireUseRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => {
+        reset()
+        return withSession(tmp.path, (registry) =>
+          Effect.gen(function* () {
+            const jobs = yield* Job.Service
+            const scope = yield* Scope.Scope
+            const waiting = yield* settleTool(registry, call({ command: idleCommand }, "call-background-signal")).pipe(
+              Effect.forkIn(scope, { startImmediately: true }),
+            )
+
+            const backgroundWhenReady = (remaining = 1000): Effect.Effect<Job.Info[], Error> =>
+              Effect.gen(function* () {
+                const backgrounded = yield* jobs.backgroundAll({ sessionID })
+                if (backgrounded.length > 0) return backgrounded
+                if (remaining <= 0) return yield* Effect.fail(new Error("Timed out waiting for foreground shell job"))
+                yield* Effect.promise(() => Bun.sleep(1))
+                return yield* backgroundWhenReady(remaining - 1)
+              })
+            expect(yield* backgroundWhenReady()).toMatchObject([{ id: "call-background-signal", type: "shell" }])
+
+            const settled = yield* Fiber.join(waiting)
+            const structured = settled.output?.structured as Record<string, unknown> | undefined
+            const shellID = typeof structured?.shellID === "string" ? structured.shellID : undefined
+            expect(settled.output?.structured).toMatchObject({ truncated: false })
+            expect(settled.output?.content[0]).toMatchObject({
+              type: "text",
+              text: expect.stringContaining("running in the background"),
+            })
+            expect(shellID).toStartWith("sh_")
+
+            const shell = yield* Shell.Service
+            if (!shellID) return
+            const id = ShellSchema.ID.make(shellID)
+            expect((yield* shell.list()).map((info) => info.id)).toContain(id)
+            yield* shell.remove(id)
+          }),
+        )
+      },
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]().then(() => undefined)),
+    ),
+  )
 })
 
 test("keeps locked deferred parity TODOs visible", async () => {

packages/plugin/src/v2/effect/generated/api.ts

@@ -182,13 +182,18 @@ export type Endpoint4_18Input = { readonly sessionID: Endpoint4_18Request["param
 export type Endpoint4_18Output = EffectValue<ReturnType<RawClient["server.session"]["session.interrupt"]>>
 export type SessionInterruptOperation<E = never> = (input: Endpoint4_18Input) => Effect.Effect<Endpoint4_18Output, E>
 
-type Endpoint4_19Request = Parameters<RawClient["server.session"]["session.message"]>[0]
-export type Endpoint4_19Input = {
-  readonly sessionID: Endpoint4_19Request["params"]["sessionID"]
-  readonly messageID: Endpoint4_19Request["params"]["messageID"]
+type Endpoint4_19Request = Parameters<RawClient["server.session"]["session.background"]>[0]
+export type Endpoint4_19Input = { readonly sessionID: Endpoint4_19Request["params"]["sessionID"] }
+export type Endpoint4_19Output = EffectValue<ReturnType<RawClient["server.session"]["session.background"]>>
+export type SessionBackgroundOperation<E = never> = (input: Endpoint4_19Input) => Effect.Effect<Endpoint4_19Output, E>
+
+type Endpoint4_20Request = Parameters<RawClient["server.session"]["session.message"]>[0]
+export type Endpoint4_20Input = {
+  readonly sessionID: Endpoint4_20Request["params"]["sessionID"]
+  readonly messageID: Endpoint4_20Request["params"]["messageID"]
 }
-export type Endpoint4_19Output = EffectValue<ReturnType<RawClient["server.session"]["session.message"]>>["data"]
-export type SessionMessageOperation<E = never> = (input: Endpoint4_19Input) => Effect.Effect<Endpoint4_19Output, E>
+export type Endpoint4_20Output = EffectValue<ReturnType<RawClient["server.session"]["session.message"]>>["data"]
+export type SessionMessageOperation<E = never> = (input: Endpoint4_20Input) => Effect.Effect<Endpoint4_20Output, E>
 
 export interface SessionApi<E = never> {
   readonly list: SessionListOperation<E>
@@ -210,6 +215,7 @@ export interface SessionApi<E = never> {
   readonly history: SessionHistoryOperation<E>
   readonly events: SessionEventsOperation<E>
   readonly interrupt: SessionInterruptOperation<E>
+  readonly background: SessionBackgroundOperation<E>
   readonly message: SessionMessageOperation<E>
 }
 

packages/protocol/src/groups/session.ts

@@ -411,6 +411,22 @@ export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S>(sessionLo
           }),
         ),
     )
+    .add(
+      HttpApiEndpoint.post("session.background", "/api/session/:sessionID/background", {
+        params: { sessionID: Session.ID },
+        success: HttpApiSchema.NoContent,
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.background",
+            summary: "Background blocking session tools",
+            description:
+              "Move active foreground backgroundable tools for this session into background observation. Idle requests are a no-op.",
+          }),
+        ),
+    )
     .add(
       HttpApiEndpoint.get("session.message", "/api/session/:sessionID/message/:messageID", {
         params: { sessionID: Session.ID, messageID: SessionMessage.ID },

packages/schema/src/tui-event.ts

@@ -19,6 +19,7 @@ export const CommandExecute = Event.define({
         "session.new",
         "session.share",
         "session.interrupt",
+        "session.background",
         "session.compact",
         "session.page.up",
         "session.page.down",