@ai-devkit/agent-manager 0.36.0 → 0.38.0

package/src/utils/process.ts

@@ -6,18 +6,56 @@
  * remain exported for compatibility with existing consumers.
  */
 
+import * as fs from "fs";
 import * as path from "path";
 import { execFile, execFileSync } from "child_process";
 import type { ProcessInfo } from "../adapters/AgentAdapter.js";
 
 const PROCESS_EXEC_MAX_BUFFER = 10 * 1024 * 1024;
 const VALID_EXECUTABLE_NAME = /^[a-zA-Z0-9_-]+$/;
+const ABSOLUTE_PATH = /^(?:\/|[a-zA-Z]:[\\/])/;
+const PATH_SEPARATOR = /[\\/]/;
 
-export function executableBasename(command: string): string {
-  const executable = command.trim().split(/\s+/)[0] || "";
+function pathBasename(executable: string): string {
   return path.basename(executable.replace(/\\/g, "/")).toLowerCase();
 }
 
+function isFile(filePath: string): boolean {
+  try {
+    return fs.statSync(filePath, { throwIfNoEntry: false })?.isFile() ?? false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve argv[0] from a `ps` command line.
+ *
+ * `ps` joins argv with spaces, so an executable installed under a directory
+ * containing spaces (`/Applications/Some App.app/Contents/Resources/codex`)
+ * spans several whitespace tokens. When the first token of an absolute path
+ * is not itself a file, longer space-joined prefixes ending in a token with a
+ * path separator are tried, and the first one that exists on disk wins.
+ * Otherwise the first token is returned, so arguments are never folded into
+ * the executable path unless that combined path really is a file.
+ */
+export function executablePath(command: string): string {
+  const parts = command.trim().split(/(\s+)/);
+  const first = parts[0] ?? "";
+  if (parts.length === 1 || !ABSOLUTE_PATH.test(first) || isFile(first)) return first;
+
+  let prefix = first;
+  for (let i = 2; i < parts.length; i += 2) {
+    prefix += parts[i - 1] + parts[i];
+    if (PATH_SEPARATOR.test(parts[i]) && isFile(prefix)) return prefix;
+  }
+  return first;
+}
+
+export function executableBasename(command: string): string {
+  return pathBasename(executablePath(command));
+}
+
 function normalizeExecutableName(name: string): string {
   const lower = name.toLowerCase();
   return lower.endsWith(".exe") ? lower.slice(0, -4) : lower;
@@ -27,15 +65,36 @@ function normalizedProcessNames(namePatterns: readonly string[]): Set<string> {
   return new Set(namePatterns.filter(Boolean).map(normalizeExecutableName));
 }
 
+/**
+ * Whether argv[0] of `command` is one of `names`.
+ *
+ * The first token is checked with string operations only, as before. The
+ * filesystem is consulted only for absolute commands where a later
+ * path-like token ends in one of the names, i.e. a possible executable under
+ * a directory containing spaces.
+ */
+function matchesExecutableName(command: string, names: ReadonlySet<string>): boolean {
+  const tokens = command.trim().split(/\s+/);
+  const first = tokens[0] ?? "";
+  if (names.has(normalizeExecutableName(pathBasename(first)))) return true;
+  if (!ABSOLUTE_PATH.test(first)) return false;
+
+  const mayContinuePath = tokens
+    .slice(1)
+    .some(
+      (token) =>
+        PATH_SEPARATOR.test(token) && names.has(normalizeExecutableName(pathBasename(token))),
+    );
+  return mayContinuePath && names.has(normalizeExecutableName(executableBasename(command)));
+}
+
 export function filterByProcessNames(
   processes: readonly ProcessInfo[],
   namePatterns: readonly string[],
 ): ProcessInfo[] {
   const names = normalizedProcessNames(namePatterns);
   if (names.size === 0) return [];
-  return processes.filter((process) =>
-    names.has(normalizeExecutableName(executableBasename(process.command))),
-  );
+  return processes.filter((process) => matchesExecutableName(process.command, names));
 }
 
 /**
@@ -72,7 +131,7 @@ export function listAgentProcesses(namePattern: string): ProcessInfo[] {
       const tty = match[3];
       const command = match[4];
 
-      if (!names.has(normalizeExecutableName(executableBasename(command)))) continue;
+      if (!matchesExecutableName(command, names)) continue;
 
       const ttyShort = tty.startsWith("/dev/") ? tty.slice(5) : tty;
 
@@ -91,8 +150,25 @@ export function listAgentProcesses(namePattern: string): ProcessInfo[] {
   }
 }
 
-function execFileText(file: string, args: readonly string[]): Promise<string> {
-  return new Promise((resolve, reject) => {
+/** Runs an executable and resolves with its stdout. Injectable for tests. */
+export type ProcessExec = (file: string, args: readonly string[]) => Promise<string>;
+
+export interface ProcessSnapshotOptions {
+  /**
+   * Decides which name-matched processes are worth enriching with cwd and
+   * start time. Non-candidates are still returned (pid, ppid, tty, command
+   * only) so adapters can walk parent chains. Omitted = enrich everything.
+   */
+  isCandidate?: (process: ProcessInfo) => boolean;
+}
+
+export type ProcessSnapshotCapture = (
+  namePatterns: readonly string[],
+  options?: ProcessSnapshotOptions,
+) => Promise<ProcessInfo[]>;
+
+const execFileText: ProcessExec = (file, args) =>
+  new Promise((resolve, reject) => {
     execFile(
       file,
       args,
@@ -106,10 +182,17 @@ function execFileText(file: string, args: readonly string[]): Promise<string> {
       },
     );
   });
+
+interface ParsedProcessList {
+  /** Every PID in the listing, used to evict cache entries for exited processes. */
+  allPids: Set<number>;
+  /** Processes whose executable matches one of the requested names. */
+  matched: ProcessInfo[];
 }
 
-function parseProcessList(output: string, namePatterns: ReadonlySet<string>): ProcessInfo[] {
-  const processes: ProcessInfo[] = [];
+function parseProcessList(output: string, namePatterns: ReadonlySet<string>): ParsedProcessList {
+  const allPids = new Set<number>();
+  const matched: ProcessInfo[] = [];
 
   for (const line of output.trim().split("\n")) {
     if (!line.trim()) continue;
@@ -120,14 +203,13 @@ function parseProcessList(output: string, namePatterns: ReadonlySet<string>): Pr
     const pid = parseInt(match[1], 10);
     const ppid = parseInt(match[2], 10);
     if (Number.isNaN(pid) || Number.isNaN(ppid)) continue;
+    allPids.add(pid);
 
     const tty = match[3];
     const command = match[4];
-    const base = executableBasename(command);
-    const normalizedBase = normalizeExecutableName(base);
-    if (!namePatterns.has(normalizedBase)) continue;
+    if (!matchesExecutableName(command, namePatterns)) continue;
 
-    processes.push({
+    matched.push({
       pid,
       ppid,
       command,
@@ -136,15 +218,18 @@ function parseProcessList(output: string, namePatterns: ReadonlySet<string>): Pr
     });
   }
 
-  return processes;
+  return { allPids, matched };
 }
 
-async function batchGetProcessCwdsAsync(pids: number[]): Promise<Map<number, string>> {
+async function batchGetProcessCwdsAsync(
+  exec: ProcessExec,
+  pids: number[],
+): Promise<Map<number, string>> {
   const result = new Map<number, string>();
   if (pids.length === 0) return result;
 
   try {
-    const output = await execFileText("lsof", ["-a", "-d", "cwd", "-Fn", "-p", pids.join(",")]);
+    const output = await exec("lsof", ["-a", "-d", "cwd", "-Fn", "-p", pids.join(",")]);
     let currentPid: number | null = null;
     for (const line of output.trim().split("\n")) {
       if (line.startsWith("p")) {
@@ -159,7 +244,7 @@ async function batchGetProcessCwdsAsync(pids: number[]): Promise<Map<number, str
     const entries = await Promise.all(
       pids.map(async (pid) => {
         try {
-          const output = await execFileText("pwdx", [String(pid)]);
+          const output = await exec("pwdx", [String(pid)]);
           const match = output.match(/^\d+:\s*(.+)$/);
           return match ? ([pid, match[1].trim()] as const) : null;
         } catch {
@@ -174,12 +259,15 @@ async function batchGetProcessCwdsAsync(pids: number[]): Promise<Map<number, str
   }
 }
 
-async function batchGetProcessStartTimesAsync(pids: number[]): Promise<Map<number, Date>> {
+async function batchGetProcessStartTimesAsync(
+  exec: ProcessExec,
+  pids: number[],
+): Promise<Map<number, Date>> {
   const result = new Map<number, Date>();
   if (pids.length === 0) return result;
 
   try {
-    const output = await execFileText("ps", ["-o", "pid=,lstart=", "-p", pids.join(",")]);
+    const output = await exec("ps", ["-o", "pid=,lstart=", "-p", pids.join(",")]);
     for (const rawLine of output.split("\n")) {
       const match = rawLine.trim().match(/^(\d+)\s+(.+)$/);
       if (!match) continue;
@@ -193,36 +281,92 @@ async function batchGetProcessStartTimesAsync(pids: number[]): Promise<Map<numbe
   return result;
 }
 
+interface CachedStartTime {
+  /** ppid + command seen when the start time was read; a mismatch means PID reuse. */
+  identity: string;
+  startTime: Date;
+}
+
+function processIdentity(process: ProcessInfo): string {
+  return `${process.ppid ?? ""}\0${process.command}`;
+}
+
 /**
- * Capture and enrich relevant processes without blocking the event loop.
- * One base process listing is shared by every requested executable name.
+ * Create a snapshot capture function with its own start-time cache.
+ *
+ * Start times never change for a live process, so each PID is queried with
+ * `ps lstart` once and reused on later refreshes. A cache entry is dropped
+ * when its PID disappears from the base listing, and ignored when the PID's
+ * ppid/command no longer match (PID reuse). cwd is re-read every refresh
+ * because a process can change directory.
  */
-export async function captureProcessSnapshot(
-  namePatterns: readonly string[],
-): Promise<ProcessInfo[]> {
-  const names = normalizedProcessNames(
-    namePatterns.filter((name) => Boolean(name) && VALID_EXECUTABLE_NAME.test(name)),
-  );
-  if (names.size === 0) return [];
+export function createProcessSnapshotCapture(
+  deps: { exec?: ProcessExec } = {},
+): ProcessSnapshotCapture {
+  const exec = deps.exec ?? execFileText;
+  const startTimeCache = new Map<number, CachedStartTime>();
+
+  const cachedStartTime = (process: ProcessInfo): Date | undefined => {
+    const cached = startTimeCache.get(process.pid);
+    return cached?.identity === processIdentity(process) ? cached.startTime : undefined;
+  };
+
+  return async (namePatterns, options = {}) => {
+    const names = normalizedProcessNames(
+      namePatterns.filter((name) => Boolean(name) && VALID_EXECUTABLE_NAME.test(name)),
+    );
+    if (names.size === 0) return [];
 
-  try {
-    const output = await execFileText("ps", ["-axo", "pid=,ppid=,tty=,command="]);
-    const processes = parseProcessList(output, names);
-    const pids = processes.map((process) => process.pid);
-    const [cwdMap, startTimeMap] = await Promise.all([
-      batchGetProcessCwdsAsync(pids),
-      batchGetProcessStartTimesAsync(pids),
-    ]);
-    return processes.map((process) => ({
-      ...process,
-      cwd: cwdMap.get(process.pid) || "",
-      startTime: startTimeMap.get(process.pid),
-    }));
-  } catch {
-    return [];
-  }
+    try {
+      const output = await exec("ps", ["-axo", "pid=,ppid=,tty=,command="]);
+      const { allPids, matched } = parseProcessList(output, names);
+
+      for (const pid of startTimeCache.keys()) {
+        if (!allPids.has(pid)) startTimeCache.delete(pid);
+      }
+
+      const { isCandidate } = options;
+      const candidates = isCandidate ? matched.filter((process) => isCandidate(process)) : matched;
+      const candidatePids = candidates.map((process) => process.pid);
+      const uncachedPids = candidates
+        .filter((process) => cachedStartTime(process) === undefined)
+        .map((process) => process.pid);
+
+      const [cwdMap, startTimeMap] = await Promise.all([
+        batchGetProcessCwdsAsync(exec, candidatePids),
+        batchGetProcessStartTimesAsync(exec, uncachedPids),
+      ]);
+
+      for (const process of candidates) {
+        const startTime = startTimeMap.get(process.pid);
+        if (startTime) {
+          startTimeCache.set(process.pid, { identity: processIdentity(process), startTime });
+        }
+      }
+
+      const candidateSet = new Set(candidatePids);
+      return matched.map((process) =>
+        candidateSet.has(process.pid)
+          ? {
+              ...process,
+              cwd: cwdMap.get(process.pid) || "",
+              startTime: cachedStartTime(process),
+            }
+          : process,
+      );
+    } catch {
+      return [];
+    }
+  };
 }
 
+/**
+ * Capture and enrich relevant processes without blocking the event loop.
+ * One base process listing is shared by every requested executable name;
+ * only processes accepted by `options.isCandidate` are enriched.
+ */
+export const captureProcessSnapshot: ProcessSnapshotCapture = createProcessSnapshotCapture();
+
 /**
  * Batch-get current working directories for multiple PIDs.
  *