@actagent/acpx 2026.6.2

package/src/process-reaper.ts

@@ -0,0 +1,427 @@
+/**
+ * ACPX process ownership checks and cleanup. The reaper only terminates
+ * ACTAgent-owned wrapper trees after validating paths, packages, and lease ids.
+ */
+import { execFile } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { promisify } from "node:util";
+import { splitCommandParts } from "./command-line.js";
+import { resolveAcpxPluginRoot } from "./config.js";
+import { ACTAGENT_ACPX_LEASE_ID_ARG, ACTAGENT_GATEWAY_INSTANCE_ID_ARG } from "./process-lease.js";
+
+const execFileAsync = promisify(execFile);
+const requireFromHere = createRequire(import.meta.url);
+const GENERATED_WRAPPER_BASENAMES = new Set([
+  "codex-acp-wrapper.mjs",
+  "claude-agent-acp-wrapper.mjs",
+]);
+const ACTAGENT_PLUGIN_DEPS_MARKER = "/plugin-runtime-deps/";
+const OWNED_ACP_PACKAGE_NAMES = [
+  "@zed-industries/codex-acp",
+  "@zed-industries/codex-acp-darwin-arm64",
+  "@zed-industries/codex-acp-darwin-x64",
+  "@zed-industries/codex-acp-linux-arm64",
+  "@zed-industries/codex-acp-linux-x64",
+  "@zed-industries/codex-acp-win32-arm64",
+  "@zed-industries/codex-acp-win32-x64",
+  "@agentclientprotocol/claude-agent-acp",
+  "acpx",
+];
+const ACP_PACKAGE_MARKERS = [
+  ...OWNED_ACP_PACKAGE_NAMES.map((packageName) => `/node_modules/${packageName}/`),
+  "/acpx/dist/",
+];
+
+/** Minimal process-table row used by ACPX cleanup. */
+export type AcpxProcessInfo = {
+  pid: number;
+  ppid: number;
+  command: string;
+};
+
+/** Injectable process-listing and termination hooks for tests. */
+export type AcpxProcessCleanupDeps = {
+  listProcesses?: () => Promise<AcpxProcessInfo[]>;
+  killProcess?: (pid: number, signal: NodeJS.Signals) => void;
+  sleep?: (ms: number) => Promise<void>;
+};
+
+/** Result from cleaning up a single ACPX process tree. */
+export type AcpxProcessCleanupResult = {
+  inspectedPids: number[];
+  terminatedPids: number[];
+  skippedReason?: "missing-root" | "not-actagent-owned" | "unverified-root";
+};
+
+/** Result from startup orphan reaping. */
+export type AcpxStartupReapResult = {
+  inspectedPids: number[];
+  terminatedPids: number[];
+  skippedReason?: "unsupported-platform" | "process-list-unavailable";
+};
+
+function normalizePathLike(value: string): string {
+  return value.replaceAll("\\", "/");
+}
+
+function resolvePackageRoot(packageName: string): string | undefined {
+  try {
+    return normalizePathLike(path.dirname(requireFromHere.resolve(`${packageName}/package.json`)));
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveACTAgentInstallRoot(pluginRoot: string): string {
+  if (
+    path.basename(pluginRoot) === "acpx" &&
+    path.basename(path.dirname(pluginRoot)) === "extensions"
+  ) {
+    const parent = path.dirname(path.dirname(pluginRoot));
+    return path.basename(parent) === "dist" ? path.dirname(parent) : parent;
+  }
+  return path.resolve(pluginRoot, "..");
+}
+
+function resolveOwnedAcpPackageRootCandidates(packageName: string): string[] {
+  const pluginRoot = resolveAcpxPluginRoot(import.meta.url);
+  const actAgentRoot = resolveACTAgentInstallRoot(pluginRoot);
+  return [
+    resolvePackageRoot(packageName),
+    path.join(pluginRoot, "node_modules", packageName),
+    path.join(actAgentRoot, "node_modules", packageName),
+  ].flatMap((root) => (root ? [normalizePathLike(root)] : []));
+}
+
+const OWNED_ACP_PACKAGE_ROOTS = Array.from(
+  new Set(OWNED_ACP_PACKAGE_NAMES.flatMap(resolveOwnedAcpPackageRootCandidates)),
+);
+
+function commandBelongsToResolvedAcpPackage(command: string): boolean {
+  return OWNED_ACP_PACKAGE_ROOTS.some((root) => command.includes(`${root}/`));
+}
+
+function commandMentionsGeneratedWrapper(command: string): boolean {
+  return Array.from(GENERATED_WRAPPER_BASENAMES).some((basename) => command.includes(basename));
+}
+
+function commandWrapperBelongsToRoot(command: string, wrapperRoot: string | undefined): boolean {
+  if (!wrapperRoot) {
+    return true;
+  }
+  const normalizedCommand = normalizePathLike(command);
+  const normalizedRoot = normalizePathLike(wrapperRoot).replace(/\/+$/, "");
+  return Array.from(GENERATED_WRAPPER_BASENAMES).some((basename) =>
+    normalizedCommand.includes(`${normalizedRoot}/${basename}`),
+  );
+}
+
+/** Check whether a command references an ACTAgent-generated ACPX wrapper path. */
+export function isACTAgentLeaseAwareAcpxProcessCommand(params: {
+  command: string | undefined;
+  wrapperRoot?: string;
+}): boolean {
+  const command = params.command?.trim();
+  if (!command) {
+    return false;
+  }
+  const normalized = normalizePathLike(command);
+  return (
+    commandMentionsGeneratedWrapper(normalized) &&
+    commandWrapperBelongsToRoot(normalized, params.wrapperRoot)
+  );
+}
+
+function commandsReferToSameRootCommand(liveCommand: string, storedCommand: string | undefined) {
+  if (!storedCommand?.trim()) {
+    return true;
+  }
+  return normalizePathLike(liveCommand).trim() === normalizePathLike(storedCommand).trim();
+}
+
+function commandOptionEquals(
+  parts: string[],
+  option: string,
+  expected: string | undefined,
+): boolean {
+  if (!expected) {
+    return true;
+  }
+  const index = parts.indexOf(option);
+  return index >= 0 && parts[index + 1] === expected;
+}
+
+function liveCommandMatchesLeaseIdentity(params: {
+  command: string | undefined;
+  expectedLeaseId?: string;
+  expectedGatewayInstanceId?: string;
+}): boolean {
+  if (!params.expectedLeaseId && !params.expectedGatewayInstanceId) {
+    return true;
+  }
+  const parts = splitCommandParts(params.command ?? "");
+  return (
+    commandOptionEquals(parts, ACTAGENT_ACPX_LEASE_ID_ARG, params.expectedLeaseId) &&
+    commandOptionEquals(parts, ACTAGENT_GATEWAY_INSTANCE_ID_ARG, params.expectedGatewayInstanceId)
+  );
+}
+
+/** Check whether a command is owned by ACTAgent ACPX runtime packages or wrappers. */
+export function isACTAgentOwnedAcpxProcessCommand(params: {
+  command: string | undefined;
+  wrapperRoot?: string;
+}): boolean {
+  const command = params.command?.trim();
+  if (!command) {
+    return false;
+  }
+  const normalized = normalizePathLike(command);
+  if (
+    isACTAgentLeaseAwareAcpxProcessCommand({
+      command: normalized,
+      wrapperRoot: params.wrapperRoot,
+    })
+  ) {
+    return true;
+  }
+  if (commandBelongsToResolvedAcpPackage(normalized)) {
+    return true;
+  }
+  if (!normalized.includes(ACTAGENT_PLUGIN_DEPS_MARKER)) {
+    return false;
+  }
+  return ACP_PACKAGE_MARKERS.some((marker) => normalized.includes(marker));
+}
+
+function parseProcessList(stdout: string): AcpxProcessInfo[] {
+  const processes: AcpxProcessInfo[] = [];
+  for (const line of stdout.split(/\r?\n/)) {
+    const match = /^\s*(?<pid>\d+)\s+(?<ppid>\d+)\s+(?<command>.+?)\s*$/.exec(line);
+    if (!match?.groups) {
+      continue;
+    }
+    processes.push({
+      pid: Number.parseInt(match.groups.pid, 10),
+      ppid: Number.parseInt(match.groups.ppid, 10),
+      command: match.groups.command,
+    });
+  }
+  return processes;
+}
+
+/** List host processes in the compact shape needed by ACPX cleanup. */
+export async function listPlatformProcesses(): Promise<AcpxProcessInfo[]> {
+  if (process.platform === "win32") {
+    return [];
+  }
+  const { stdout } = await execFileAsync("ps", ["-axo", "pid=,ppid=,command="], {
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  return parseProcessList(stdout);
+}
+
+function collectProcessTree(processes: AcpxProcessInfo[], rootPid: number): AcpxProcessInfo[] {
+  const childrenByParent = new Map<number, AcpxProcessInfo[]>();
+  for (const processInfo of processes) {
+    const children = childrenByParent.get(processInfo.ppid) ?? [];
+    children.push(processInfo);
+    childrenByParent.set(processInfo.ppid, children);
+  }
+
+  const byPid = new Map(processes.map((processInfo) => [processInfo.pid, processInfo]));
+  const root = byPid.get(rootPid);
+  const collected: AcpxProcessInfo[] = [];
+  if (root) {
+    collected.push(root);
+  }
+
+  const queue = [...(childrenByParent.get(rootPid) ?? [])];
+  while (queue.length > 0) {
+    const next = queue.shift();
+    if (!next || collected.some((processInfo) => processInfo.pid === next.pid)) {
+      continue;
+    }
+    collected.push(next);
+    queue.push(...(childrenByParent.get(next.pid) ?? []));
+  }
+
+  return collected;
+}
+
+function uniquePids(processes: AcpxProcessInfo[]): number[] {
+  return Array.from(
+    new Set(
+      processes
+        .map((processInfo) => processInfo.pid)
+        .filter((pid) => Number.isInteger(pid) && pid > 0 && pid !== process.pid),
+    ),
+  );
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function terminatePids(
+  pids: number[],
+  deps: AcpxProcessCleanupDeps | undefined,
+): Promise<number[]> {
+  const killProcess = deps?.killProcess ?? ((pid, signal) => process.kill(pid, signal));
+  const sleep =
+    deps?.sleep ??
+    ((ms) =>
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, ms);
+      }));
+  const terminated: number[] = [];
+
+  for (const pid of pids) {
+    try {
+      killProcess(pid, "SIGTERM");
+      terminated.push(pid);
+    } catch {
+      // The process may already be gone.
+    }
+  }
+  if (terminated.length === 0) {
+    return terminated;
+  }
+  await sleep(750);
+  for (const pid of terminated) {
+    if (deps?.killProcess || isProcessAlive(pid)) {
+      try {
+        killProcess(pid, "SIGKILL");
+      } catch {
+        // Best-effort cleanup only.
+      }
+    }
+  }
+  return terminated;
+}
+
+/** Terminate one validated ACTAgent-owned ACPX wrapper process tree. */
+export async function cleanupACTAgentOwnedAcpxProcessTree(params: {
+  rootPid?: number;
+  rootCommand?: string;
+  expectedLeaseId?: string;
+  expectedGatewayInstanceId?: string;
+  wrapperRoot?: string;
+  deps?: AcpxProcessCleanupDeps;
+}): Promise<AcpxProcessCleanupResult> {
+  const rootPid = params.rootPid;
+  if (!rootPid || rootPid <= 0 || rootPid === process.pid) {
+    return { inspectedPids: [], terminatedPids: [], skippedReason: "missing-root" };
+  }
+
+  let processes: AcpxProcessInfo[];
+  try {
+    processes = await (params.deps?.listProcesses ?? listPlatformProcesses)();
+  } catch {
+    processes = [];
+  }
+
+  const listedTree = collectProcessTree(processes, rootPid);
+  // Session-store PIDs are stale data. If the live process table cannot prove
+  // that this PID still belongs to an ACTAgent-owned wrapper, fail closed to
+  // avoid killing an unrelated process after PID reuse.
+  if (listedTree.length === 0) {
+    return { inspectedPids: [], terminatedPids: [], skippedReason: "unverified-root" };
+  }
+  const rootCommand = listedTree[0]?.command ?? params.rootCommand;
+  const liveCommandWasGeneratedWrapper = commandMentionsGeneratedWrapper(
+    normalizePathLike(rootCommand ?? ""),
+  );
+  const storedCommandWasGeneratedWrapper = commandMentionsGeneratedWrapper(
+    normalizePathLike(params.rootCommand ?? ""),
+  );
+  if (!liveCommandWasGeneratedWrapper && storedCommandWasGeneratedWrapper) {
+    return {
+      inspectedPids: listedTree.map((processInfo) => processInfo.pid),
+      terminatedPids: [],
+      skippedReason: "not-actagent-owned",
+    };
+  }
+  if (
+    !liveCommandWasGeneratedWrapper &&
+    !commandsReferToSameRootCommand(rootCommand ?? "", params.rootCommand)
+  ) {
+    return {
+      inspectedPids: listedTree.map((processInfo) => processInfo.pid),
+      terminatedPids: [],
+      skippedReason: "not-actagent-owned",
+    };
+  }
+  if (
+    !isACTAgentOwnedAcpxProcessCommand({
+      command: rootCommand,
+      wrapperRoot: params.wrapperRoot,
+    })
+  ) {
+    return {
+      inspectedPids: listedTree.map((processInfo) => processInfo.pid),
+      terminatedPids: [],
+      skippedReason: "not-actagent-owned",
+    };
+  }
+  if (
+    !liveCommandMatchesLeaseIdentity({
+      command: rootCommand,
+      expectedLeaseId: params.expectedLeaseId,
+      expectedGatewayInstanceId: params.expectedGatewayInstanceId,
+    })
+  ) {
+    return {
+      inspectedPids: listedTree.map((processInfo) => processInfo.pid),
+      terminatedPids: [],
+      skippedReason: "not-actagent-owned",
+    };
+  }
+
+  const pids = uniquePids(listedTree.toReversed());
+  return {
+    inspectedPids: uniquePids(listedTree),
+    terminatedPids: await terminatePids(pids, params.deps),
+  };
+}
+
+/** Reap orphaned ACTAgent-owned ACPX wrapper trees during runtime startup. */
+export async function reapStaleACTAgentOwnedAcpxOrphans(params: {
+  wrapperRoot: string;
+  deps?: AcpxProcessCleanupDeps;
+}): Promise<AcpxStartupReapResult> {
+  if (process.platform === "win32") {
+    return { inspectedPids: [], terminatedPids: [], skippedReason: "unsupported-platform" };
+  }
+
+  let processes: AcpxProcessInfo[];
+  try {
+    processes = await (params.deps?.listProcesses ?? listPlatformProcesses)();
+  } catch {
+    return { inspectedPids: [], terminatedPids: [], skippedReason: "process-list-unavailable" };
+  }
+
+  const orphans = processes.filter(
+    (processInfo) =>
+      processInfo.ppid === 1 &&
+      isACTAgentOwnedAcpxProcessCommand({
+        command: processInfo.command,
+        wrapperRoot: params.wrapperRoot,
+      }),
+  );
+  // Startup reaping starts from currently visible orphan roots and then expands
+  // each tree, so adapter grandchildren do not survive as fresh orphans after
+  // the wrapper root exits.
+  const orphanTrees = orphans.map((orphan) => collectProcessTree(processes, orphan.pid));
+  const inspectedPids = uniquePids(orphanTrees.flat());
+  const pids = uniquePids(orphanTrees.flatMap((tree) => tree.toReversed()));
+  return {
+    inspectedPids,
+    terminatedPids: await terminatePids(pids, params.deps),
+  };
+}

package/src/runtime-internals/mcp-command-line.mjs

@@ -0,0 +1,128 @@
+/**
+ * Command-line parser for ACPX MCP proxy targets. It handles simple quoting and
+ * Windows executable paths before spawning the configured MCP target.
+ */
+const WINDOWS_DIRECT_EXECUTABLE_PATH_RE =
+  /^(?<command>(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+[\\/]).*?\.(?:exe|com))(?=\s|$)(?:\s+(?<rest>.*))?$/i;
+
+// Windows wrapper scripts need their host shell or interpreter (`cmd.exe`,
+// `powershell.exe`, or `node`) instead of direct spawning.
+const WINDOWS_WRAPPER_PATH_RE =
+  /^(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+[\\/]).*?\.(?:bat|cmd|cjs|js|mjs|ps1)$/i;
+
+function splitCommandParts(value, platform = process.platform) {
+  const parts = [];
+  let current = "";
+  let quote = null;
+  let escaping = false;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const ch = value[index];
+    const next = value[index + 1];
+    if (escaping) {
+      current += ch;
+      escaping = false;
+      continue;
+    }
+    if (ch === "\\") {
+      if (quote === "'") {
+        current += ch;
+        continue;
+      }
+      if (platform === "win32") {
+        if (quote === '"') {
+          if (next === '"' || next === "\\") {
+            escaping = true;
+            continue;
+          }
+          current += ch;
+          continue;
+        }
+        if (!quote) {
+          current += ch;
+          continue;
+        }
+      }
+      escaping = true;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (current.length > 0) {
+        parts.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += ch;
+  }
+
+  if (escaping) {
+    current += "\\";
+  }
+  if (quote) {
+    throw new Error("Invalid agent command: unterminated quote");
+  }
+  if (current.length > 0) {
+    parts.push(current);
+  }
+  return parts;
+}
+
+function splitWindowsExecutableCommand(value, platform = process.platform) {
+  if (platform !== "win32") {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.startsWith('"') || trimmed.startsWith("'")) {
+    return null;
+  }
+  const match = trimmed.match(WINDOWS_DIRECT_EXECUTABLE_PATH_RE);
+  if (!match?.groups?.command) {
+    return null;
+  }
+  const rest = match.groups.rest?.trim() ?? "";
+  return {
+    command: match.groups.command,
+    args: rest ? splitCommandParts(rest, platform) : [],
+  };
+}
+
+function assertSupportedWindowsCommand(command, platform = process.platform) {
+  if (platform !== "win32" || !WINDOWS_WRAPPER_PATH_RE.test(command)) {
+    return;
+  }
+  throw new Error(
+    `Unsupported Windows agent command wrapper: ${command}. ` +
+      "Invoke wrapper scripts through their shell or interpreter instead " +
+      "(for example `cmd.exe /c`, `powershell.exe -File`, or `node <script>`).",
+  );
+}
+
+/** Split a configured command string into `{ command, args }` for child_process.spawn. */
+export function splitCommandLine(value, platform = process.platform) {
+  const windowsCommand = splitWindowsExecutableCommand(value, platform);
+  const parts = windowsCommand ?? splitCommandParts(value, platform);
+  if (parts.length === 0) {
+    throw new Error("Invalid agent command: empty command");
+  }
+  const parsed = Array.isArray(parts)
+    ? {
+        command: parts[0],
+        args: parts.slice(1),
+      }
+    : parts;
+  assertSupportedWindowsCommand(parsed.command, platform);
+  return parsed;
+}

package/src/runtime-internals/mcp-command-line.test.ts

@@ -0,0 +1,60 @@
+// ACPX tests cover mcp command line plugin behavior.
+import { describe, expect, it } from "vitest";
+
+type SplitCommandLine = (
+  value: string,
+  platform?: string,
+) => {
+  command: string;
+  args: string[];
+};
+
+async function loadSplitCommandLine(): Promise<SplitCommandLine> {
+  const moduleUrl = new URL("./mcp-command-line.mjs", import.meta.url);
+  return (await import(moduleUrl.href)).splitCommandLine as SplitCommandLine;
+}
+
+describe("mcp-command-line", () => {
+  it("parses quoted Windows executable paths without dropping backslashes", async () => {
+    const splitCommandLine = await loadSplitCommandLine();
+    const parsed = splitCommandLine(
+      '"C:\\Program Files\\Claude\\claude.exe" --stdio --flag "two words"',
+      "win32",
+    );
+
+    expect(parsed).toEqual({
+      command: "C:\\Program Files\\Claude\\claude.exe",
+      args: ["--stdio", "--flag", "two words"],
+    });
+  });
+
+  it("parses unquoted Windows executable paths without mangling backslashes", async () => {
+    const splitCommandLine = await loadSplitCommandLine();
+    const parsed = splitCommandLine("C:\\Users\\alerl\\.local\\bin\\claude.exe --version", "win32");
+
+    expect(parsed).toEqual({
+      command: "C:\\Users\\alerl\\.local\\bin\\claude.exe",
+      args: ["--version"],
+    });
+  });
+
+  it("preserves unquoted Windows path arguments after the executable", async () => {
+    const splitCommandLine = await loadSplitCommandLine();
+    const parsed = splitCommandLine(
+      '"C:\\Program Files\\Claude\\claude.exe" --config C:\\Users\\me\\cfg.json',
+      "win32",
+    );
+
+    expect(parsed).toEqual({
+      command: "C:\\Program Files\\Claude\\claude.exe",
+      args: ["--config", "C:\\Users\\me\\cfg.json"],
+    });
+  });
+
+  it("rejects direct Windows wrapper-script commands with a helpful error", async () => {
+    const splitCommandLine = await loadSplitCommandLine();
+    expect(() =>
+      splitCommandLine('"C:\\Users\\me\\bin\\claude-wrapper.cmd" --stdio', "win32"),
+    ).toThrow(/Invoke wrapper scripts through their shell or interpreter instead/);
+  });
+});