@cdoing/core 0.1.0

package/src/tools/shell-exec.ts

@@ -0,0 +1,251 @@
+import { exec } from "child_process";
+import * as os from "os";
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import type { SandboxManager } from "../sandbox";
+import type { PermissionManager } from "../permissions";
+import { extractShellPaths } from "../utils/shell-paths";
+
+const IS_WINDOWS = os.platform() === "win32";
+
+/**
+ * Get the shell command and args for the current platform.
+ * - Windows: PowerShell (more capable than cmd.exe)
+ * - macOS: user's shell with login flag (loads .zshrc/.bashrc for PATH, nvm, pyenv, etc.)
+ * - Linux: user's shell with login flag
+ */
+function getShellCommand(command: string): { shell: string; args: string[] } {
+  if (IS_WINDOWS) {
+    return {
+      shell: "powershell.exe",
+      args: ["-NoLogo", "-ExecutionPolicy", "Bypass", "-Command", command],
+    };
+  }
+  const userShell = process.env.SHELL || (os.platform() === "darwin" ? "/bin/zsh" : "/bin/bash");
+  return { shell: userShell, args: ["-l", "-c", command] };
+}
+
+/** For exec() — the shell to use */
+const SHELL = IS_WINDOWS ? "powershell.exe" : process.env.SHELL || "/bin/sh";
+
+/** Color-supporting environment variables */
+const COLOR_ENV = {
+  FORCE_COLOR: "1",
+  COLORTERM: "truecolor",
+  TERM: "xterm-256color",
+  CLICOLOR: "1",
+  CLICOLOR_FORCE: "1",
+};
+
+/** Absolute danger — always blocked regardless of permissions */
+const ALWAYS_BLOCKED = [
+  // Unix — catastrophic filesystem destruction
+  "rm -rf /",
+  "rm -rf ~",
+  "rm -rf /*",
+  "rm -rf ~/*",
+  "rm -rf $HOME",
+  "mkfs",
+  "dd if=",
+  ":(){",           // fork bomb
+  // Windows — catastrophic filesystem destruction
+  "rd /s /q C:\\",
+  "del /f /s /q C:\\",
+  "format C:",
+  "rd /s /q %systemroot%",
+];
+
+/** Destructive patterns for elevated permission message */
+const DESTRUCTIVE_PATTERNS = [
+  // File deletion (Unix)
+  /\brm\s/, /\brm$/, /\brmdir\s/, /\bunlink\s/, /\bshred\s/,
+  // File deletion (Windows)
+  /\bdel\s/, /\brd\s/, /\berase\s/,
+  // Git destructive operations
+  /\bgit\s+clean\b/,
+  /\bgit\s+reset\s+--hard\b/,
+  /\bgit\s+push\s+.*--force\b/, /\bgit\s+push\s+-f\b/,
+  /\bgit\s+checkout\s+--\s/, /\bgit\s+restore\s/,
+  /\bgit\s+branch\s+-[dD]\b/,
+  /\bgit\s+rebase\b/,
+  /\bgit\s+stash\s+drop\b/,
+  // Process killing
+  /\bkill\s+-9\b/, /\bkillall\b/, /\bpkill\b/,
+  // Permission changes
+  /\bchmod\s+777\b/, /\bchmod\s+-R\b/, /\bchown\s+-R\b/,
+  // Database destructive (SQL injection risk via shell)
+  /\bDROP\s+(TABLE|DATABASE)\b/i, /\bTRUNCATE\s+TABLE\b/i, /\bDELETE\s+FROM\b/i,
+  // Disk/system
+  /\bdd\s/, /\bmv\s+\//, /\bsudo\s/,
+  // Docker destructive
+  /\bdocker\s+(rm|rmi|system\s+prune)\b/,
+  // npm/package destructive
+  /\bnpm\s+unpublish\b/,
+];
+
+
+export class ShellExecTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "shell_exec",
+    description:
+      `Execute a shell command and return its output. Use for builds, tests, git commands, etc. Requires user permission before execution.
+
+All file paths in commands are checked against permission rules:
+- Read paths (cat, less, grep, etc.) are checked against Read deny rules.
+- Write paths (cp, mv, redirect >, tee, etc.) are checked against Edit deny rules.
+- Delete paths (rm, rmdir, unlink, etc.) are checked against Delete deny rules.
+- Destructive commands are flagged as high-risk in the permission prompt.
+
+Commands are also subject to sandbox restrictions.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: "The shell command to execute" },
+        timeout: { type: "number", description: "Timeout in ms. Default: 120000" },
+        background: {
+          type: "boolean",
+          description: "Run in background. Returns immediately with PID. Use for servers/watchers. Default: false.",
+        },
+        env_vars: {
+          type: "object",
+          description: "Environment variables to set (e.g., {\"PORT\": \"3001\", \"DEBUG\": \"app:*\"})",
+          additionalProperties: { type: "string" },
+        },
+        debug: {
+          type: "boolean",
+          description: "Enable debug/verbose mode. Sets DEBUG=*, NODE_DEBUG=*, RUST_BACKTRACE=1, PYTHONTRACEBACK=1. Default: false",
+        },
+        dangerouslyDisableSandbox: {
+          type: "boolean",
+          description: "Set to true to run this command outside the sandbox. Requires permission approval.",
+        },
+      },
+      required: ["command"],
+    },
+    requiresPermission: true,
+    permissionMessage: (input) => {
+      const cmd = String(input.command || "");
+      if (DESTRUCTIVE_PATTERNS.some((p) => p.test(cmd))) {
+        return `⚠ DESTRUCTIVE command: ${cmd}`;
+      }
+      return `Run command: ${cmd}`;
+    },
+  };
+
+  private workingDir: string;
+  private sandboxManager?: SandboxManager;
+  private permissionManager?: PermissionManager;
+
+  constructor(workingDir: string, sandboxManager?: SandboxManager, permissionManager?: PermissionManager) {
+    this.workingDir = workingDir;
+    this.sandboxManager = sandboxManager;
+    this.permissionManager = permissionManager;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const command = input.command as string;
+    const timeout = (input.timeout as number) || 120000;
+    const dangerouslyDisableSandbox = (input.dangerouslyDisableSandbox as boolean) || false;
+
+    // Always-blocked patterns (catastrophic destruction)
+    for (const pat of ALWAYS_BLOCKED) {
+      if (command.includes(pat))
+        return { success: false, output: "", error: `Blocked dangerous pattern: ${pat}` };
+    }
+
+    // ── Permission-based path checks ────────────────────────────────────────
+    if (this.permissionManager) {
+      const paths = extractShellPaths(command, this.workingDir);
+
+      // Check read paths against Read deny rules
+      for (const p of paths.read) {
+        const result = this.permissionManager.checkPathPermission(p, "Read");
+        if (result === "deny") {
+          return { success: false, output: "", error: `Permission denied: read access to "${p}" is blocked by settings rules` };
+        }
+      }
+
+      // Check write paths against Edit deny rules
+      for (const p of paths.write) {
+        const result = this.permissionManager.checkPathPermission(p, "Edit");
+        if (result === "deny") {
+          return { success: false, output: "", error: `Permission denied: write access to "${p}" is blocked by settings rules` };
+        }
+      }
+
+      // Check delete paths against Delete deny rules
+      for (const p of paths.delete) {
+        const result = this.permissionManager.checkPathPermission(p, "Delete");
+        if (result === "deny") {
+          return { success: false, output: "", error: `Permission denied: delete access to "${p}" is blocked by settings rules` };
+        }
+      }
+    }
+
+    // ── Sandbox checks ──────────────────────────────────────────────────────
+    if (this.sandboxManager) {
+      const check = this.sandboxManager.checkShellCommand(command, dangerouslyDisableSandbox);
+      if (!check.allowed) {
+        return { success: false, output: "", error: check.reason || "Sandbox: command blocked" };
+      }
+    }
+
+    // Build environment
+    const env = this.sandboxManager ? this.sandboxManager.getShellEnv() : { ...process.env };
+
+    // Merge user-provided env vars
+    const envVars = input.env_vars as Record<string, string> | undefined;
+    if (envVars && typeof envVars === "object") {
+      for (const [key, val] of Object.entries(envVars)) {
+        env[key] = String(val);
+      }
+    }
+
+    // Debug mode
+    if (input.debug) {
+      env.DEBUG = env.DEBUG || "*";
+      env.NODE_DEBUG = env.NODE_DEBUG || "*";
+      env.RUST_BACKTRACE = env.RUST_BACKTRACE || "1";
+      env.PYTHONTRACEBACK = env.PYTHONTRACEBACK || "1";
+      env.PYTHONFAULTHANDLER = env.PYTHONFAULTHANDLER || "1";
+    }
+
+    const background = (input.background as boolean) || false;
+
+    // Merge color env for better terminal output
+    Object.assign(env, COLOR_ENV);
+
+    // Background mode: spawn detached, return immediately with PID
+    if (background) {
+      const { spawn } = require("child_process") as typeof import("child_process");
+      const { shell, args } = getShellCommand(command);
+      const child = spawn(shell, args, {
+        cwd: this.workingDir,
+        env,
+        detached: !IS_WINDOWS,
+        stdio: "ignore",
+      });
+      child.unref();
+      return { success: true, output: `Started in background (PID: ${child.pid})` };
+    }
+
+    return new Promise((resolve) => {
+      exec(command, { cwd: this.workingDir, timeout, maxBuffer: 10 * 1024 * 1024, env, shell: SHELL },
+        (error, stdout, stderr) => {
+          const outputParts: string[] = [];
+          if (stdout) outputParts.push(stdout.trimEnd());
+          if (stderr) outputParts.push(`STDERR:\n${stderr.trimEnd()}`);
+          const output = outputParts.join("\n\n") || "(no output)";
+
+          if (error?.killed) {
+            return resolve({ success: false, output, error: `Timed out after ${timeout}ms` });
+          }
+
+          if (error) {
+            resolve({ success: false, output, error: `Exit code: ${error.code}` });
+          } else {
+            resolve({ success: true, output });
+          }
+        });
+    });
+  }
+}

package/src/tools/sub-agent-manager.ts

@@ -0,0 +1,183 @@
+/**
+ * SubAgentManager — Tracks all spawned sub-agents.
+ *
+ * Provides lifecycle management: spawn with custom timeout,
+ * check status/output, and terminate running agents.
+ */
+
+export type SubAgentStatus = "running" | "completed" | "failed" | "terminated" | "timed_out";
+
+export interface SubAgentEntry {
+  id: string;
+  task: string;
+  status: SubAgentStatus;
+  output: string;
+  error?: string;
+  startedAt: number;
+  finishedAt?: number;
+  /** AbortController to cancel a running agent */
+  abort?: AbortController;
+}
+
+export class SubAgentManager {
+  private agents: Map<string, SubAgentEntry> = new Map();
+  private idCounter = 0;
+
+  /** Generate a unique agent ID */
+  private nextId(): string {
+    this.idCounter++;
+    return `agent_${this.idCounter}_${Date.now().toString(36)}`;
+  }
+
+  /**
+   * Spawn a sub-agent. Runs in background — returns the ID immediately.
+   * The caller provides runnerFn which actually executes the agent.
+   */
+  spawn(
+    task: string,
+    runnerFn: (signal: AbortSignal) => Promise<string>,
+    timeoutMs?: number,
+  ): string {
+    const id = this.nextId();
+    const abort = new AbortController();
+
+    const entry: SubAgentEntry = {
+      id,
+      task,
+      status: "running",
+      output: "",
+      startedAt: Date.now(),
+      abort,
+    };
+    this.agents.set(id, entry);
+
+    // Set up timeout if requested
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    if (timeoutMs && timeoutMs > 0) {
+      timeoutHandle = setTimeout(() => {
+        if (entry.status === "running") {
+          entry.status = "timed_out";
+          entry.error = `Timed out after ${timeoutMs}ms`;
+          entry.finishedAt = Date.now();
+          abort.abort();
+        }
+      }, timeoutMs);
+    }
+
+    // Run the agent in background
+    runnerFn(abort.signal)
+      .then((result) => {
+        if (entry.status === "running") {
+          entry.status = "completed";
+          entry.output = result;
+          entry.finishedAt = Date.now();
+        }
+      })
+      .catch((err) => {
+        if (entry.status === "running") {
+          const msg = err instanceof Error ? err.message : String(err);
+          if (msg === "__cancelled__" || abort.signal.aborted) {
+            // Only set terminated if not already timed_out
+            if (entry.status === "running") {
+              entry.status = "terminated";
+              entry.error = "Terminated by user";
+              entry.finishedAt = Date.now();
+            }
+          } else {
+            entry.status = "failed";
+            entry.error = msg;
+            entry.finishedAt = Date.now();
+          }
+        }
+      })
+      .finally(() => {
+        if (timeoutHandle) clearTimeout(timeoutHandle);
+        delete entry.abort; // clean up reference
+      });
+
+    return id;
+  }
+
+  /**
+   * Spawn and wait — runs synchronously (blocks until done or timeout).
+   * Used when the LLM does NOT request background mode.
+   */
+  async spawnAndWait(
+    task: string,
+    runnerFn: (signal: AbortSignal) => Promise<string>,
+    timeoutMs?: number,
+  ): Promise<SubAgentEntry> {
+    const id = this.spawn(task, runnerFn, timeoutMs);
+    const entry = this.agents.get(id)!;
+
+    // Poll until done (the promise is already running)
+    await new Promise<void>((resolve) => {
+      const check = () => {
+        if (entry.status !== "running") {
+          resolve();
+        } else {
+          setTimeout(check, 50);
+        }
+      };
+      check();
+    });
+
+    return entry;
+  }
+
+  /** Get a specific agent's info */
+  get(id: string): SubAgentEntry | undefined {
+    return this.agents.get(id);
+  }
+
+  /** Get status of a specific agent */
+  getStatus(id: string): { id: string; status: SubAgentStatus; task: string; output: string; error?: string; durationMs?: number } | null {
+    const entry = this.agents.get(id);
+    if (!entry) return null;
+
+    const durationMs = entry.finishedAt
+      ? entry.finishedAt - entry.startedAt
+      : Date.now() - entry.startedAt;
+
+    return {
+      id: entry.id,
+      status: entry.status,
+      task: entry.task,
+      output: entry.output,
+      error: entry.error,
+      durationMs,
+    };
+  }
+
+  /** List all agents with their statuses */
+  listAll(): Array<{ id: string; task: string; status: SubAgentStatus; durationMs: number }> {
+    return Array.from(this.agents.values()).map((entry) => ({
+      id: entry.id,
+      task: entry.task,
+      status: entry.status,
+      durationMs: entry.finishedAt
+        ? entry.finishedAt - entry.startedAt
+        : Date.now() - entry.startedAt,
+    }));
+  }
+
+  /** Terminate a running agent */
+  terminate(id: string): boolean {
+    const entry = this.agents.get(id);
+    if (!entry || entry.status !== "running") return false;
+
+    entry.status = "terminated";
+    entry.error = "Terminated by user";
+    entry.finishedAt = Date.now();
+    if (entry.abort) {
+      entry.abort.abort();
+      delete entry.abort;
+    }
+    return true;
+  }
+
+  /** Check if any agents are still running */
+  hasRunning(): boolean {
+    return Array.from(this.agents.values()).some((e) => e.status === "running");
+  }
+}

package/src/tools/sub-agent-status.ts

@@ -0,0 +1,67 @@
+/**
+ * Sub-Agent Status Tool — check status and output of spawned sub-agents.
+ */
+
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import type { SubAgentManager } from "./sub-agent-manager";
+
+export class SubAgentStatusTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "sub_agent_status",
+    description:
+      "Check the status and output of a background sub-agent by its ID, or list all sub-agents. Use this to poll for completion of background sub-agents.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent_id: {
+          type: "string",
+          description:
+            "The ID of the sub-agent to check. Omit to list all sub-agents.",
+        },
+      },
+      required: [],
+    },
+    requiresPermission: false,
+  };
+
+  private manager: SubAgentManager;
+
+  constructor(manager: SubAgentManager) {
+    this.manager = manager;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const agentId = input.agent_id as string | undefined;
+
+    if (agentId) {
+      // Get specific agent status
+      const status = this.manager.getStatus(agentId);
+      if (!status) {
+        return {
+          success: false,
+          output: "",
+          error: `No sub-agent found with ID "${agentId}". Use sub_agent_status without an agent_id to list all agents.`,
+        };
+      }
+
+      return {
+        success: true,
+        output: JSON.stringify(status, null, 2),
+      };
+    }
+
+    // List all agents
+    const all = this.manager.listAll();
+    if (all.length === 0) {
+      return {
+        success: true,
+        output: "No sub-agents have been spawned yet.",
+      };
+    }
+
+    return {
+      success: true,
+      output: JSON.stringify(all, null, 2),
+    };
+  }
+}

package/src/tools/sub-agent-terminate.ts

@@ -0,0 +1,62 @@
+/**
+ * Sub-Agent Terminate Tool — stop a running sub-agent.
+ */
+
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import type { SubAgentManager } from "./sub-agent-manager";
+
+export class SubAgentTerminateTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "sub_agent_terminate",
+    description:
+      "Terminate a running sub-agent by its ID. Use this to stop a long-running or stuck background sub-agent.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent_id: {
+          type: "string",
+          description: "The ID of the sub-agent to terminate",
+        },
+      },
+      required: ["agent_id"],
+    },
+    requiresPermission: false,
+  };
+
+  private manager: SubAgentManager;
+
+  constructor(manager: SubAgentManager) {
+    this.manager = manager;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const agentId = input.agent_id as string;
+
+    if (!agentId) {
+      return { success: false, output: "", error: "agent_id is required" };
+    }
+
+    const terminated = this.manager.terminate(agentId);
+
+    if (!terminated) {
+      const status = this.manager.getStatus(agentId);
+      if (!status) {
+        return {
+          success: false,
+          output: "",
+          error: `No sub-agent found with ID "${agentId}".`,
+        };
+      }
+      return {
+        success: false,
+        output: "",
+        error: `Sub-agent "${agentId}" is not running (status: ${status.status}). Only running agents can be terminated.`,
+      };
+    }
+
+    return {
+      success: true,
+      output: `Sub-agent "${agentId}" has been terminated.`,
+    };
+  }
+}