🤖 feat: add display_name field for background processes

Author: ethanndickson

src/common/types/tools.ts

@@ -8,6 +8,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)
+  display_name?: string; // Human-readable name for background processes
 }
 
 interface CommonBashFields {
@@ -205,7 +206,7 @@ export interface BashBackgroundTerminateArgs {
 }
 
 export type BashBackgroundTerminateResult =
-  | { success: true; message: string }
+  | { success: true; message: string; display_name?: string }
   | { success: false; error: string };
 
 // Bash Background List Tool Types
@@ -219,6 +220,7 @@ export interface BashBackgroundListProcess {
   exitCode?: number;
   stdout_path: string; // Path to stdout log file
   stderr_path: string; // Path to stderr log file
+  display_name?: string; // Human-readable name (e.g., "Dev Server")
 }
 
 export type BashBackgroundListResult =

src/common/utils/tools/toolDefinitions.ts

@@ -64,6 +64,13 @@ export const TOOL_DEFINITIONS = {
             "Read output via bash (e.g. tail, grep, cat). " +
             "Process persists across tool calls until terminated or workspace is removed."
         ),
+      display_name: z
+        .string()
+        .optional()
+        .describe(
+          "Human-readable name for background processes (e.g., 'Dev Server', 'TypeCheck Watch'). " +
+            "Only used when run_in_background=true."
+        ),
     }),
   },
   file_read: {

src/node/services/backgroundProcessManager.ts

@@ -14,6 +14,7 @@ export interface BackgroundProcessMeta {
   status: "running" | "exited" | "killed" | "failed";
   exitCode?: number;
   exitTime?: number;
+  displayName?: string;
 }
 
 /**
@@ -30,6 +31,7 @@ export interface BackgroundProcess {
   exitTime?: number; // Timestamp when exited (undefined if running)
   status: "running" | "exited" | "killed" | "failed";
   handle: BackgroundHandle; // For process interaction
+  displayName?: string; // Human-readable name (e.g., "Dev Server")
 }
 
 /**
@@ -59,6 +61,7 @@ export class BackgroundProcessManager {
       cwd: string;
       secrets?: Record<string, string>;
       niceness?: number;
+      displayName?: string;
     }
   ): Promise<
     { success: true; processId: string; outputDir: string } | { success: false; error: string }
@@ -91,6 +94,7 @@ export class BackgroundProcessManager {
       script,
       startTime,
       status: "running",
+      displayName: config.displayName,
     };
     await handle.writeMeta(JSON.stringify(meta, null, 2));
 
@@ -103,6 +107,7 @@ export class BackgroundProcessManager {
       startTime,
       status: "running",
       handle,
+      displayName: config.displayName,
     };
 
     // Store process in map

src/node/services/tools/bash.ts

@@ -230,7 +230,7 @@ export const createBashTool: ToolFactory = (config: ToolConfiguration) => {
     description: TOOL_DEFINITIONS.bash.description + "\nRuns in " + config.cwd + " - no cd needed",
     inputSchema: TOOL_DEFINITIONS.bash.schema,
     execute: async (
-      { script, timeout_secs, run_in_background },
+      { script, timeout_secs, run_in_background, display_name },
       { abortSignal }
     ): Promise<BashToolResult> => {
       // Validate script input
@@ -267,6 +267,7 @@ export const createBashTool: ToolFactory = (config: ToolConfiguration) => {
             cwd: config.cwd,
             secrets: config.secrets,
             niceness: config.niceness,
+            displayName: display_name,
           }
         );
 

src/node/services/tools/bash_background_list.ts

@@ -38,6 +38,7 @@ export const createBashBackgroundListTool: ToolFactory = (config: ToolConfigurat
           exitCode: p.exitCode,
           stdout_path: `${p.outputDir}/stdout.log`,
           stderr_path: `${p.outputDir}/stderr.log`,
+          display_name: p.displayName,
         })),
       };
     },

src/node/services/tools/bash_background_terminate.ts

@@ -39,6 +39,7 @@ export const createBashBackgroundTerminateTool: ToolFactory = (config: ToolConfi
         return {
           success: true,
           message: `Process ${process_id} terminated`,
+          display_name: process.displayName,
         };
       }