@ai-devkit/agent-manager 0.35.0 → 0.37.0

package/src/capacity/openai.ts

@@ -0,0 +1,355 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseWhamUsage } from "./wham.js";
+import type { CapacityReport, CapacityWindow } from "./types.js";
+
+const OPENAI_USAGE_BASE_URL = "https://api.openai.com/v1/organization/usage";
+const OPENAI_MODELS_URL = "https://api.openai.com/v1/models";
+const WHAM_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const OPENAI_USAGE_ENDPOINTS = ["completions", "responses"] as const;
+const USAGE_WINDOW_DAYS = 7;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const MISSING_API_KEY_MESSAGE =
+  "OpenAI credentials not found; set OPENAI_API_KEY, configure the Pi openai provider, or log in to OpenAI via Pi";
+const EPOCH_MS_FLOOR = 1e12;
+
+export type OpenAiUsageBucket = { startMs: number; tokens: number };
+type UnknownRecord = Record<string, unknown>;
+
+/**
+ * Resolved OpenAI credential: a platform API key (env or Pi `openai` entry)
+ * or the OAuth login Pi stores as `openai-codex` for ChatGPT-backed access.
+ */
+export type OpenAiCredential =
+  | { kind: "platform"; key: string }
+  | { kind: "oauth"; access: string; accountId: string; expiresMs: number | null };
+
+export type OpenAiCredentialOptions = {
+  env?: NodeJS.ProcessEnv;
+  readFile?: (path: string, encoding: BufferEncoding) => Promise<string>;
+};
+
+export type OpenAiProbeOptions = OpenAiCredentialOptions & {
+  checkedAt: string;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+};
+type OpenAiRequestContext = OpenAiProbeOptions & { key: string };
+type OAuthCredential = Extract<OpenAiCredential, { kind: "oauth" }>;
+
+function record(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/** Pi stores `expires` in epoch milliseconds, codex-style tokens use seconds. */
+function toEpochMs(value: unknown): number | null {
+  const raw = finiteNumber(value);
+  if (raw === null || raw <= 0) return null;
+  return raw > EPOCH_MS_FLOOR ? raw : raw * 1000;
+}
+
+async function readPiAuthRoot(options: OpenAiCredentialOptions): Promise<UnknownRecord> {
+  const env = options.env ?? process.env;
+  const authPath = join(env.HOME || homedir(), ".pi", "agent", "auth.json");
+  let parsed: UnknownRecord;
+  try {
+    const contents = await (options.readFile ?? readFile)(authPath, "utf8");
+    const root = record(JSON.parse(contents));
+    if (!root) throw new Error("invalid");
+    parsed = root;
+  } catch (error) {
+    if (record(error)?.code === "ENOENT") {
+      throw new Error(MISSING_API_KEY_MESSAGE);
+    }
+    throw new Error("OpenAI Pi auth file is malformed");
+  }
+  return parsed;
+}
+
+/**
+ * Resolves the OpenAI credential in priority order: `OPENAI_API_KEY` env,
+ * then the Pi `openai` platform-key entry, then the Pi `openai-codex` OAuth
+ * login written by `pi login` (no manual setup required).
+ */
+export async function resolveOpenAiCredential(
+  options: OpenAiCredentialOptions = {},
+): Promise<OpenAiCredential> {
+  const env = options.env ?? process.env;
+  const environmentKey = nonEmptyText(env.OPENAI_API_KEY);
+  if (environmentKey) return { kind: "platform", key: environmentKey };
+
+  const parsed = await readPiAuthRoot(options);
+
+  const platform = record(parsed.openai);
+  if (platform) {
+    const key = platform.type === "api_key" ? nonEmptyText(platform.key) : null;
+    if (!key) {
+      throw new Error("OpenAI Pi auth file has a malformed openai credential");
+    }
+    return { kind: "platform", key };
+  }
+
+  const oauth = record(parsed["openai-codex"]);
+  const access = oauth?.type === "oauth" ? nonEmptyText(oauth.access) : null;
+  const accountId = nonEmptyText(oauth?.accountId);
+  if (oauth && access && accountId) {
+    return { kind: "oauth", access, accountId, expiresMs: toEpochMs(oauth.expires) };
+  }
+  throw new Error(MISSING_API_KEY_MESSAGE);
+}
+
+function bucketTokens(value: unknown): number {
+  const results = Array.isArray(value) ? value : [];
+  return results.reduce(
+    (total, entry) =>
+      total +
+      (finiteNumber(record(entry)?.input_tokens) ?? 0) +
+      (finiteNumber(record(entry)?.output_tokens) ?? 0),
+    0,
+  );
+}
+
+/**
+ * Maps one OpenAI Usage API payload (day buckets of per-model token counts)
+ * into summed UTC-day buckets. Entries without a numeric
+ * aggregation_timestamp are skipped because they cannot be placed in time.
+ */
+export function parseOpenAiUsage(raw: unknown): OpenAiUsageBucket[] {
+  const data = record(raw)?.data;
+  if (!Array.isArray(data)) throw new Error("Invalid OpenAI usage response");
+  const buckets: OpenAiUsageBucket[] = [];
+  for (const entry of data) {
+    const seconds = finiteNumber(record(entry)?.aggregation_timestamp);
+    if (seconds === null) continue;
+    buckets.push({ startMs: seconds * 1000, tokens: bucketTokens(record(entry)?.results) });
+  }
+  return buckets;
+}
+
+function openAiCapacityReport(
+  windows: CapacityWindow[],
+  checkedAt: string,
+  authenticated: boolean,
+): CapacityReport {
+  return {
+    harness: "pi",
+    provider: "openai",
+    generatedAt: checkedAt,
+    authenticated,
+    available: windows.length > 0 ? "yes" : "unknown",
+    windows,
+    creditsRemaining: null,
+  };
+}
+
+/**
+ * Builds the capacity report from merged day buckets: trailing-7-day and
+ * current-UTC-day token usage. The platform is pay-as-you-go and exposes no
+ * queryable limit, so windows report consumption only — no faked percentages.
+ */
+export function buildOpenAiReport(buckets: OpenAiUsageBucket[], checkedAt: string): CapacityReport {
+  const nowMs = Date.parse(checkedAt);
+  const todayStartMs = Math.floor(nowMs / DAY_MS) * DAY_MS;
+  const weekStartMs = todayStartMs - (USAGE_WINDOW_DAYS - 1) * DAY_MS;
+  let todayTokens = 0;
+  let weekTokens = 0;
+  for (const bucket of buckets) {
+    if (bucket.startMs === todayStartMs) todayTokens += bucket.tokens;
+    if (bucket.startMs >= weekStartMs) weekTokens += bucket.tokens;
+  }
+  const windows: CapacityWindow[] = [
+    {
+      id: "openai:tokens:today",
+      label: "Tokens · today (UTC)",
+      limitType: "TOKENS_LIMIT",
+      durationMinutes: 24 * 60,
+      usedPercent: null,
+      resetsAt: new Date(todayStartMs + DAY_MS).toISOString(),
+      total: null,
+      current: todayTokens,
+      remaining: null,
+    },
+    {
+      id: "openai:tokens:week",
+      label: "Tokens · 7 days",
+      limitType: "TOKENS_LIMIT",
+      durationMinutes: USAGE_WINDOW_DAYS * 24 * 60,
+      usedPercent: null,
+      resetsAt: null,
+      total: null,
+      current: weekTokens,
+      remaining: null,
+    },
+  ];
+  return openAiCapacityReport(windows, checkedAt, true);
+}
+
+async function fetchUsage(context: OpenAiRequestContext): Promise<unknown[] | number | null> {
+  const fetcher = context.fetch ?? globalThis.fetch;
+  const endSeconds = Math.floor(Date.parse(context.checkedAt) / 1000);
+  const startSeconds = endSeconds - USAGE_WINDOW_DAYS * 24 * 60 * 60;
+  const query = `start_time=${startSeconds}&end_time=${endSeconds}`;
+  const payloads: unknown[] = [];
+  for (const endpoint of OPENAI_USAGE_ENDPOINTS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), context.timeoutMs ?? 5000);
+    let response: Response;
+    try {
+      response = await fetcher(`${OPENAI_USAGE_BASE_URL}/${endpoint}?${query}`, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${context.key}`,
+        },
+        signal: controller.signal,
+      });
+    } catch {
+      throw new Error("OpenAI usage request failed");
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.status === 401) return null;
+    if (response.status === 403) return response.status;
+    if (response.status !== 200) {
+      throw new Error(`OpenAI usage request failed: HTTP ${response.status}`);
+    }
+    try {
+      payloads.push(await response.json());
+    } catch {
+      throw new Error("OpenAI usage response is not valid JSON");
+    }
+  }
+  return payloads;
+}
+
+async function verifyKey(context: OpenAiRequestContext): Promise<boolean> {
+  const fetcher = context.fetch ?? globalThis.fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), context.timeoutMs ?? 5000);
+  try {
+    const response = await fetcher(OPENAI_MODELS_URL, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${context.key}` },
+      signal: controller.signal,
+    });
+    return response.status !== 401;
+  } catch {
+    throw new Error("OpenAI usage request failed");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function probeOpenAiCapacity(options: OpenAiProbeOptions): Promise<CapacityReport> {
+  const credential = await resolveOpenAiCredential(options);
+  if (credential.kind === "oauth") {
+    return probeOpenAiOauthCapacity(credential, options);
+  }
+  const probe: OpenAiProbeOptions & { key: string } = { ...options, key: credential.key };
+  const result = await fetchUsage(probe);
+  if (result === null) {
+    return openAiCapacityReport([], options.checkedAt, false);
+  }
+  if (typeof result === "number") {
+    const authenticated = await verifyKey(probe);
+    return openAiCapacityReport([], options.checkedAt, authenticated);
+  }
+  const buckets = result.flatMap(parseOpenAiUsage);
+  return buildOpenAiReport(buckets, options.checkedAt);
+}
+
+/** Mirrors codex.ts: JWT `exp` (epoch seconds) as expiry fallback. */
+function jwtExpiryMs(token: string): number | null {
+  const part = token.split(".")[1];
+  if (!part) return null;
+  try {
+    const exp = finiteNumber(
+      record(JSON.parse(Buffer.from(part, "base64url").toString("utf8")))?.exp,
+    );
+    return exp === null ? null : exp * 1000;
+  } catch {
+    return null;
+  }
+}
+
+function oauthExpired(credential: OAuthCredential, nowMs: number): boolean {
+  const expiryMs = credential.expiresMs ?? jwtExpiryMs(credential.access);
+  return expiryMs !== null && expiryMs <= nowMs;
+}
+
+async function fetchWhamUsage(
+  credential: OAuthCredential,
+  options: OpenAiProbeOptions,
+): Promise<unknown | null> {
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 5000);
+  let response: Response;
+  try {
+    response = await fetcher(WHAM_USAGE_URL, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${credential.access}`,
+        "ChatGPT-Account-Id": credential.accountId,
+      },
+      signal: controller.signal,
+    });
+  } catch {
+    throw new Error("OpenAI usage request failed");
+  } finally {
+    clearTimeout(timer);
+  }
+  if (response.status === 401 || response.status === 403) return null;
+  if (response.status !== 200) {
+    throw new Error(`OpenAI usage request failed: HTTP ${response.status}`);
+  }
+  try {
+    return await response.json();
+  } catch {
+    throw new Error("OpenAI usage response is not valid JSON");
+  }
+}
+
+/**
+ * OAuth path for Pi's OpenAI login: consumes the same wham/usage endpoint as
+ * the codex harness. Stale logins are never fetched (no refresh, matching
+ * codex.ts); they render as authenticated-but-stale instead.
+ */
+async function probeOpenAiOauthCapacity(
+  credential: OAuthCredential,
+  options: OpenAiProbeOptions,
+): Promise<CapacityReport> {
+  const staleReport: CapacityReport = {
+    harness: "pi",
+    provider: "openai",
+    generatedAt: options.checkedAt,
+    authenticated: true,
+    available: "unknown",
+    windows: [],
+    creditsRemaining: null,
+  };
+  const nowMs = Date.parse(options.checkedAt);
+  if (Number.isNaN(nowMs) || oauthExpired(credential, nowMs)) return staleReport;
+  const raw = await fetchWhamUsage(credential, options);
+  if (raw === null) {
+    return { ...staleReport, authenticated: false };
+  }
+  const snapshot = parseWhamUsage(raw);
+  const hasUsage = snapshot.windows.some((window) => window.usedPercent !== null);
+  return {
+    ...staleReport,
+    available: hasUsage ? "yes" : "unknown",
+    windows: snapshot.windows,
+    creditsRemaining: snapshot.creditsRemaining,
+  };
+}

package/src/capacity/wham.ts

@@ -0,0 +1,84 @@
+import type { CapacityWindow } from "./types.js";
+
+type WhamUsageSnapshot = {
+  windows: CapacityWindow[];
+  creditsRemaining: number | null;
+};
+
+type UnknownRecord = Record<string, unknown>;
+
+function record(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+export function resetTime(value: unknown): string | null {
+  const seconds = finiteNumber(value);
+  if (seconds !== null) return new Date(seconds * 1000).toISOString();
+  if (typeof value === "string" && !Number.isNaN(Date.parse(value)))
+    return new Date(value).toISOString();
+  return null;
+}
+
+export function safeIdentifier(value: unknown): string | null {
+  const candidate = nonEmptyText(value);
+  if (!candidate || !/^[a-z][a-z0-9_-]{0,63}$/i.test(candidate)) return null;
+  if (/(?:account|token|secret|key)[_-]?\d{6,}/i.test(candidate)) return null;
+  return candidate;
+}
+
+export function toRateWindow(value: unknown, id: string, label: string): CapacityWindow | null {
+  const input = record(value);
+  if (!input) return null;
+  const used = finiteNumber(input.used_percent);
+  const seconds = finiteNumber(input.limit_window_seconds);
+  return {
+    id,
+    label,
+    durationMinutes: seconds === null ? null : seconds / 60,
+    usedPercent: used,
+    resetsAt: resetTime(input.reset_at),
+  };
+}
+
+function extraWindows(value: unknown): CapacityWindow[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry, index) => {
+    const limit = record(entry);
+    if (!limit) return [];
+    const scope = safeIdentifier(limit.limit_name) ?? `extra-${index + 1}`;
+    const windows = record(limit.rate_limit) ?? limit;
+    return [
+      toRateWindow(windows.primary_window, `${scope}:primary`, `${scope} primary`),
+      toRateWindow(windows.secondary_window, `${scope}:secondary`, `${scope} secondary`),
+    ].filter((window): window is CapacityWindow => window !== null);
+  });
+}
+
+/**
+ * Parses the chatgpt.com backend wham/usage payload shared by every
+ * OAuth-backed OpenAI consumer (codex harness and pi login) into generic
+ * capacity windows plus the credit balance.
+ */
+export function parseWhamUsage(raw: unknown): WhamUsageSnapshot {
+  const response = record(raw) ?? {};
+  const limits = record(response.rate_limit) ?? {};
+  const credits = record(response.credits) ?? {};
+  return {
+    windows: [
+      toRateWindow(limits.primary_window, "session", "Session"),
+      toRateWindow(limits.secondary_window, "weekly", "Weekly"),
+      ...extraWindows(response.additional_rate_limits),
+    ].filter((window): window is CapacityWindow => window !== null),
+    creditsRemaining: finiteNumber(credits.balance),
+  };
+}

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);
+  }
+}