@ai-devkit/agent-manager 0.40.0 → 0.42.0

package/src/AgentManager.ts

@@ -8,6 +8,8 @@
 import type {
   AgentAdapter,
   AgentInfo,
+  AgentStatus,
+  AgentType,
   SessionSummary,
   ListSessionsOptions,
   ProcessInfo,
@@ -22,6 +24,7 @@ import {
 import {
   captureProcessSnapshot,
   filterByProcessNames,
+  snapshotOptions,
   type ProcessSnapshotCapture,
 } from "./utils/process.js";
 import {
@@ -31,6 +34,17 @@ import {
   type HerdrAgentPane,
 } from "./runtime/herdr/HerdrAgentDiscovery.js";
 
+/** Discovery patterns of one adapter: exact names plus basename prefixes. */
+function adapterPatterns(adapter: AgentAdapter): {
+  names: string[];
+  prefixes: string[];
+} {
+  return {
+    names: adapter.processNames ? [...adapter.processNames] : [],
+    prefixes: adapter.processNamePrefixes ? [...adapter.processNamePrefixes] : [],
+  };
+}
+
 export interface ListAgentsOptions {
   /**
    * Sort key for the returned list. Defaults to `status`, which orders
@@ -45,6 +59,20 @@ export interface AgentManagerOptions {
     | (() => AgentRuntimeProvider | Promise<AgentRuntimeProvider>);
   fetchHerdrAgentPanes?: () => Promise<readonly HerdrAgentPane[]>;
   onRuntimeDiscoveryError?: (error: unknown) => void;
+  /**
+   * Daemon-side enriched agents ({@link DaemonClient.listAgents} wire
+   * shape: `AgentInfo` with `lastActive` as an ISO string). A non-null
+   * result is authoritative for every harness type — all local adapters
+   * are skipped. Returning null or throwing forces the local path;
+   * omitting it disables daemon consumption.
+   */
+  fetchEnrichedAgents?: () => Promise<Array<
+    Omit<AgentInfo, "lastActive" | "type" | "status"> & {
+      type: string;
+      status: string;
+      lastActive: string;
+    }
+  > | null>;
 }
 
 class AgentNotRunningError extends Error {
@@ -162,18 +190,46 @@ export class AgentManager {
     const allAgents: AgentInfo[] = [];
     const errors: Array<{ type: string; error: Error }> = [];
 
-    const adapters = Array.from(this.adapters.values());
+    // A non-null daemon answer is authoritative for every harness type, so
+    // local adapters only run when the daemon is absent.
+    let daemonAgents: AgentInfo[] | null = null;
+    if (this.options.fetchEnrichedAgents) {
+      try {
+        const enriched = await this.options.fetchEnrichedAgents();
+        if (enriched) {
+          daemonAgents = enriched.map((a) => ({
+            ...a,
+            type: a.type as AgentType,
+            status: a.status as AgentStatus,
+            lastActive: new Date(a.lastActive),
+          }));
+        }
+      } catch {
+        daemonAgents = null;
+      }
+    }
+    if (daemonAgents) allAgents.push(...daemonAgents);
+
+    const adapters = daemonAgents ? [] : Array.from(this.adapters.values());
     const processNames = Array.from(
       new Set(
         adapters.flatMap((adapter) => (adapter.processNames ? [...adapter.processNames] : [])),
       ),
     );
+    const namePrefixes = Array.from(
+      new Set(
+        adapters.flatMap((adapter) =>
+          adapter.processNamePrefixes ? [...adapter.processNamePrefixes] : [],
+        ),
+      ),
+    );
     let processes: readonly ProcessInfo[] = [];
-    if (processNames.length > 0) {
+    if (processNames.length > 0 || namePrefixes.length > 0) {
       try {
-        processes = await this.captureSnapshot(processNames, {
-          isCandidate: (process) => this.isCandidateProcess(adapters, process),
-        });
+        processes = await this.captureSnapshot(
+          processNames,
+          snapshotOptions(namePrefixes, (process) => this.isCandidateProcess(adapters, process)),
+        );
       } catch {
         processes = [];
       }
@@ -182,9 +238,12 @@ export class AgentManager {
     // Query all adapters in parallel using executable-scoped slices of the shared snapshot.
     const adapterPromises = adapters.map(async (adapter) => {
       try {
-        const agents = adapter.processNames
+        const hasPatterns =
+          adapter.processNames !== undefined || adapter.processNamePrefixes !== undefined;
+        const { names, prefixes } = adapterPatterns(adapter);
+        const agents = hasPatterns
           ? await adapter.detectAgents({
-              processes: filterByProcessNames(processes, adapter.processNames),
+              processes: filterByProcessNames(processes, names, prefixes),
             })
           : await adapter.detectAgents();
         return { type: adapter.type, agents, error: null };
@@ -248,8 +307,11 @@ export class AgentManager {
    */
   private isCandidateProcess(adapters: readonly AgentAdapter[], process: ProcessInfo): boolean {
     return adapters.some((adapter) => {
-      if (!adapter.processNames) return false;
-      if (filterByProcessNames([process], adapter.processNames).length === 0) return false;
+      if (adapter.processNames === undefined && adapter.processNamePrefixes === undefined) {
+        return false;
+      }
+      const { names, prefixes } = adapterPatterns(adapter);
+      if (filterByProcessNames([process], names, prefixes).length === 0) return false;
       try {
         return adapter.canHandle(process);
       } catch {

package/src/__tests__/AgentManager.test.ts

@@ -478,6 +478,90 @@ describe("AgentManager", () => {
     });
   });
 
+  describe("listAgents — daemon enrichment", () => {
+    const wireAgent = (overrides: Record<string, unknown> = {}) => ({
+      name: "daemon-claude",
+      type: "claude",
+      status: "waiting",
+      summary: "daemon summary",
+      pid: 777,
+      projectPath: "/daemon/proj",
+      sessionId: "daemon-sid",
+      lastActive: "2026-10-08T12:00:00.000Z",
+      ...overrides,
+    });
+
+    it("serves agents from the daemon and skips all local adapters", async () => {
+      const local = new MockAdapter("claude", [createMockAgent({ name: "local-claude" })]);
+      const detectSpy = vi.spyOn(local, "detectAgents");
+      const m = new AgentManager(new AgentRegistry(path.join(tmpDir, "agents.json")), undefined, {
+        fetchEnrichedAgents: async () => [wireAgent()],
+      });
+      m.registerAdapter(local);
+
+      const agents = await m.listAgents();
+      expect(detectSpy).not.toHaveBeenCalled();
+      expect(agents).toHaveLength(1);
+      expect(agents[0].name).toBe("daemon-claude");
+      expect(agents[0].lastActive).toEqual(new Date("2026-10-08T12:00:00.000Z"));
+    });
+
+    it("falls back to all-local when the daemon returns null", async () => {
+      const m = new AgentManager(new AgentRegistry(path.join(tmpDir, "agents.json")), undefined, {
+        fetchEnrichedAgents: async () => null,
+      });
+      m.registerAdapter(new MockAdapter("claude", [createMockAgent({ name: "local-claude" })]));
+      const agents = await m.listAgents();
+      expect(agents.map((a) => a.name)).toEqual(["local-claude"]);
+    });
+
+    it("falls back to all-local when the daemon call throws", async () => {
+      const m = new AgentManager(new AgentRegistry(path.join(tmpDir, "agents.json")), undefined, {
+        fetchEnrichedAgents: async () => {
+          throw new Error("socket gone");
+        },
+      });
+      m.registerAdapter(new MockAdapter("claude", [createMockAgent({ name: "local-claude" })]));
+      const agents = await m.listAgents();
+      expect(agents.map((a) => a.name)).toEqual(["local-claude"]);
+    });
+
+    it("serves every type from the daemon in one sweep", async () => {
+      const claudeLocal = new MockAdapter("claude", [createMockAgent({ name: "local-claude" })]);
+      const codexLocal = new MockAdapter("codex", [
+        createMockAgent({ name: "local-codex", type: "codex" }),
+      ]);
+      const claudeSpy = vi.spyOn(claudeLocal, "detectAgents");
+      const codexSpy = vi.spyOn(codexLocal, "detectAgents");
+      const m = new AgentManager(new AgentRegistry(path.join(tmpDir, "agents.json")), undefined, {
+        fetchEnrichedAgents: async () => [
+          wireAgent(),
+          wireAgent({ type: "codex", name: "daemon-codex", pid: 888 }),
+        ],
+      });
+      m.registerAdapter(claudeLocal);
+      m.registerAdapter(codexLocal);
+
+      const agents = await m.listAgents();
+      expect(claudeSpy).not.toHaveBeenCalled();
+      expect(codexSpy).not.toHaveBeenCalled();
+      expect(agents.map((a) => a.name).sort()).toEqual(["daemon-claude", "daemon-codex"]);
+    });
+
+    it("treats an empty daemon answer as authoritative", async () => {
+      const local = new MockAdapter("claude", [createMockAgent({ name: "local-claude" })]);
+      const detectSpy = vi.spyOn(local, "detectAgents");
+      const m = new AgentManager(new AgentRegistry(path.join(tmpDir, "agents.json")), undefined, {
+        fetchEnrichedAgents: async () => [],
+      });
+      m.registerAdapter(local);
+
+      const agents = await m.listAgents();
+      expect(detectSpy).not.toHaveBeenCalled();
+      expect(agents).toEqual([]);
+    });
+  });
+
   describe("listAgents — registry persistence", () => {
     let tmpDir: string;
     let regPath: string;

package/src/__tests__/fixtures.test.ts

@@ -0,0 +1,245 @@
+/**
+ * Fixture replay: materialize each committed bundle into a fake HOME,
+ * run the adapter's detectAgents with the recorded processes + frozen
+ * clock, and require byte-identical output to `expected`.
+ *
+ * The same bundles are consumed by devkit-harness Rust tests — this file is
+ * the TS↔TS side of the parity oracle.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import Database from "better-sqlite3";
+import { createBuiltinAdapters } from "../harnesses/index.js";
+import { CodexAdapter } from "../harnesses/codex/CodexAdapter.js";
+import { PiAdapter } from "../harnesses/pi/PiAdapter.js";
+import { GeminiCliAdapter } from "../harnesses/gemini/GeminiCliAdapter.js";
+import { CopilotAdapter } from "../harnesses/copilot/CopilotAdapter.js";
+import { AgentRegistry, type RegistryEntry } from "../utils/AgentRegistry.js";
+import { expand, expandNow, normalizeAgents, withFrozenClock } from "../fixtures/bundle.js";
+import type { FixtureBundle } from "../fixtures/bundle.js";
+import { captureLive, FIXTURES_ROOT } from "../fixtures/capture.js";
+
+const bundlePaths = fs.existsSync(FIXTURES_ROOT)
+  ? fs.readdirSync(FIXTURES_ROOT, { withFileTypes: true }).flatMap((d) =>
+      d.isDirectory()
+        ? fs
+            .readdirSync(path.join(FIXTURES_ROOT, d.name))
+            .filter((f) => f.endsWith(".json"))
+            .map((f) => path.join(FIXTURES_ROOT, d.name, f))
+        : [],
+    )
+  : [];
+
+/** Adapters whose detect path consults AgentRegistry. */
+const REGISTRY_AWARE = new Set(["codex", "pi", "gemini_cli", "copilot"]);
+
+function adapterFor(type: string, registry?: AgentRegistry) {
+  // Adapters that consult the registry during detection get the seeded
+  // isolated instance so replay never reads real ~/.ai-devkit state.
+  if (type === "codex" && registry) return new CodexAdapter(registry);
+  if (type === "pi" && registry) return new PiAdapter(registry);
+  if (type === "gemini_cli" && registry) return new GeminiCliAdapter(registry);
+  if (type === "copilot" && registry) return new CopilotAdapter(registry);
+  const adapter = createBuiltinAdapters().find((a) => a.type === type);
+  if (!adapter) throw new Error(`no builtin adapter for "${type}"`);
+  return adapter;
+}
+
+/** Seed an isolated registry at `<home>/.ai-devkit/agents.json`. */
+function seedRegistry(
+  bundle: FixtureBundle,
+  home: string,
+  nowIso: string,
+): AgentRegistry | undefined {
+  if (!REGISTRY_AWARE.has(bundle.adapter)) return undefined;
+  const registry = new AgentRegistry(path.join(home, ".ai-devkit", "agents.json"));
+  const entries = (bundle.registry ?? []).map(
+    (e) =>
+      ({
+        name: "",
+        type: bundle.adapter,
+        runtime: "tmux",
+        runtimeRef: null,
+        cwd: "",
+        startedAt: nowIso,
+        sessionId: "",
+        sessionFilePath: "",
+        pinned: false,
+        ...expand(expandNow(e as Record<string, unknown>, nowIso), home),
+      }) as RegistryEntry,
+  );
+  registry.registerBatch(entries);
+  return registry;
+}
+
+/** Materialize a bundle into a temp HOME; returns cleanup + replay inputs. */
+function materialize(bundle: FixtureBundle) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "fixture-home-"));
+  // "$TODAY" resolves to the local `YYYY/MM/DD` day key at write time — Codex
+  // date-dir discovery derives day keys from process start times in local
+  // time, so static dirs would drift across replay days/timezones.
+  const now = new Date();
+  const todayKey = [
+    String(now.getFullYear()).padStart(4, "0"),
+    String(now.getMonth() + 1).padStart(2, "0"),
+    String(now.getDate()).padStart(2, "0"),
+  ].join("/");
+  for (const [rel, content] of Object.entries(bundle.home)) {
+    const p = path.join(home, expand(rel.split("$TODAY").join(todayKey), home));
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, expand(content.split("$TODAY").join(todayKey), home));
+  }
+  // SQLite stores (OpenCode's opencode.db) materialize from ordered SQL
+  // statements — binary dbs can't travel in the JSON `home` map.
+  for (const [rel, stmts] of Object.entries(bundle.sqlite ?? {})) {
+    const p = path.join(home, expand(rel.split("$TODAY").join(todayKey), home));
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const db = new Database(p);
+    try {
+      for (const stmt of stmts) {
+        db.exec(expand(stmt.split("$TODAY").join(todayKey), home));
+      }
+    } finally {
+      db.close();
+    }
+  }
+  // "$NOW" resolves to the instant home files were written — legacy
+  // cwd+birthtime matching compares process start times against real file
+  // creation times, so a static timestamp would drift out of tolerance.
+  const nowIso = new Date().toISOString();
+  // Deterministic mtimes for adapters that read them (Grok lastActive /
+  // latest-session pick) — "$NOW" resolves like the process sentinel.
+  for (const [rel, mt] of Object.entries(bundle.mtimes ?? {})) {
+    const p = path.join(home, expand(rel.split("$TODAY").join(todayKey), home));
+    const ms = mt === "$NOW" ? Date.parse(nowIso) : mt;
+    fs.utimesSync(p, ms / 1000, ms / 1000);
+  }
+  // JSON round-tripped Date fields (e.g. ProcessInfo.startTime) come back as
+  // ISO strings — adapters expect real Date instances.
+  const processes = expandNow(expand(bundle.processes, home), nowIso).map((p) => ({
+    ...p,
+    startTime: p.startTime ? new Date(p.startTime) : undefined,
+  }));
+  const frozenNow = bundle.frozenNow === "$NOW" ? Date.parse(nowIso) : bundle.frozenNow;
+  // Pids whose startTime resolves to the materialization instant — Codex
+  // derives session day-dirs from start times, so only these paths contain
+  // the replay-day key and normalize to $TODAY.
+  const nowPids = new Set(bundle.processes.filter((p) => p.startTime === "$NOW").map((p) => p.pid));
+  return {
+    home,
+    processes,
+    frozenNow,
+    todayKey,
+    // Only $NOW resolves — $FIXTURE_HOME and $TODAY stay literal to match
+    // the normalized actual form.
+    expected: expandNow(bundle.expected, nowIso),
+    cleanup: () => fs.rmSync(home, { recursive: true, force: true }),
+    nowIso,
+    nowPids,
+  };
+}
+
+describe("fixture replay (TS parity oracle)", () => {
+  const saved = process.env.HOME;
+  afterEach(() => {
+    if (saved === undefined) delete process.env.HOME;
+    else process.env.HOME = saved;
+  });
+
+  if (bundlePaths.length === 0) {
+    it.todo("no fixture bundles committed yet — run AI_DEVKIT_FIXTURE_CAPTURE=1");
+    return;
+  }
+
+  for (const bundlePath of bundlePaths) {
+    it(`replays ${path.relative(FIXTURES_ROOT, bundlePath)}`, async () => {
+      const bundle: FixtureBundle = JSON.parse(fs.readFileSync(bundlePath, "utf8"));
+      const { home, processes, frozenNow, expected, cleanup, todayKey, nowIso, nowPids } =
+        materialize(bundle);
+      // Pin XDG to the fixture's canonical share dir — an ambient
+      // XDG_DATA_HOME would resolve the real opencode.db into replay.
+      const savedXdg = process.env.XDG_DATA_HOME;
+      // Same for ANTIGRAVITY_CLI_HOME — clearing it falls the adapter
+      // back to the pinned HOME's canonical base dir.
+      const savedAgy = process.env.ANTIGRAVITY_CLI_HOME;
+      try {
+        process.env.HOME = home;
+        process.env.XDG_DATA_HOME = path.join(home, ".local", "share");
+        delete process.env.ANTIGRAVITY_CLI_HOME;
+        const registry = seedRegistry(bundle, home, nowIso);
+        const agents = await withFrozenClock(frozenNow, () =>
+          adapterFor(bundle.adapter, registry).detectAgents({ processes }),
+        );
+        // Day-key dirs normalize back to $TODAY only for agents whose
+        // process startTime was $NOW — static-start agents keep concrete
+        // dates so live bundles stay replayable on any day.
+        const actual = JSON.parse(JSON.stringify(normalizeAgents(agents, home))).map((a) =>
+          nowPids.has(a.pid) ? JSON.parse(JSON.stringify(a).split(todayKey).join("$TODAY")) : a,
+        );
+        expect(actual).toEqual(expected);
+      } finally {
+        if (savedXdg === undefined) delete process.env.XDG_DATA_HOME;
+        else process.env.XDG_DATA_HOME = savedXdg;
+        if (savedAgy === undefined) delete process.env.ANTIGRAVITY_CLI_HOME;
+        else process.env.ANTIGRAVITY_CLI_HOME = savedAgy;
+        cleanup();
+      }
+    });
+  }
+});
+
+// Opt-in live capture: AI_DEVKIT_FIXTURE_CAPTURE=1 npx vitest run fixtures
+describe.runIf(process.env.AI_DEVKIT_FIXTURE_CAPTURE === "1")("fixture capture (live)", () => {
+  it("captures claude bundle from the live machine", async () => {
+    const out = await captureLive(adapterFor("claude"), "live");
+    expect(fs.existsSync(out)).toBe(true);
+  }, 30000);
+
+  it("captures codex bundle from the live machine", async () => {
+    const out = await captureLive(adapterFor("codex"), "live");
+    expect(fs.existsSync(out)).toBe(true);
+  }, 30000);
+
+  it("captures pi bundle from the live machine", async () => {
+    const out = await captureLive(adapterFor("pi"), "live");
+    expect(fs.existsSync(out)).toBe(true);
+  }, 30000);
+
+  it("captures gemini_cli bundle from the live machine", async () => {
+    const out = await captureLive(adapterFor("gemini_cli"), "live");
+    expect(fs.existsSync(out)).toBe(true);
+  }, 30000);
+
+  it("captures copilot bundle from the live machine", async () => {
+    const out = await captureLive(adapterFor("copilot"), "live");
+    expect(fs.existsSync(out)).toBe(true);
+  }, 30000);
+
+  it("captures grok_cli bundle from the live machine", async () => {
+    const out = await captureLive(adapterFor("grok_cli"), "live");
+    expect(fs.existsSync(out)).toBe(true);
+  }, 30000);
+
+  it("captures opencode bundle from the live machine", async () => {
+    const out = await captureLive(adapterFor("opencode"), "live");
+    expect(fs.existsSync(out)).toBe(true);
+  }, 30000);
+
+  it("captures devin bundle from the live machine", async () => {
+    const out = await captureLive(adapterFor("devin"), "live");
+    expect(fs.existsSync(out)).toBe(true);
+  }, 30000);
+
+  it("captures kiro bundle from the live machine", async () => {
+    const out = await captureLive(adapterFor("kiro"), "live");
+    expect(fs.existsSync(out)).toBe(true);
+  }, 30000);
+
+  it("captures antigravity_cli bundle from the live machine", async () => {
+    const out = await captureLive(adapterFor("antigravity_cli"), "live");
+    expect(fs.existsSync(out)).toBe(true);
+  }, 30000);
+});

package/src/__tests__/harnesses/devin/DevinAdapter.test.ts

@@ -239,9 +239,7 @@ describe("DevinAdapter", () => {
         { id: "newer", directory: "/repo", timeCreated: now - 200, lastActivityAt: now - 60 },
         { id: "hidden-sess", directory: "/repo", timeCreated: now - 10, hidden: 1 },
       ],
-      nodes: [
-        { sessionId: "newer", nodeId: 1, role: "user", content: "hi", createdAt: now - 60 },
-      ],
+      nodes: [{ sessionId: "newer", nodeId: 1, role: "user", content: "hi", createdAt: now - 60 }],
     });
 
     const agents = await adapter.detectAgents({

package/src/__tests__/harnesses/devin/DevinSessionParser.test.ts

@@ -59,9 +59,7 @@ describe("DevinSessionParser", () => {
     });
     const db = openDb();
     try {
-      expect(parser.getConversation(db, "s")).toEqual([
-        { role: "assistant", content: "final" },
-      ]);
+      expect(parser.getConversation(db, "s")).toEqual([{ role: "assistant", content: "final" }]);
     } finally {
       db.close();
     }
@@ -99,9 +97,7 @@ describe("DevinSessionParser", () => {
     });
     const db = openDb();
     try {
-      expect(parser.getConversation(db, "s")).toEqual([
-        { role: "assistant", content: "working" },
-      ]);
+      expect(parser.getConversation(db, "s")).toEqual([{ role: "assistant", content: "working" }]);
       expect(parser.getConversation(db, "s", { verbose: true })).toEqual([
         { role: "assistant", content: "[thinking] hmm" },
         { role: "assistant", content: "working" },
@@ -145,9 +141,7 @@ describe("DevinSessionParser", () => {
     });
     const db = openDb();
     try {
-      expect(parser.getConversation(db, "s")).toEqual([
-        { role: "assistant", content: "ok" },
-      ]);
+      expect(parser.getConversation(db, "s")).toEqual([{ role: "assistant", content: "ok" }]);
       expect(parser.getConversation(db, "missing")).toEqual([]);
     } finally {
       db.close();