🤖 feat: add background bash process execution

Adds ability to run long-running bash processes in the background without
blocking the AI conversation. Useful for builds, test suites, dev servers,
and other processes that take longer than typical tool timeouts.

Core components:
- CircularBuffer<T>: O(1) ring buffer for stdout/stderr (1000 lines each)
- BackgroundProcessManager: lifecycle management with spawn/list/terminate/cleanup
- Process IDs use 'bg-{8-hex-chars}' format for uniqueness

New tools:
- bash tool: enhanced with run_in_background parameter
- bash_background_read: check status and retrieve buffered output
- bash_background_list: discover processes after context loss
- bash_background_terminate: graceful shutdown (SIGTERM → SIGKILL)

Features:
- Automatic cleanup on workspace deletion
- Output buffers preserved after process exit
- Filtering support in read tool (tail, regex)
- Workspace isolation (processes scoped to workspace)

Test coverage: 84 tests across all components

Author: ethanndickson

src/browser/components/RightSidebar/CodeReview/ReviewPanel.tsx

@@ -269,7 +269,8 @@ export const ReviewPanel: React.FC<ReviewPanelProps> = ({
         }
 
         const diffOutput = diffResult.data.output ?? "";
-        const truncationInfo = diffResult.data.truncated;
+        const truncationInfo =
+          "truncated" in diffResult.data ? diffResult.data.truncated : undefined;
 
         const fileDiffs = parseDiff(diffOutput);
         const allHunks = extractAllHunks(fileDiffs);

src/common/types/tools.ts

@@ -7,6 +7,7 @@
 export interface BashToolArgs {
   script: string;
   timeout_secs?: number; // Optional: defaults to 3 seconds for interactivity
+  run_in_background?: boolean; // Run without blocking (for long-running processes)
 }
 
 interface CommonBashFields {
@@ -26,6 +27,12 @@ export type BashToolResult =
         totalLines: number;
       };
     })
+  | (CommonBashFields & {
+      success: true;
+      output: string;
+      exitCode: 0;
+      backgroundProcessId: string; // Background spawn succeeded
+    })
   | (CommonBashFields & {
       success: false;
       output?: string;
@@ -190,6 +197,56 @@ export interface StatusSetToolArgs {
   url?: string;
 }
 
+// Bash Background Tool Types
+export interface BashBackgroundReadArgs {
+  process_id: string;
+  stdout_tail?: number; // Last N lines of stdout
+  stderr_tail?: number; // Last N lines of stderr
+  stdout_regex?: string; // Filter stdout by regex
+  stderr_regex?: string; // Filter stderr by regex
+}
+
+export type BashBackgroundReadResult =
+  | {
+      success: true;
+      process_id: string;
+      status: "running" | "exited" | "killed" | "failed";
+      script: string;
+      pid?: number; // OS process ID
+      uptime_ms: number;
+      exitCode?: number;
+      stdout: string[];
+      stderr: string[];
+    }
+  | {
+      success: false;
+      error: string;
+    };
+
+export interface BashBackgroundTerminateArgs {
+  process_id: string;
+}
+
+export type BashBackgroundTerminateResult =
+  | { success: true; message: string }
+  | { success: false; error: string };
+
+// Bash Background List Tool Types
+export type BashBackgroundListArgs = Record<string, never>;
+
+export interface BashBackgroundListProcess {
+  process_id: string;
+  status: "running" | "exited" | "killed" | "failed";
+  script: string;
+  pid?: number;
+  uptime_ms: number;
+  exitCode?: number;
+}
+
+export type BashBackgroundListResult =
+  | { success: true; processes: BashBackgroundListProcess[] }
+  | { success: false; error: string };
+
 export type StatusSetToolResult =
   | {
       success: true;

src/common/utils/tools/toolDefinitions.ts

@@ -52,6 +52,19 @@ export const TOOL_DEFINITIONS = {
         .describe(
           `Timeout (seconds, default: ${BASH_DEFAULT_TIMEOUT_SECS}). Start small and increase on retry; avoid large initial values to keep UX responsive`
         ),
+      run_in_background: z
+        .boolean()
+        .default(false)
+        .describe(
+          "Run this command in the background without blocking. " +
+            "Use for processes running >5s (dev servers, builds, file watchers). " +
+            "Do NOT use for quick commands (<5s), interactive processes (no stdin support), " +
+            "or processes requiring real-time output (use foreground with larger timeout instead). " +
+            "Returns immediately with process ID for status checking and termination. " +
+            "Output is buffered (max 1000 lines per stream, oldest evicted when full). " +
+            "Poll frequently with bash_background_read for high-output processes. " +
+            "Process persists across tool calls until terminated or workspace is removed."
+        ),
     }),
   },
   file_read: {
@@ -229,6 +242,56 @@ export const TOOL_DEFINITIONS = {
       })
       .strict(),
   },
+  bash_background_read: {
+    description:
+      "Check status and read output from a background bash process. " +
+      "Use this to inspect long-running processes started with run_in_background=true. " +
+      "Supports filtering output with tail and regex options.",
+    schema: z.object({
+      process_id: z
+        .string()
+        .regex(/^bg-[0-9a-f]{8}$/, "Invalid process ID format")
+        .describe("Background process ID returned from bash tool"),
+      stdout_tail: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Return last N lines of stdout (default: all buffered)"),
+      stderr_tail: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Return last N lines of stderr (default: all buffered)"),
+      stdout_regex: z
+        .string()
+        .optional()
+        .describe("Filter stdout lines by regex pattern (applied before tail)"),
+      stderr_regex: z
+        .string()
+        .optional()
+        .describe("Filter stderr lines by regex pattern (applied before tail)"),
+    }),
+  },
+  bash_background_list: {
+    description:
+      "List all background processes for the current workspace. " +
+      "Useful for discovering running processes after context loss or resuming a conversation.",
+    schema: z.object({}),
+  },
+  bash_background_terminate: {
+    description:
+      "Terminate a background bash process. " +
+      "Sends SIGTERM, waits briefly, then sends SIGKILL if needed. " +
+      "Process output remains available for inspection after termination.",
+    schema: z.object({
+      process_id: z
+        .string()
+        .regex(/^bg-[0-9a-f]{8}$/, "Invalid process ID format")
+        .describe("Background process ID to terminate"),
+    }),
+  },
   web_fetch: {
     description:
       `Fetch a web page and extract its main content as clean markdown. ` +

src/common/utils/tools/tools.ts

@@ -1,6 +1,9 @@
 import { type Tool } from "ai";
 import { createFileReadTool } from "@/node/services/tools/file_read";
 import { createBashTool } from "@/node/services/tools/bash";
+import { createBashBackgroundReadTool } from "@/node/services/tools/bash_background_read";
+import { createBashBackgroundListTool } from "@/node/services/tools/bash_background_list";
+import { createBashBackgroundTerminateTool } from "@/node/services/tools/bash_background_terminate";
 import { createFileEditReplaceStringTool } from "@/node/services/tools/file_edit_replace_string";
 // DISABLED: import { createFileEditReplaceLinesTool } from "@/node/services/tools/file_edit_replace_lines";
 import { createFileEditInsertTool } from "@/node/services/tools/file_edit_insert";
@@ -12,6 +15,7 @@ import { log } from "@/node/services/log";
 
 import type { Runtime } from "@/node/runtime/Runtime";
 import type { InitStateManager } from "@/node/services/initStateManager";
+import type { BackgroundProcessManager } from "@/node/services/backgroundProcessManager";
 
 /**
  * Configuration for tools that need runtime context
@@ -29,6 +33,10 @@ export interface ToolConfiguration {
   runtimeTempDir: string;
   /** Overflow policy for bash tool output (optional, not exposed to AI) */
   overflow_policy?: "truncate" | "tmpfile";
+  /** Background process manager for bash tool (optional, AI-only) */
+  backgroundProcessManager?: BackgroundProcessManager;
+  /** Workspace ID for tracking background processes (optional for token estimation) */
+  workspaceId?: string;
 }
 
 /**
@@ -99,6 +107,9 @@ export async function getToolsForModel(
     // and line number miscalculations. Use file_edit_replace_string instead.
     // file_edit_replace_lines: wrap(createFileEditReplaceLinesTool(config)),
     bash: wrap(createBashTool(config)),
+    bash_background_read: wrap(createBashBackgroundReadTool(config)),
+    bash_background_list: wrap(createBashBackgroundListTool(config)),
+    bash_background_terminate: wrap(createBashBackgroundTerminateTool(config)),
     web_fetch: wrap(createWebFetchTool(config)),
   };
 

src/node/services/aiService.ts

@@ -20,6 +20,7 @@ import { getToolsForModel } from "@/common/utils/tools/tools";
 import { createRuntime } from "@/node/runtime/runtimeFactory";
 import { secretsToRecord } from "@/common/types/secrets";
 import type { MuxProviderOptions } from "@/common/types/providerOptions";
+import type { BackgroundProcessManager } from "@/node/services/backgroundProcessManager";
 import { log } from "./log";
 import {
   transformModelMessages,
@@ -141,12 +142,14 @@ export class AIService extends EventEmitter {
   private readonly initStateManager: InitStateManager;
   private readonly mockModeEnabled: boolean;
   private readonly mockScenarioPlayer?: MockScenarioPlayer;
+  private readonly backgroundProcessManager?: BackgroundProcessManager;
 
   constructor(
     config: Config,
     historyService: HistoryService,
     partialService: PartialService,
-    initStateManager: InitStateManager
+    initStateManager: InitStateManager,
+    backgroundProcessManager?: BackgroundProcessManager
   ) {
     super();
     // Increase max listeners to accommodate multiple concurrent workspace listeners
@@ -156,6 +159,7 @@ export class AIService extends EventEmitter {
     this.historyService = historyService;
     this.partialService = partialService;
     this.initStateManager = initStateManager;
+    this.backgroundProcessManager = backgroundProcessManager;
     this.streamManager = new StreamManager(historyService, partialService);
     void this.ensureSessionsDir();
     this.setupStreamEventForwarding();
@@ -762,6 +766,8 @@ export class AIService extends EventEmitter {
           runtime,
           secrets: secretsToRecord(projectSecrets),
           runtimeTempDir,
+          backgroundProcessManager: this.backgroundProcessManager,
+          workspaceId,
         },
         workspaceId,
         this.initStateManager,