@ai-devkit/agent-manager 0.35.0 → 0.37.0

package/src/__tests__/utils/matchingConstants.test.ts

@@ -0,0 +1,40 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { MATCH_TOLERANCE_MS as reExported } from "../../utils/matching.js";
+import { MATCH_TOLERANCE_MS } from "../../utils/matchingConstants.js";
+
+const SRC_DIR = fileURLToPath(new URL("../../", import.meta.url));
+const CONSTANTS_FILE = path.join(SRC_DIR, "utils", "matchingConstants.ts");
+/** `3 * 60 * 1000`, `180000`, `180_000`, or `3 * 60_000` written in source. */
+const TOLERANCE_LITERAL = /\b3\s*\*\s*60\s*\*\s*1_?000\b|\b180_?000\b|\b3\s*\*\s*60_?000\b/;
+
+function listSourceFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== "__tests__") files.push(...listSourceFiles(full));
+    } else if (entry.name.endsWith(".ts")) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+describe("MATCH_TOLERANCE_MS", () => {
+  it("is 3 minutes and re-exported unchanged from utils/matching", () => {
+    expect(MATCH_TOLERANCE_MS).toBe(3 * 60 * 1000);
+    expect(reExported).toBe(MATCH_TOLERANCE_MS);
+  });
+
+  it("is not duplicated as a literal elsewhere in agent-manager source", () => {
+    const offenders = listSourceFiles(SRC_DIR)
+      .filter((file) => file !== CONSTANTS_FILE)
+      .filter((file) => TOLERANCE_LITERAL.test(fs.readFileSync(file, "utf8")))
+      .map((file) => path.relative(SRC_DIR, file));
+
+    expect(offenders).toEqual([]);
+  });
+});

package/src/__tests__/utils/process.test.ts

@@ -4,6 +4,9 @@
 
 import type { MockedFunction } from "vitest";
 
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
 import { execFile, execFileSync } from "child_process";
 import {
   listAgentProcesses,
@@ -13,8 +16,13 @@ import {
   findWrapperProcess,
   findWrapperProcessPids,
   captureProcessSnapshot,
+  createProcessSnapshotCapture,
   filterByProcessNames,
+  executableBasename,
+  executablePath,
+  type ProcessExec,
 } from "../../utils/process.js";
+import type { ProcessInfo } from "../../adapters/AgentAdapter.js";
 
 vi.mock("child_process", () => ({
   execFile: vi.fn(),
@@ -79,6 +87,167 @@ describe("captureProcessSnapshot", () => {
   });
 });
 
+describe("createProcessSnapshotCapture", () => {
+  interface FakeProcess {
+    pid: number;
+    ppid?: number;
+    command: string;
+    cwd?: string;
+    lstart?: string;
+  }
+
+  function createFakeExec(initial: FakeProcess[]) {
+    let table = initial;
+    const calls: Array<{ file: string; args: readonly string[] }> = [];
+    const pidsArg = (args: readonly string[]) =>
+      args[args.indexOf("-p") + 1].split(",").map((pid) => parseInt(pid, 10));
+    const exec: ProcessExec = async (file, args) => {
+      calls.push({ file, args });
+      if (file === "ps" && args.includes("-axo")) {
+        return table.map((p) => `${p.pid} ${p.ppid ?? 1} s001 ${p.command}`).join("\n");
+      }
+      const requested = new Set(pidsArg(args));
+      const rows = table.filter((p) => requested.has(p.pid));
+      if (file === "lsof") {
+        return rows.map((p) => `p${p.pid}\nn${p.cwd ?? "/"}`).join("\n");
+      }
+      if (file === "ps" && args.some((arg) => arg.includes("lstart="))) {
+        return rows.map((p) => `${p.pid} ${p.lstart ?? "Wed Mar 18 23:18:01 2026"}`).join("\n");
+      }
+      throw new Error(`unexpected command: ${file} ${args.join(" ")}`);
+    };
+    return {
+      exec,
+      calls,
+      setTable: (next: FakeProcess[]) => {
+        table = next;
+      },
+      enrichedPids: (file: "lsof" | "lstart") =>
+        calls
+          .filter((call) =>
+            file === "lsof"
+              ? call.file === "lsof"
+              : call.args.some((arg) => arg.includes("lstart=")),
+          )
+          .map((call) => pidsArg(call.args)),
+    };
+  }
+
+  const isGemini = (process: ProcessInfo) => /gemini/.test(process.command);
+
+  it("enriches only candidate PIDs but still returns every name-matched process", async () => {
+    const fake = createFakeExec([
+      { pid: 10, command: "node /opt/gemini.js", cwd: "/g" },
+      { pid: 11, command: "node /opt/vite.js", cwd: "/v" },
+      { pid: 12, command: "/usr/bin/unrelated" },
+    ]);
+    const capture = createProcessSnapshotCapture({ exec: fake.exec });
+
+    const snapshot = await capture(["node"], { isCandidate: isGemini });
+
+    expect(snapshot.map((process) => process.pid)).toEqual([10, 11]);
+    expect(snapshot[0]).toMatchObject({ cwd: "/g", startTime: expect.any(Date) });
+    expect(snapshot[1].cwd).toBe("");
+    expect(snapshot[1].startTime).toBeUndefined();
+    expect(fake.enrichedPids("lsof")).toEqual([[10]]);
+    expect(fake.enrichedPids("lstart")).toEqual([[10]]);
+  });
+
+  it("enriches every name-matched process when no candidate predicate is given", async () => {
+    const fake = createFakeExec([
+      { pid: 10, command: "node /opt/gemini.js" },
+      { pid: 11, command: "node /opt/vite.js" },
+    ]);
+    const capture = createProcessSnapshotCapture({ exec: fake.exec });
+
+    await capture(["node"]);
+
+    expect(fake.enrichedPids("lsof")).toEqual([[10, 11]]);
+    expect(fake.enrichedPids("lstart")).toEqual([[10, 11]]);
+  });
+
+  it("spawns only the base ps when no process is a candidate", async () => {
+    const fake = createFakeExec([
+      { pid: 11, command: "node /opt/vite.js" },
+      { pid: 12, command: "node /opt/eslint-server.js" },
+    ]);
+    const capture = createProcessSnapshotCapture({ exec: fake.exec });
+
+    const snapshot = await capture(["node"], { isCandidate: isGemini });
+
+    expect(snapshot.map((process) => process.pid)).toEqual([11, 12]);
+    expect(fake.calls).toHaveLength(1);
+    expect(fake.calls[0].args).toContain("-axo");
+  });
+
+  it("fetches start times once per live PID across refreshes, but cwd every refresh", async () => {
+    const fake = createFakeExec([
+      { pid: 10, command: "node /opt/gemini.js", lstart: "Wed Mar 18 23:18:01 2026" },
+    ]);
+    const capture = createProcessSnapshotCapture({ exec: fake.exec });
+
+    const first = await capture(["node"], { isCandidate: isGemini });
+    fake.setTable([
+      { pid: 10, command: "node /opt/gemini.js", lstart: "Wed Mar 18 23:18:01 2026" },
+      { pid: 20, command: "node /opt/gemini.js", lstart: "Thu Mar 19 10:00:00 2026" },
+    ]);
+    const second = await capture(["node"], { isCandidate: isGemini });
+    const third = await capture(["node"], { isCandidate: isGemini });
+
+    expect(fake.enrichedPids("lstart")).toEqual([[10], [20]]);
+    expect(fake.enrichedPids("lsof")).toEqual([[10], [10, 20], [10, 20]]);
+    expect(second[0].startTime).toEqual(first[0].startTime);
+    expect(third.map((process) => process.startTime)).toEqual([
+      new Date("Wed Mar 18 23:18:01 2026"),
+      new Date("Thu Mar 19 10:00:00 2026"),
+    ]);
+  });
+
+  it("refetches the start time when a PID is reused by a different process", async () => {
+    const fake = createFakeExec([
+      { pid: 10, command: "node /opt/gemini.js", lstart: "Wed Mar 18 23:18:01 2026" },
+    ]);
+    const capture = createProcessSnapshotCapture({ exec: fake.exec });
+
+    await capture(["node"], { isCandidate: isGemini });
+    fake.setTable([
+      { pid: 10, command: "node /opt/gemini.js --resume", lstart: "Fri Mar 20 08:00:00 2026" },
+    ]);
+    const reused = await capture(["node"], { isCandidate: isGemini });
+
+    expect(fake.enrichedPids("lstart")).toEqual([[10], [10]]);
+    expect(reused[0].startTime).toEqual(new Date("Fri Mar 20 08:00:00 2026"));
+  });
+
+  it("forgets cached start times once the PID disappears", async () => {
+    const fake = createFakeExec([
+      { pid: 10, command: "node /opt/gemini.js", lstart: "Wed Mar 18 23:18:01 2026" },
+    ]);
+    const capture = createProcessSnapshotCapture({ exec: fake.exec });
+
+    await capture(["node"], { isCandidate: isGemini });
+    fake.setTable([]);
+    await capture(["node"], { isCandidate: isGemini });
+    fake.setTable([
+      { pid: 10, command: "node /opt/gemini.js", lstart: "Fri Mar 20 08:00:00 2026" },
+    ]);
+    const restarted = await capture(["node"], { isCandidate: isGemini });
+
+    expect(fake.enrichedPids("lstart")).toEqual([[10], [10]]);
+    expect(restarted[0].startTime).toEqual(new Date("Fri Mar 20 08:00:00 2026"));
+  });
+
+  it("retries start times that could not be read", async () => {
+    const fake = createFakeExec([{ pid: 10, command: "node /opt/gemini.js", lstart: "garbage" }]);
+    const capture = createProcessSnapshotCapture({ exec: fake.exec });
+
+    await capture(["node"], { isCandidate: isGemini });
+    await capture(["node"], { isCandidate: isGemini });
+
+    expect(fake.enrichedPids("lstart")).toEqual([[10], [10]]);
+  });
+});
+
 describe("filterByProcessNames", () => {
   it("matches only argv[0] and normalizes Windows paths and executable suffixes", () => {
     const processes: ProcessInfo[] = [
@@ -92,6 +261,91 @@ describe("filterByProcessNames", () => {
   });
 });
 
+describe("executables installed under paths containing spaces", () => {
+  let root: string;
+  let codexPath: string;
+  let nodePath: string;
+  let editorPath: string;
+
+  function install(relativePath: string): string {
+    const fullPath = path.join(root, relativePath);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    fs.writeFileSync(fullPath, "");
+    return fullPath;
+  }
+
+  beforeEach(() => {
+    mockedExecFileSync.mockReset();
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "process-spaces-"));
+    codexPath = install("Applications/Some App.app/Contents/Resources/codex");
+    nodePath = install("Applications/Dev Tools/node/bin/node");
+    editorPath = install("usr/bin/vim");
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("recovers argv[0] when its directory contains spaces", () => {
+    expect(executableBasename(`${codexPath} exec --cd /repo`)).toBe("codex");
+    expect(executablePath(`${codexPath} exec --cd /repo`)).toBe(codexPath);
+    expect(executableBasename(`${nodePath} /Users/me/.npm/bin/gemini --yolo`)).toBe("node");
+  });
+
+  it("does not treat arguments containing spaces as part of the executable path", () => {
+    expect(executableBasename(`${editorPath} My Notes/claude`)).toBe("vim");
+    expect(executableBasename(`${codexPath} exec fix the Other Dir/claude bug`)).toBe("codex");
+    expect(executableBasename("/usr/local/bin/node --title my agent/claude")).toBe("node");
+  });
+
+  it("keeps the first-token behaviour for commands without spaces in the path", () => {
+    expect(executableBasename("claude")).toBe("claude");
+    expect(executableBasename("/usr/local/bin/CLAUDE --continue")).toBe("claude");
+    expect(executableBasename("C:\\tools\\node.exe C:\\bin\\pi.js")).toBe("node.exe");
+    expect(executableBasename("  ")).toBe("");
+  });
+
+  it("matches spaced executables by name in filterByProcessNames", () => {
+    const processes: ProcessInfo[] = [
+      { pid: 1, command: `${codexPath} resume --last`, cwd: "", tty: "" },
+      { pid: 2, command: `${nodePath} /opt/gemini.js`, cwd: "", tty: "" },
+      { pid: 3, command: `${editorPath} Some App.app/Contents/Resources/codex`, cwd: "", tty: "" },
+      { pid: 4, command: `${codexPath} exec review My Folder/claude`, cwd: "", tty: "" },
+    ];
+
+    expect(filterByProcessNames(processes, ["codex"])).toEqual([processes[0], processes[3]]);
+    expect(filterByProcessNames(processes, ["node"])).toEqual([processes[1]]);
+    expect(filterByProcessNames(processes, ["claude"])).toEqual([]);
+  });
+
+  it("captures spaced executables with a single base ps call", async () => {
+    const calls: Array<{ file: string; args: readonly string[] }> = [];
+    const exec: ProcessExec = async (file, args) => {
+      calls.push({ file, args });
+      if (file === "ps" && args.includes("-axo")) {
+        return [
+          `100 1 s001 ${codexPath} --sandbox workspace-write`,
+          `200 1 s002 ${editorPath} Some App.app/Contents/Resources/codex`,
+        ].join("\n");
+      }
+      return "";
+    };
+    const capture = createProcessSnapshotCapture({ exec });
+
+    const snapshot = await capture(["codex"]);
+
+    expect(snapshot.map((process) => process.pid)).toEqual([100]);
+    expect(snapshot[0].command).toBe(`${codexPath} --sandbox workspace-write`);
+    expect(calls.filter((call) => call.args.includes("-axo"))).toHaveLength(1);
+  });
+
+  it("lists spaced executables in listAgentProcesses", () => {
+    mockedExecFileSync.mockReturnValue(`100 1 s001 ${codexPath} exec --json\n`);
+
+    expect(listAgentProcesses("codex").map((process) => process.pid)).toEqual([100]);
+  });
+});
+
 describe("listAgentProcesses", () => {
   beforeEach(() => {
     mockedExecFileSync.mockReset();

package/src/adapters/AgentAdapter.ts

@@ -5,18 +5,23 @@
  * Each adapter is responsible for detecting agents of a specific type (e.g., claude).
  */
 
+/** Every built-in harness type, in the order the CLI lists them. */
+export const AGENT_TYPES = [
+  "claude",
+  "codex",
+  "gemini_cli",
+  "grok_cli",
+  "kiro",
+  "antigravity_cli",
+  "opencode",
+  "copilot",
+  "pi",
+] as const;
+
 /**
  * Type of AI agent
  */
-export type AgentType =
-  | "claude"
-  | "gemini_cli"
-  | "grok_cli"
-  | "codex"
-  | "opencode"
-  | "copilot"
-  | "pi"
-  | "other";
+export type AgentType = (typeof AGENT_TYPES)[number] | "other";
 
 /**
  * Current status of an agent
@@ -95,6 +100,25 @@ export interface ConversationMessage {
   timestamp?: string;
 }
 
+/**
+ * Options for {@link AgentAdapter.getConversation}.
+ */
+export interface ConversationOptions {
+  /** Include tool call/result details */
+  verbose?: boolean;
+  /**
+   * Return only the last `tail` messages (after verbose filtering). When
+   * omitted or not a positive integer, the full conversation is returned.
+   *
+   * JSONL-backed adapters read backward from the end of the file and, on
+   * later calls, parse only appended bytes, so cost is proportional to the
+   * tail rather than the transcript size. Adapters backed by a single JSON
+   * document (Gemini) or a database (OpenCode) still read the whole source
+   * and slice; callers should keep an mtime cache for those.
+   */
+  tail?: number;
+}
+
 /**
  * A historical session discovered on disk (running or not).
  *
@@ -190,12 +214,13 @@ export interface AgentAdapter {
   canHandle(processInfo: ProcessInfo): boolean;
 
   /**
-   * Read the full conversation from a session file
+   * Read the conversation from a session file
    * @param sessionFilePath Path to the session JSONL file
    * @param options.verbose Include tool call/result details
+   * @param options.tail Return only the last N messages (see {@link ConversationOptions.tail})
    * @returns Array of conversation messages
    */
-  getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[];
+  getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[];
 
   /**
    * Enumerate historical sessions for this tool from disk.
@@ -212,7 +237,7 @@ export interface AgentAdapter {
   /**
    * Resolve exact historical session matches without enumerating every summary.
    *
-   * Built-in adapters implement this using their provider-native storage shape.
+   * Built-in adapters implement this using their harness-native storage shape.
    * The method remains optional so external adapters can fall back to
    * {@link listSessions} until they adopt direct lookup.
    */