🤖 Pass abort controllers through runtime stack

Add abort signal support to all long-running runtime operations to prevent indefinite hangs. Operations with timeouts <10s are excluded per design to avoid noise.

Changes:
- Runtime interface: Add optional abortSignal to readFile/writeFile/stat and workspace operations
- LocalRuntime: Accept and check abort signals in file operations and workspace lifecycle
- SSHRuntime: Pass abort signals through to exec() calls for long-running operations:
  - File I/O (300s timeout)
  - Git clone operations (300s timeout)
  - Init hook execution (3600s timeout)
  - Workspace rename/delete (30s timeout)
- Helper functions: Accept and propagate abort signals through readFileString/writeFileString
- Bash tool: Pass abort signal to runtime.writeFile() for overflow files

All abort signals are optional parameters for backward compatibility.

Testing:
- 794 unit tests pass
- 57 integration tests pass (executeBash, runtimeExecuteBash, runtimeFileEditing, createWorkspace, renameWorkspace, removeWorkspace)
- Typecheck and lint clean

Author: ammar-agent

src/runtime/LocalRuntime.ts

@@ -205,14 +205,28 @@ export class LocalRuntime implements Runtime {
     return { stdout, stderr, stdin, exitCode, duration };
   }
 
-  readFile(filePath: string): ReadableStream<Uint8Array> {
+  readFile(filePath: string, abortSignal?: AbortSignal): ReadableStream<Uint8Array> {
     const nodeStream = fs.createReadStream(filePath);
 
     // Handle errors by wrapping in a transform
     const webStream = Readable.toWeb(nodeStream) as unknown as ReadableStream<Uint8Array>;
 
     return new ReadableStream<Uint8Array>({
       async start(controller: ReadableStreamDefaultController<Uint8Array>) {
+        // Check if already aborted
+        if (abortSignal?.aborted) {
+          controller.error(new Error("Read operation aborted"));
+          nodeStream.destroy();
+          return;
+        }
+
+        // Set up abort listener
+        const abortHandler = () => {
+          controller.error(new Error("Read operation aborted"));
+          nodeStream.destroy();
+        };
+        abortSignal?.addEventListener("abort", abortHandler);
+
         try {
           const reader = webStream.getReader();
           while (true) {
@@ -229,17 +243,24 @@ export class LocalRuntime implements Runtime {
               err instanceof Error ? err : undefined
             )
           );
+        } finally {
+          abortSignal?.removeEventListener("abort", abortHandler);
         }
       },
     });
   }
 
-  writeFile(filePath: string): WritableStream<Uint8Array> {
+  writeFile(filePath: string, abortSignal?: AbortSignal): WritableStream<Uint8Array> {
     let tempPath: string;
     let writer: WritableStreamDefaultWriter<Uint8Array>;
 
     return new WritableStream<Uint8Array>({
       async start() {
+        // Check if already aborted
+        if (abortSignal?.aborted) {
+          throw new Error("Write operation aborted");
+        }
+
         // Create parent directories if they don't exist
         const parentDir = path.dirname(filePath);
         await fsPromises.mkdir(parentDir, { recursive: true });
@@ -249,8 +270,19 @@ export class LocalRuntime implements Runtime {
         const nodeStream = fs.createWriteStream(tempPath);
         const webStream = Writable.toWeb(nodeStream) as WritableStream<Uint8Array>;
         writer = webStream.getWriter();
+
+        // Set up abort listener
+        const abortHandler = () => {
+          writer.abort("Write operation aborted").catch(() => {
+            // Ignore errors during abort
+          });
+        };
+        abortSignal?.addEventListener("abort", abortHandler);
       },
       async write(chunk: Uint8Array) {
+        if (abortSignal?.aborted) {
+          throw new Error("Write operation aborted");
+        }
         await writer.write(chunk);
       },
       async close() {
@@ -282,7 +314,12 @@ export class LocalRuntime implements Runtime {
     });
   }
 
-  async stat(filePath: string): Promise<FileStat> {
+  async stat(filePath: string, abortSignal?: AbortSignal): Promise<FileStat> {
+    // Check if already aborted
+    if (abortSignal?.aborted) {
+      throw new Error("Stat operation aborted");
+    }
+
     try {
       const stats = await fsPromises.stat(filePath);
       return {
@@ -450,10 +487,15 @@ export class LocalRuntime implements Runtime {
   async renameWorkspace(
     projectPath: string,
     oldName: string,
-    newName: string
+    newName: string,
+    abortSignal?: AbortSignal
   ): Promise<
     { success: true; oldPath: string; newPath: string } | { success: false; error: string }
   > {
+    // Check if already aborted
+    if (abortSignal?.aborted) {
+      return { success: false, error: "Rename operation aborted" };
+    }
     // Compute workspace paths using canonical method
     const oldPath = this.getWorkspacePath(projectPath, oldName);
     const newPath = this.getWorkspacePath(projectPath, newName);
@@ -473,8 +515,14 @@ export class LocalRuntime implements Runtime {
   async deleteWorkspace(
     projectPath: string,
     workspaceName: string,
-    force: boolean
+    force: boolean,
+    abortSignal?: AbortSignal
   ): Promise<{ success: true; deletedPath: string } | { success: false; error: string }> {
+    // Check if already aborted
+    if (abortSignal?.aborted) {
+      return { success: false, error: "Delete operation aborted" };
+    }
+
     // Compute workspace path using the canonical method
     const deletedPath = this.getWorkspacePath(projectPath, workspaceName);
 

src/runtime/Runtime.ts

@@ -119,6 +119,8 @@ export interface WorkspaceCreationParams {
   directoryName: string;
   /** Logger for streaming creation progress and init hook output */
   initLogger: InitLogger;
+  /** Optional abort signal for cancellation */
+  abortSignal?: AbortSignal;
 }
 
 /**
@@ -145,6 +147,8 @@ export interface WorkspaceInitParams {
   workspacePath: string;
   /** Logger for streaming initialization progress and output */
   initLogger: InitLogger;
+  /** Optional abort signal for cancellation */
+  abortSignal?: AbortSignal;
 }
 
 /**
@@ -174,26 +178,29 @@ export interface Runtime {
   /**
    * Read file contents as a stream
    * @param path Absolute or relative path to file
+   * @param abortSignal Optional abort signal for cancellation
    * @returns Readable stream of file contents
    * @throws RuntimeError if file cannot be read
    */
-  readFile(path: string): ReadableStream<Uint8Array>;
+  readFile(path: string, abortSignal?: AbortSignal): ReadableStream<Uint8Array>;
 
   /**
    * Write file contents atomically from a stream
    * @param path Absolute or relative path to file
+   * @param abortSignal Optional abort signal for cancellation
    * @returns Writable stream for file contents
    * @throws RuntimeError if file cannot be written
    */
-  writeFile(path: string): WritableStream<Uint8Array>;
+  writeFile(path: string, abortSignal?: AbortSignal): WritableStream<Uint8Array>;
 
   /**
    * Get file statistics
    * @param path Absolute or relative path to file/directory
+   * @param abortSignal Optional abort signal for cancellation
    * @returns File statistics
    * @throws RuntimeError if path does not exist or cannot be accessed
    */
-  stat(path: string): Promise<FileStat>;
+  stat(path: string, abortSignal?: AbortSignal): Promise<FileStat>;
 
   /**
    * Normalize a path for comparison purposes within this runtime's context.
@@ -258,12 +265,14 @@ export interface Runtime {
    * @param projectPath Project root path (local path, used for git commands in LocalRuntime and to extract project name)
    * @param oldName Current workspace name
    * @param newName New workspace name
+   * @param abortSignal Optional abort signal for cancellation
    * @returns Promise resolving to Result with old/new paths on success, or error message
    */
   renameWorkspace(
     projectPath: string,
     oldName: string,
-    newName: string
+    newName: string,
+    abortSignal?: AbortSignal
   ): Promise<
     { success: true; oldPath: string; newPath: string } | { success: false; error: string }
   >;
@@ -281,12 +290,14 @@ export interface Runtime {
    * @param projectPath Project root path (local path, used for git commands in LocalRuntime and to extract project name)
    * @param workspaceName Workspace name to delete
    * @param force If true, force deletion even with uncommitted changes or special conditions (submodules, etc.)
+   * @param abortSignal Optional abort signal for cancellation
    * @returns Promise resolving to Result with deleted path on success, or error message
    */
   deleteWorkspace(
     projectPath: string,
     workspaceName: string,
-    force: boolean
+    force: boolean,
+    abortSignal?: AbortSignal
   ): Promise<{ success: true; deletedPath: string } | { success: false; error: string }>;
 }
 

src/runtime/SSHRuntime.ts

@@ -184,14 +184,15 @@ export class SSHRuntime implements Runtime {
   /**
    * Read file contents over SSH as a stream
    */
-  readFile(path: string): ReadableStream<Uint8Array> {
+  readFile(path: string, abortSignal?: AbortSignal): ReadableStream<Uint8Array> {
     // Return stdout, but wrap to handle errors from exec() and exit code
     return new ReadableStream<Uint8Array>({
       start: async (controller: ReadableStreamDefaultController<Uint8Array>) => {
         try {
           const stream = await this.exec(`cat ${shescape.quote(path)}`, {
             cwd: this.config.srcBaseDir,
             timeout: 300, // 5 minutes - reasonable for large files
+            abortSignal,
           });
 
           const reader = stream.stdout.getReader();
@@ -232,7 +233,7 @@ export class SSHRuntime implements Runtime {
   /**
    * Write file contents over SSH atomically from a stream
    */
-  writeFile(path: string): WritableStream<Uint8Array> {
+  writeFile(path: string, abortSignal?: AbortSignal): WritableStream<Uint8Array> {
     const tempPath = `${path}.tmp.${Date.now()}`;
     // Create parent directory if needed, then write file atomically
     // Use shescape.quote for safe path escaping
@@ -245,6 +246,7 @@ export class SSHRuntime implements Runtime {
       execPromise ??= this.exec(writeCommand, {
         cwd: this.config.srcBaseDir,
         timeout: 300, // 5 minutes - reasonable for large files
+        abortSignal,
       });
       return execPromise;
     };
@@ -282,12 +284,13 @@ export class SSHRuntime implements Runtime {
   /**
    * Get file statistics over SSH
    */
-  async stat(path: string): Promise<FileStat> {
+  async stat(path: string, _abortSignal?: AbortSignal): Promise<FileStat> {
     // Use stat with format string to get: size, mtime, type
     // %s = size, %Y = mtime (seconds since epoch), %F = file type
+    // Note: timeout is <10s so no abort signal needed per requirement
     const stream = await this.exec(`stat -c '%s %Y %F' ${shescape.quote(path)}`, {
       cwd: this.config.srcBaseDir,
-      timeout: 10, // 10 seconds - stat should be fast
+      timeout: 10, // 10 seconds - stat should be fast (no abort needed per requirement)
     });
 
     const [stdout, stderr, exitCode] = await Promise.all([
@@ -404,7 +407,8 @@ export class SSHRuntime implements Runtime {
   private async syncProjectToRemote(
     projectPath: string,
     workspacePath: string,
-    initLogger: InitLogger
+    initLogger: InitLogger,
+    abortSignal?: AbortSignal
   ): Promise<void> {
     // Use timestamp-based bundle path to avoid conflicts (simpler than $$)
     const timestamp = Date.now();
@@ -470,6 +474,7 @@ export class SSHRuntime implements Runtime {
       const cloneStream = await this.exec(`git clone --quiet ${bundleTempPath} ${cloneDestPath}`, {
         cwd: "~",
         timeout: 300, // 5 minutes for clone
+        abortSignal,
       });
 
       const [cloneStdout, cloneStderr, cloneExitCode] = await Promise.all([
@@ -491,6 +496,7 @@ export class SSHRuntime implements Runtime {
         {
           cwd: "~",
           timeout: 30,
+          abortSignal,
         }
       );
       await createTrackingBranchesStream.exitCode;
@@ -561,7 +567,8 @@ export class SSHRuntime implements Runtime {
   private async runInitHook(
     projectPath: string,
     workspacePath: string,
-    initLogger: InitLogger
+    initLogger: InitLogger,
+    abortSignal?: AbortSignal
   ): Promise<void> {
     // Check if hook exists locally (we synced the project, so local check is sufficient)
     const hookExists = await checkInitHookExists(projectPath);
@@ -582,6 +589,7 @@ export class SSHRuntime implements Runtime {
     const hookStream = await this.exec(hookCommand, {
       cwd: workspacePath, // Run in the workspace directory
       timeout: 3600, // 1 hour - generous timeout for init hooks
+      abortSignal,
     });
 
     // Create line-buffered loggers
@@ -685,13 +693,13 @@ export class SSHRuntime implements Runtime {
   }
 
   async initWorkspace(params: WorkspaceInitParams): Promise<WorkspaceInitResult> {
-    const { projectPath, branchName, trunkBranch, workspacePath, initLogger } = params;
+    const { projectPath, branchName, trunkBranch, workspacePath, initLogger, abortSignal } = params;
 
     try {
       // 1. Sync project to remote (opportunistic rsync with scp fallback)
       initLogger.logStep("Syncing project files to remote...");
       try {
-        await this.syncProjectToRemote(projectPath, workspacePath, initLogger);
+        await this.syncProjectToRemote(projectPath, workspacePath, initLogger, abortSignal);
       } catch (error) {
         const errorMsg = getErrorMessage(error);
         initLogger.logStderr(`Failed to sync project: ${errorMsg}`);
@@ -715,6 +723,7 @@ export class SSHRuntime implements Runtime {
       const checkoutStream = await this.exec(checkoutCmd, {
         cwd: workspacePath, // Use the full workspace path for git operations
         timeout: 300, // 5 minutes for git checkout (can be slow on large repos)
+        abortSignal,
       });
 
       const [stdout, stderr, exitCode] = await Promise.all([
@@ -738,7 +747,7 @@ export class SSHRuntime implements Runtime {
       // Note: runInitHook calls logComplete() internally if hook exists
       const hookExists = await checkInitHookExists(projectPath);
       if (hookExists) {
-        await this.runInitHook(projectPath, workspacePath, initLogger);
+        await this.runInitHook(projectPath, workspacePath, initLogger, abortSignal);
       } else {
         // No hook - signal completion immediately
         initLogger.logComplete(0);
@@ -759,10 +768,15 @@ export class SSHRuntime implements Runtime {
   async renameWorkspace(
     projectPath: string,
     oldName: string,
-    newName: string
+    newName: string,
+    abortSignal?: AbortSignal
   ): Promise<
     { success: true; oldPath: string; newPath: string } | { success: false; error: string }
   > {
+    // Check if already aborted
+    if (abortSignal?.aborted) {
+      return { success: false, error: "Rename operation aborted" };
+    }
     // Compute workspace paths using canonical method
     const oldPath = this.getWorkspacePath(projectPath, oldName);
     const newPath = this.getWorkspacePath(projectPath, newName);
@@ -780,6 +794,7 @@ export class SSHRuntime implements Runtime {
       const stream = await this.exec(moveCommand, {
         cwd: this.config.srcBaseDir,
         timeout: 30,
+        abortSignal,
       });
 
       await stream.stdin.close();
@@ -814,8 +829,14 @@ export class SSHRuntime implements Runtime {
   async deleteWorkspace(
     projectPath: string,
     workspaceName: string,
-    force: boolean
+    force: boolean,
+    abortSignal?: AbortSignal
   ): Promise<{ success: true; deletedPath: string } | { success: false; error: string }> {
+    // Check if already aborted
+    if (abortSignal?.aborted) {
+      return { success: false, error: "Delete operation aborted" };
+    }
+
     // Compute workspace path using canonical method
     const deletedPath = this.getWorkspacePath(projectPath, workspaceName);
 
@@ -865,6 +886,7 @@ export class SSHRuntime implements Runtime {
       const stream = await this.exec(removeCommand, {
         cwd: this.config.srcBaseDir,
         timeout: 30,
+        abortSignal,
       });
 
       await stream.stdin.close();

src/services/tools/bash.ts

@@ -412,7 +412,7 @@ export const createBashTool: ToolFactory = (config: ToolConfiguration) => {
                   const fullOutput = lines.join("\n");
 
                   // Use runtime.writeFile() for SSH support
-                  const writer = config.runtime.writeFile(overflowPath);
+                  const writer = config.runtime.writeFile(overflowPath, abortSignal);
                   const encoder = new TextEncoder();
                   const writerInstance = writer.getWriter();
                   await writerInstance.write(encoder.encode(fullOutput));