@ai-devkit/agent-manager 0.36.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,20 +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"
-  | "kiro"
-  | "antigravity_cli"
-  | "codex"
-  | "opencode"
-  | "copilot"
-  | "pi"
-  | "other";
+export type AgentType = (typeof AGENT_TYPES)[number] | "other";
 
 /**
  * Current status of an agent
@@ -97,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).
  *
@@ -192,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.
@@ -214,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.
    */

package/src/capacity/openai.ts

@@ -109,12 +109,6 @@ export async function resolveOpenAiCredential(
   throw new Error(MISSING_API_KEY_MESSAGE);
 }
 
-export async function resolveOpenAiApiKey(options: OpenAiCredentialOptions = {}): Promise<string> {
-  const credential = await resolveOpenAiCredential(options);
-  if (credential.kind === "platform") return credential.key;
-  throw new Error(MISSING_API_KEY_MESSAGE);
-}
-
 function bucketTokens(value: unknown): number {
   const results = Array.isArray(value) ? value : [];
   return results.reduce(

package/src/harnesses/antigravity/AntigravityAgentMapper.ts

@@ -0,0 +1,34 @@
+import type { AgentInfo, ProcessInfo } from "../../adapters/AgentAdapter.js";
+import { generateAgentName } from "../../utils/matching.js";
+import { processOnlyAgent } from "../shared.js";
+import { AntigravitySessionParser, type AntigravitySession } from "./AntigravitySessionParser.js";
+
+export interface AntigravitySessionAgentInput {
+  session: AntigravitySession;
+  processInfo: ProcessInfo;
+}
+
+export class AntigravityAgentMapper {
+  constructor(private readonly parser: AntigravitySessionParser = new AntigravitySessionParser()) {}
+
+  mapSessionToAgent({ session, processInfo }: AntigravitySessionAgentInput): AgentInfo {
+    return {
+      name: generateAgentName(session.projectPath, processInfo.pid),
+      type: "antigravity_cli",
+      status: this.parser.determineStatus(session),
+      summary: session.lastUserMessage || "Antigravity CLI session active",
+      pid: processInfo.pid,
+      projectPath: session.projectPath,
+      sessionId: session.sessionId,
+      lastActive: session.lastActive,
+      sessionFilePath: session.sessionFilePath,
+    };
+  }
+
+  mapProcessOnlyAgent(processInfo: ProcessInfo, cwd: string): AgentInfo {
+    return processOnlyAgent("antigravity_cli", processInfo, {
+      summary: "Antigravity CLI process running",
+      cwd,
+    });
+  }
+}

package/src/harnesses/antigravity/AntigravityCliAdapter.ts

@@ -0,0 +1,126 @@
+import type {
+  AgentAdapter,
+  AgentDetectionContext,
+  AgentInfo,
+  ProcessInfo,
+  ConversationMessage,
+  ConversationOptions,
+  SessionSummary,
+  ListSessionsOptions,
+} from "../../adapters/AgentAdapter.js";
+import { findHarnessProcesses, matchesExecutable } from "../shared.js";
+import { AntigravityAgentMapper } from "./AntigravityAgentMapper.js";
+import { AntigravitySessionLocator } from "./AntigravitySessionLocator.js";
+import { AntigravitySessionParser, type AntigravitySession } from "./AntigravitySessionParser.js";
+
+/**
+ * Antigravity CLI Adapter
+ *
+ * Detects running Antigravity CLI agents (Google's `agy` native binary) by:
+ * 1. Filtering `agy` processes from the shared process snapshot.
+ * 2. Resolving each process to its conversation via
+ *    ~/.gemini/antigravity-cli/cache/last_conversations.json, a
+ *    `{ <cwd>: <conversationId> }` map keyed by the process cwd.
+ * 3. Reading brain/<conversationId>/.system_generated/logs/transcript.jsonl;
+ *    the last user request is the summary.
+ *
+ * This is the runtime side of Antigravity, independent of the `antigravity`
+ * environment that configures the Antigravity IDE.
+ */
+export class AntigravityCliAdapter implements AgentAdapter {
+  readonly type = "antigravity_cli" as const;
+  readonly processNames = ["agy"] as const;
+
+  private parser: AntigravitySessionParser;
+  private mapper: AntigravityAgentMapper;
+  private locator: AntigravitySessionLocator;
+
+  constructor() {
+    this.parser = new AntigravitySessionParser();
+    this.mapper = new AntigravityAgentMapper(this.parser);
+    this.locator = new AntigravitySessionLocator();
+  }
+
+  canHandle(processInfo: ProcessInfo): boolean {
+    return matchesExecutable(processInfo.command, "agy");
+  }
+
+  async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    try {
+      return await this.detectRunningAgents(context);
+    } finally {
+      // Drop cached summaries for sessions that were not part of this refresh
+      this.parser.pruneSessionCache();
+    }
+  }
+
+  private async detectRunningAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    const { processes } = await findHarnessProcesses(this, context);
+    if (processes.length === 0) {
+      return [];
+    }
+
+    const agents: AgentInfo[] = [];
+    for (const { process: proc, cwd, conversation } of this.locator.matchRunningProcesses(
+      processes,
+    )) {
+      const session = conversation
+        ? this.parser.readSessionIncremental(
+            conversation.conversationId,
+            conversation.transcriptPath,
+            cwd,
+          )
+        : null;
+      if (session) {
+        agents.push(this.mapper.mapSessionToAgent({ session, processInfo: proc }));
+      } else {
+        agents.push(this.mapper.mapProcessOnlyAgent(proc, cwd));
+      }
+    }
+    return agents;
+  }
+
+  getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[] {
+    return this.parser.getConversation(sessionFilePath, options);
+  }
+
+  async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+    const filterCwd = opts?.cwd;
+    const summaries: SessionSummary[] = [];
+
+    for (const { cwd, conversationId, transcriptPath } of this.locator.listConversations()) {
+      if (filterCwd !== undefined && cwd !== filterCwd) continue;
+
+      const session = this.parser.readSession(conversationId, transcriptPath, cwd);
+      if (!session) continue;
+
+      summaries.push(this.toSessionSummary(session));
+    }
+
+    return summaries;
+  }
+
+  /** Only registered conversations are listed, so look the id up in the registry. */
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    const summaries: SessionSummary[] = [];
+    for (const { cwd, conversationId, transcriptPath } of this.locator.listConversations()) {
+      if (conversationId !== sessionId) continue;
+
+      const session = this.parser.readSession(conversationId, transcriptPath, cwd);
+      if (session) summaries.push(this.toSessionSummary(session));
+    }
+    return summaries;
+  }
+
+  private toSessionSummary(session: AntigravitySession): SessionSummary {
+    return {
+      type: this.type,
+      sessionId: session.sessionId,
+      cwd: session.projectPath,
+      firstUserMessage: session.firstUserMessage || "",
+      lastActive: session.lastActive,
+      startedAt: session.sessionStart,
+      sessionFilePath: session.sessionFilePath,
+    };
+  }
+}

package/src/harnesses/antigravity/AntigravitySessionLocator.ts

@@ -0,0 +1,75 @@
+import * as path from "path";
+import type { ProcessInfo } from "../../adapters/AgentAdapter.js";
+import { safeReadFile } from "../../utils/session.js";
+import { homeDir } from "../shared.js";
+
+const REGISTRY_FILE = path.join("cache", "last_conversations.json");
+const BRAIN_DIR = "brain";
+const TRANSCRIPT_REL = path.join(".system_generated", "logs", "transcript.jsonl");
+
+/** A workspace cwd and the conversation the CLI last used there. */
+export interface AntigravityConversationRef {
+  cwd: string;
+  conversationId: string;
+  transcriptPath: string;
+}
+
+/** A live `agy` process paired with its cwd and (if registered) conversation. */
+export interface AntigravityProcessMatch {
+  process: ProcessInfo;
+  cwd: string;
+  conversation: AntigravityConversationRef | null;
+}
+
+export interface AntigravitySessionLocatorOptions {
+  /** Overrides the base dir (defaults to ANTIGRAVITY_CLI_HOME or ~/.gemini/antigravity-cli). */
+  baseDir?: string;
+}
+
+export class AntigravitySessionLocator {
+  private readonly baseDir: string;
+
+  constructor(options: AntigravitySessionLocatorOptions = {}) {
+    this.baseDir =
+      options.baseDir ??
+      (process.env.ANTIGRAVITY_CLI_HOME || path.join(homeDir(), ".gemini", "antigravity-cli"));
+  }
+
+  /** Pair live processes with their conversation, joined on the process cwd. */
+  matchRunningProcesses(processes: ProcessInfo[]): AntigravityProcessMatch[] {
+    const byCwd = new Map(this.listConversations().map((ref) => [ref.cwd, ref]));
+    return processes.map((proc) => {
+      const cwd = proc.cwd || "";
+      return { process: proc, cwd, conversation: byCwd.get(cwd) ?? null };
+    });
+  }
+
+  /**
+   * Read cache/last_conversations.json, a `{ <cwd>: <conversationId> }` map the
+   * CLI rewrites as the current conversation per workspace changes.
+   */
+  listConversations(): AntigravityConversationRef[] {
+    const content = safeReadFile(path.join(this.baseDir, REGISTRY_FILE));
+    if (content === undefined) return [];
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      return [];
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return [];
+
+    const refs: AntigravityConversationRef[] = [];
+    for (const [cwd, conversationId] of Object.entries(parsed as Record<string, unknown>)) {
+      if (cwd && typeof conversationId === "string" && conversationId) {
+        refs.push({ cwd, conversationId, transcriptPath: this.transcriptPath(conversationId) });
+      }
+    }
+    return refs;
+  }
+
+  private transcriptPath(conversationId: string): string {
+    return path.join(this.baseDir, BRAIN_DIR, conversationId, TRANSCRIPT_REL);
+  }
+}