@ai-devkit/agent-manager 0.4.0 → 0.5.0

package/src/adapters/ClaudeCodeAdapter.ts

@@ -1,18 +1,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { execSync } from 'child_process';
 import type { AgentAdapter, AgentInfo, ProcessInfo } from './AgentAdapter';
 import { AgentStatus } from './AgentAdapter';
-import { listProcesses } from '../utils/process';
-import { readJson } from '../utils/file';
-
-/**
- * Structure of ~/.claude/projects/{path}/sessions-index.json
- */
-interface SessionsIndex {
-    originalPath: string;
-}
-
+import { listAgentProcesses, enrichProcesses } from '../utils/process';
+import { batchGetSessionFileBirthtimes } from '../utils/session';
+import type { SessionFile } from '../utils/session';
+import { matchProcessesToSessions, generateAgentName } from '../utils/matching';
 /**
  * Entry in session JSONL file
  */
@@ -30,6 +23,26 @@ interface SessionEntry {
     };
 }
 
+/**
+ * Entry in ~/.claude/sessions/<pid>.json written by Claude Code
+ */
+interface PidFileEntry {
+    pid: number;
+    sessionId: string;
+    cwd: string;
+    startedAt: number; // epoch milliseconds
+    kind: string;
+    entrypoint: string;
+}
+
+/**
+ * A process directly matched to a session via PID file (authoritative path)
+ */
+interface DirectMatch {
+    process: ProcessInfo;
+    sessionFile: SessionFile;
+}
+
 /**
  * Claude Code session information
  */
@@ -45,33 +58,26 @@ interface ClaudeSession {
     lastUserMessage?: string;
 }
 
-type SessionMatchMode = 'cwd' | 'missing-cwd' | 'parent-child';
-
 /**
  * Claude Code Adapter
  *
  * Detects Claude Code agents by:
- * 1. Finding running claude processes
- * 2. Getting process start times for accurate session matching
- * 3. Reading bounded session files from ~/.claude/projects/
- * 4. Matching sessions to processes via CWD then start time ranking
+ * 1. Finding running claude processes via shared listAgentProcesses()
+ * 2. Enriching with CWD and start times via shared enrichProcesses()
+ * 3. Attempting authoritative PID-file matching via ~/.claude/sessions/<pid>.json
+ * 4. Falling back to CWD+birthtime heuristic (matchProcessesToSessions) for processes without a PID file
  * 5. Extracting summary from last user message in session JSONL
  */
 export class ClaudeCodeAdapter implements AgentAdapter {
     readonly type = 'claude' as const;
 
-    /** Limit session parsing per run to keep list latency bounded. */
-    private static readonly MIN_SESSION_SCAN = 12;
-    private static readonly MAX_SESSION_SCAN = 40;
-    private static readonly SESSION_SCAN_MULTIPLIER = 4;
-    /** Matching tolerance between process start time and session start time. */
-    private static readonly PROCESS_SESSION_TIME_TOLERANCE_MS = 2 * 60 * 1000;
-
     private projectsDir: string;
+    private sessionsDir: string;
 
     constructor() {
         const homeDir = process.env.HOME || process.env.USERPROFILE || '';
         this.projectsDir = path.join(homeDir, '.claude', 'projects');
+        this.sessionsDir = path.join(homeDir, '.claude', 'sessions');
     }
 
     /**
@@ -91,398 +97,202 @@ export class ClaudeCodeAdapter implements AgentAdapter {
      * Detect running Claude Code agents
      */
     async detectAgents(): Promise<AgentInfo[]> {
-        const claudeProcesses = this.listClaudeProcesses();
-        if (claudeProcesses.length === 0) {
+        const processes = enrichProcesses(listAgentProcesses('claude'));
+        if (processes.length === 0) {
             return [];
         }
 
-        const processStartByPid = this.getProcessStartTimes(
-            claudeProcesses.map((p) => p.pid),
-        );
-        const sessionScanLimit = this.calculateSessionScanLimit(claudeProcesses.length);
-        const sessions = this.readSessions(sessionScanLimit);
+        // Step 1: try authoritative PID-file matching for every process
+        const { direct, fallback } = this.tryPidFileMatching(processes);
 
-        if (sessions.length === 0) {
-            return claudeProcesses.map((p) =>
-                this.mapProcessOnlyAgent(p, []),
-            );
-        }
+        // Step 2: run legacy CWD+birthtime matching only for processes without a PID file
+        const legacySessions = this.discoverSessions(fallback);
+        const legacyMatches =
+            fallback.length > 0 && legacySessions.length > 0
+                ? matchProcessesToSessions(fallback, legacySessions)
+                : [];
+
+        const matchedPids = new Set([
+            ...direct.map((d) => d.process.pid),
+            ...legacyMatches.map((m) => m.process.pid),
+        ]);
 
-        const sortedSessions = [...sessions].sort(
-            (a, b) => b.lastActive.getTime() - a.lastActive.getTime(),
-        );
-        const usedSessionIds = new Set<string>();
-        const assignedPids = new Set<number>();
         const agents: AgentInfo[] = [];
 
-        const modes: SessionMatchMode[] = ['cwd', 'missing-cwd', 'parent-child'];
-        for (const mode of modes) {
-            this.assignSessionsForMode(
-                mode,
-                claudeProcesses,
-                sortedSessions,
-                usedSessionIds,
-                assignedPids,
-                processStartByPid,
-                agents,
-            );
+        // Build agents from direct (PID-file) matches
+        for (const { process: proc, sessionFile } of direct) {
+            const sessionData = this.readSession(sessionFile.filePath, sessionFile.resolvedCwd);
+            if (sessionData) {
+                agents.push(this.mapSessionToAgent(sessionData, proc, sessionFile));
+            } else {
+                matchedPids.delete(proc.pid);
+            }
         }
 
-        for (const processInfo of claudeProcesses) {
-            if (assignedPids.has(processInfo.pid)) {
-                continue;
+        // Build agents from legacy matches
+        for (const match of legacyMatches) {
+            const sessionData = this.readSession(
+                match.session.filePath,
+                match.session.resolvedCwd,
+            );
+            if (sessionData) {
+                agents.push(this.mapSessionToAgent(sessionData, match.process, match.session));
+            } else {
+                matchedPids.delete(match.process.pid);
             }
+        }
 
-            assignedPids.add(processInfo.pid);
-            agents.push(this.mapProcessOnlyAgent(processInfo, agents));
+        // Any process with no match (direct or legacy) appears as IDLE
+        for (const proc of processes) {
+            if (!matchedPids.has(proc.pid)) {
+                agents.push(this.mapProcessOnlyAgent(proc));
+            }
         }
 
         return agents;
     }
 
-    private listClaudeProcesses(): ProcessInfo[] {
-        return listProcesses({ namePattern: 'claude' }).filter((p) =>
-            this.canHandle(p),
-        );
-    }
+    /**
+     * Discover session files for the given processes.
+     *
+     * For each unique process CWD, encodes it to derive the expected
+     * ~/.claude/projects/<encoded>/ directory, then gets session file birthtimes
+     * via a single batched stat call across all directories.
+     */
+    private discoverSessions(processes: ProcessInfo[]): SessionFile[] {
+        // Collect valid project dirs and map them back to their CWD
+        const dirToCwd = new Map<string, string>();
 
-    private calculateSessionScanLimit(processCount: number): number {
-        return Math.min(
-            Math.max(
-                processCount * ClaudeCodeAdapter.SESSION_SCAN_MULTIPLIER,
-                ClaudeCodeAdapter.MIN_SESSION_SCAN,
-            ),
-            ClaudeCodeAdapter.MAX_SESSION_SCAN,
-        );
-    }
+        for (const proc of processes) {
+            if (!proc.cwd) continue;
 
-    private assignSessionsForMode(
-        mode: SessionMatchMode,
-        claudeProcesses: ProcessInfo[],
-        sessions: ClaudeSession[],
-        usedSessionIds: Set<string>,
-        assignedPids: Set<number>,
-        processStartByPid: Map<number, Date>,
-        agents: AgentInfo[],
-    ): void {
-        for (const processInfo of claudeProcesses) {
-            if (assignedPids.has(processInfo.pid)) {
-                continue;
-            }
+            const projectDir = this.getProjectDir(proc.cwd);
+            if (dirToCwd.has(projectDir)) continue;
 
-            const session = this.selectBestSession(
-                processInfo,
-                sessions,
-                usedSessionIds,
-                processStartByPid,
-                mode,
-            );
-            if (!session) {
+            try {
+                if (!fs.statSync(projectDir).isDirectory()) continue;
+            } catch {
                 continue;
             }
 
-            usedSessionIds.add(session.sessionId);
-            assignedPids.add(processInfo.pid);
-            agents.push(this.mapSessionToAgent(session, processInfo, agents));
+            dirToCwd.set(projectDir, proc.cwd);
+        }
+
+        if (dirToCwd.size === 0) return [];
+
+        // Single batched stat call across all directories
+        const files = batchGetSessionFileBirthtimes([...dirToCwd.keys()]);
+
+        // Set resolvedCwd based on which project dir the file belongs to
+        for (const file of files) {
+            file.resolvedCwd = dirToCwd.get(file.projectDir) || '';
+        }
+
+        return files;
+    }
+
+    /**
+     * Attempt to match each process to its session via ~/.claude/sessions/<pid>.json.
+     *
+     * Returns:
+     *   direct  — processes matched authoritatively via PID file
+     *   fallback — processes with no valid PID file (sent to legacy matching)
+     *
+     * Per-process fallback triggers on: file absent, malformed JSON,
+     * stale startedAt (>60 s from proc.startTime), or missing JSONL.
+     */
+    private tryPidFileMatching(processes: ProcessInfo[]): {
+        direct: DirectMatch[];
+        fallback: ProcessInfo[];
+    } {
+        const direct: DirectMatch[] = [];
+        const fallback: ProcessInfo[] = [];
+
+        for (const proc of processes) {
+            const pidFilePath = path.join(this.sessionsDir, `${proc.pid}.json`);
+            try {
+                const entry = JSON.parse(
+                    fs.readFileSync(pidFilePath, 'utf-8'),
+                ) as PidFileEntry;
+
+                // Stale-file guard: reject PID files from a previous process with the same PID
+                if (proc.startTime) {
+                    const deltaMs = Math.abs(proc.startTime.getTime() - entry.startedAt);
+                    if (deltaMs > 60000) {
+                        fallback.push(proc);
+                        continue;
+                    }
+                }
+
+                const projectDir = this.getProjectDir(entry.cwd);
+                const jsonlPath = path.join(projectDir, `${entry.sessionId}.jsonl`);
+
+                if (!fs.existsSync(jsonlPath)) {
+                    fallback.push(proc);
+                    continue;
+                }
+
+                direct.push({
+                    process: proc,
+                    sessionFile: {
+                        sessionId: entry.sessionId,
+                        filePath: jsonlPath,
+                        projectDir,
+                        birthtimeMs: entry.startedAt,
+                        resolvedCwd: entry.cwd,
+                    },
+                });
+            } catch {
+                // PID file absent, unreadable, or malformed — fall back per-process
+                fallback.push(proc);
+            }
         }
+
+        return { direct, fallback };
+    }
+
+    /**
+     * Derive the Claude Code project directory for a given CWD.
+     *
+     * Claude Code encodes paths by replacing '/' with '-':
+     * /Users/foo/bar → ~/.claude/projects/-Users-foo-bar/
+     */
+    private getProjectDir(cwd: string): string {
+        const encoded = cwd.replace(/\//g, '-');
+        return path.join(this.projectsDir, encoded);
     }
 
     private mapSessionToAgent(
         session: ClaudeSession,
         processInfo: ProcessInfo,
-        existingAgents: AgentInfo[],
+        sessionFile: SessionFile,
     ): AgentInfo {
         return {
-            name: this.generateAgentName(session, existingAgents),
+            name: generateAgentName(processInfo.cwd, processInfo.pid),
             type: this.type,
             status: this.determineStatus(session),
             summary: session.lastUserMessage || 'Session started',
             pid: processInfo.pid,
-            projectPath: session.projectPath || processInfo.cwd || '',
-            sessionId: session.sessionId,
+            projectPath: sessionFile.resolvedCwd || processInfo.cwd || '',
+            sessionId: sessionFile.sessionId,
             slug: session.slug,
             lastActive: session.lastActive,
         };
     }
 
-    private mapProcessOnlyAgent(
-        processInfo: ProcessInfo,
-        existingAgents: AgentInfo[],
-    ): AgentInfo {
-        const processCwd = processInfo.cwd || '';
-        const projectName = path.basename(processCwd) || 'claude';
-        const hasDuplicate = existingAgents.some((a) => a.projectPath === processCwd);
-
+    private mapProcessOnlyAgent(processInfo: ProcessInfo): AgentInfo {
         return {
-            name: hasDuplicate ? `${projectName} (pid-${processInfo.pid})` : projectName,
+            name: generateAgentName(processInfo.cwd || '', processInfo.pid),
             type: this.type,
             status: AgentStatus.IDLE,
             summary: 'Unknown',
             pid: processInfo.pid,
-            projectPath: processCwd,
+            projectPath: processInfo.cwd || '',
             sessionId: `pid-${processInfo.pid}`,
             lastActive: new Date(),
         };
     }
 
-    private selectBestSession(
-        processInfo: ProcessInfo,
-        sessions: ClaudeSession[],
-        usedSessionIds: Set<string>,
-        processStartByPid: Map<number, Date>,
-        mode: SessionMatchMode,
-    ): ClaudeSession | undefined {
-        const candidates = this.filterCandidateSessions(
-            processInfo,
-            sessions,
-            usedSessionIds,
-            mode,
-        );
-
-        if (candidates.length === 0) {
-            return undefined;
-        }
-
-        const processStart = processStartByPid.get(processInfo.pid);
-        if (!processStart) {
-            return candidates.sort(
-                (a, b) => b.lastActive.getTime() - a.lastActive.getTime(),
-            )[0];
-        }
-
-        const best = this.rankCandidatesByStartTime(candidates, processStart)[0];
-        if (!best) {
-            return undefined;
-        }
-
-        // In early modes (cwd/missing-cwd), defer assignment when the best
-        // candidate is outside start-time tolerance — a closer match may
-        // exist in parent-child mode (e.g., worktree sessions).
-        if (mode !== 'parent-child') {
-            const diffMs = Math.abs(
-                best.sessionStart.getTime() - processStart.getTime(),
-            );
-            if (diffMs > ClaudeCodeAdapter.PROCESS_SESSION_TIME_TOLERANCE_MS) {
-                return undefined;
-            }
-        }
-
-        return best;
-    }
-
-    private filterCandidateSessions(
-        processInfo: ProcessInfo,
-        sessions: ClaudeSession[],
-        usedSessionIds: Set<string>,
-        mode: SessionMatchMode,
-    ): ClaudeSession[] {
-        return sessions.filter((session) => {
-            if (usedSessionIds.has(session.sessionId)) {
-                return false;
-            }
-
-            if (mode === 'cwd') {
-                return (
-                    this.pathEquals(processInfo.cwd, session.projectPath) ||
-                    this.pathEquals(processInfo.cwd, session.lastCwd)
-                );
-            }
-
-            if (mode === 'missing-cwd') {
-                return !session.projectPath;
-            }
-
-            // parent-child mode: match if process CWD equals, is under, or is
-            // a parent of session project/lastCwd.  This also catches exact CWD
-            // matches that were deferred from `cwd` mode due to start-time tolerance.
-            return (
-                this.pathRelated(processInfo.cwd, session.projectPath) ||
-                this.pathRelated(processInfo.cwd, session.lastCwd)
-            );
-        });
-    }
-
-    private rankCandidatesByStartTime(
-        candidates: ClaudeSession[],
-        processStart: Date,
-    ): ClaudeSession[] {
-        const toleranceMs = ClaudeCodeAdapter.PROCESS_SESSION_TIME_TOLERANCE_MS;
-
-        return candidates
-            .map((session) => {
-                const diffMs = Math.abs(
-                    session.sessionStart.getTime() - processStart.getTime(),
-                );
-                const outsideTolerance = diffMs > toleranceMs ? 1 : 0;
-                return {
-                    session,
-                    rank: outsideTolerance,
-                    diffMs,
-                    recency: session.lastActive.getTime(),
-                };
-            })
-            .sort((a, b) => {
-                if (a.rank !== b.rank) return a.rank - b.rank;
-                // Within tolerance (rank 0): prefer most recently active session.
-                // The exact diff is noise — a 6s vs 45s difference is meaningless,
-                // but the session with recent activity is more likely the real one.
-                if (a.rank === 0) return b.recency - a.recency;
-                // Outside tolerance: prefer smallest time difference, then recency.
-                if (a.diffMs !== b.diffMs) return a.diffMs - b.diffMs;
-                return b.recency - a.recency;
-            })
-            .map((ranked) => ranked.session);
-    }
-
-    private getProcessStartTimes(pids: number[]): Map<number, Date> {
-        if (pids.length === 0 || process.env.JEST_WORKER_ID) {
-            return new Map();
-        }
-
-        try {
-            const output = execSync(
-                `ps -o pid=,etime= -p ${pids.join(',')}`,
-                { encoding: 'utf-8' },
-            );
-            const nowMs = Date.now();
-            const startTimes = new Map<number, Date>();
-
-            for (const rawLine of output.split('\n')) {
-                const line = rawLine.trim();
-                if (!line) continue;
-
-                const parts = line.split(/\s+/);
-                if (parts.length < 2) continue;
-
-                const pid = Number.parseInt(parts[0], 10);
-                const elapsedSeconds = this.parseElapsedSeconds(parts[1]);
-                if (!Number.isFinite(pid) || elapsedSeconds === null) continue;
-
-                startTimes.set(pid, new Date(nowMs - elapsedSeconds * 1000));
-            }
-
-            return startTimes;
-        } catch {
-            return new Map();
-        }
-    }
-
-    private parseElapsedSeconds(etime: string): number | null {
-        const match = etime
-            .trim()
-            .match(/^(?:(\d+)-)?(?:(\d{1,2}):)?(\d{1,2}):(\d{2})$/);
-        if (!match) {
-            return null;
-        }
-
-        const days = Number.parseInt(match[1] || '0', 10);
-        const hours = Number.parseInt(match[2] || '0', 10);
-        const minutes = Number.parseInt(match[3] || '0', 10);
-        const seconds = Number.parseInt(match[4] || '0', 10);
-
-        return ((days * 24 + hours) * 60 + minutes) * 60 + seconds;
-    }
-
-    /**
-     * Read Claude Code sessions with bounded scanning
-     */
-    private readSessions(limit: number): ClaudeSession[] {
-        const sessionFiles = this.findSessionFiles(limit);
-        const sessions: ClaudeSession[] = [];
-
-        for (const file of sessionFiles) {
-            try {
-                const session = this.readSession(file.filePath, file.projectPath);
-                if (session) {
-                    sessions.push(session);
-                }
-            } catch (error) {
-                console.error(`Failed to parse Claude session ${file.filePath}:`, error);
-            }
-        }
-
-        return sessions;
-    }
-
-    /**
-     * Find session files bounded by mtime, sorted most-recent first
-     */
-    private findSessionFiles(
-        limit: number,
-    ): Array<{ filePath: string; projectPath: string; mtimeMs: number }> {
-        if (!fs.existsSync(this.projectsDir)) {
-            return [];
-        }
-
-        const files: Array<{
-            filePath: string;
-            projectPath: string;
-            mtimeMs: number;
-        }> = [];
-
-        for (const dirName of fs.readdirSync(this.projectsDir)) {
-            if (dirName.startsWith('.')) {
-                continue;
-            }
-
-            const projectDir = path.join(this.projectsDir, dirName);
-            try {
-                if (!fs.statSync(projectDir).isDirectory()) continue;
-            } catch {
-                continue;
-            }
-
-            const indexPath = path.join(projectDir, 'sessions-index.json');
-            const index = readJson<SessionsIndex>(indexPath);
-            const projectPath = index?.originalPath || '';
-
-            for (const entry of fs.readdirSync(projectDir)) {
-                if (!entry.endsWith('.jsonl')) {
-                    continue;
-                }
-
-                const filePath = path.join(projectDir, entry);
-                try {
-                    files.push({
-                        filePath,
-                        projectPath,
-                        mtimeMs: fs.statSync(filePath).mtimeMs,
-                    });
-                } catch {
-                    continue;
-                }
-            }
-        }
-
-        // Ensure breadth: include at least the most recent session per project,
-        // then fill remaining slots with globally most-recent sessions.
-        const sorted = files.sort((a, b) => b.mtimeMs - a.mtimeMs);
-        const result: typeof files = [];
-        const seenProjects = new Set<string>();
-
-        // First pass: one most-recent session per project directory
-        for (const file of sorted) {
-            const projDir = path.dirname(file.filePath);
-            if (!seenProjects.has(projDir)) {
-                seenProjects.add(projDir);
-                result.push(file);
-            }
-        }
-
-        // Second pass: fill remaining slots with globally most-recent
-        if (result.length < limit) {
-            const resultSet = new Set(result.map((f) => f.filePath));
-            for (const file of sorted) {
-                if (result.length >= limit) break;
-                if (!resultSet.has(file.filePath)) {
-                    result.push(file);
-                }
-            }
-        }
-
-        return result.sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, limit);
-    }
-
     /**
      * Parse a single session file into ClaudeSession
      */
@@ -627,57 +437,6 @@ export class ClaudeCodeAdapter implements AgentAdapter {
         return AgentStatus.UNKNOWN;
     }
 
-    /**
-     * Generate unique agent name
-     * Uses project basename, appends slug if multiple sessions for same project
-     */
-    private generateAgentName(
-        session: ClaudeSession,
-        existingAgents: AgentInfo[],
-    ): string {
-        const projectName = path.basename(session.projectPath) || 'claude';
-
-        const sameProjectAgents = existingAgents.filter(
-            (a) => a.projectPath === session.projectPath,
-        );
-
-        if (sameProjectAgents.length === 0) {
-            return projectName;
-        }
-
-        if (session.slug) {
-            const slugPart = session.slug.includes('-')
-                ? session.slug.split('-')[0]
-                : session.slug.slice(0, 8);
-            return `${projectName} (${slugPart})`;
-        }
-
-        return `${projectName} (${session.sessionId.slice(0, 8)})`;
-    }
-
-    /** Check if two paths are equal, or one is a parent/child of the other. */
-    private pathRelated(a?: string, b?: string): boolean {
-        return this.pathEquals(a, b) || this.isChildPath(a, b) || this.isChildPath(b, a);
-    }
-
-    private pathEquals(a?: string, b?: string): boolean {
-        if (!a || !b) {
-            return false;
-        }
-
-        return this.normalizePath(a) === this.normalizePath(b);
-    }
-
-    private isChildPath(child?: string, parent?: string): boolean {
-        if (!child || !parent) {
-            return false;
-        }
-
-        const normalizedChild = this.normalizePath(child);
-        const normalizedParent = this.normalizePath(parent);
-        return normalizedChild.startsWith(`${normalizedParent}${path.sep}`);
-    }
-
     /**
      * Extract meaningful text from a user message content.
      * Handles string and array formats, skill command expansion, and noise filtering.
@@ -758,11 +517,4 @@ export class ClaudeCodeAdapter implements AgentAdapter {
         return type === 'last-prompt' || type === 'file-history-snapshot';
     }
 
-    private normalizePath(value: string): string {
-        const resolved = path.resolve(value);
-        if (resolved.length > 1 && resolved.endsWith(path.sep)) {
-            return resolved.slice(0, -1);
-        }
-        return resolved;
-    }
 }