🤖 refactor: move background execution to Runtime interface

Remove BackgroundExecutor abstraction layer - Runtime already handles
local vs SSH execution differences, so background spawning belongs there.

- Add spawnBackground() to Runtime interface with BackgroundHandle type
- Implement LocalBackgroundHandle in LocalRuntime with event buffering
- Stub SSHRuntime.spawnBackground() (not supported for SSH workspaces)
- Simplify BackgroundProcessManager to call runtime directly
- Update bash tool to pass runtime from ToolConfiguration
- Remove aiService executor registration (no longer needed)
- Delete backgroundExecutor.ts, localBackgroundExecutor.ts, sshBackgroundExecutor.ts

~300 LoC removed, cleaner separation of concerns.

Author: ethanndickson

src/common/utils/tools/tools.ts

@@ -16,7 +16,6 @@ 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";
-import type { BackgroundExecutor } from "@/node/services/backgroundExecutor";
 
 /**
  * Configuration for tools that need runtime context
@@ -36,8 +35,6 @@ export interface ToolConfiguration {
   overflow_policy?: "truncate" | "tmpfile";
   /** Background process manager for bash tool (optional, AI-only) */
   backgroundProcessManager?: BackgroundProcessManager;
-  /** Background executor for this workspace (optional, AI-only) */
-  backgroundExecutor?: BackgroundExecutor;
   /** Workspace ID for tracking background processes (optional for token estimation) */
   workspaceId?: string;
 }

src/node/runtime/LocalRuntime.ts

@@ -15,6 +15,9 @@ import type {
   WorkspaceForkParams,
   WorkspaceForkResult,
   InitLogger,
+  BackgroundSpawnOptions,
+  BackgroundSpawnResult,
+  BackgroundHandle,
 } from "./Runtime";
 import { RuntimeError as RuntimeErrorClass } from "./Runtime";
 import { NON_INTERACTIVE_ENV_VARS } from "@/common/constants/env";
@@ -30,6 +33,130 @@ import {
 import { execAsync, DisposableProcess } from "@/node/utils/disposableExec";
 import { getProjectName } from "@/node/utils/runtime/helpers";
 import { getErrorMessage } from "@/common/utils/errors";
+import { once } from "node:events";
+import { log } from "@/node/services/log";
+
+/**
+ * Handle to a local background process.
+ *
+ * Buffers early events until callbacks are registered, since the manager
+ * registers callbacks after spawn() returns (but output may arrive before).
+ */
+class LocalBackgroundHandle implements BackgroundHandle {
+  private stdoutCallback?: (line: string) => void;
+  private stderrCallback?: (line: string) => void;
+  private exitCallback?: (exitCode: number) => void;
+  private terminated = false;
+
+  // Buffers for events that arrive before callbacks are registered
+  private pendingStdout: string[] = [];
+  private pendingStderr: string[] = [];
+  private pendingExitCode?: number;
+
+  constructor(private readonly disposable: DisposableProcess) {}
+
+  onStdout(callback: (line: string) => void): void {
+    this.stdoutCallback = callback;
+    // Flush buffered events
+    for (const line of this.pendingStdout) {
+      callback(line);
+    }
+    this.pendingStdout = [];
+  }
+
+  onStderr(callback: (line: string) => void): void {
+    this.stderrCallback = callback;
+    // Flush buffered events
+    for (const line of this.pendingStderr) {
+      callback(line);
+    }
+    this.pendingStderr = [];
+  }
+
+  onExit(callback: (exitCode: number) => void): void {
+    this.exitCallback = callback;
+    // Flush buffered event
+    if (this.pendingExitCode !== undefined) {
+      callback(this.pendingExitCode);
+      this.pendingExitCode = undefined;
+    }
+  }
+
+  /** Internal: called when stdout line arrives */
+  _emitStdout(line: string): void {
+    if (this.stdoutCallback) {
+      this.stdoutCallback(line);
+    } else {
+      this.pendingStdout.push(line);
+    }
+  }
+
+  /** Internal: called when stderr line arrives */
+  _emitStderr(line: string): void {
+    if (this.stderrCallback) {
+      this.stderrCallback(line);
+    } else {
+      this.pendingStderr.push(line);
+    }
+  }
+
+  /** Internal: called when process exits */
+  _emitExit(exitCode: number): void {
+    if (this.exitCallback) {
+      this.exitCallback(exitCode);
+    } else {
+      this.pendingExitCode = exitCode;
+    }
+  }
+
+  isRunning(): Promise<boolean> {
+    return Promise.resolve(this.disposable.underlying.exitCode === null);
+  }
+
+  async terminate(): Promise<void> {
+    if (this.terminated) return;
+
+    const pid = this.disposable.underlying.pid;
+    if (pid === undefined) {
+      this.terminated = true;
+      return;
+    }
+
+    try {
+      // Send SIGTERM to the process group for graceful shutdown
+      // Use negative PID to kill the entire process group (detached processes are group leaders)
+      const pgid = -pid;
+      log.debug(`LocalBackgroundHandle: Sending SIGTERM to process group (PGID: ${pgid})`);
+      process.kill(pgid, "SIGTERM");
+
+      // Wait 2 seconds for graceful shutdown
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      // Check if process is still running
+      if (await this.isRunning()) {
+        log.debug(`LocalBackgroundHandle: Process still running, sending SIGKILL`);
+        process.kill(pgid, "SIGKILL");
+      }
+    } catch (error) {
+      // Process may already be dead - that's fine
+      log.debug(
+        `LocalBackgroundHandle: Error during terminate: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    this.terminated = true;
+  }
+
+  dispose(): Promise<void> {
+    return Promise.resolve(this.disposable[Symbol.dispose]());
+  }
+
+  /** Get the underlying child process (for spawn event waiting) */
+  get child() {
+    return this.disposable.underlying;
+  }
+}
+
 import { expandTilde } from "./tildeExpansion";
 
 /**
@@ -179,6 +306,99 @@ export class LocalRuntime implements Runtime {
     return { stdout, stderr, stdin, exitCode, duration };
   }
 
+  async spawnBackground(
+    script: string,
+    options: BackgroundSpawnOptions
+  ): Promise<BackgroundSpawnResult> {
+    log.debug(`LocalRuntime.spawnBackground: Spawning in ${options.cwd}`);
+
+    // Check if working directory exists
+    try {
+      await fsPromises.access(options.cwd);
+    } catch {
+      return { success: false, error: `Working directory does not exist: ${options.cwd}` };
+    }
+
+    // Build command with optional niceness
+    const isWindows = process.platform === "win32";
+    const bashPath = getBashPath();
+    const spawnCommand = options.niceness !== undefined && !isWindows ? "nice" : bashPath;
+    const spawnArgs =
+      options.niceness !== undefined && !isWindows
+        ? ["-n", options.niceness.toString(), bashPath, "-c", script]
+        : ["-c", script];
+
+    const childProcess = spawn(spawnCommand, spawnArgs, {
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        ...(options.env ?? {}),
+        ...NON_INTERACTIVE_ENV_VARS,
+      },
+      stdio: ["pipe", "pipe", "pipe"],
+      detached: true,
+    });
+
+    const disposable = new DisposableProcess(childProcess);
+
+    // Declare handle before setting up listeners
+    // eslint-disable-next-line prefer-const
+    let handle: LocalBackgroundHandle;
+
+    // Set up line-buffered output streaming
+    const decoder = new TextDecoder();
+    let stdoutBuffer = "";
+    let stderrBuffer = "";
+
+    childProcess.stdout.on("data", (chunk: Buffer) => {
+      stdoutBuffer += decoder.decode(chunk, { stream: true });
+      const lines = stdoutBuffer.split("\n");
+      stdoutBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        handle._emitStdout(line);
+      }
+    });
+
+    childProcess.stderr.on("data", (chunk: Buffer) => {
+      stderrBuffer += decoder.decode(chunk, { stream: true });
+      const lines = stderrBuffer.split("\n");
+      stderrBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        handle._emitStderr(line);
+      }
+    });
+
+    childProcess.on("exit", (code) => {
+      // Flush remaining partial lines
+      if (stdoutBuffer) handle._emitStdout(stdoutBuffer);
+      if (stderrBuffer) handle._emitStderr(stderrBuffer);
+      handle._emitExit(code ?? 0);
+    });
+
+    handle = new LocalBackgroundHandle(disposable);
+
+    // Wait for spawn or error
+    try {
+      await Promise.race([
+        once(childProcess, "spawn"),
+        once(childProcess, "error").then(([err]) => {
+          throw err;
+        }),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error("Spawn did not complete in time")), 2000)
+        ),
+      ]);
+    } catch (e) {
+      const err = e as Error;
+      log.debug(`LocalRuntime.spawnBackground: Failed to spawn: ${err.message}`);
+      await handle.dispose();
+      return { success: false, error: err.message };
+    }
+
+    log.debug(`LocalRuntime.spawnBackground: Spawned with PID ${childProcess.pid ?? "unknown"}`);
+    return { success: true, handle };
+  }
+
   readFile(filePath: string, _abortSignal?: AbortSignal): ReadableStream<Uint8Array> {
     // Note: _abortSignal ignored for local operations (fast, no need for cancellation)
     const nodeStream = fs.createReadStream(filePath);

src/node/runtime/Runtime.ts

@@ -64,6 +64,64 @@ export interface ExecOptions {
   forcePTY?: boolean;
 }
 
+/**
+ * Options for spawning a background process
+ */
+export interface BackgroundSpawnOptions {
+  /** Working directory for command execution */
+  cwd: string;
+  /** Environment variables to inject */
+  env?: Record<string, string>;
+  /** Process niceness level (-20 to 19, lower = higher priority) */
+  niceness?: number;
+}
+
+/**
+ * Handle to a background process.
+ * Abstracts away whether process is local or remote.
+ */
+export interface BackgroundHandle {
+  /**
+   * Register callback for stdout lines.
+   * For local: called in real-time as output arrives.
+   * For SSH: called when output is polled/read.
+   */
+  onStdout(callback: (line: string) => void): void;
+
+  /**
+   * Register callback for stderr lines.
+   */
+  onStderr(callback: (line: string) => void): void;
+
+  /**
+   * Register callback for process exit.
+   * @param callback Receives exit code (128+signal for signal termination)
+   */
+  onExit(callback: (exitCode: number) => void): void;
+
+  /**
+   * Check if process is still running.
+   */
+  isRunning(): Promise<boolean>;
+
+  /**
+   * Terminate the process (SIGTERM → wait → SIGKILL).
+   */
+  terminate(): Promise<void>;
+
+  /**
+   * Clean up resources (called after process exits or on error).
+   */
+  dispose(): Promise<void>;
+}
+
+/**
+ * Result of spawning a background process
+ */
+export type BackgroundSpawnResult =
+  | { success: true; handle: BackgroundHandle }
+  | { success: false; error: string };
+
 /**
  * Streaming result from executing a command
  */
@@ -211,6 +269,17 @@ export interface Runtime {
    */
   exec(command: string, options: ExecOptions): Promise<ExecStream>;
 
+  /**
+   * Spawn a detached background process.
+   * Returns a handle for monitoring output and terminating the process.
+   * Unlike exec(), background processes have no timeout and run until terminated.
+   *
+   * @param script Bash script to execute
+   * @param options Execution options (cwd, env, niceness)
+   * @returns BackgroundHandle on success, or error
+   */
+  spawnBackground(script: string, options: BackgroundSpawnOptions): Promise<BackgroundSpawnResult>;
+
   /**
    * Read file contents as a stream
    * @param path Absolute or relative path to file

src/node/runtime/SSHRuntime.ts

@@ -13,6 +13,8 @@ import type {
   WorkspaceForkParams,
   WorkspaceForkResult,
   InitLogger,
+  BackgroundSpawnOptions,
+  BackgroundSpawnResult,
 } from "./Runtime";
 import { RuntimeError as RuntimeErrorClass } from "./Runtime";
 import { EXIT_CODE_ABORTED, EXIT_CODE_TIMEOUT } from "@/common/constants/exitCodes";
@@ -247,6 +249,18 @@ export class SSHRuntime implements Runtime {
     return { stdout, stderr, stdin, exitCode, duration };
   }
 
+  spawnBackground(
+    _script: string,
+    _options: BackgroundSpawnOptions
+  ): Promise<BackgroundSpawnResult> {
+    // SSH background execution not yet implemented
+    // Would require: remote process management, output polling, etc.
+    return Promise.resolve({
+      success: false,
+      error: "Background process execution is not supported for SSH workspaces",
+    });
+  }
+
   /**
    * Read file contents over SSH as a stream
    */