Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
6.2 KB
Raw Blame
// Running the external commands capture context needs: resolved on PATH
// first (a tool that is not installed is never spawned), at the lowest CPU
// priority, with stdin closed, a hard timeout that kills the whole process
// group, and a cap on what is read back. Never throws: a failure is null.
//
// macOS: a /usr/bin Command Line Tools shim is never run when the tools are
// missing (the guard of capture/command-guard.ts).

import { spawn } from "node:child_process";
import { setPriority } from "node:os";

import { cltSkipReason, configureCltProbe, resolveCommand, type ResolveOptions } from "../command-guard.js";

export type RunResult = { code: number | null; stdout: string; stderr: string; truncated: boolean; timedOut: boolean };

export type RunOptions = {
  timeoutMs?: number;
  maxBytes?: number;
  cwd?: string;
  env?: NodeJS.ProcessEnv;
};

export type Runner = (file: string, args: string[], options?: RunOptions) => Promise<RunResult | null>;

const DEFAULT_TIMEOUT_MS = 5_000;
const DEFAULT_MAX_BYTES = 1024 * 1024;

/** The child environment: the user's, without anything that could make a tool prompt or page. */
export function quietEnv(extra: NodeJS.ProcessEnv = {}): NodeJS.ProcessEnv {
  return {
    ...process.env,
    PAGER: "cat",
    GIT_PAGER: "cat",
    GIT_TERMINAL_PROMPT: "0",
    NO_COLOR: "1",
    TERM: "dumb",
    HOMEBREW_NO_AUTO_UPDATE: "1",
    HOMEBREW_NO_ANALYTICS: "1",
    HOMEBREW_NO_ENV_HINTS: "1",
    DEBIAN_FRONTEND: "noninteractive",
    npm_config_update_notifier: "false",
    ...extra,
  };
}

/** Runs `file` (an absolute path) and resolves with its output, or null when it could not start. */
/** The taskkill command line that ends a Windows process tree (tests). */
export function windowsTreeKillArgs(pid: number): string[] {
  return ["/PID", String(pid), "/T", "/F"];
}

export const runCommand: Runner = (file, args, options = {}) => {
  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
  return new Promise((resolvePromise) => {
    let child: ReturnType<typeof spawn>;
    // A .cmd/.bat (npm.cmd) only runs through cmd.exe; every argument capture passes is a plain word.
    if (process.platform === "win32" && /\.(?:cmd|bat)$/i.test(file)) {
      if (args.some((arg) => /["%^&|<>\r\n]/.test(arg))) {
        resolvePromise(null);
        return;
      }
      args = ["/d", "/s", "/c", `"${[file, ...args].map((arg) => (/\s/.test(arg) ? `"${arg}"` : arg)).join(" ")}"`];
      file = process.env.ComSpec || "cmd.exe";
    }
    try {
      child = spawn(file, args, {
        windowsVerbatimArguments: process.platform === "win32" && /cmd\.exe$/i.test(file),
        cwd: options.cwd,
        env: options.env ?? quietEnv(),
        stdio: ["ignore", "pipe", "pipe"],
        windowsHide: true,
        detached: process.platform !== "win32",
      });
    } catch {
      resolvePromise(null);
      return;
    }
    if (typeof child.pid === "number") {
      try {
        setPriority(child.pid, 19);
      } catch {
        // Not permitted or already gone: it runs at the normal priority.
      }
    }
    const out: Buffer[] = [];
    const err: Buffer[] = [];
    let outBytes = 0;
    let errBytes = 0;
    let truncated = false;
    let timedOut = false;
    let settled = false;
    const kill = () => {
      try {
        if (process.platform === "win32" && typeof child.pid === "number") {
          // The whole tree: cmd.exe running a .cmd/.bat (npm.cmd) leaves its node child behind otherwise.
          spawn(process.env.SystemRoot ? `${process.env.SystemRoot}\\System32\\taskkill.exe` : "taskkill", windowsTreeKillArgs(child.pid), { stdio: "ignore", windowsHide: true }).on("error", () => child.kill("SIGKILL"));
        } else if (typeof child.pid === "number") process.kill(-child.pid, "SIGKILL");
        else child.kill("SIGKILL");
      } catch {
        try {
          child.kill("SIGKILL");
        } catch {
          // Gone.
        }
      }
    };
    const finish = (code: number | null) => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      resolvePromise({
        code,
        stdout: Buffer.concat(out).toString("utf8"),
        stderr: Buffer.concat(err).toString("utf8"),
        truncated,
        timedOut,
      });
    };
    const timer = setTimeout(() => {
      timedOut = true;
      kill();
      finish(null);
    }, timeoutMs);
    timer.unref?.();
    child.stdout?.on("data", (chunk: Buffer) => {
      if (outBytes >= maxBytes) return;
      const room = maxBytes - outBytes;
      if (chunk.length > room) {
        truncated = true;
        out.push(chunk.subarray(0, room));
        outBytes = maxBytes;
        kill();
        return;
      }
      out.push(chunk);
      outBytes += chunk.length;
    });
    child.stderr?.on("data", (chunk: Buffer) => {
      if (errBytes >= 64 * 1024) return;
      err.push(chunk);
      errBytes += chunk.length;
    });
    child.on("error", () => {
      if (!settled) {
        settled = true;
        clearTimeout(timer);
        resolvePromise(null);
      }
    });
    child.on("close", (code) => finish(code));
  });
};

// --- PATH lookup and the Command Line Tools guard: capture/command-guard.ts ---------

export { resolveCommand, type ResolveOptions };
/** Test hook: the guard's platform and xcode-select check (command-guard.ts configureCltProbe). */
export const configureContextCltProbe = configureCltProbe;

/** Whether running `resolvedPath` as `command` would open the Command Line Tools install dialog. */
export async function wouldPromptClt(command: string, resolvedPath: string | null): Promise<boolean> {
  return (await cltSkipReason(command, resolvedPath)) !== null;
}

/**
 * Resolves `command` on PATH and runs it, unless it is not installed or is a
 * Command Line Tools shim on a Mac without them (null either way).
 */
export async function runTool(command: string, args: string[], options: RunOptions & { run?: Runner; resolve?: (command: string) => string | null } = {}): Promise<RunResult | null> {
  const resolved = (options.resolve ?? resolveCommand)(command);
  if (!resolved) return null;
  if (await wouldPromptClt(command, resolved)) return null;
  return (options.run ?? runCommand)(resolved, args, options);
}