@actagent/acpx 2026.6.2

package/src/process-lease.ts

@@ -0,0 +1,194 @@
+/**
+ * Persistent lease store for ACPX wrapper processes. Leases let ACTAgent attach
+ * gateway/session identity to spawned ACP processes and clean them up later.
+ */
+import { randomUUID, createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readJsonFileWithFallback, writeJsonFileAtomically } from "actagent/plugin-sdk/json-store";
+
+/** Environment variable carrying the ACPX process lease id. */
+export const ACTAGENT_ACPX_LEASE_ID_ENV = "ACTAGENT_ACPX_LEASE_ID";
+/** Environment variable carrying the owning gateway instance id. */
+export const ACTAGENT_GATEWAY_INSTANCE_ID_ENV = "ACTAGENT_GATEWAY_INSTANCE_ID";
+/** CLI argument carrying the ACPX process lease id for platforms without env wrapping. */
+export const ACTAGENT_ACPX_LEASE_ID_ARG = "--actagent-acpx-lease-id";
+/** CLI argument carrying the owning gateway instance id. */
+export const ACTAGENT_GATEWAY_INSTANCE_ID_ARG = "--actagent-gateway-instance-id";
+
+/** Lifecycle state for a tracked ACPX wrapper process. */
+export type AcpxProcessLeaseState = "open" | "closing" | "closed" | "lost";
+
+/** Persisted identity and command metadata for one ACPX wrapper process. */
+export type AcpxProcessLease = {
+  leaseId: string;
+  gatewayInstanceId: string;
+  sessionKey: string;
+  wrapperRoot: string;
+  wrapperPath: string;
+  rootPid: number;
+  processGroupId?: number;
+  commandHash: string;
+  startedAt: number;
+  state: AcpxProcessLeaseState;
+};
+
+/** Async lease store used by runtime sessions and cleanup routines. */
+export type AcpxProcessLeaseStore = {
+  load(leaseId: string): Promise<AcpxProcessLease | undefined>;
+  listOpen(gatewayInstanceId?: string): Promise<AcpxProcessLease[]>;
+  save(lease: AcpxProcessLease): Promise<void>;
+  markState(leaseId: string, state: AcpxProcessLeaseState): Promise<void>;
+};
+
+type LeaseFile = {
+  version: 1;
+  leases: AcpxProcessLease[];
+};
+
+const LEASE_FILE = "process-leases.json";
+
+function normalizeLease(value: unknown): AcpxProcessLease | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    typeof record.leaseId !== "string" ||
+    typeof record.gatewayInstanceId !== "string" ||
+    typeof record.sessionKey !== "string" ||
+    typeof record.wrapperRoot !== "string" ||
+    typeof record.wrapperPath !== "string" ||
+    typeof record.rootPid !== "number" ||
+    typeof record.commandHash !== "string" ||
+    typeof record.startedAt !== "number" ||
+    !["open", "closing", "closed", "lost"].includes(String(record.state))
+  ) {
+    return undefined;
+  }
+  return {
+    leaseId: record.leaseId,
+    gatewayInstanceId: record.gatewayInstanceId,
+    sessionKey: record.sessionKey,
+    wrapperRoot: record.wrapperRoot,
+    wrapperPath: record.wrapperPath,
+    rootPid: record.rootPid,
+    ...(typeof record.processGroupId === "number" ? { processGroupId: record.processGroupId } : {}),
+    commandHash: record.commandHash,
+    startedAt: record.startedAt,
+    state: record.state as AcpxProcessLeaseState,
+  };
+}
+
+async function readLeaseFile(filePath: string): Promise<LeaseFile> {
+  const { value } = await readJsonFileWithFallback<Partial<LeaseFile>>(filePath, {
+    version: 1,
+    leases: [],
+  });
+  const leases = Array.isArray(value.leases)
+    ? value.leases.map(normalizeLease).filter((lease): lease is AcpxProcessLease => Boolean(lease))
+    : [];
+  return { version: 1, leases };
+}
+
+function writeLeaseFile(filePath: string, value: LeaseFile): Promise<void> {
+  return writeJsonFileAtomically(filePath, value);
+}
+
+/** Create a serialized JSON-backed ACPX process lease store. */
+export function createAcpxProcessLeaseStore(params: { stateDir: string }): AcpxProcessLeaseStore {
+  const filePath = path.join(params.stateDir, LEASE_FILE);
+  let updateQueue: Promise<void> = Promise.resolve();
+
+  async function update(
+    mutator: (leases: AcpxProcessLease[]) => AcpxProcessLease[],
+  ): Promise<void> {
+    const run = updateQueue.then(async () => {
+      await fs.mkdir(params.stateDir, { recursive: true });
+      const current = await readLeaseFile(filePath);
+      await writeLeaseFile(filePath, {
+        version: 1,
+        leases: mutator(current.leases),
+      });
+    });
+    updateQueue = run.catch(() => {});
+    await run;
+  }
+
+  async function readCurrent(): Promise<LeaseFile> {
+    await updateQueue;
+    return await readLeaseFile(filePath);
+  }
+
+  return {
+    async load(leaseId) {
+      const current = await readCurrent();
+      return current.leases.find((lease) => lease.leaseId === leaseId);
+    },
+    async listOpen(gatewayInstanceId) {
+      const current = await readCurrent();
+      return current.leases.filter(
+        (lease) =>
+          (lease.state === "open" || lease.state === "closing") &&
+          (!gatewayInstanceId || lease.gatewayInstanceId === gatewayInstanceId),
+      );
+    },
+    async save(lease) {
+      await update((leases) => [
+        ...leases.filter((entry) => entry.leaseId !== lease.leaseId),
+        lease,
+      ]);
+    },
+    async markState(leaseId, state) {
+      await update((leases) =>
+        leases.map((lease) => (lease.leaseId === leaseId ? { ...lease, state } : lease)),
+      );
+    },
+  };
+}
+
+/** Create a unique lease id for one ACPX wrapper process. */
+export function createAcpxProcessLeaseId(): string {
+  return randomUUID();
+}
+
+/** Hash a wrapper command so process leases can detect command drift. */
+export function hashAcpxProcessCommand(command: string): string {
+  return createHash("sha256").update(command).digest("hex");
+}
+
+function quoteEnvValue(value: string): string {
+  return /^[A-Za-z0-9_./:=@+-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function appendAcpxLeaseArgs(params: {
+  command: string;
+  leaseId: string;
+  gatewayInstanceId: string;
+}): string {
+  return [
+    params.command,
+    ACTAGENT_ACPX_LEASE_ID_ARG,
+    quoteEnvValue(params.leaseId),
+    ACTAGENT_GATEWAY_INSTANCE_ID_ARG,
+    quoteEnvValue(params.gatewayInstanceId),
+  ].join(" ");
+}
+
+/** Add ACPX lease identity to a command through env vars and portable args. */
+export function withAcpxLeaseEnvironment(params: {
+  command: string;
+  leaseId: string;
+  gatewayInstanceId: string;
+  platform?: NodeJS.Platform;
+}): string {
+  if ((params.platform ?? process.platform) === "win32") {
+    return appendAcpxLeaseArgs(params);
+  }
+  return [
+    "env",
+    `${ACTAGENT_ACPX_LEASE_ID_ENV}=${quoteEnvValue(params.leaseId)}`,
+    `${ACTAGENT_GATEWAY_INSTANCE_ID_ENV}=${quoteEnvValue(params.gatewayInstanceId)}`,
+    appendAcpxLeaseArgs(params),
+  ].join(" ");
+}

package/src/process-reaper.test.ts

@@ -0,0 +1,337 @@
+// ACPX tests cover process reaper plugin behavior.
+import path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import { ACTAGENT_ACPX_LEASE_ID_ARG, ACTAGENT_GATEWAY_INSTANCE_ID_ARG } from "./process-lease.js";
+import {
+  cleanupACTAgentOwnedAcpxProcessTree,
+  isACTAgentLeaseAwareAcpxProcessCommand,
+  isACTAgentOwnedAcpxProcessCommand,
+  reapStaleACTAgentOwnedAcpxOrphans,
+  type AcpxProcessInfo,
+} from "./process-reaper.js";
+
+const WRAPPER_ROOT = "/tmp/actagent-state/acpx";
+const CODEX_WRAPPER_COMMAND = `node ${WRAPPER_ROOT}/codex-acp-wrapper.mjs`;
+const CODEX_WRAPPER_COMMAND_WITH_LEASE = `${CODEX_WRAPPER_COMMAND} ${ACTAGENT_ACPX_LEASE_ID_ARG} lease-1 ${ACTAGENT_GATEWAY_INSTANCE_ID_ARG} gateway-1`;
+const CLAUDE_WRAPPER_COMMAND = `node ${WRAPPER_ROOT}/claude-agent-acp-wrapper.mjs`;
+const PLUGIN_DEPS_CODEX_COMMAND =
+  "node /tmp/actagent/plugin-runtime-deps/node_modules/@zed-industries/codex-acp/bin/codex-acp.js";
+const LOCAL_NODE_MODULES_CODEX_COMMAND = `node ${path.resolve(
+  "node_modules/@zed-industries/codex-acp/bin/codex-acp.js",
+)}`;
+const LOCAL_NODE_MODULES_CODEX_PLATFORM_COMMAND = path.resolve(
+  "node_modules/@zed-industries/codex-acp-linux-x64/bin/codex-acp",
+);
+
+function cleanupDeps(processes: AcpxProcessInfo[]) {
+  const killed: Array<{ pid: number; signal: NodeJS.Signals }> = [];
+  return {
+    killed,
+    deps: {
+      listProcesses: vi.fn(async () => processes),
+      killProcess: vi.fn((pid: number, signal: NodeJS.Signals) => {
+        killed.push({ pid, signal });
+      }),
+      sleep: vi.fn(async () => {}),
+    },
+  };
+}
+
+function collectMatching<T, U>(
+  items: readonly T[],
+  predicate: (item: T) => boolean,
+  map: (item: T) => U,
+): U[] {
+  const matches: U[] = [];
+  for (const item of items) {
+    if (predicate(item)) {
+      matches.push(map(item));
+    }
+  }
+  return matches;
+}
+
+describe("process reaper", () => {
+  it("recognizes generated Codex and Claude wrappers only under the configured root", () => {
+    expect(
+      isACTAgentOwnedAcpxProcessCommand({
+        command: CODEX_WRAPPER_COMMAND,
+        wrapperRoot: WRAPPER_ROOT,
+      }),
+    ).toBe(true);
+    expect(
+      isACTAgentOwnedAcpxProcessCommand({
+        command: CLAUDE_WRAPPER_COMMAND,
+        wrapperRoot: WRAPPER_ROOT,
+      }),
+    ).toBe(true);
+    expect(
+      isACTAgentOwnedAcpxProcessCommand({
+        command: "node /tmp/other/codex-acp-wrapper.mjs",
+        wrapperRoot: WRAPPER_ROOT,
+      }),
+    ).toBe(false);
+  });
+
+  it("only treats generated wrappers as launch-lease aware", () => {
+    expect(
+      isACTAgentLeaseAwareAcpxProcessCommand({
+        command: CODEX_WRAPPER_COMMAND,
+        wrapperRoot: WRAPPER_ROOT,
+      }),
+    ).toBe(true);
+    expect(
+      isACTAgentLeaseAwareAcpxProcessCommand({ command: LOCAL_NODE_MODULES_CODEX_COMMAND }),
+    ).toBe(false);
+    expect(isACTAgentLeaseAwareAcpxProcessCommand({ command: PLUGIN_DEPS_CODEX_COMMAND })).toBe(
+      false,
+    );
+  });
+
+  it("recognizes ACTAgent plugin-runtime-deps ACP adapter children", () => {
+    expect(isACTAgentOwnedAcpxProcessCommand({ command: PLUGIN_DEPS_CODEX_COMMAND })).toBe(true);
+    expect(isACTAgentOwnedAcpxProcessCommand({ command: "npx @zed-industries/codex-acp" })).toBe(
+      false,
+    );
+  });
+
+  it("recognizes plugin-local ACP adapter package paths without trusting arbitrary installs", () => {
+    expect(isACTAgentOwnedAcpxProcessCommand({ command: LOCAL_NODE_MODULES_CODEX_COMMAND })).toBe(
+      true,
+    );
+    expect(
+      isACTAgentOwnedAcpxProcessCommand({
+        command: "node /tmp/other-project/node_modules/@zed-industries/codex-acp/bin/codex-acp.js",
+      }),
+    ).toBe(false);
+  });
+
+  it("kills an owned recorded process tree children first", async () => {
+    const { deps, killed } = cleanupDeps([
+      { pid: 100, ppid: 1, command: CODEX_WRAPPER_COMMAND },
+      { pid: 101, ppid: 100, command: PLUGIN_DEPS_CODEX_COMMAND },
+      { pid: 102, ppid: 101, command: "node child.js" },
+    ]);
+
+    const result = await cleanupACTAgentOwnedAcpxProcessTree({
+      rootPid: 100,
+      rootCommand: CODEX_WRAPPER_COMMAND,
+      wrapperRoot: WRAPPER_ROOT,
+      deps,
+    });
+
+    expect(result.skippedReason).toBeUndefined();
+    expect(result.inspectedPids).toEqual([100, 101, 102]);
+    expect(killed.slice(0, 3)).toEqual([
+      { pid: 102, signal: "SIGTERM" },
+      { pid: 101, signal: "SIGTERM" },
+      { pid: 100, signal: "SIGTERM" },
+    ]);
+  });
+
+  it("allows wrapper-root verification when stored wrapper commands are shell-quoted", async () => {
+    const { deps, killed } = cleanupDeps([{ pid: 110, ppid: 1, command: CODEX_WRAPPER_COMMAND }]);
+
+    const result = await cleanupACTAgentOwnedAcpxProcessTree({
+      rootPid: 110,
+      rootCommand: `"/usr/local/bin/node" "${WRAPPER_ROOT}/codex-acp-wrapper.mjs"`,
+      wrapperRoot: WRAPPER_ROOT,
+      deps,
+    });
+
+    expect(result.skippedReason).toBeUndefined();
+    expect(killed[0]).toEqual({ pid: 110, signal: "SIGTERM" });
+  });
+
+  it("requires matching lease identity before killing a leased process tree", async () => {
+    const { deps, killed } = cleanupDeps([
+      { pid: 112, ppid: 1, command: CODEX_WRAPPER_COMMAND_WITH_LEASE },
+    ]);
+
+    const result = await cleanupACTAgentOwnedAcpxProcessTree({
+      rootPid: 112,
+      rootCommand: CODEX_WRAPPER_COMMAND,
+      expectedLeaseId: "lease-1",
+      expectedGatewayInstanceId: "gateway-1",
+      wrapperRoot: WRAPPER_ROOT,
+      deps,
+    });
+
+    expect(result.skippedReason).toBeUndefined();
+    expect(killed[0]).toEqual({ pid: 112, signal: "SIGTERM" });
+  });
+
+  it("does not kill a reused same-root wrapper pid with a different lease identity", async () => {
+    const { deps, killed } = cleanupDeps([
+      {
+        pid: 113,
+        ppid: 1,
+        command: `${CODEX_WRAPPER_COMMAND} ${ACTAGENT_ACPX_LEASE_ID_ARG} other-lease ${ACTAGENT_GATEWAY_INSTANCE_ID_ARG} gateway-1`,
+      },
+    ]);
+
+    const result = await cleanupACTAgentOwnedAcpxProcessTree({
+      rootPid: 113,
+      rootCommand: CODEX_WRAPPER_COMMAND,
+      expectedLeaseId: "lease-1",
+      expectedGatewayInstanceId: "gateway-1",
+      wrapperRoot: WRAPPER_ROOT,
+      deps,
+    });
+
+    expect(result).toEqual({
+      inspectedPids: [113],
+      terminatedPids: [],
+      skippedReason: "not-actagent-owned",
+    });
+    expect(killed).toStrictEqual([]);
+  });
+
+  it("skips recorded pid cleanup when process listing is unavailable", async () => {
+    const killed: Array<{ pid: number; signal: NodeJS.Signals }> = [];
+    const result = await cleanupACTAgentOwnedAcpxProcessTree({
+      rootPid: 200,
+      rootCommand: CODEX_WRAPPER_COMMAND,
+      wrapperRoot: WRAPPER_ROOT,
+      deps: {
+        listProcesses: vi.fn(async () => {
+          throw new Error("ps unavailable");
+        }),
+        killProcess: vi.fn((pid, signal) => {
+          killed.push({ pid, signal });
+        }),
+        sleep: vi.fn(async () => {}),
+      },
+    });
+
+    expect(result).toEqual({
+      inspectedPids: [],
+      terminatedPids: [],
+      skippedReason: "unverified-root",
+    });
+    expect(killed).toStrictEqual([]);
+  });
+
+  it("does not kill a reused pid when the live command is not ACTAgent-owned", async () => {
+    const { deps, killed } = cleanupDeps([{ pid: 250, ppid: 1, command: "node unrelated.js" }]);
+
+    const result = await cleanupACTAgentOwnedAcpxProcessTree({
+      rootPid: 250,
+      rootCommand: CODEX_WRAPPER_COMMAND,
+      wrapperRoot: WRAPPER_ROOT,
+      deps,
+    });
+
+    expect(result).toEqual({
+      inspectedPids: [250],
+      terminatedPids: [],
+      skippedReason: "not-actagent-owned",
+    });
+    expect(killed).toStrictEqual([]);
+  });
+
+  it("does not kill a reused adapter pid when the stored root was a generated wrapper", async () => {
+    const { deps, killed } = cleanupDeps([
+      {
+        pid: 260,
+        ppid: 1,
+        command: PLUGIN_DEPS_CODEX_COMMAND,
+      },
+    ]);
+
+    const result = await cleanupACTAgentOwnedAcpxProcessTree({
+      rootPid: 260,
+      rootCommand: CODEX_WRAPPER_COMMAND,
+      wrapperRoot: WRAPPER_ROOT,
+      deps,
+    });
+
+    expect(result).toEqual({
+      inspectedPids: [260],
+      terminatedPids: [],
+      skippedReason: "not-actagent-owned",
+    });
+    expect(killed).toStrictEqual([]);
+  });
+
+  it("skips non-owned recorded process trees", async () => {
+    const { deps, killed } = cleanupDeps([{ pid: 300, ppid: 1, command: "node server.js" }]);
+
+    const result = await cleanupACTAgentOwnedAcpxProcessTree({
+      rootPid: 300,
+      rootCommand: "node server.js",
+      wrapperRoot: WRAPPER_ROOT,
+      deps,
+    });
+
+    expect(result.skippedReason).toBe("not-actagent-owned");
+    expect(killed).toStrictEqual([]);
+  });
+
+  it("reaps stale ACTAgent-owned wrapper and adapter orphans on startup", async () => {
+    const { deps, killed } = cleanupDeps([
+      { pid: 400, ppid: 1, command: CODEX_WRAPPER_COMMAND },
+      { pid: 401, ppid: 400, command: PLUGIN_DEPS_CODEX_COMMAND },
+      { pid: 402, ppid: 401, command: "node child.js" },
+      { pid: 403, ppid: 1, command: CLAUDE_WRAPPER_COMMAND },
+      { pid: 404, ppid: 403, command: "node claude-child.js" },
+      { pid: 405, ppid: 1, command: PLUGIN_DEPS_CODEX_COMMAND },
+      { pid: 406, ppid: 1, command: "node /tmp/other/codex-acp-wrapper.mjs" },
+    ]);
+
+    const result = await reapStaleACTAgentOwnedAcpxOrphans({
+      wrapperRoot: WRAPPER_ROOT,
+      deps,
+    });
+
+    expect(result.skippedReason).toBeUndefined();
+    expect(result.inspectedPids).toEqual([400, 401, 402, 403, 404, 405]);
+    expect(
+      collectMatching(
+        killed,
+        (entry) => entry.signal === "SIGTERM",
+        (entry) => entry.pid,
+      ),
+    ).toEqual([402, 401, 400, 404, 403, 405]);
+  });
+
+  it("reaps plugin-local Codex ACP adapter orphans when the generated wrapper is already gone", async () => {
+    const { deps, killed } = cleanupDeps([
+      { pid: 500, ppid: 1, command: LOCAL_NODE_MODULES_CODEX_COMMAND },
+      { pid: 501, ppid: 500, command: LOCAL_NODE_MODULES_CODEX_PLATFORM_COMMAND },
+    ]);
+
+    const result = await reapStaleACTAgentOwnedAcpxOrphans({
+      wrapperRoot: WRAPPER_ROOT,
+      deps,
+    });
+
+    expect(result.skippedReason).toBeUndefined();
+    expect(result.inspectedPids).toEqual([500, 501]);
+    expect(
+      collectMatching(
+        killed,
+        (entry) => entry.signal === "SIGTERM",
+        (entry) => entry.pid,
+      ),
+    ).toEqual([501, 500]);
+  });
+
+  it("keeps startup scans quiet when process listing is unavailable", async () => {
+    const result = await reapStaleACTAgentOwnedAcpxOrphans({
+      wrapperRoot: WRAPPER_ROOT,
+      deps: {
+        listProcesses: vi.fn(async () => {
+          throw new Error("ps unavailable");
+        }),
+        sleep: vi.fn(async () => {}),
+      },
+    });
+
+    expect(result).toEqual({
+      inspectedPids: [],
+      terminatedPids: [],
+      skippedReason: "process-list-unavailable",
+    });
+  });
+});