opencode-orchestrator 0.4.9 → 0.4.13

package/README.md

@@ -28,17 +28,15 @@ A **5-agent autonomous architecture** designed to solve complex engineering task
 
 **Core Philosophy**: Intelligence is a resource. We orchestrate that resource through **Phase-based Workflows** and **Mandatory Environment Scans** to ensure code always fits the project's infrastructure.
 
-> 🦀 **Powered by Rust** — Background tasks and parallel searches run on native Rust binaries for maximum performance.
-
 ### Key Features
-- **🎯 Autonomous Loop** — Commander runs relentlessly until the mission is complete.
+- **🎯 Autonomous Loop** — Commander runs relentlessly until mission is complete.
 - **🔍 Environment Scan** — Mandatory analysis of Infra (Docker/OS), Stack, and Domain before any code change.
 - **🔨 Smart Implementation** — Builder matches existing codebase patterns exactly.
 - **🛡️ Rigorous Audit** — Inspector proves success with environment-specific evidence (Builds/Tests/Logs).
 - **💾 Persistent Context** — Recorder saves session state to disk, enabling resume at any time.
 - **🏗️ Parallel Agents** — Delegated agent execution (`delegate_task`) with sync/async modes.
 - **⏳ Background Tasks** — Run long commands (builds, tests) in background and check results later.
-- **🔎 mgrep** — Multi-pattern parallel search powered by Rust for blazing-fast codebase analysis.
+- **🔎 mgrep** — Multi-pattern parallel search for fast codebase analysis.
 
 ---
 
@@ -95,158 +93,8 @@ Trigger parallel agent execution with prompts like:
 
 Commander will automatically use `delegate_task` with `background: true` for independent tasks.
 
-**Parallel Execution UI**
-
-When tasks run in parallel, you'll see detailed progress in OpenCode:
-
-```
-## 🚀 BACKGROUND TASK SPAWNED
-
-**Task Details**
-- **ID**: `task_a1b2c3d4`
-- **Agent**: builder
-- **Description**: Implement authentication system
-- **Status**: ⏳ Running in background (non-blocking)
-
-**Active Tasks**
-- Running: 2
-- Pending: 1
-
----
-
-**Monitoring Commands**
-
-Check progress anytime:
-- `list_tasks()` - View all parallel tasks
-- `get_task_result({ taskId: "task_a1b2c3d4" })` - Get latest result
-- `cancel_task({ taskId: "task_a1b2c3d4" })` - Stop this task
-
----
-
-✓ System will notify when ALL tasks complete. You can continue working!
-```
-
-**Terminal Logs**
-
 Monitor parallel tasks in terminal:
 
-```
-[parallel] 🚀 SPAWNED task_a1b2c3d4 → builder: Implement authentication
-[parallel] 🚀 SPAWNED task_e5f6g7h8 → inspector: Review module
-[parallel] ✅ COMPLETED task_e5f6g7h8 → inspector: Review module (45s)
-[parallel] 🗑️ CLEANED task_e5f6g7h8 (session deleted)
-```
-
-**All Tasks Complete**
-
-When all parallel tasks finish, you'll see:
-
-```
-**All Parallel Tasks Complete**
-
-✅ `task_a1b2c3d4` (1m 30s): Implement authentication
-✅ `task_e5f6g7h8` (45s): Review module
-
----
-
-**Retrieval Options**
-
-Use `get_task_result({ taskId: "task_xxx" })` to retrieve full results.
-
----
-
-**Task Summary**
-
-Total Tasks: 2
-Status: All Complete
-Mode: Background (non-blocking)
-```
-"Build and test in parallel"
-"Implement feature X while reviewing module Y"
-"Run linting, tests, and build at the same time"
-```
-
-Commander will automatically use `delegate_task` with `background: true` for independent tasks.
-
-**Parallel Execution UI**
-
-When tasks run in parallel, you'll see detailed progress in OpenCode:
-
-```
-╔════════════════════════════════════════════════════════════╗
-║  🚀 BACKGROUND TASK SPAWNED                                   ║
-╠═════════════════════════════════════════════════════════════╣
-║  Task ID:     task_a1b2c3d4                                 ║
-║  Agent:       builder                                           ║
-║  Description: Implement authentication system                       ║
-║  Status:      ⏳ RUNNING (background)                          ║
-╠═════════════════════════════════════════════════════════════╣
-║  Running: 2     │ Pending: 1                                 ║
-╚══════════════════════════════════════════════════════════════╝
-
----
-
-**Parallel Execution Started**
-
-- 📌 Task ID: `task_a1b2c3d4`
-- 🤖 Agent: builder
-- 📝 Description: Implement authentication system
-- ⏳ Status: Running in background (non-blocking)
-- 🔄 Active Tasks: 2 running, 1 pending
-
-**Monitoring**
-
-Check progress anytime with:
-- `list_tasks()` - View all parallel tasks
-- `get_task_result({ taskId: "task_a1b2c3d4" })` - Get latest result
-- `cancel_task({ taskId: "task_a1b2c3d4" })` - Stop this task
-
-System will notify when ALL tasks complete. You can continue working!
-```
-
-**Terminal Logs**
-
-Monitor parallel tasks in terminal:
-
-```
-[parallel] 🚀 SPAWNED task_a1b2c3d4 → builder: Implement authentication
-[parallel] 🚀 SPAWNED task_e5f6g7h8 → inspector: Review module
-[parallel] ✅ COMPLETED task_e5f6g7h8 → inspector: Review module (45s)
-[parallel] 🗑️ CLEANED task_e5f6g7h8 (session deleted)
-```
-
-**All Tasks Complete**
-
-When all parallel tasks finish, you'll see:
-
-```
-**All Parallel Tasks Complete**
-
-✅ `task_a1b2c3d4` (1m 30s): Implement authentication
-✅ `task_e5f6g7h8` (45s): Review module
-
----
-
-**Retrieval Options**
-
-Use `get_task_result({ taskId: "task_xxx" })` to retrieve full results.
-
----
-
-**Task Summary**
-
-Total Tasks: 2
-Status: All Complete
-Mode: Background (non-blocking)
-```
-"Build and test in parallel"
-"Implement feature X while reviewing module Y"
-"Run linting, tests, and build at the same time"
-```
-
-Commander will automatically use `delegate_task` with `background: true` for independent tasks.
-
-Monitor parallel tasks in the terminal:
 ```
 [parallel] 🚀 SPAWNED task_a1b2 → builder: Implement feature X
 [parallel] 🚀 SPAWNED task_c3d4 → inspector: Review module Y

package/dist/core/background.d.ts

@@ -8,6 +8,7 @@ import { ChildProcess } from "child_process";
 export type TaskStatus = "pending" | "running" | "done" | "error" | "timeout";
 export interface BackgroundTask {
     id: string;
+    sessionID?: string;
     command: string;
     args: string[];
     cwd: string;
@@ -26,17 +27,45 @@ export interface RunBackgroundOptions {
     cwd?: string;
     timeout?: number;
     label?: string;
+    sessionID?: string;
 }
 declare class BackgroundTaskManager {
     private static _instance;
     private tasks;
     private debugMode;
+    private storageDir;
+    private storageFile;
+    private monitoringInterval?;
     private constructor();
     static get instance(): BackgroundTaskManager;
     /**
      * Generate a unique task ID in the format job_xxxxxxxx
      */
     private generateId;
+    /**
+     * Ensure storage directory exists
+     */
+    private ensureStorageDir;
+    /**
+     * Load tasks from disk on startup
+     */
+    private loadFromDisk;
+    /**
+     * Save tasks to disk
+     */
+    private saveToDisk;
+    /**
+     * Start periodic monitoring of running processes
+     */
+    private startMonitoring;
+    /**
+     * Stop monitoring
+     */
+    private stopMonitoring;
+    /**
+     * Monitor running processes and detect zombie processes
+     */
+    private monitorRunningProcesses;
     /**
      * Debug logging helper
      */
@@ -57,6 +86,10 @@ declare class BackgroundTaskManager {
      * Get tasks by status
      */
     getByStatus(status: TaskStatus): BackgroundTask[];
+    /**
+     * Clean up tasks by session ID
+     */
+    cleanupBySession(sessionID: string): number;
     /**
      * Clear completed/failed tasks
      */

package/dist/index.d.ts

@@ -82,23 +82,25 @@ declare const OrchestratorPlugin: (input: PluginInput) => Promise<{
                 cwd: import("zod").ZodOptional<import("zod").ZodString>;
                 timeout: import("zod").ZodOptional<import("zod").ZodNumber>;
                 label: import("zod").ZodOptional<import("zod").ZodString>;
+                sessionID: import("zod").ZodOptional<import("zod").ZodString>;
             };
             execute(args: {
                 command: string;
                 cwd?: string | undefined;
                 timeout?: number | undefined;
                 label?: string | undefined;
+                sessionID?: string | undefined;
             }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
         };
         check_background: {
             description: string;
             args: {
-                task_id: import("zod").ZodString;
-                tail_lines: import("zod").ZodOptional<import("zod").ZodNumber>;
+                taskId: import("zod").ZodString;
+                tailLines: import("zod").ZodOptional<import("zod").ZodNumber>;
             };
             execute(args: {
-                task_id: string;
-                tail_lines?: number | undefined;
+                taskId: string;
+                tailLines?: number | undefined;
             }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
         };
         list_background: {
@@ -106,22 +108,22 @@ declare const OrchestratorPlugin: (input: PluginInput) => Promise<{
             args: {
                 status: import("zod").ZodOptional<import("zod").ZodEnum<{
                     running: "running";
-                    all: "all";
                     done: "done";
                     error: "error";
+                    all: "all";
                 }>>;
             };
             execute(args: {
-                status?: "running" | "all" | "done" | "error" | undefined;
+                status?: "running" | "done" | "error" | "all" | undefined;
             }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
         };
         kill_background: {
             description: string;
             args: {
-                task_id: import("zod").ZodString;
+                taskId: import("zod").ZodString;
             };
             execute(args: {
-                task_id: string;
+                taskId: string;
             }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
         };
     };

package/dist/index.js

@@ -99,8 +99,8 @@ PREFER background=true (PARALLEL):
 EXAMPLE - PARALLEL:
 \`\`\`
 // Multiple tasks in parallel
-delegate_task({ agent: "builder", description: "Implement X", prompt: "...", background: true })
-delegate_task({ agent: "inspector", description: "Review Y", prompt: "...", background: true })
+delegate_task({ agent: "${AGENT_NAMES.BUILDER}", description: "Implement X", prompt: "...", background: true })
+delegate_task({ agent: "${AGENT_NAMES.INSPECTOR}", description: "Review Y", prompt: "...", background: true })
 
 // Continue other work (don't wait!)
 
@@ -111,7 +111,7 @@ get_task_result({ taskId: "task_xxx" })
 EXAMPLE - SYNC (rare):
 \`\`\`
 // Only when you absolutely need the result now
-const result = delegate_task({ agent: "builder", ..., background: false })
+const result = delegate_task({ agent: "${AGENT_NAMES.BUILDER}", ..., background: false })
 // Result is immediately available
 \`\`\`
 </agent_calling>
@@ -138,10 +138,10 @@ During implementation:
 PARALLEL EXECUTION TOOLS:
 
 1. **spawn_agent** - Launch agents in parallel sessions
-   spawn_agent({ agent: "builder", description: "Implement X", prompt: "..." })
-   spawn_agent({ agent: "inspector", description: "Review Y", prompt: "..." })
-   \u2192 Agents run concurrently, system notifies when ALL complete
-   \u2192 Use get_task_result({ taskId }) to retrieve results
+    spawn_agent({ agent: "${AGENT_NAMES.BUILDER}", description: "Implement X", prompt: "..." })
+    spawn_agent({ agent: "${AGENT_NAMES.INSPECTOR}", description: "Review Y", prompt: "..." })
+    \u2192 Agents run concurrently, system notifies when ALL complete
+    \u2192 Use get_task_result({ taskId }) to retrieve results
 
 2. **run_background** - Run shell commands asynchronously
    run_background({ command: "npm run build" })
@@ -192,10 +192,10 @@ WORKFLOW:
 <empty_responses>
 | Agent Empty (or Gibberish) | Action |
 |----------------------------|--------|
-| recorder | Fresh start. Proceed to survey. |
-| architect | Try simpler plan yourself. |
-| builder | Call inspector to diagnose. |
-| inspector | Retry with more context. |
+| ${AGENT_NAMES.RECORDER} | Fresh start. Proceed to survey. |
+| ${AGENT_NAMES.ARCHITECT} | Try simpler plan yourself. |
+| ${AGENT_NAMES.BUILDER} | Call inspector to diagnose. |
+| ${AGENT_NAMES.INSPECTOR} | Retry with more context. |
 </empty_responses>
 
 STRICT RULE: If any agent output contains gibberish, mixed-language hallucinations, or fails the language rule, REJECT it immediately and trigger a "STRICT_CLEAN_START" retry.
@@ -13319,9 +13319,357 @@ Returns matches grouped by pattern, with file paths and line numbers.
   }
 });
 
+// src/core/background.ts
+import { spawn as spawn2 } from "child_process";
+import { randomBytes } from "crypto";
+import { mkdirSync, readFileSync, writeFileSync, existsSync as existsSync3 } from "fs";
+import { join as join2 } from "path";
+import { homedir } from "os";
+var BackgroundTaskManager = class _BackgroundTaskManager {
+  static _instance;
+  tasks = /* @__PURE__ */ new Map();
+  debugMode = true;
+  // Enable debug mode
+  storageDir;
+  storageFile;
+  monitoringInterval;
+  constructor() {
+    this.storageDir = join2(homedir(), ".opencode-orchestrator");
+    this.storageFile = join2(this.storageDir, "tasks.json");
+    this.loadFromDisk();
+    this.startMonitoring();
+  }
+  static get instance() {
+    if (!_BackgroundTaskManager._instance) {
+      _BackgroundTaskManager._instance = new _BackgroundTaskManager();
+    }
+    return _BackgroundTaskManager._instance;
+  }
+  /**
+   * Generate a unique task ID in the format job_xxxxxxxx
+   */
+  generateId() {
+    const hex3 = randomBytes(4).toString("hex");
+    return `job_${hex3}`;
+  }
+  /**
+   * Ensure storage directory exists
+   */
+  ensureStorageDir() {
+    if (!existsSync3(this.storageDir)) {
+      mkdirSync(this.storageDir, { recursive: true });
+      this.debug("system", `Created storage directory: ${this.storageDir}`);
+    }
+  }
+  /**
+   * Load tasks from disk on startup
+   */
+  loadFromDisk() {
+    this.ensureStorageDir();
+    if (!existsSync3(this.storageFile)) {
+      this.debug("system", "No existing task data on disk");
+      return;
+    }
+    try {
+      const data = readFileSync(this.storageFile, "utf-8");
+      const tasksData = JSON.parse(data);
+      for (const [id, taskData] of Object.entries(tasksData)) {
+        const task = taskData;
+        task.process = void 0;
+        if (task.status === "running") {
+          task.status = "error";
+          task.errorOutput += "\n[Process lost on restart]";
+          task.endTime = Date.now();
+          task.exitCode = null;
+        }
+        this.tasks.set(id, task);
+      }
+      this.debug("system", `Loaded ${this.tasks.size} tasks from disk`);
+    } catch (error45) {
+      this.debug(
+        "system",
+        `Failed to load tasks: ${error45 instanceof Error ? error45.message : String(error45)}`
+      );
+    }
+  }
+  /**
+   * Save tasks to disk
+   */
+  saveToDisk() {
+    this.ensureStorageDir();
+    try {
+      const tasksData = {};
+      for (const [id, task] of this.tasks.entries()) {
+        tasksData[id] = task;
+      }
+      writeFileSync(
+        this.storageFile,
+        JSON.stringify(tasksData, null, 2),
+        "utf-8"
+      );
+    } catch (error45) {
+      this.debug(
+        "system",
+        `Failed to save tasks: ${error45 instanceof Error ? error45.message : String(error45)}`
+      );
+    }
+  }
+  /**
+   * Start periodic monitoring of running processes
+   */
+  startMonitoring() {
+    const MONITOR_INTERVAL_MS = 5e3;
+    this.monitoringInterval = setInterval(() => {
+      this.monitorRunningProcesses();
+    }, MONITOR_INTERVAL_MS);
+    if (this.monitoringInterval) {
+      this.monitoringInterval.unref();
+    }
+  }
+  /**
+   * Stop monitoring
+   */
+  stopMonitoring() {
+    if (this.monitoringInterval) {
+      clearInterval(this.monitoringInterval);
+      this.monitoringInterval = void 0;
+    }
+  }
+  /**
+   * Monitor running processes and detect zombie processes
+   */
+  monitorRunningProcesses() {
+    const now = Date.now();
+    let hasRunningTasks = false;
+    for (const [id, task] of this.tasks.entries()) {
+      if (task.status !== "running") continue;
+      hasRunningTasks = true;
+      if (task.process && task.process.pid) {
+        const pid = task.process.pid;
+        try {
+          process.kill(pid, 0);
+        } catch (error45) {
+          task.status = "error";
+          task.errorOutput += `
+Process disappeared (PID ${pid})`;
+          task.endTime = Date.now();
+          task.exitCode = null;
+          task.process = void 0;
+          this.saveToDisk();
+          this.debug(id, `Process dead (PID ${pid}), marked as error`);
+        }
+      } else if (task.process) {
+        task.status = "error";
+        task.errorOutput += "\nProcess reference lost";
+        task.endTime = Date.now();
+        task.exitCode = null;
+        this.saveToDisk();
+        this.debug(id, "Process reference lost, marked as error");
+      }
+    }
+    if (!hasRunningTasks && this.monitoringInterval) {
+      this.stopMonitoring();
+    }
+  }
+  /**
+   * Debug logging helper
+   */
+  debug(taskId, message) {
+    if (this.debugMode) {
+      const timestamp = (/* @__PURE__ */ new Date()).toISOString().substring(11, 23);
+      console.log(`[BG-DEBUG ${timestamp}] ${taskId}: ${message}`);
+    }
+  }
+  /**
+   * Run a command in the background
+   */
+  run(options) {
+    const id = this.generateId();
+    const { command, cwd = process.cwd(), timeout = 3e5, label } = options;
+    const isWindows = process.platform === "win32";
+    const shell = isWindows ? "cmd.exe" : "/bin/sh";
+    const shellFlag = isWindows ? "/c" : "-c";
+    const task = {
+      id,
+      command,
+      args: [shellFlag, command],
+      cwd,
+      label,
+      status: "running",
+      output: "",
+      errorOutput: "",
+      exitCode: null,
+      startTime: Date.now(),
+      timeout
+    };
+    this.tasks.set(id, task);
+    this.saveToDisk();
+    this.debug(id, `Starting: ${command} (cwd: ${cwd})`);
+    try {
+      const proc = spawn2(shell, task.args, {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: false
+      });
+      task.process = proc;
+      proc.stdout?.on("data", (data) => {
+        const text = data.toString();
+        task.output += text;
+        this.debug(
+          id,
+          `stdout: ${text.substring(0, 100)}${text.length > 100 ? "..." : ""}`
+        );
+      });
+      proc.stderr?.on("data", (data) => {
+        const text = data.toString();
+        task.errorOutput += text;
+        this.debug(
+          id,
+          `stderr: ${text.substring(0, 100)}${text.length > 100 ? "..." : ""}`
+        );
+      });
+      proc.on("close", (code) => {
+        task.exitCode = code;
+        task.endTime = Date.now();
+        task.status = code === 0 ? "done" : "error";
+        task.process = void 0;
+        this.saveToDisk();
+        const duration3 = ((task.endTime - task.startTime) / 1e3).toFixed(2);
+        this.debug(id, `Completed with code ${code} in ${duration3}s`);
+      });
+      proc.on("error", (err) => {
+        task.status = "error";
+        task.errorOutput += `
+Process error: ${err.message}`;
+        task.endTime = Date.now();
+        task.process = void 0;
+        this.saveToDisk();
+        this.debug(id, `Error: ${err.message}`);
+      });
+      setTimeout(() => {
+        if (task.status === "running" && task.process) {
+          this.debug(id, `Timeout after ${timeout}ms, killing process`);
+          task.process.kill("SIGKILL");
+          task.status = "timeout";
+          task.endTime = Date.now();
+          task.errorOutput += `
+Process killed: timeout after ${timeout}ms`;
+          this.saveToDisk();
+        }
+      }, timeout);
+    } catch (err) {
+      task.status = "error";
+      task.errorOutput = `Failed to spawn: ${err instanceof Error ? err.message : String(err)}`;
+      task.endTime = Date.now();
+      this.saveToDisk();
+      this.debug(id, `Spawn failed: ${task.errorOutput}`);
+    }
+    return task;
+  }
+  /**
+   * Get task by ID
+   */
+  get(taskId) {
+    return this.tasks.get(taskId);
+  }
+  /**
+   * Get all tasks
+   */
+  getAll() {
+    return Array.from(this.tasks.values());
+  }
+  /**
+   * Get tasks by status
+   */
+  getByStatus(status) {
+    return this.getAll().filter((t) => t.status === status);
+  }
+  /**
+   * Clean up tasks by session ID
+   */
+  cleanupBySession(sessionID) {
+    let count = 0;
+    for (const [id, task] of this.tasks) {
+      if (task.sessionID === sessionID) {
+        if (task.process && task.status === "running") {
+          task.process.kill("SIGKILL");
+        }
+        this.tasks.delete(id);
+        count++;
+        this.debug(id, `Cleaned up for session ${sessionID}`);
+      }
+    }
+    this.saveToDisk();
+    return count;
+  }
+  /**
+   * Clear completed/failed tasks
+   */
+  clearCompleted() {
+    let count = 0;
+    for (const [id, task] of this.tasks) {
+      if (task.status !== "running" && task.status !== "pending") {
+        this.tasks.delete(id);
+        count++;
+      }
+    }
+    this.saveToDisk();
+    return count;
+  }
+  /**
+   * Kill a running task
+   */
+  kill(taskId) {
+    const task = this.tasks.get(taskId);
+    if (task?.process) {
+      task.process.kill("SIGKILL");
+      task.status = "error";
+      task.errorOutput += "\nKilled by user";
+      task.endTime = Date.now();
+      this.saveToDisk();
+      this.debug(taskId, "Killed by user");
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Format duration for display
+   */
+  formatDuration(task) {
+    const end = task.endTime || Date.now();
+    const seconds = (end - task.startTime) / 1e3;
+    if (seconds < 60) {
+      return `${seconds.toFixed(1)}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m ${remainingSeconds.toFixed(0)}s`;
+  }
+  /**
+   * Get status emoji
+   */
+  getStatusEmoji(status) {
+    switch (status) {
+      case "pending":
+        return "\u23F8\uFE0F";
+      case "running":
+        return "\u23F3";
+      case "done":
+        return "\u2705";
+      case "error":
+        return "\u274C";
+      case "timeout":
+        return "\u23F0";
+      default:
+        return "\u2753";
+    }
+  }
+};
+var backgroundTaskManager = BackgroundTaskManager.instance;
+
 // src/tools/background.ts
 var runBackgroundTool = tool({
-  description: `Run a shell command in background and get a task ID.
+  description: `Run a shell command in the background and get a task ID.
 
 <purpose>
 Execute long-running commands (builds, tests, etc.) without blocking.
@@ -13344,10 +13692,31 @@ The command runs asynchronously - use check_background to get results.
     command: tool.schema.string().describe("Shell command to execute"),
     cwd: tool.schema.string().optional().describe("Working directory (default: project root)"),
     timeout: tool.schema.number().optional().describe("Timeout in milliseconds (default: 300000 = 5 min)"),
-    label: tool.schema.string().optional().describe("Human-readable label for this task")
+    label: tool.schema.string().optional().describe("Human-readable label for this task"),
+    sessionID: tool.schema.string().optional().describe("Session ID for automatic cleanup on session deletion")
   },
   async execute(args) {
-    return callRustTool("run_background", args);
+    const { command, cwd, timeout, label, sessionID } = args;
+    const task = backgroundTaskManager.run({
+      command,
+      cwd: cwd || process.cwd(),
+      timeout: timeout || 3e5,
+      label,
+      sessionID
+    });
+    const displayLabel = label ? ` (${label})` : "";
+    return `\u{1F680} **Background Task Started**${displayLabel}
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+| Property | Value |
+|----------|-------|
+| **Task ID** | \`${task.id}\` |
+| **Command** | \`${command}\` |
+| **Status** | ${backgroundTaskManager.getStatusEmoji(task.status)} ${task.status} |
+| **Working Dir** | ${task.cwd} |
+| **Timeout** | ${(task.timeout / 1e3).toFixed(0)}s |
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+\u{1F4CC} **Next Step**: Use \`check_background\` with task ID \`${task.id}\` to get results.`;
   }
 });
 var checkBackgroundTool = tool({
@@ -13365,11 +13734,75 @@ Use this after run_background to get results.
 - Full output (stdout + stderr)
 </output_includes>`,
   args: {
-    task_id: tool.schema.string().describe("Task ID from run_background (e.g., job_a1b2c3d4)"),
-    tail_lines: tool.schema.number().optional().describe("Limit output to last N lines (default: show all)")
+    taskId: tool.schema.string().describe("Task ID from run_background (e.g., job_a1b2c3d4)"),
+    tailLines: tool.schema.number().optional().describe("Limit output to last N lines (default: show all)")
   },
   async execute(args) {
-    return callRustTool("check_background", args);
+    const { taskId, tailLines } = args;
+    const task = backgroundTaskManager.get(taskId);
+    if (!task) {
+      const allTasks = backgroundTaskManager.getAll();
+      if (allTasks.length === 0) {
+        return `\u274C Task \`${taskId}\` not found. No background tasks exist.`;
+      }
+      const taskList = allTasks.map((t) => `- \`${t.id}\`: ${t.command.substring(0, 30)}...`).join("\n");
+      return `\u274C Task \`${taskId}\` not found.
+
+**Available tasks:**
+${taskList}`;
+    }
+    const duration3 = backgroundTaskManager.formatDuration(task);
+    const statusEmoji = backgroundTaskManager.getStatusEmoji(task.status);
+    let output = task.output;
+    let stderr = task.errorOutput;
+    if (tailLines && tailLines > 0) {
+      const outputLines = output.split("\n");
+      const stderrLines = stderr.split("\n");
+      output = outputLines.slice(-tailLines).join("\n");
+      stderr = stderrLines.slice(-tailLines).join("\n");
+    }
+    const maxLen = 1e4;
+    if (output.length > maxLen) {
+      output = `[...truncated ${output.length - maxLen} chars...]
+` + output.substring(output.length - maxLen);
+    }
+    if (stderr.length > maxLen) {
+      stderr = `[...truncated ${stderr.length - maxLen} chars...]
+` + stderr.substring(stderr.length - maxLen);
+    }
+    const labelDisplay = task.label ? ` (${task.label})` : "";
+    let result = `${statusEmoji} **Task ${task.id}**${labelDisplay}
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+| Property | Value |
+|----------|-------|
+| **Command** | \`${task.command}\` |
+| **Status** | ${statusEmoji} **${task.status.toUpperCase()}** |
+| **Duration** | ${duration3}${task.status === "running" ? " (ongoing)" : ""} |
+${task.exitCode !== null ? `| **Exit Code** | ${task.exitCode} |` : ""}
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`;
+    if (output.trim()) {
+      result += `
+
+\u{1F4E4} **Output (stdout)**:
+\`\`\`
+${output.trim()}
+\`\`\``;
+    }
+    if (stderr.trim()) {
+      result += `
+
+\u26A0\uFE0F **Errors (stderr)**:
+\`\`\`
+${stderr.trim()}
+\`\`\``;
+    }
+    if (task.status === "running") {
+      result += `
+
+\u23F3 Task still running... Check again later with:
+\`check_background({ taskId: "${task.id}" })\``;
+    }
+    return result;
   }
 });
 var listBackgroundTool = tool({
@@ -13383,7 +13816,39 @@ Useful to check what's in progress before starting new tasks.
     status: tool.schema.enum(["all", "running", "done", "error"]).optional().describe("Filter by status (default: all)")
   },
   async execute(args) {
-    return callRustTool("list_background", args);
+    const { status = "all" } = args;
+    let tasks;
+    if (status === "all") {
+      tasks = backgroundTaskManager.getAll();
+    } else {
+      tasks = backgroundTaskManager.getByStatus(status);
+    }
+    if (tasks.length === 0) {
+      return `\u{1F4CB} **No background tasks** ${status !== "all" ? `with status "${status}"` : ""}
+
+Use \`run_background\` to start a new background task.`;
+    }
+    tasks.sort((a, b) => b.startTime - a.startTime);
+    const rows = tasks.map((task) => {
+      const emoji3 = backgroundTaskManager.getStatusEmoji(task.status);
+      const duration3 = backgroundTaskManager.formatDuration(task);
+      const cmdShort = task.command.length > 25 ? task.command.substring(0, 22) + "..." : task.command;
+      const labelPart = task.label ? ` [${task.label}]` : "";
+      return `| \`${task.id}\` | ${emoji3} ${task.status.padEnd(7)} | ${cmdShort.padEnd(25)}${labelPart} | ${duration3.padStart(8)} |`;
+    }).join("\n");
+    const runningCount = tasks.filter((t) => t.status === "running").length;
+    const doneCount = tasks.filter((t) => t.status === "done").length;
+    const errorCount = tasks.filter((t) => t.status === "error" || t.status === "timeout").length;
+    return `\u{1F4CB} **Background Tasks** (${tasks.length} total)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+| \u23F3 Running: ${runningCount} | \u2705 Done: ${doneCount} | \u274C Error/Timeout: ${errorCount} |
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+| Task ID | Status | Command | Duration |
+|---------|--------|---------|----------|
+${rows}
+
+\u{1F4A1} Use \`check_background({ taskId: "job_xxxxx" })\` to see full output.`;
   }
 });
 var killBackgroundTool = tool({
@@ -13393,10 +13858,24 @@ var killBackgroundTool = tool({
 Stop a background task that is taking too long or no longer needed.
 </purpose>`,
   args: {
-    task_id: tool.schema.string().describe("Task ID to kill (e.g., job_a1b2c3d4)")
+    taskId: tool.schema.string().describe("Task ID to kill (e.g., job_a1b2c3d4)")
   },
   async execute(args) {
-    return callRustTool("kill_background", args);
+    const { taskId } = args;
+    const task = backgroundTaskManager.get(taskId);
+    if (!task) {
+      return `\u274C Task \`${taskId}\` not found.`;
+    }
+    if (task.status !== "running") {
+      return `\u26A0\uFE0F Task \`${taskId}\` is not running (status: ${task.status}).`;
+    }
+    const killed = backgroundTaskManager.kill(taskId);
+    if (killed) {
+      return `\u{1F6D1} Task \`${taskId}\` has been killed.
+Command: \`${task.command}\`
+Duration before kill: ${backgroundTaskManager.formatDuration(task)}`;
+    }
+    return `\u26A0\uFE0F Could not kill task \`${taskId}\`. It may have already finished.`;
   }
 });
 
@@ -13922,10 +14401,14 @@ var createDelegateTaskTool = (manager, client) => tool({
 - Auto-cleanup: 5 minutes after completion
 </safety>`,
   args: {
-    agent: tool.schema.string().describe("Agent name (e.g., 'builder', 'inspector', 'architect')"),
+    agent: tool.schema.string().describe(
+      `Agent name (e.g., '${AGENT_NAMES.BUILDER}', '${AGENT_NAMES.INSPECTOR}', '${AGENT_NAMES.ARCHITECT}')`
+    ),
     description: tool.schema.string().describe("Short task description"),
     prompt: tool.schema.string().describe("Full prompt/instructions for the agent"),
-    background: tool.schema.boolean().describe("true=async (returns task_id), false=sync (waits for result). REQUIRED.")
+    background: tool.schema.boolean().describe(
+      "true=async (returns task_id), false=sync (waits for result). REQUIRED."
+    )
   },
   async execute(args, context) {
     const { agent, description, prompt, background } = args;
@@ -13946,7 +14429,9 @@ var createDelegateTaskTool = (manager, client) => tool({
         });
         const runningCount = manager.getRunningTasks().length;
         const pendingCount = manager.getPendingCount(ctx.sessionID);
-        console.log(`[parallel] \u{1F680} SPAWNED ${task.id} \u2192 ${agent}: ${description}`);
+        console.log(
+          `[parallel] \u{1F680} SPAWNED ${task.id} \u2192 ${agent}: ${description}`
+        );
         return `
 ## \u{1F680} BACKGROUND TASK SPAWNED
 
@@ -14025,7 +14510,9 @@ Session ID: ${sessionID}`;
           continue;
         }
         if (Date.now() - startTime < MIN_STABILITY_MS2) continue;
-        const messagesResult2 = await session.messages({ path: { id: sessionID } });
+        const messagesResult2 = await session.messages({
+          path: { id: sessionID }
+        });
         const messages2 = messagesResult2.data ?? [];
         const currentMsgCount = messages2.length;
         if (currentMsgCount === lastMsgCount) {
@@ -14036,7 +14523,9 @@ Session ID: ${sessionID}`;
           lastMsgCount = currentMsgCount;
         }
       }
-      const messagesResult = await session.messages({ path: { id: sessionID } });
+      const messagesResult = await session.messages({
+        path: { id: sessionID }
+      });
       const messages = messagesResult.data ?? [];
       const assistantMsgs = messages.filter((m) => m.info?.role === "assistant").reverse();
       const lastMsg = assistantMsgs[0];
@@ -14050,7 +14539,9 @@ Session ID: ${sessionID}`;
       ) ?? [];
       const textContent = textParts.map((p) => p.text ?? "").filter(Boolean).join("\n");
       const duration3 = Math.floor((Date.now() - startTime) / 1e3);
-      console.log(`[delegate] \u2705 COMPLETED ${agent}: ${description} (${duration3}s)`);
+      console.log(
+        `[delegate] \u2705 COMPLETED ${agent}: ${description} (${duration3}s)`
+      );
       return `\u2705 **Task Completed** (${duration3}s)
 
 Agent: ${agent}
@@ -14085,7 +14576,9 @@ Wait for the "All Complete" notification before checking.
 Use \`list_tasks\` to see available tasks.`;
     }
     if (task.status === "running") {
-      const elapsed = Math.floor((Date.now() - task.startedAt.getTime()) / 1e3);
+      const elapsed = Math.floor(
+        (Date.now() - task.startedAt.getTime()) / 1e3
+      );
       return `\u23F3 **Task Still Running**
 
 | Property | Value |
@@ -14167,7 +14660,9 @@ Use \`delegate_task({ ..., background: true })\` to spawn background tasks.`;
       }
     };
     const rows = tasks.map((t) => {
-      const elapsed = Math.floor((Date.now() - t.startedAt.getTime()) / 1e3);
+      const elapsed = Math.floor(
+        (Date.now() - t.startedAt.getTime()) / 1e3
+      );
       const desc = t.description.length > 25 ? t.description.slice(0, 22) + "..." : t.description;
       return `| \`${t.id}\` | ${statusIcon(t.status)} ${t.status} | ${t.agent} | ${desc} | ${elapsed}s |`;
     }).join("\n");
@@ -14352,11 +14847,11 @@ var PLUGIN_VERSION = "0.2.4";
 var DEFAULT_MAX_STEPS = 500;
 var TASK_COMMAND_MAX_STEPS = 1e3;
 var AGENT_EMOJI2 = {
-  "architect": "\u{1F3D7}\uFE0F",
-  "builder": "\u{1F528}",
-  "inspector": "\u{1F50D}",
-  "recorder": "\u{1F4BE}",
-  "commander": "\u{1F3AF}"
+  [AGENT_NAMES.ARCHITECT]: "\u{1F3D7}\uFE0F",
+  [AGENT_NAMES.BUILDER]: "\u{1F528}",
+  [AGENT_NAMES.INSPECTOR]: "\u{1F50D}",
+  [AGENT_NAMES.RECORDER]: "\u{1F4BE}",
+  [AGENT_NAMES.COMMANDER]: "\u{1F3AF}"
 };
 var CONTINUE_INSTRUCTION = `<auto_continue>
 <status>Mission not complete. Keep executing.</status>
@@ -14415,7 +14910,7 @@ var OrchestratorPlugin = async (input) => {
       }
       const orchestratorAgents = {
         Commander: {
-          name: "Commander",
+          name: AGENT_NAMES.COMMANDER,
           description: "Autonomous orchestrator - executes until mission complete",
           systemPrompt: AGENTS.commander.systemPrompt
         }
@@ -14435,7 +14930,7 @@ var OrchestratorPlugin = async (input) => {
       const parsed = detectSlashCommand(originalText);
       const sessionID = msgInput.sessionID;
       const agentName = (msgInput.agent || "").toLowerCase();
-      if (agentName === "commander" && !sessions.has(sessionID)) {
+      if (agentName === AGENT_NAMES.COMMANDER && !sessions.has(sessionID)) {
         const now = Date.now();
         sessions.set(sessionID, {
           active: true,
@@ -14712,8 +15207,13 @@ ${stateSession.graph.getTaskSummary()}`;
       if (event.type === "session.deleted") {
         const props = event.properties;
         if (props?.info?.id) {
-          sessions.delete(props.info.id);
-          state.sessions.delete(props.info.id);
+          const sessionID = props.info.id;
+          sessions.delete(sessionID);
+          state.sessions.delete(sessionID);
+          const cleanedCount = backgroundTaskManager.cleanupBySession(sessionID);
+          if (cleanedCount > 0) {
+            console.log(`[background] Cleaned up ${cleanedCount} tasks for deleted session ${sessionID}`);
+          }
         }
       }
     }

package/dist/tools/background.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Background Task Tools for OpenCode Orchestrator
+ *
+ * These tools allow the AI to run commands in the background and check their results later.
+ * This is useful for long-running builds, tests, or other operations.
+ */
 export declare const runBackgroundTool: {
     description: string;
     args: {
@@ -5,23 +11,25 @@ export declare const runBackgroundTool: {
         cwd: import("zod").ZodOptional<import("zod").ZodString>;
         timeout: import("zod").ZodOptional<import("zod").ZodNumber>;
         label: import("zod").ZodOptional<import("zod").ZodString>;
+        sessionID: import("zod").ZodOptional<import("zod").ZodString>;
     };
     execute(args: {
         command: string;
         cwd?: string | undefined;
         timeout?: number | undefined;
         label?: string | undefined;
+        sessionID?: string | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 export declare const checkBackgroundTool: {
     description: string;
     args: {
-        task_id: import("zod").ZodString;
-        tail_lines: import("zod").ZodOptional<import("zod").ZodNumber>;
+        taskId: import("zod").ZodString;
+        tailLines: import("zod").ZodOptional<import("zod").ZodNumber>;
     };
     execute(args: {
-        task_id: string;
-        tail_lines?: number | undefined;
+        taskId: string;
+        tailLines?: number | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 export declare const listBackgroundTool: {
@@ -29,21 +37,21 @@ export declare const listBackgroundTool: {
     args: {
         status: import("zod").ZodOptional<import("zod").ZodEnum<{
             running: "running";
-            all: "all";
             done: "done";
             error: "error";
+            all: "all";
         }>>;
     };
     execute(args: {
-        status?: "running" | "all" | "done" | "error" | undefined;
+        status?: "running" | "done" | "error" | "all" | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 export declare const killBackgroundTool: {
     description: string;
     args: {
-        task_id: import("zod").ZodString;
+        taskId: import("zod").ZodString;
     };
     execute(args: {
-        task_id: string;
+        taskId: string;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "opencode-orchestrator",
   "displayName": "OpenCode Orchestrator",
   "description": "Distributed Cognitive Architecture for OpenCode. Turns simple prompts into specialized multi-agent workflows (Planner, Coder, Reviewer).",
-  "version": "0.4.9",
+  "version": "0.4.13",
   "author": "agnusdei1207",
   "license": "MIT",
   "repository": {