Merge branch 'bash-tool-run-in-background'

Author: qorzj

src/prompt.ts

@@ -351,6 +351,11 @@ export function getTools(_options: PromptToolOptions = {}, externalTools: ToolDe
               },
               uniqueItems: true,
             },
+            run_in_background: {
+              type: "boolean",
+              description:
+                "Set to true to run the command in the background. Use this only when you need to perform a blocking task and do not need the result immediately.",
+            },
           },
           required: ["command", "sideEffects"],
           additionalProperties: false,

src/session.ts

@@ -8,6 +8,7 @@ import type { ChatCompletionMessageParam, ChatCompletionContentPart } from "open
 import { launchNotifyScript } from "./common/notify";
 import { buildThinkingRequestOptions } from "./common/openai-thinking";
 import { DEEPSEEK_V4_MODELS, supportsMultimodal } from "./common/model-capabilities";
+import { readTextFileWithMetadata } from "./common/file-utils";
 import {
   getCompactPrompt,
   getDefaultSkillPrompt,
@@ -60,6 +61,7 @@ export type {
 const MAX_SESSION_ENTRIES = 50;
 const MAX_PROJECT_CODE_LENGTH = 64;
 const PROJECT_CODE_HASH_LENGTH = 16;
+const BACKGROUND_FAILURE_LOG_TAIL_CHARS = 4000;
 const DEFAULT_COMPACT_PROMPT_TOKEN_THRESHOLD = 128 * 1024;
 const DEEPSEEK_V4_COMPACT_PROMPT_TOKEN_THRESHOLD = 512 * 1024;
 
@@ -330,6 +332,7 @@ export class SessionManager {
   private activePromptController: AbortController | null = null;
   private readonly sessionControllers = new Map<string, AbortController>();
   private readonly processTimeoutControls = new Map<string, ProcessTimeoutControl>();
+  private readonly liveProcessKeys = new Set<string>();
   private readonly toolExecutor: ToolExecutor;
   private readonly mcpManager = new McpManager();
   private mcpToolDefinitions: ToolDefinition[] = [];
@@ -379,6 +382,7 @@ export class SessionManager {
         sessionController.abort();
       }
     }
+    this.killLiveProcesses();
     this.sessionControllers.clear();
     this.processTimeoutControls.clear();
     this.mcpManager.disconnect();
@@ -1525,7 +1529,9 @@ ${skillMd}
     const killedPids: number[] = [];
     const failedPids: number[] = [];
     for (const pid of processIds) {
-      this.processTimeoutControls.delete(this.getProcessControlKey(sessionId, pid));
+      const processControlKey = this.getProcessControlKey(sessionId, pid);
+      this.processTimeoutControls.delete(processControlKey);
+      this.liveProcessKeys.delete(processControlKey);
       if (killProcessTree(pid, "SIGKILL")) {
         killedPids.push(pid);
         continue;
@@ -1892,21 +1898,11 @@ ${skillMd}
     const processIds = options.processIds ?? [];
     for (const pid of processIds) {
       const processControlKey = this.getProcessControlKey(sessionId, pid);
-      if (!this.processTimeoutControls.has(processControlKey)) {
+      if (!this.processTimeoutControls.has(processControlKey) && !this.liveProcessKeys.has(processControlKey)) {
         continue;
       }
 
-      const killedGroup = killProcessTree(pid, "SIGKILL");
-      if (killedGroup) {
-        this.processTimeoutControls.delete(processControlKey);
-        continue;
-      }
-      try {
-        process.kill(pid, "SIGKILL");
-      } catch {
-        // ignore process-kill failures during cleanup
-      }
-      this.processTimeoutControls.delete(processControlKey);
+      this.killTrackedProcess(processControlKey, pid);
     }
 
     clearSessionState(sessionId);
@@ -2172,6 +2168,7 @@ ${skillMd}
       onProcessExit: (pid) => this.removeSessionProcess(sessionId, pid),
       onProcessStdout: (pid, chunk) => this.onProcessStdout?.(Number(pid), chunk),
       onProcessTimeoutControl: (pid, control) => this.setSessionProcessTimeoutControl(sessionId, pid, control),
+      onBackgroundProcessComplete: (completion) => this.addBackgroundProcessCompletionMessage(sessionId, completion),
       onBeforeFileMutation: (filePath) => this.prepareFileMutationCheckpoint(sessionId, filePath),
       onAfterFileMutation: (filePath) => this.recordFileMutationCheckpoint(sessionId, filePath),
       shouldStop: () => this.isInterrupted(sessionId),
@@ -2666,6 +2663,7 @@ ${skillMd}
 
   private addSessionProcess(sessionId: string, processId: string | number, command: string): void {
     const now = new Date().toISOString();
+    this.liveProcessKeys.add(this.getProcessControlKey(sessionId, processId));
     this.updateSessionEntry(sessionId, (entry) => {
       const processes = new Map(entry.processes ?? []);
       processes.set(String(processId), { startTime: now, command });
@@ -2677,9 +2675,86 @@ ${skillMd}
     });
   }
 
+  private addBackgroundProcessCompletionMessage(
+    sessionId: string,
+    completion: {
+      command: string;
+      outputPath: string;
+      ok: boolean;
+      exitCode: number | null;
+      signal: string | null;
+      error?: string;
+      completedAtMs: number;
+      startedAtMs: number;
+    }
+  ): void {
+    const status = completion.ok ? "completed" : "failed";
+    const exitText =
+      completion.exitCode !== null
+        ? `exit code ${completion.exitCode}`
+        : completion.signal
+          ? `signal ${completion.signal}`
+          : completion.error || "unknown status";
+    const durationMs = Math.max(0, completion.completedAtMs - completion.startedAtMs);
+    const baseContent =
+      `Background command "${completion.command}" ${status} with ${exitText} ` +
+      `after ${this.formatBackgroundDuration(durationMs)}. Output: ${completion.outputPath}`;
+    const logTail = completion.ok ? null : this.buildBackgroundFailureLogTailSlice(completion.outputPath);
+    const content = logTail ? `${baseContent}\n${logTail}` : baseContent;
+    this.addSessionSystemMessage(sessionId, content, true);
+  }
+
+  private buildBackgroundFailureLogTailSlice(outputPath: string): string | null {
+    const tail = this.readTextFileTail(outputPath, BACKGROUND_FAILURE_LOG_TAIL_CHARS);
+    if (!tail || !tail.content) {
+      return null;
+    }
+    const prefix = tail.truncated ? `(${tail.totalBytes} bytes)...\n` : "";
+    return [
+      `<background_task_failure_log path="${outputPath}">`,
+      `${prefix}${tail.content}`,
+      "</background_task_failure_log>",
+    ].join("\n");
+  }
+
+  private readTextFileTail(
+    filePath: string,
+    maxChars: number
+  ): { content: string; totalBytes: number; truncated: boolean } | null {
+    try {
+      const stat = fs.statSync(filePath);
+      if (!stat.isFile() || stat.size <= 0) {
+        return null;
+      }
+      const content = readTextFileWithMetadata(filePath).content;
+      return {
+        content: content.slice(-maxChars).trimEnd(),
+        totalBytes: stat.size,
+        truncated: content.length > maxChars,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  private formatBackgroundDuration(durationMs: number): string {
+    if (durationMs < 1000) {
+      return `${durationMs}ms`;
+    }
+    const seconds = Math.round(durationMs / 1000);
+    if (seconds < 60) {
+      return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+  }
+
   private removeSessionProcess(sessionId: string, processId: string | number): void {
     const now = new Date().toISOString();
-    this.processTimeoutControls.delete(this.getProcessControlKey(sessionId, processId));
+    const processControlKey = this.getProcessControlKey(sessionId, processId);
+    this.processTimeoutControls.delete(processControlKey);
+    this.liveProcessKeys.delete(processControlKey);
     this.updateSessionEntry(sessionId, (entry) => {
       const processes = new Map(entry.processes ?? []);
       processes.delete(String(processId));
@@ -2742,6 +2817,37 @@ ${skillMd}
     return `${sessionId}:${String(processId)}`;
   }
 
+  private killLiveProcesses(): void {
+    for (const processControlKey of Array.from(this.liveProcessKeys)) {
+      const processId = this.getProcessIdFromControlKey(processControlKey);
+      if (processId === null) {
+        this.liveProcessKeys.delete(processControlKey);
+        continue;
+      }
+      this.killTrackedProcess(processControlKey, processId);
+    }
+  }
+
+  private killTrackedProcess(processControlKey: string, processId: number): void {
+    const killedGroup = killProcessTree(processId, "SIGKILL");
+    if (!killedGroup) {
+      try {
+        process.kill(processId, "SIGKILL");
+      } catch {
+        // Ignore process-kill failures during cleanup.
+      }
+    }
+    this.processTimeoutControls.delete(processControlKey);
+    this.liveProcessKeys.delete(processControlKey);
+  }
+
+  private getProcessIdFromControlKey(processControlKey: string): number | null {
+    const separatorIndex = processControlKey.lastIndexOf(":");
+    const rawProcessId = separatorIndex >= 0 ? processControlKey.slice(separatorIndex + 1) : processControlKey;
+    const processId = Number(rawProcessId);
+    return Number.isInteger(processId) && processId > 0 ? processId : null;
+  }
+
   private getProcessIds(processes: Map<string, SessionProcessEntry> | null): number[] {
     if (!processes) {
       return [];

src/tests/prompt.test.ts

@@ -30,6 +30,8 @@ test("getTools requires bash sideEffects permission scopes", () => {
   assert.equal(sideEffects.type, "array");
   assert.equal(sideEffects.items?.enum?.includes("write-out-cwd"), true);
   assert.equal(sideEffects.items?.enum?.includes("unknown"), true);
+  const runInBackground = tool.function.parameters.properties.run_in_background as { type?: unknown };
+  assert.equal(runInBackground.type, "boolean");
 });
 
 test("getSystemPrompt always includes WebSearch docs", () => {
@@ -43,6 +45,14 @@ test("getSystemPrompt includes UpdatePlan docs", () => {
   assert.equal(prompt.includes("The `plan` argument is a markdown string, not an array of step objects."), true);
 });
 
+test("getSystemPrompt includes Bash background guidance", () => {
+  const prompt = getSystemPrompt("/tmp/project");
+  assert.equal(prompt.includes("run_in_background: true"), true);
+  assert.equal(prompt.includes("do NOT add `&`"), true);
+  assert.equal(prompt.includes("use the `stopCommand` returned in the tool result metadata"), true);
+  assert.equal(prompt.includes("stop background tasks that has not reported a completed state"), true);
+});
+
 test("getSystemPrompt does not include runtime context", () => {
   const prompt = getSystemPrompt("/tmp/project");
   assert.equal(prompt.includes("# Local Workspace Environment"), false);

src/tests/session.test.ts

@@ -108,6 +108,49 @@ test("SessionManager preserves structured system content when building OpenAI me
   ]);
 });
 
+test("SessionManager appends failed background log tail as XML", () => {
+  const workspace = createTempDir("deepcode-background-log-workspace-");
+  const home = createTempDir("deepcode-background-log-home-");
+  setHomeDir(home);
+  const outputPath = path.join(workspace, "background.log");
+  fs.writeFileSync(outputPath, ["before", "failure <line> & one", "failure line two"].join("\n"), "utf8");
+  let systemMessage: SessionMessage | null = null;
+  const manager = new SessionManager({
+    projectRoot: workspace,
+    createOpenAIClient: () => ({
+      client: null,
+      model: "test-model",
+      thinkingEnabled: false,
+    }),
+    getResolvedSettings: () => ({ model: "test-model" }),
+    renderMarkdown: (text) => text,
+    onAssistantMessage: (message) => {
+      systemMessage = message;
+    },
+  });
+
+  (manager as any).addBackgroundProcessCompletionMessage("session-background-fail", {
+    command: "npm test",
+    outputPath,
+    ok: false,
+    exitCode: 1,
+    signal: null,
+    startedAtMs: 0,
+    completedAtMs: 1200,
+  });
+
+  assert.ok(systemMessage);
+  const message = systemMessage as SessionMessage;
+  assert.equal(message.role, "system");
+  const content = message.content ?? "";
+  assert.match(content, /Background command "npm test" failed with exit code 1/);
+  assert.match(content, new RegExp(`<background_task_failure_log path="${escapeRegExp(outputPath)}">`));
+  assert.match(content, /failure <line> & one[\s\S]*failure line two/);
+  assert.doesNotMatch(content, /failure &lt;line&gt; &amp; one/);
+  assert.doesNotMatch(content, /<output_path>/);
+  assert.doesNotMatch(content, /<tail>/);
+});
+
 test("SessionManager filters image content for non-multimodal models", () => {
   const manager = new SessionManager({
     projectRoot: process.cwd(),
@@ -499,6 +542,67 @@ rl.on("line", (line) => {
   assert.deepEqual(manager.getMcpStatus(), []);
 });
 
+test("SessionManager dispose kills live processes without timeout controls", (t) => {
+  if (process.platform === "win32") {
+    t.skip("process group kill assertion is non-Windows specific");
+    return;
+  }
+
+  const workspace = createTempDir("deepcode-dispose-process-workspace-");
+  const home = createTempDir("deepcode-dispose-process-home-");
+  setHomeDir(home);
+  const manager = createSessionManager(workspace, "machine-id-dispose-process");
+  const sessionId = createSessionAndMessages(manager, "session-dispose-process", "Dispose process session");
+  const originalKill = process.kill;
+  const killed: Array<{ pid: number; signal?: NodeJS.Signals | number }> = [];
+
+  try {
+    process.kill = ((pid: number, signal?: NodeJS.Signals | number) => {
+      killed.push({ pid, signal });
+      return true;
+    }) as typeof process.kill;
+
+    (manager as any).addSessionProcess(sessionId, 1234, "python3 -m http.server 8080");
+    manager.dispose();
+  } finally {
+    process.kill = originalKill;
+  }
+
+  assert.deepEqual(killed, [{ pid: -1234, signal: "SIGKILL" }]);
+});
+
+test("SessionManager deleteSession ignores persisted processes that are not live", (t) => {
+  if (process.platform === "win32") {
+    t.skip("process group kill assertion is non-Windows specific");
+    return;
+  }
+
+  const workspace = createTempDir("deepcode-delete-stale-process-workspace-");
+  const home = createTempDir("deepcode-delete-stale-process-home-");
+  setHomeDir(home);
+  const manager = createSessionManager(workspace, "machine-id-delete-stale-process");
+  const sessionId = createSessionAndMessages(manager, "session-delete-stale-process", "Delete stale process session");
+  (manager as any).updateSessionEntry(sessionId, (entry: any) => ({
+    ...entry,
+    processes: new Map([["1234", { startTime: new Date().toISOString(), command: "stale process" }]]),
+  }));
+  const originalKill = process.kill;
+  const killed: Array<{ pid: number; signal?: NodeJS.Signals | number }> = [];
+
+  try {
+    process.kill = ((pid: number, signal?: NodeJS.Signals | number) => {
+      killed.push({ pid, signal });
+      return true;
+    }) as typeof process.kill;
+
+    assert.equal(manager.deleteSession(sessionId), true);
+  } finally {
+    process.kill = originalKill;
+  }
+
+  assert.deepEqual(killed, []);
+});
+
 test("SessionManager refreshes cached MCP tool definitions after server crash", async () => {
   const workspace = createTempDir("deepcode-mcp-crash-cache-workspace-");
   const serverPath = path.join(workspace, "mcp-server-crash.cjs");