@standardagents/code 0.0.0-dev.fffff

package/src/host-tools.ts

@@ -0,0 +1,570 @@
+/**
+ * Host-side executors for forwarded coding tools. These run on the user's
+ * machine. Paths are resolved relative to the project directory; everything is
+ * best-effort and returns a structured {@link HostResult} rather than throwing.
+ */
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import type { HostResult } from "./types.ts";
+import { ProcessRegistry, LOG_DIR, type ProcessEntry } from "./process-registry.ts";
+import type { McpManager } from "./mcp.ts";
+import { saveMcpServer, removeMcpServer, serverFromCommand } from "./mcp-config.ts";
+
+/**
+ * How long to watch a freshly-started background process before declaring it
+ * "running". Fast failures (port already in use, missing binary, bad flag) exit
+ * within milliseconds; this window catches them so we never report or track a
+ * process that never actually came up.
+ */
+const STARTUP_GRACE_MS = 600;
+
+/** True if a pid is still alive (signal-0 probe; EPERM = alive but not ours). */
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** Read the last `n` non-empty lines of a log file (empty string if unreadable). */
+async function readLogTail(logPath: string, n: number): Promise<string> {
+  try {
+    const content = await fsp.readFile(logPath, "utf8");
+    return content.split("\n").filter(Boolean).slice(-n).join("\n");
+  } catch {
+    return "";
+  }
+}
+
+export class HostTools {
+  constructor(
+    private projectDir: string,
+    private registry?: ProcessRegistry,
+    private threadId?: string,
+    private machine?: string,
+    private mcp?: McpManager,
+    /** Called after the MCP server set changes so the catalog can be re-published. */
+    private onMcpCatalogChange?: () => void
+  ) {}
+
+  /** Resolve a user/model-supplied path against the project directory. */
+  resolve(p: string | undefined): string {
+    if (!p || p === ".") return this.projectDir;
+    return path.resolve(this.projectDir, p);
+  }
+
+  /** True when the resolved path escapes the project directory. */
+  isOutsideProject(p: string | undefined): boolean {
+    const abs = this.resolve(p);
+    const rel = path.relative(this.projectDir, abs);
+    return rel.startsWith("..") || path.isAbsolute(rel);
+  }
+
+  async execute(tool: string, args: Record<string, unknown>): Promise<HostResult> {
+    try {
+      switch (tool) {
+        case "read_file":
+          return await this.readFile(args);
+        case "list_dir":
+          return await this.listDir(args);
+        case "grep":
+          return await this.grep(args);
+        case "glob":
+          return await this.glob(args);
+        case "write_file":
+          return await this.writeFile(args);
+        case "edit_file":
+          return await this.editFile(args);
+        case "bash":
+          return await this.bash(args);
+        case "delete":
+          return await this.deletePath(args);
+        case "background_process": {
+          // One tool, dispatched by action: start launches + verifies a process;
+          // list/logs/stop inspect or terminate tracked ones.
+          const action = String(args.action || "list");
+          if (action === "start") return await this.runBackground(args);
+          return await this.backgroundProcesses(args);
+        }
+        case "mcp": {
+          // Forwarded MCP tool: the CLI is the MCP host, so the negotiation and
+          // execution happen here against the locally-connected server.
+          if (!this.mcp) {
+            return { ok: false, error: "MCP is not available in this session." };
+          }
+          // Removing a server also drops it from the stored config and republishes
+          // the catalog, so it doesn't linger or reconnect.
+          if (String(args.action) === "remove") {
+            const name = String(args.server || "");
+            if (!name) return { ok: false, error: "remove requires a 'server' name." };
+            this.mcp.disconnect(name);
+            removeMcpServer(name);
+            this.onMcpCatalogChange?.();
+            return { ok: true, result: JSON.stringify({ removed: name }) };
+          }
+          return await this.mcp.dispatch(args);
+        }
+        case "install_mcp":
+          return await this.installMcp(args);
+        default:
+          return { ok: false, error: `Unknown tool: ${tool}` };
+      }
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  private async readFile(args: Record<string, unknown>): Promise<HostResult> {
+    const file = this.resolve(String(args.path || ""));
+    const stat = await fsp.stat(file).catch(() => null);
+    if (!stat) return { ok: false, error: `File not found: ${args.path}` };
+    if (stat.isDirectory()) return { ok: false, error: `${args.path} is a directory` };
+    if (stat.size > 2_000_000) return { ok: false, error: `File too large (${stat.size} bytes)` };
+
+    const content = await fsp.readFile(file, "utf8");
+    const lines = content.split("\n");
+    const offset = typeof args.offset === "number" ? Math.max(1, args.offset) : 1;
+    const limit = typeof args.limit === "number" ? args.limit : lines.length;
+    const slice = lines.slice(offset - 1, offset - 1 + limit);
+    const numbered = slice.map((l, i) => `${offset + i}\t${l}`).join("\n");
+    return { ok: true, result: numbered || "(empty file)" };
+  }
+
+  private async listDir(args: Record<string, unknown>): Promise<HostResult> {
+    const dir = this.resolve(args.path ? String(args.path) : undefined);
+    const entries = await fsp.readdir(dir, { withFileTypes: true });
+    const sorted = entries
+      .filter((e) => e.name !== ".git" && e.name !== "node_modules")
+      .sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
+    const lines = sorted.map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+    const header = `${path.relative(this.projectDir, dir) || "."} (${lines.length} entries)`;
+    return { ok: true, result: `${header}\n${lines.join("\n")}` };
+  }
+
+  private async grep(args: Record<string, unknown>): Promise<HostResult> {
+    const pattern = String(args.pattern || "");
+    if (!pattern) return { ok: false, error: "pattern is required" };
+    const searchPath = this.resolve(args.path ? String(args.path) : undefined);
+    const rgArgs = ["--line-number", "--no-heading", "--color", "never", "--max-count", "200"];
+    if (args.ignore_case) rgArgs.push("-i");
+    if (args.glob) rgArgs.push("--glob", String(args.glob));
+    rgArgs.push("--", pattern, searchPath);
+    const rg = await this.run("rg", rgArgs, this.projectDir, 30000);
+    if (rg.code === 127) {
+      return { ok: false, error: "ripgrep (rg) not found on host; install it for grep." };
+    }
+    // rg exits 1 with no matches — treat as a successful empty result.
+    const out = rg.stdout.trim();
+    return { ok: true, result: out || "(no matches)" };
+  }
+
+  private async glob(args: Record<string, unknown>): Promise<HostResult> {
+    const pattern = String(args.pattern || "");
+    if (!pattern) return { ok: false, error: "pattern is required" };
+    const base = this.resolve(args.path ? String(args.path) : undefined);
+    const rg = await this.run("rg", ["--files", "--glob", pattern, base], this.projectDir, 30000);
+    if (rg.code === 127) {
+      // Fallback: native recursive walk with a simple glob match.
+      const matches = await this.walkGlob(base, pattern);
+      return { ok: true, result: matches.slice(0, 300).join("\n") || "(no files)" };
+    }
+    const rel = rg.stdout
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((p) => path.relative(this.projectDir, p))
+      .slice(0, 300);
+    return { ok: true, result: rel.join("\n") || "(no files)" };
+  }
+
+  private async writeFile(args: Record<string, unknown>): Promise<HostResult> {
+    const file = this.resolve(String(args.path || ""));
+    const content = String(args.content ?? "");
+    await fsp.mkdir(path.dirname(file), { recursive: true });
+    const existed = fs.existsSync(file);
+    await fsp.writeFile(file, content, "utf8");
+    return {
+      ok: true,
+      result: `${existed ? "Overwrote" : "Created"} ${path.relative(this.projectDir, file)} (${Buffer.byteLength(content)} bytes)`,
+    };
+  }
+
+  private async editFile(args: Record<string, unknown>): Promise<HostResult> {
+    const file = this.resolve(String(args.path || ""));
+    const oldStr = String(args.old_string ?? "");
+    const newStr = String(args.new_string ?? "");
+    const replaceAll = args.replace_all === true;
+    const stat = await fsp.stat(file).catch(() => null);
+    if (!stat) return { ok: false, error: `File not found: ${args.path}` };
+
+    const content = await fsp.readFile(file, "utf8");
+    if (oldStr === "") return { ok: false, error: "old_string cannot be empty" };
+    const count = content.split(oldStr).length - 1;
+    if (count === 0) return { ok: false, error: "old_string not found in file (it must match exactly)." };
+    if (count > 1 && !replaceAll) {
+      return { ok: false, error: `old_string is not unique (${count} matches). Add more context or set replace_all.` };
+    }
+    const updated = replaceAll ? content.split(oldStr).join(newStr) : content.replace(oldStr, newStr);
+    await fsp.writeFile(file, updated, "utf8");
+    return { ok: true, result: `Edited ${path.relative(this.projectDir, file)} (${count} replacement${count === 1 ? "" : "s"})` };
+  }
+
+  private async deletePath(args: Record<string, unknown>): Promise<HostResult> {
+    const target = this.resolve(String(args.path || ""));
+    const recursive = args.recursive === true;
+    const stat = await fsp.stat(target).catch(() => null);
+    if (!stat) return { ok: false, error: `Path not found: ${args.path}` };
+    if (stat.isDirectory() && !recursive) {
+      return { ok: false, error: `${args.path} is a directory; set recursive to delete it.` };
+    }
+    await fsp.rm(target, { recursive, force: false });
+    return { ok: true, result: `Deleted ${path.relative(this.projectDir, target) || target}` };
+  }
+
+  private async bash(args: Record<string, unknown>): Promise<HostResult> {
+    const command = String(args.command || "");
+    if (!command.trim()) return { ok: false, error: "command is required" };
+    const cwd = args.cwd ? this.resolve(String(args.cwd)) : this.projectDir;
+    const timeout = typeof args.timeout_ms === "number" ? args.timeout_ms : 120000;
+    const res = await this.run("bash", ["-lc", command], cwd, timeout);
+    const combined = [res.stdout, res.stderr].filter(Boolean).join("\n").trim();
+    const truncated = combined.length > 30000 ? combined.slice(0, 30000) + "\n…(truncated)" : combined;
+    if (res.timedOut) {
+      return { ok: false, error: `Command timed out after ${timeout}ms.\n${truncated}` };
+    }
+    const status = `exit code ${res.code}`;
+    return {
+      ok: res.code === 0,
+      result: `${truncated || "(no output)"}\n[${status}]`,
+      error: res.code === 0 ? undefined : `Command failed (${status}).\n${truncated}`,
+    };
+  }
+
+  /** Start a tracked long-running process, detached, with output to a log file. */
+  private async runBackground(args: Record<string, unknown>): Promise<HostResult> {
+    const command = String(args.command || "");
+    if (!command.trim()) return { ok: false, error: "command is required" };
+    const cwd = args.cwd ? this.resolve(String(args.cwd)) : this.projectDir;
+    const id = crypto.randomUUID().slice(0, 8);
+    const logPath = path.join(LOG_DIR, `${id}.log`);
+
+    let out: number;
+    try {
+      await fsp.mkdir(LOG_DIR, { recursive: true });
+      out = fs.openSync(logPath, "a");
+    } catch (err) {
+      return { ok: false, error: `Could not open log file: ${err instanceof Error ? err.message : String(err)}` };
+    }
+
+    let child;
+    try {
+      child = spawn("bash", ["-lc", command], { cwd, detached: true, stdio: ["ignore", out, out] });
+    } catch (err) {
+      fs.closeSync(out);
+      return { ok: false, error: `Failed to start: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    fs.closeSync(out); // the child holds its own copy of the fd
+    const pid = child.pid;
+    if (!pid) return { ok: false, error: "Process failed to start (no pid)." };
+
+    // Verify the process actually STAYED UP before we record it. A command that
+    // fails fast (a port already in use, a missing binary, a bad flag) exits
+    // within milliseconds — we don't want to report a phantom "running" process
+    // or persist it to the registry. Watch for an early exit during a short
+    // grace window, then surface the captured output so the agent can see why.
+    let earlyExit: number | null | undefined;
+    const onEarlyExit = (code: number | null) => {
+      earlyExit = code;
+    };
+    child.on("exit", onEarlyExit);
+    await new Promise((r) => setTimeout(r, STARTUP_GRACE_MS));
+
+    if (earlyExit !== undefined || !isAlive(pid)) {
+      const tail = await readLogTail(logPath, 15);
+      const code = earlyExit ?? "unknown";
+      return {
+        ok: false,
+        error:
+          `The process exited immediately (exit code ${code}) — it did not stay running, ` +
+          `so nothing was started or tracked.` +
+          (tail ? `\n\nOutput:\n${tail}` : " No output was captured."),
+      };
+    }
+
+    // It survived the grace window — now it's safe to detach and record it.
+    child.removeListener("exit", onEarlyExit);
+    child.unref();
+
+    if (this.registry) {
+      const entry: ProcessEntry = {
+        id,
+        pid,
+        command,
+        description: typeof args.description === "string" ? args.description : undefined,
+        cwd,
+        machine: this.machine ?? "",
+        logPath,
+        startedAt: Date.now(),
+        status: "running",
+      };
+      // Persist to the thread's KV (server-side) so the process is visible on
+      // resume from any machine.
+      await this.registry.add(entry);
+      child.on("exit", (code) => void this.registry?.markExited(id, code));
+    }
+
+    return {
+      ok: true,
+      result: JSON.stringify(
+        {
+          id,
+          pid,
+          status: "running",
+          logPath,
+          note: `Started in the background as process ${id} (pid ${pid}) and confirmed running. Output is logged to ${logPath}. Use background_process (list/logs/stop) to check on it or stop it.`,
+        },
+        null,
+        2
+      ),
+    };
+  }
+
+  /**
+   * Install + connect an MCP server from a name + launch command (e.g.
+   * "npx -y @playwright/mcp@latest"). Saves it to the user's MCP config,
+   * launches it, runs the handshake, and republishes the catalog on success so
+   * the agent immediately sees its tools. The connect IS the install — for `npx`
+   * commands the package is fetched on first run.
+   */
+  private async installMcp(args: Record<string, unknown>): Promise<HostResult> {
+    if (!this.mcp) return { ok: false, error: "MCP is not available in this session." };
+    const name = String(args.name || "");
+    const command = String(args.command || "");
+    if (!name || !command) {
+      return { ok: false, error: "install_mcp needs a `name` and a `command` (e.g. \"npx -y @playwright/mcp@latest\")." };
+    }
+
+    let env: Record<string, string> | undefined;
+    if (typeof args.env_json === "string" && args.env_json.trim()) {
+      try {
+        const parsed = JSON.parse(args.env_json);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) env = parsed as Record<string, string>;
+        else return { ok: false, error: "env_json must encode a JSON object of environment variables." };
+      } catch (e) {
+        return { ok: false, error: `env_json is not valid JSON: ${e instanceof Error ? e.message : String(e)}` };
+      }
+    }
+
+    const cfg = serverFromCommand(name, command, env);
+    if (!cfg) return { ok: false, error: `Could not parse the command: "${command}".` };
+
+    saveMcpServer(cfg);
+    try {
+      const client = await this.mcp.connect(cfg);
+      this.onMcpCatalogChange?.();
+      const tools = client.tools.map((t) => t.name);
+      return {
+        ok: true,
+        result: JSON.stringify(
+          {
+            server: cfg.name,
+            command: `${cfg.command} ${cfg.args.join(" ")}`.trim(),
+            connected: true,
+            toolCount: tools.length,
+            tools,
+            note:
+              `Installed and connected MCP server "${cfg.name}" with ${tools.length} tool${tools.length === 1 ? "" : "s"}` +
+              `${tools.length ? `: ${tools.join(", ")}` : ""}. They are available now and will auto-connect next session.`,
+          },
+          null,
+          2
+        ),
+      };
+    } catch (err) {
+      this.onMcpCatalogChange?.();
+      return {
+        ok: false,
+        error: `Saved MCP server "${cfg.name}" but it failed to start: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
+  /** List / inspect logs of / stop tracked background processes. */
+  private async backgroundProcesses(args: Record<string, unknown>): Promise<HostResult> {
+    const action = String(args.action || "list");
+    if (!this.registry) {
+      return { ok: true, result: "Background-process tracking is not available in this session." };
+    }
+
+    if (action === "list") {
+      const procs = await this.registry.list();
+      if (!procs.length) return { ok: true, result: "No background processes for this session." };
+      const lines = procs.map((p) => {
+        const age = relativeAge(p.startedAt);
+        const status =
+          p.status === "running"
+            ? "running"
+            : `${p.status}${typeof p.exitCode === "number" ? ` (exit ${p.exitCode})` : ""}`;
+        return `${p.id}  [${status}]  pid ${p.pid}  started ${age}\n    ${p.command}`;
+      });
+      return { ok: true, result: lines.join("\n") };
+    }
+
+    const id = String(args.id || "");
+    const proc = await this.registry.get(id);
+    if (!proc) return { ok: false, error: `No background process with id ${id}` };
+
+    if (action === "logs") {
+      const maxLines = typeof args.lines === "number" ? args.lines : 60;
+      let content = "";
+      try {
+        content = await fsp.readFile(proc.logPath, "utf8");
+      } catch {
+        return { ok: true, result: `(no output captured yet for ${id})` };
+      }
+      const tail = content.split("\n").slice(-maxLines).join("\n");
+      return { ok: true, result: tail || `(no output yet for ${id})` };
+    }
+
+    if (action === "stop") {
+      if (proc.status !== "running") {
+        return { ok: true, result: `Process ${id} is already ${proc.status}.` };
+      }
+      try {
+        process.kill(-proc.pid, "SIGTERM");
+        setTimeout(() => {
+          try {
+            process.kill(-proc.pid, "SIGKILL");
+          } catch {
+            // already gone
+          }
+        }, 3000);
+      } catch {
+        try {
+          process.kill(proc.pid, "SIGKILL");
+        } catch {
+          // already gone
+        }
+      }
+      await this.registry.markStopped(id);
+      return { ok: true, result: `Stopped background process ${id} (pid ${proc.pid}).` };
+    }
+
+    return { ok: false, error: `Unknown action: ${action}` };
+  }
+
+  private run(
+    cmd: string,
+    args: string[],
+    cwd: string,
+    timeoutMs: number
+  ): Promise<{ stdout: string; stderr: string; code: number; timedOut: boolean }> {
+    return new Promise((resolve) => {
+      let stdout = "";
+      let stderr = "";
+      let timedOut = false;
+      let exitCode = 0;
+      let settled = false;
+      // Cap captured output so a chatty/looping command can't grow memory
+      // without bound (which previously could take the whole CLI down).
+      const MAX_OUTPUT = 256 * 1024;
+
+      let child;
+      try {
+        // Own process group so a timeout can kill the whole tree, and so a
+        // backgrounded server keeps running after the CLI exits.
+        child = spawn(cmd, args, { cwd, detached: true });
+      } catch {
+        resolve({ stdout: "", stderr: "", code: 127, timedOut: false });
+        return;
+      }
+      child.unref();
+
+      let graceTimer: ReturnType<typeof setTimeout> | null = null;
+      const settle = (code: number) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (graceTimer) clearTimeout(graceTimer);
+        resolve({ stdout, stderr, code, timedOut });
+      };
+
+      const timer = setTimeout(() => {
+        timedOut = true;
+        try {
+          if (child.pid) process.kill(-child.pid, "SIGKILL");
+        } catch {
+          try {
+            child.kill("SIGKILL");
+          } catch {
+            // already gone
+          }
+        }
+        // Settle even if `close` never arrives (a detached child may hold stdio).
+        setTimeout(() => settle(exitCode), 250);
+      }, timeoutMs);
+
+      child.stdout?.on("data", (d) => {
+        if (stdout.length < MAX_OUTPUT) stdout += d.toString();
+      });
+      child.stderr?.on("data", (d) => {
+        if (stderr.length < MAX_OUTPUT) stderr += d.toString();
+      });
+      child.on("error", (err: NodeJS.ErrnoException) => {
+        if (!stderr) stderr = String(err);
+        settle(err.code === "ENOENT" ? 127 : 1);
+      });
+      // Normal completion: stdio drained.
+      child.on("close", (code) => settle(code ?? exitCode));
+      // The process exited but stdio may stay open if it backgrounded a child
+      // that inherited the pipes (e.g. `server &`). Resolve shortly after exit
+      // so background commands return promptly instead of hanging on `close`.
+      child.on("exit", (code) => {
+        exitCode = code ?? 0;
+        graceTimer = setTimeout(() => settle(exitCode), 250);
+      });
+    });
+  }
+
+  private async walkGlob(base: string, pattern: string): Promise<string[]> {
+    const re = globToRegExp(pattern);
+    const out: string[] = [];
+    const walk = async (dir: string) => {
+      const entries = await fsp.readdir(dir, { withFileTypes: true }).catch(() => []);
+      for (const e of entries) {
+        if (e.name === ".git" || e.name === "node_modules") continue;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) await walk(full);
+        else {
+          const rel = path.relative(this.projectDir, full);
+          if (re.test(rel) || re.test(e.name)) out.push(rel);
+        }
+      }
+    };
+    await walk(base);
+    return out;
+  }
+}
+
+function relativeAge(startedAt: number): string {
+  const diff = (Date.now() - startedAt) / 1000;
+  if (diff < 60) return `${Math.floor(diff)}s ago`;
+  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
+  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`;
+  return `${Math.floor(diff / 86400)}d ago`;
+}
+
+function globToRegExp(glob: string): RegExp {
+  const escaped = glob
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, " ")
+    .replace(/\*/g, "[^/]*")
+    .replace(/ /g, ".*")
+    .replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`);
+}