@ai-devkit/agent-manager 0.32.0 → 0.33.1

package/src/providers/gemini/GeminiSessionLocator.ts

@@ -0,0 +1,183 @@
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import type { ProcessInfo } from "../../adapters/AgentAdapter.js";
+import type { SessionFile } from "../../utils/session.js";
+import { isDirectory, safeReaddir } from "../../utils/session.js";
+
+export interface GeminiSessionDiscovery {
+  sessions: SessionFile[];
+  contentCache: Map<string, string>;
+}
+
+export interface GeminiSessionLocatorOptions {
+  geminiTmpDir?: string;
+}
+
+interface GeminiSessionMetadata {
+  sessionId?: string;
+  projectHash?: string;
+}
+
+const SESSION_FILE_PREFIX = "session-";
+const CHATS_DIR_NAME = "chats";
+
+export class GeminiSessionLocator {
+  private readonly geminiTmpDir: string;
+
+  constructor(options: GeminiSessionLocatorOptions = {}) {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+    this.geminiTmpDir = options.geminiTmpDir ?? path.join(homeDir, ".gemini", "tmp");
+  }
+
+  /**
+   * Discover session files for the given processes.
+   *
+   * Gemini CLI writes sessions to ~/.gemini/tmp/<shortId>/chats/session-*.json
+   * where <shortId> is opaque (managed by a project registry). We scan every
+   * shortId directory and filter by matching session.projectHash against
+   * sha256(process.cwd) to bind each session to a candidate process CWD.
+   */
+  discoverSessions(processes: ProcessInfo[]): GeminiSessionDiscovery {
+    const empty = { sessions: [] as SessionFile[], contentCache: new Map<string, string>() };
+    if (!fs.existsSync(this.geminiTmpDir)) return empty;
+
+    const cwdHashMap = this.buildCwdHashMap(processes);
+    if (cwdHashMap.size === 0) return empty;
+
+    const contentCache = new Map<string, string>();
+    const sessions: SessionFile[] = [];
+
+    let shortIdEntries: string[];
+    try {
+      shortIdEntries = fs.readdirSync(this.geminiTmpDir);
+    } catch {
+      return empty;
+    }
+
+    for (const shortId of shortIdEntries) {
+      const chatsDir = path.join(this.geminiTmpDir, shortId, CHATS_DIR_NAME);
+      if (!isDirectory(chatsDir)) continue;
+
+      for (const fileName of safeReaddir(chatsDir)) {
+        if (!this.isSessionFile(fileName)) continue;
+
+        const session = this.readCandidateSession(chatsDir, fileName, cwdHashMap);
+        if (!session) continue;
+
+        contentCache.set(session.filePath, session.content);
+        sessions.push(session.sessionFile);
+      }
+    }
+
+    return { sessions, contentCache };
+  }
+
+  discoverHistoricalSessionFiles(): string[] {
+    if (!isDirectory(this.geminiTmpDir)) return [];
+
+    const files: string[] = [];
+    for (const shortId of safeReaddir(this.geminiTmpDir)) {
+      const chatsDir = path.join(this.geminiTmpDir, shortId, CHATS_DIR_NAME);
+      if (!isDirectory(chatsDir)) continue;
+
+      for (const fileName of safeReaddir(chatsDir)) {
+        if (this.isSessionFile(fileName)) {
+          files.push(path.join(chatsDir, fileName));
+        }
+      }
+    }
+
+    return files;
+  }
+
+  private readCandidateSession(
+    chatsDir: string,
+    fileName: string,
+    cwdHashMap: Map<string, string>,
+  ): { filePath: string; content: string; sessionFile: SessionFile } | null {
+    const filePath = path.join(chatsDir, fileName);
+
+    let content: string;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      return null;
+    }
+
+    const parsed = this.parseSessionMetadata(content);
+    if (!parsed?.projectHash) return null;
+
+    const resolvedCwd = cwdHashMap.get(parsed.projectHash);
+    if (!resolvedCwd) return null;
+
+    let birthtimeMs = 0;
+    try {
+      birthtimeMs = fs.statSync(filePath).birthtimeMs;
+    } catch {
+      return null;
+    }
+
+    return {
+      filePath,
+      content,
+      sessionFile: {
+        sessionId: parsed.sessionId || fileName.replace(/\.json$/, ""),
+        filePath,
+        projectDir: chatsDir,
+        birthtimeMs,
+        resolvedCwd,
+      },
+    };
+  }
+
+  private buildCwdHashMap(processes: ProcessInfo[]): Map<string, string> {
+    const map = new Map<string, string>();
+    for (const proc of processes) {
+      if (!proc.cwd) continue;
+
+      // Gemini CLI resolves its project root by walking up from the
+      // startup directory looking for a `.git` boundary marker. A
+      // session's projectHash therefore tracks that ancestor rather
+      // than the process' actual CWD. Enumerate every ancestor as a
+      // candidate so subdirectory invocations still line up with the
+      // session the Gemini process wrote.
+      for (const candidate of this.candidateProjectRoots(proc.cwd)) {
+        const hash = this.hashProjectRoot(candidate);
+        if (!map.has(hash)) {
+          map.set(hash, proc.cwd);
+        }
+      }
+    }
+    return map;
+  }
+
+  private candidateProjectRoots(cwd: string): string[] {
+    const roots: string[] = [];
+    let current = path.resolve(cwd);
+    let parent = path.dirname(current);
+    while (parent !== current) {
+      roots.push(current);
+      current = parent;
+      parent = path.dirname(current);
+    }
+    roots.push(current);
+    return roots;
+  }
+
+  private hashProjectRoot(projectRoot: string): string {
+    return crypto.createHash("sha256").update(projectRoot).digest("hex");
+  }
+
+  private isSessionFile(fileName: string): boolean {
+    return fileName.startsWith(SESSION_FILE_PREFIX) && fileName.endsWith(".json");
+  }
+
+  private parseSessionMetadata(content: string): GeminiSessionMetadata | null {
+    try {
+      return JSON.parse(content) as GeminiSessionMetadata;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/providers/gemini/GeminiSessionParser.ts

@@ -0,0 +1,271 @@
+import * as fs from "fs";
+import type { ConversationMessage, SessionSummary } from "../../adapters/AgentAdapter.js";
+import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import { safeReadFile, safeStat } from "../../utils/session.js";
+
+/**
+ * A single Gemini CLI message content part. Mirrors the `{text?: string}`
+ * shape that Gemini writes for user message parts (derived from the
+ * Gemini API `Content.parts[]` schema). Non-text part variants (data,
+ * file, etc.) are preserved via the index signature but ignored by
+ * `resolveContent` since the adapter only surfaces human-readable text.
+ */
+interface GeminiContentPart {
+  text?: string;
+  [key: string]: unknown;
+}
+
+type GeminiMessageContent = string | GeminiContentPart[];
+
+export interface GeminiMessageEntry {
+  id?: string;
+  timestamp?: string;
+  type?: string;
+  /**
+   * Gemini CLI stores two different content shapes depending on the
+   * message origin:
+   * - `type: "user"` messages carry the raw Part[] from userContent.parts
+   *   (e.g. `[{ text: "hello" }]`).
+   * - `type: "gemini"` (assistant) messages carry a pre-joined string
+   *   built from `consolidatedParts.filter(p => p.text).join('').trim()`.
+   * Both forms must be normalized via resolveContent before any string
+   * operation is applied.
+   */
+  content?: GeminiMessageContent;
+  displayContent?: GeminiMessageContent;
+}
+
+export interface GeminiSessionFile {
+  sessionId?: string;
+  projectHash?: string;
+  startTime?: string;
+  lastUpdated?: string;
+  messages?: GeminiMessageEntry[];
+  directories?: string[];
+  kind?: string;
+}
+
+export interface GeminiSession {
+  sessionId: string;
+  projectPath: string;
+  summary: string;
+  sessionStart: Date;
+  lastActive: Date;
+  lastMessageType?: string;
+}
+
+const IDLE_THRESHOLD_MINUTES = 5;
+
+export class GeminiSessionParser {
+  /**
+   * Parse session file content into GeminiSession.
+   * Uses cached content if available, otherwise reads from disk.
+   */
+  parseSession(cachedContent: string | undefined, filePath: string): GeminiSession | null {
+    const content = cachedContent ?? this.readSessionFile(filePath);
+    if (content === null) return null;
+
+    const parsed = this.parseSessionJson(content);
+    if (!parsed?.sessionId) return null;
+
+    const messages = Array.isArray(parsed.messages) ? parsed.messages : [];
+    const lastEntry = messages.length > 0 ? messages[messages.length - 1] : undefined;
+    const fileStat = safeStat(filePath);
+
+    const lastActive =
+      this.parseTimestamp(parsed.lastUpdated) ||
+      this.parseTimestamp(lastEntry?.timestamp) ||
+      fileStat?.mtime ||
+      new Date();
+
+    const sessionStart = this.parseTimestamp(parsed.startTime) || lastActive;
+    const projectPath =
+      Array.isArray(parsed.directories) && parsed.directories.length > 0
+        ? parsed.directories[0]
+        : "";
+
+    return {
+      sessionId: parsed.sessionId,
+      projectPath,
+      summary: this.extractSummary(messages),
+      sessionStart,
+      lastActive,
+      lastMessageType: lastEntry?.type,
+    };
+  }
+
+  determineStatus(session: GeminiSession): AgentStatus {
+    const diffMs = Date.now() - session.lastActive.getTime();
+    const diffMinutes = diffMs / 60000;
+
+    if (diffMinutes > IDLE_THRESHOLD_MINUTES) {
+      return AgentStatus.IDLE;
+    }
+
+    if (session.lastMessageType === "gemini" || session.lastMessageType === "assistant") {
+      return AgentStatus.WAITING;
+    }
+
+    return AgentStatus.RUNNING;
+  }
+
+  /**
+   * Read the full conversation from a Gemini CLI session JSON file.
+   *
+   * Gemini sessions store messages in an array with `type` field — typically
+   * 'user' or 'gemini' for visible turns, with tool and system entries mixed in.
+   */
+  getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+    const verbose = options?.verbose ?? false;
+    const content = safeReadFile(sessionFilePath);
+    if (content === undefined) return [];
+
+    const parsed = this.parseSessionJson(content);
+    if (!Array.isArray(parsed?.messages)) return [];
+
+    const messages: ConversationMessage[] = [];
+    for (const entry of parsed.messages) {
+      const role = this.roleForEntry(entry?.type, verbose);
+      if (!role) continue;
+
+      const text = this.messageText(entry).trim();
+      if (!text) continue;
+
+      messages.push({
+        role,
+        content: text,
+        timestamp: entry.timestamp,
+      });
+    }
+
+    return messages;
+  }
+
+  /**
+   * Read a Gemini session JSON file and produce a {@link SessionSummary}.
+   * Returns null when the file is unreadable, the JSON doesn't parse,
+   * or the body lacks a sessionId.
+   */
+  fileToSessionSummary(filePath: string): SessionSummary | null {
+    const content = safeReadFile(filePath);
+    if (content === undefined) return null;
+
+    const parsed = this.parseSessionJson(content);
+    if (!parsed?.sessionId) return null;
+
+    const messages = Array.isArray(parsed.messages) ? parsed.messages : [];
+    const firstUserMessage = this.extractFirstUserMessage(messages);
+    const cwd =
+      Array.isArray(parsed.directories) && parsed.directories.length > 0
+        ? parsed.directories[0]
+        : "";
+
+    const stat = safeStat(filePath);
+    const lastEntryTimestamp = this.parseTimestamp(
+      messages.length > 0 ? messages[messages.length - 1]?.timestamp : undefined,
+    );
+    const lastActive =
+      this.parseTimestamp(parsed.lastUpdated) || lastEntryTimestamp || stat?.mtime || new Date();
+    const startedAt =
+      this.parseTimestamp(parsed.startTime) || stat?.birthtime || stat?.mtime || lastActive;
+
+    return {
+      type: "gemini_cli",
+      sessionId: parsed.sessionId,
+      cwd,
+      firstUserMessage,
+      lastActive,
+      startedAt,
+      sessionFilePath: filePath,
+    };
+  }
+
+  private parseSessionJson(content: string): GeminiSessionFile | null {
+    try {
+      return JSON.parse(content) as GeminiSessionFile;
+    } catch {
+      return null;
+    }
+  }
+
+  private readSessionFile(filePath: string): string | null {
+    try {
+      return fs.readFileSync(filePath, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+
+  private roleForEntry(
+    entryType: string | undefined,
+    verbose: boolean,
+  ): ConversationMessage["role"] | null {
+    if (entryType === "user") return "user";
+    if (entryType === "gemini" || entryType === "assistant") return "assistant";
+    if (verbose && entryType) return "system";
+    return null;
+  }
+
+  private extractSummary(messages: GeminiMessageEntry[]): string {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const entry = messages[i];
+      if (entry?.type !== "user") continue;
+      const text = this.messageText(entry).trim();
+      if (text) return this.truncate(text, 120);
+    }
+
+    return "Gemini CLI session active";
+  }
+
+  /**
+   * Normalize an entry's content/displayContent into a plain string.
+   * Prefers displayContent when both are present (matches Gemini CLI's
+   * own rendering priority for the /chat UI).
+   */
+  private messageText(entry: GeminiMessageEntry): string {
+    const displayText = this.resolveContent(entry.displayContent);
+    if (displayText) return displayText;
+    return this.resolveContent(entry.content);
+  }
+
+  /**
+   * Collapse a Gemini message content field into plain text.
+   * Accepts either a pre-joined string (assistant turns) or a Part[]
+   * list (user turns carrying `[{text: "..."}]`). Non-text part
+   * variants (data, file) are dropped since this helper is only used
+   * for summary/conversation rendering.
+   */
+  private resolveContent(content: GeminiMessageContent | undefined): string {
+    if (!content) return "";
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content)) return "";
+
+    const parts: string[] = [];
+    for (const part of content) {
+      if (part && typeof part.text === "string" && part.text) {
+        parts.push(part.text);
+      }
+    }
+    return parts.join("");
+  }
+
+  private extractFirstUserMessage(messages: GeminiMessageEntry[]): string {
+    for (const entry of messages) {
+      if (entry?.type !== "user") continue;
+      const text = this.messageText(entry).trim();
+      if (text) return text;
+    }
+    return "";
+  }
+
+  private parseTimestamp(value?: string): Date | null {
+    if (!value) return null;
+    const timestamp = new Date(value);
+    return Number.isNaN(timestamp.getTime()) ? null : timestamp;
+  }
+
+  private truncate(value: string, maxLength: number): string {
+    if (value.length <= maxLength) return value;
+    return `${value.slice(0, maxLength - 3)}...`;
+  }
+}

package/src/providers/pi/PiAdapter.ts

@@ -0,0 +1,183 @@
+import * as fs from "fs";
+import * as path from "path";
+import type {
+  AgentAdapter,
+  AgentInfo,
+  ProcessInfo,
+  ConversationMessage,
+  SessionSummary,
+  ListSessionsOptions,
+  AgentDetectionContext,
+} from "../../adapters/AgentAdapter.js";
+import {
+  captureProcessSnapshot,
+  executableBasename,
+  filterByProcessNames,
+} from "../../utils/process.js";
+import { AgentRegistry } from "../../utils/AgentRegistry.js";
+import { PiAgentMapper } from "./PiAgentMapper.js";
+import { PiSessionLocator } from "./PiSessionLocator.js";
+import { PiSessionParser } from "./PiSessionParser.js";
+import { PiSessionTracker } from "./PiSessionTracker.js";
+
+interface MappedAgentResult {
+  agents: AgentInfo[];
+  fallback: ProcessInfo[];
+}
+
+interface SessionFileMatch {
+  process: ProcessInfo;
+  filePath: string;
+}
+
+export class PiAdapter implements AgentAdapter {
+  readonly type = "pi" as const;
+  readonly processNames = ["pi", "node"] as const;
+
+  private readonly piSessionsDir: string;
+  private readonly trackerPath: string;
+  private readonly registry: AgentRegistry;
+  private readonly parser: PiSessionParser;
+  private readonly mapper: PiAgentMapper;
+
+  constructor(registry: AgentRegistry = AgentRegistry.default()) {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+    const piAgentDir = path.join(homeDir, ".pi", "agent");
+    this.piSessionsDir = path.join(piAgentDir, "sessions");
+    this.trackerPath = path.join(piAgentDir, "sessions.json");
+    this.registry = registry;
+    this.parser = new PiSessionParser();
+    this.mapper = new PiAgentMapper(this.parser);
+  }
+
+  canHandle(processInfo: ProcessInfo): boolean {
+    return this.isPiExecutable(processInfo.command);
+  }
+
+  async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    const processes = await this.getPiProcesses(context);
+    if (processes.length === 0) return [];
+
+    const cacheResult = this.mapRegistryCache(processes);
+    const trackerResult = this.mapTrackerMatches(cacheResult.fallback);
+    const locatorResult = this.createLocator().matchRunningProcesses(trackerResult.fallback);
+    const legacyResult = this.mapLegacyMatches(locatorResult.legacyMatches);
+    const unmatchedProcesses = this.findUnmatchedProcesses(
+      locatorResult.fallback,
+      legacyResult.agents,
+    );
+
+    return [
+      ...cacheResult.agents,
+      ...trackerResult.agents,
+      ...legacyResult.agents,
+      ...unmatchedProcesses.map((processInfo) => this.mapper.mapProcessOnlyAgent(processInfo)),
+    ];
+  }
+
+  getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+    return this.parser.getConversation(sessionFilePath, options);
+  }
+
+  async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+    const summaries: SessionSummary[] = [];
+
+    for (const filePath of this.createLocator().discoverHistoricalSessionFiles()) {
+      const summary = this.parser.fileToSessionSummary(filePath);
+      if (!summary) continue;
+      if (opts?.cwd !== undefined && summary.cwd !== opts.cwd) continue;
+      summaries.push(summary);
+    }
+
+    return summaries;
+  }
+
+  private async getPiProcesses(context?: AgentDetectionContext): Promise<ProcessInfo[]> {
+    const snapshot = context?.processes ?? (await captureProcessSnapshot(this.processNames));
+    const relevant = filterByProcessNames(snapshot, this.processNames);
+
+    const byPid = new Map<number, ProcessInfo>();
+    for (const processInfo of relevant) {
+      if (this.canHandle(processInfo)) byPid.set(processInfo.pid, processInfo);
+    }
+    return Array.from(byPid.values());
+  }
+
+  private createLocator(): PiSessionLocator {
+    return new PiSessionLocator({ sessionsDir: this.piSessionsDir }, this.parser);
+  }
+
+  private createTracker(): PiSessionTracker {
+    return new PiSessionTracker({
+      sessionsDir: this.piSessionsDir,
+      trackerPath: this.trackerPath,
+    });
+  }
+
+  private mapRegistryCache(processes: ProcessInfo[]): MappedAgentResult {
+    const matches: SessionFileMatch[] = [];
+    const fallback: ProcessInfo[] = [];
+    const byPid = new Map(this.registry.list().map((entry) => [entry.pid, entry]));
+
+    for (const processInfo of processes) {
+      const entry = byPid.get(processInfo.pid);
+      if (
+        !entry ||
+        entry.type !== this.type ||
+        !entry.sessionFilePath ||
+        !fs.existsSync(entry.sessionFilePath)
+      ) {
+        fallback.push(processInfo);
+        continue;
+      }
+
+      matches.push({ process: processInfo, filePath: entry.sessionFilePath });
+    }
+
+    const mapped = this.mapSessionFileMatches(matches);
+    return { agents: mapped.agents, fallback: [...fallback, ...mapped.fallback] };
+  }
+
+  private mapTrackerMatches(processes: ProcessInfo[]): MappedAgentResult {
+    const { matches, fallback } = this.createTracker().match(processes);
+    const mapped = this.mapSessionFileMatches(matches);
+    return { agents: mapped.agents, fallback: [...fallback, ...mapped.fallback] };
+  }
+
+  private mapLegacyMatches(
+    matches: Array<{ process: ProcessInfo; session: { filePath: string } }>,
+  ): MappedAgentResult {
+    return this.mapSessionFileMatches(
+      matches.map((match) => ({ process: match.process, filePath: match.session.filePath })),
+    );
+  }
+
+  private mapSessionFileMatches(matches: SessionFileMatch[]): MappedAgentResult {
+    const agents: AgentInfo[] = [];
+    const fallback: ProcessInfo[] = [];
+
+    for (const match of matches) {
+      const session = this.parser.readSession(match.filePath, match.process.cwd);
+      if (session) {
+        agents.push(this.mapper.mapSessionToAgent(session, match.process, match.filePath));
+      } else {
+        fallback.push(match.process);
+      }
+    }
+
+    return { agents, fallback };
+  }
+
+  private findUnmatchedProcesses(processes: ProcessInfo[], agents: AgentInfo[]): ProcessInfo[] {
+    const matchedPids = new Set(agents.map((agent) => agent.pid));
+    return processes.filter((processInfo) => !matchedPids.has(processInfo.pid));
+  }
+
+  private isPiExecutable(command: string): boolean {
+    for (const token of command.trim().split(/\s+/)) {
+      const base = executableBasename(token);
+      if (base === "pi" || base === "pi.exe" || base === "pi.js") return true;
+    }
+    return false;
+  }
+}

package/src/providers/pi/PiAgentMapper.ts

@@ -0,0 +1,36 @@
+import type { AgentInfo, ProcessInfo } from "../../adapters/AgentAdapter.js";
+import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import { generateAgentName } from "../../utils/matching.js";
+import { type PiSession, PiSessionParser } from "./PiSessionParser.js";
+
+export class PiAgentMapper {
+  constructor(private readonly parser: PiSessionParser = new PiSessionParser()) {}
+
+  mapSessionToAgent(session: PiSession, processInfo: ProcessInfo, filePath: string): AgentInfo {
+    const projectPath = session.projectPath || processInfo.cwd || "";
+    return {
+      name: generateAgentName(projectPath, processInfo.pid),
+      type: "pi",
+      status: this.parser.determineStatus(session),
+      summary: session.summary || "Pi session active",
+      pid: processInfo.pid,
+      projectPath,
+      sessionId: session.sessionId,
+      lastActive: session.lastActive,
+      sessionFilePath: filePath,
+    };
+  }
+
+  mapProcessOnlyAgent(processInfo: ProcessInfo): AgentInfo {
+    return {
+      name: generateAgentName(processInfo.cwd || "", processInfo.pid),
+      type: "pi",
+      status: AgentStatus.RUNNING,
+      summary: "Pi process running",
+      pid: processInfo.pid,
+      projectPath: processInfo.cwd || "",
+      sessionId: `pid-${processInfo.pid}`,
+      lastActive: new Date(),
+    };
+  }
+}