feat: cancel client-side tools (#113)

src/tools/README.md

@@ -0,0 +1,19 @@
+# Client-side tool guidelines
+
+How to implement tools that run locally in Letta Code.
+
+## Contract
+- Function signature: `(args, opts?) => Promise<{ toolReturn: string; status: "success" | "error"; stdout?: string[]; stderr?: string[] }>`
+- Optional `opts.signal?: AbortSignal`. If you spawn a subprocess, wire this signal to it so Esc/abort can kill it cleanly. If you’re pure in-process, you can ignore it.
+
+## Subprocess tools (e.g., Bash)
+- Pass the provided `AbortSignal` to `exec`/`spawn` so abort kills the child. Normalize abort errors to `toolReturn: "User interrupted tool execution", status: "error"`.
+- Avoid running multiple subprocesses unless you also expose a cancel hook; we execute tools serially to avoid races.
+
+## In-process tools (read/write/edit)
+- You can ignore the signal, but still return a clear `toolReturn` and `status`.
+- Be deterministic and side-effect aware; the runner keeps tools serial to avoid file races.
+
+## Errors
+- Return a concise error message in `toolReturn` and set `status: "error"`.
+- Don’t `console.error` from tools; the UI surfaces the returned message.

src/tools/impl/Bash.ts

@@ -12,6 +12,7 @@ interface BashArgs {
   timeout?: number;
   description?: string;
   run_in_background?: boolean;
+  signal?: AbortSignal;
 }
 
 interface BashResult {
@@ -19,7 +20,7 @@ interface BashResult {
     type: string;
     text: string;
   }>;
-  isError?: boolean;
+  status: "success" | "error";
 }
 
 export async function bash(args: BashArgs): Promise<BashResult> {
@@ -29,13 +30,17 @@ export async function bash(args: BashArgs): Promise<BashResult> {
     timeout = 120000,
     description: _description,
     run_in_background = false,
+    signal,
   } = args;
   const userCwd = process.env.USER_CWD || process.cwd();
 
   if (command === "/bashes") {
     const processes = Array.from(backgroundProcesses.entries());
     if (processes.length === 0) {
-      return { content: [{ type: "text", text: "(no content)" }] };
+      return {
+        content: [{ type: "text", text: "(no content)" }],
+        status: "success",
+      };
     }
     let output = "";
     for (const [id, proc] of processes) {
@@ -44,7 +49,10 @@ export async function bash(args: BashArgs): Promise<BashResult> {
         : "unknown";
       output += `${id}: ${proc.command} (${proc.status}, runtime: ${runtime})\n`;
     }
-    return { content: [{ type: "text", text: output.trim() }] };
+    return {
+      content: [{ type: "text", text: output.trim() }],
+      status: "success",
+    };
   }
 
   if (run_in_background) {
@@ -100,6 +108,7 @@ export async function bash(args: BashArgs): Promise<BashResult> {
           text: `Command running in background with ID: ${bashId}`,
         },
       ],
+      status: "success",
     };
   }
 
@@ -110,6 +119,7 @@ export async function bash(args: BashArgs): Promise<BashResult> {
       maxBuffer: 10 * 1024 * 1024,
       cwd: userCwd,
       env: { ...process.env },
+      signal,
     };
     const { stdout, stderr } = await execAsync(command, options);
     const stdoutStr = typeof stdout === "string" ? stdout : stdout.toString();
@@ -126,6 +136,7 @@ export async function bash(args: BashArgs): Promise<BashResult> {
 
     return {
       content: [{ type: "text", text: truncatedOutput }],
+      status: "success",
     };
   } catch (error) {
     const err = error as NodeJS.ErrnoException & {
@@ -133,14 +144,26 @@ export async function bash(args: BashArgs): Promise<BashResult> {
       stderr?: string;
       killed?: boolean;
       signal?: string;
+      code?: string;
+      name?: string;
     };
+    const isAbort =
+      signal?.aborted ||
+      err.code === "ABORT_ERR" ||
+      err.name === "AbortError" ||
+      err.message === "The operation was aborted";
+
     let errorMessage = "";
-    if (err.killed && err.signal === "SIGTERM")
-      errorMessage = `Command timed out after ${effectiveTimeout}ms\n`;
-    if (err.code) errorMessage += `Exit code: ${err.code}\n`;
-    if (err.stderr) errorMessage += err.stderr;
-    else if (err.message) errorMessage += err.message;
-    if (err.stdout) errorMessage = `${err.stdout}\n${errorMessage}`;
+    if (isAbort) {
+      errorMessage = "User interrupted tool execution";
+    } else {
+      if (err.killed && err.signal === "SIGTERM")
+        errorMessage = `Command timed out after ${effectiveTimeout}ms\n`;
+      if (err.code) errorMessage += `Exit code: ${err.code}\n`;
+      if (err.stderr) errorMessage += err.stderr;
+      else if (err.message) errorMessage += err.message;
+      if (err.stdout) errorMessage = `${err.stdout}\n${errorMessage}`;
+    }
 
     // Apply character limit even to error messages
     const { content: truncatedError } = truncateByChars(
@@ -151,7 +174,7 @@ export async function bash(args: BashArgs): Promise<BashResult> {
 
     return {
       content: [{ type: "text", text: truncatedError }],
-      isError: true,
+      status: "error",
     };
   }
 }

src/tools/manager.ts

@@ -459,6 +459,7 @@ function flattenToolResponse(result: unknown): string {
 export async function executeTool(
   name: string,
   args: ToolArgs,
+  options?: { signal?: AbortSignal },
 ): Promise<ToolExecutionResult> {
   const tool = toolRegistry.get(name);
 
@@ -470,7 +471,13 @@ export async function executeTool(
   }
 
   try {
-    const result = await tool.fn(args);
+    // Inject abort signal for tools that support it (currently Bash) without altering schemas
+    const argsWithSignal =
+      name === "Bash" && options?.signal
+        ? { ...args, signal: options.signal }
+        : args;
+
+    const result = await tool.fn(argsWithSignal);
 
     // Extract stdout/stderr if present (for bash tools)
     const recordResult = isRecord(result) ? result : undefined;
@@ -478,7 +485,6 @@ export async function executeTool(
     const stderrValue = recordResult?.stderr;
     const stdout = isStringArray(stdoutValue) ? stdoutValue : undefined;
     const stderr = isStringArray(stderrValue) ? stderrValue : undefined;
-
     // Flatten the response to plain text
     const flattenedResponse = flattenToolResponse(result);
 
@@ -490,6 +496,21 @@ export async function executeTool(
       ...(stderr && { stderr }),
     };
   } catch (error) {
+    const isAbort =
+      error instanceof Error &&
+      (error.name === "AbortError" ||
+        error.message === "The operation was aborted" ||
+        // node:child_process AbortError may include code/message variants
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (error as any).code === "ABORT_ERR");
+
+    if (isAbort) {
+      return {
+        toolReturn: "User interrupted tool execution",
+        status: "error",
+      };
+    }
+
     // Don't console.error here - it pollutes the TUI
     // The error message is already returned in toolReturn
     return {