@ai-devkit/agent-manager 0.3.0 → 0.5.0

package/src/index.ts

@@ -9,6 +9,4 @@ export { TerminalFocusManager, TerminalType } from './terminal/TerminalFocusMana
 export type { TerminalLocation } from './terminal/TerminalFocusManager';
 export { TtyWriter } from './terminal/TtyWriter';
 
-export { listProcesses, getProcessCwd, getProcessTty, isProcessRunning, getProcessInfo } from './utils/process';
-export type { ListProcessesOptions } from './utils/process';
-export { readLastLines, readJsonLines, fileExists, readJson } from './utils/file';
+export { getProcessTty } from './utils/process';

package/src/utils/index.ts

@@ -1,3 +1,6 @@
-export { listProcesses, getProcessCwd, getProcessTty, isProcessRunning, getProcessInfo } from './process';
-export type { ListProcessesOptions } from './process';
-export { readLastLines, readJsonLines, fileExists, readJson } from './file';
+export { listAgentProcesses, batchGetProcessCwds, batchGetProcessStartTimes, enrichProcesses } from './process';
+export { getProcessTty } from './process';
+export { batchGetSessionFileBirthtimes } from './session';
+export type { SessionFile } from './session';
+export { matchProcessesToSessions, generateAgentName } from './matching';
+export type { MatchResult } from './matching';

package/src/utils/matching.ts

@@ -0,0 +1,92 @@
+/**
+ * Session Matching Utilities
+ *
+ * Shared 1:1 greedy matching algorithm that pairs running processes with session files
+ * based on CWD and birth-time proximity to process start time.
+ */
+
+import * as path from 'path';
+import type { ProcessInfo } from '../adapters/AgentAdapter';
+import type { SessionFile } from './session';
+
+/** Maximum allowed delta between process start time and session file birth time. */
+const TOLERANCE_MS = 3 * 60 * 1000; // 3 minutes
+
+/**
+ * Result of matching a process to a session file.
+ */
+export interface MatchResult {
+    /** The matched process */
+    process: ProcessInfo;
+
+    /** The matched session file */
+    session: SessionFile;
+
+    /** Absolute time delta in ms between process start and session birth time */
+    deltaMs: number;
+}
+
+/**
+ * Match processes to session files using 1:1 greedy assignment.
+ *
+ * Algorithm:
+ * 1. Exclude processes without startTime (they become process-only fallback).
+ * 2. Build candidate pairs where process.cwd === session.resolvedCwd
+ *    and |process.startTime - session.birthtimeMs| <= 3 minutes.
+ * 3. Sort candidates by deltaMs ascending (best matches first).
+ * 4. Greedily assign: once a process or session is matched, skip it.
+ *
+ * Adapters must set session.resolvedCwd before calling this function.
+ */
+export function matchProcessesToSessions(
+    processes: ProcessInfo[],
+    sessions: SessionFile[],
+): MatchResult[] {
+    // Build all candidate pairs
+    const candidates: Array<{ process: ProcessInfo; session: SessionFile; deltaMs: number }> = [];
+
+    for (const proc of processes) {
+        if (!proc.startTime || !proc.cwd) continue;
+
+        const processStartMs = proc.startTime.getTime();
+
+        for (const session of sessions) {
+            if (!session.resolvedCwd) continue;
+            if (proc.cwd !== session.resolvedCwd) continue;
+
+            const deltaMs = Math.abs(processStartMs - session.birthtimeMs);
+            if (deltaMs > TOLERANCE_MS) continue;
+
+            candidates.push({ process: proc, session, deltaMs });
+        }
+    }
+
+    // Sort by smallest delta first
+    candidates.sort((a, b) => a.deltaMs - b.deltaMs);
+
+    // Greedy 1:1 assignment
+    const matchedPids = new Set<number>();
+    const matchedSessionIds = new Set<string>();
+    const results: MatchResult[] = [];
+
+    for (const candidate of candidates) {
+        if (matchedPids.has(candidate.process.pid)) continue;
+        if (matchedSessionIds.has(candidate.session.sessionId)) continue;
+
+        matchedPids.add(candidate.process.pid);
+        matchedSessionIds.add(candidate.session.sessionId);
+        results.push(candidate);
+    }
+
+    return results;
+}
+
+/**
+ * Generate a deterministic agent name from CWD and PID.
+ *
+ * Format: "folderName (pid)"
+ */
+export function generateAgentName(cwd: string, pid: number): string {
+    const folderName = path.basename(cwd) || 'unknown';
+    return `${folderName} (${pid})`;
+}

package/src/utils/process.ts

@@ -1,145 +1,187 @@
 /**
  * Process Detection Utilities
- * 
- * Utilities for detecting and inspecting running processes on the system.
- * Primarily focused on macOS/Unix-like systems using the `ps` command.
+ *
+ * Shared shell command wrappers for detecting and inspecting running processes.
+ * All execSync calls for process data live here — adapters must not call execSync directly.
  */
 
+import * as path from 'path';
 import { execSync } from 'child_process';
 import type { ProcessInfo } from '../adapters/AgentAdapter';
 
 /**
- * Options for listing processes
+ * List running processes matching an agent executable name.
+ *
+ * Uses `ps aux | grep <pattern>` at shell level for performance, then post-filters
+ * by checking that the executable basename matches exactly (avoids matching
+ * `claude-helper`, `vscode-claude-extension`, or the grep process itself).
+ *
+ * Returned ProcessInfo has pid, command, tty populated.
+ * cwd and startTime are NOT populated — call enrichProcesses() to fill them.
  */
-export interface ListProcessesOptions {
-    /** Filter processes by name pattern (case-insensitive) */
-    namePattern?: string;
-
-    /** Include only processes matching these PIDs */
-    pids?: number[];
-}
+export function listAgentProcesses(namePattern: string): ProcessInfo[] {
+    // Validate pattern contains only safe characters (alphanumeric, dash, underscore)
+    if (!namePattern || !/^[a-zA-Z0-9_-]+$/.test(namePattern)) {
+        return [];
+    }
 
-/**
- * List running processes on the system
- * 
- * @param options Filtering options
- * @returns Array of process information
- * 
- * @example
- * ```typescript
- * // List all Claude Code processes
- * const processes = listProcesses({ namePattern: 'claude' });
- * 
- * // Get specific process info
- * const process = listProcesses({ pids: [12345] });
- * ```
- */
-export function listProcesses(options: ListProcessesOptions = {}): ProcessInfo[] {
     try {
-        // Get all processes with full details
-        // Format: user pid command
-        const psOutput = execSync('ps aux', { encoding: 'utf-8' });
+        // Use [c]laude trick to avoid matching the grep process itself
+        const escapedPattern = `[${namePattern[0]}]${namePattern.slice(1)}`;
 
-        const lines = psOutput.trim().split('\n');
-        // Skip header line
-        const processLines = lines.slice(1);
+        const output = execSync(
+            `ps aux | grep -i '${escapedPattern}'`,
+            { encoding: 'utf-8' },
+        );
 
         const processes: ProcessInfo[] = [];
 
-        for (const line of processLines) {
-            // Parse ps aux output
-            // Format: USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
-            const parts = line.trim().split(/\s+/);
+        for (const line of output.trim().split('\n')) {
+            if (!line.trim()) continue;
 
+            const parts = line.trim().split(/\s+/);
             if (parts.length < 11) continue;
 
             const pid = parseInt(parts[1], 10);
-            if (isNaN(pid)) continue;
+            if (Number.isNaN(pid)) continue;
 
             const tty = parts[6];
             const command = parts.slice(10).join(' ');
 
-            // Apply PID filter
-            if (options.pids && !options.pids.includes(pid)) {
+            // Post-filter: check that the executable basename matches exactly
+            const executable = command.trim().split(/\s+/)[0] || '';
+            const base = path.basename(executable).toLowerCase();
+            if (base !== namePattern.toLowerCase() && base !== `${namePattern.toLowerCase()}.exe`) {
                 continue;
             }
 
-            // Apply name pattern filter (case-insensitive)
-            if (options.namePattern) {
-                const pattern = options.namePattern.toLowerCase();
-                const commandLower = command.toLowerCase();
-                if (!commandLower.includes(pattern)) {
-                    continue;
-                }
-            }
-
-            // Get working directory for this process
-            const cwd = getProcessCwd(pid);
-
-            // Get TTY in short format (remove /dev/ prefix if present)
             const ttyShort = tty.startsWith('/dev/') ? tty.slice(5) : tty;
 
             processes.push({
                 pid,
                 command,
-                cwd,
+                cwd: '',
                 tty: ttyShort,
             });
         }
 
         return processes;
-    } catch (error) {
-        // If ps command fails, return empty array
-        console.error('Failed to list processes:', error);
+    } catch {
         return [];
     }
 }
 
 /**
- * Get the current working directory for a specific process
- * 
- * @param pid Process ID
- * @returns Working directory path, or empty string if unavailable
+ * Batch-get current working directories for multiple PIDs.
+ *
+ * Single `lsof -a -d cwd -Fn -p PID1,PID2,...` call.
+ * Returns partial results — if lsof fails for one PID, others still return.
  */
-export function getProcessCwd(pid: number): string {
-    try {
-        // Use lsof to get the current working directory
-        // -a: AND the selections, -d cwd: get cwd only, -Fn: output format (file names only)
-        const output = execSync(`lsof -a -p ${pid} -d cwd -Fn 2>/dev/null`, {
-            encoding: 'utf-8',
-        });
+export function batchGetProcessCwds(pids: number[]): Map<number, string> {
+    const result = new Map<number, string>();
+    if (pids.length === 0) return result;
 
-        // Parse lsof output
-        // Format: p{PID}\nn{path}
-        const lines = output.trim().split('\n');
-        for (const line of lines) {
-            if (line.startsWith('n')) {
-                return line.slice(1); // Remove 'n' prefix
+    try {
+        const output = execSync(
+            `lsof -a -d cwd -Fn -p ${pids.join(',')} 2>/dev/null`,
+            { encoding: 'utf-8' },
+        );
+
+        // lsof output format: p{PID}\nn{path}\np{PID}\nn{path}...
+        let currentPid: number | null = null;
+        for (const line of output.trim().split('\n')) {
+            if (line.startsWith('p')) {
+                currentPid = parseInt(line.slice(1), 10);
+            } else if (line.startsWith('n') && currentPid !== null) {
+                result.set(currentPid, line.slice(1));
+                currentPid = null;
+            }
+        }
+    } catch {
+        // Try per-PID fallback with pwdx (Linux)
+        for (const pid of pids) {
+            try {
+                const output = execSync(`pwdx ${pid} 2>/dev/null`, { encoding: 'utf-8' });
+                const match = output.match(/^\d+:\s*(.+)$/);
+                if (match) {
+                    result.set(pid, match[1].trim());
+                }
+            } catch {
+                // Skip this PID
             }
         }
+    }
 
-        return '';
-    } catch (error) {
-        // If lsof fails, try alternative method using pwdx (Linux)
-        try {
-            const output = execSync(`pwdx ${pid} 2>/dev/null`, {
-                encoding: 'utf-8',
-            });
-            // Format: {PID}: {path}
-            const match = output.match(/^\d+:\s*(.+)$/);
-            return match ? match[1].trim() : '';
-        } catch {
-            // Both methods failed
-            return '';
+    return result;
+}
+
+/**
+ * Batch-get process start times for multiple PIDs.
+ *
+ * Single `ps -o pid=,lstart= -p PID1,PID2,...` call.
+ * Uses lstart format which gives full timestamp (e.g., "Thu Feb  5 16:00:57 2026").
+ * Returns partial results.
+ */
+export function batchGetProcessStartTimes(pids: number[]): Map<number, Date> {
+    const result = new Map<number, Date>();
+    if (pids.length === 0) return result;
+
+    try {
+        const output = execSync(
+            `ps -o pid=,lstart= -p ${pids.join(',')}`,
+            { encoding: 'utf-8' },
+        );
+
+        for (const rawLine of output.split('\n')) {
+            const line = rawLine.trim();
+            if (!line) continue;
+
+            // Format: "  PID  DAY MON DD HH:MM:SS YYYY"
+            // e.g., " 78070 Wed Mar 18 23:18:01 2026"
+            const match = line.match(/^\s*(\d+)\s+(.+)$/);
+            if (!match) continue;
+
+            const pid = parseInt(match[1], 10);
+            const dateStr = match[2].trim();
+
+            if (!Number.isFinite(pid)) continue;
+
+            const date = new Date(dateStr);
+            if (!Number.isNaN(date.getTime())) {
+                result.set(pid, date);
+            }
         }
+    } catch {
+        // Return whatever we have
+    }
+
+    return result;
+}
+
+/**
+ * Enrich ProcessInfo array with cwd and startTime.
+ *
+ * Calls batchGetProcessCwds and batchGetProcessStartTimes in batched shell calls,
+ * then populates each ProcessInfo in-place. Returns partial results —
+ * if a PID fails, that process keeps empty cwd / undefined startTime.
+ */
+export function enrichProcesses(processes: ProcessInfo[]): ProcessInfo[] {
+    if (processes.length === 0) return processes;
+
+    const pids = processes.map(p => p.pid);
+    const cwdMap = batchGetProcessCwds(pids);
+    const startTimeMap = batchGetProcessStartTimes(pids);
+
+    for (const proc of processes) {
+        proc.cwd = cwdMap.get(proc.pid) || '';
+        proc.startTime = startTimeMap.get(proc.pid);
     }
+
+    return processes;
 }
 
 /**
  * Get the TTY device for a specific process
- * 
- * @param pid Process ID
- * @returns TTY device name (e.g., "ttys030"), or "?" if unavailable
  */
 export function getProcessTty(pid: number): string {
     try {
@@ -148,37 +190,9 @@ export function getProcessTty(pid: number): string {
         });
 
         const tty = output.trim();
-        // Remove /dev/ prefix if present
         return tty.startsWith('/dev/') ? tty.slice(5) : tty;
-    } catch (error) {
-        return '?';
-    }
-}
-
-/**
- * Check if a process with the given PID is running
- * 
- * @param pid Process ID
- * @returns True if process is running
- */
-export function isProcessRunning(pid: number): boolean {
-    try {
-        // Send signal 0 to check if process exists
-        // This doesn't actually send a signal, just checks if we can
-        execSync(`kill -0 ${pid} 2>/dev/null`);
-        return true;
     } catch {
-        return false;
+        return '?';
     }
 }
 
-/**
- * Get detailed information for a specific process
- * 
- * @param pid Process ID
- * @returns Process information, or null if process not found
- */
-export function getProcessInfo(pid: number): ProcessInfo | null {
-    const processes = listProcesses({ pids: [pid] });
-    return processes.length > 0 ? processes[0] : null;
-}

package/src/utils/session.ts

@@ -0,0 +1,92 @@
+/**
+ * Session File Utilities
+ *
+ * Shell command wrappers for discovering session files and their birth times.
+ * Uses `stat` to get exact epoch-second birth timestamps without reading file contents.
+ */
+
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Represents a session file with its birth time metadata.
+ */
+export interface SessionFile {
+    /** Session identifier (filename without .jsonl extension) */
+    sessionId: string;
+
+    /** Full path to the session file */
+    filePath: string;
+
+    /** Parent directory of the session file */
+    projectDir: string;
+
+    /** File creation time in milliseconds since epoch */
+    birthtimeMs: number;
+
+    /** CWD this session maps to — set by the adapter after calling batchGetSessionFileBirthtimes() */
+    resolvedCwd: string;
+}
+
+/**
+ * Get birth times for .jsonl session files across multiple directories in a single shell call.
+ *
+ * Combines all directory globs into one `stat` command to avoid per-directory exec overhead.
+ * Returns empty array if no directories have .jsonl files or command fails.
+ * resolvedCwd is left empty — the adapter must set it.
+ */
+export function batchGetSessionFileBirthtimes(dirs: string[]): SessionFile[] {
+    if (dirs.length === 0) return [];
+
+    try {
+        const isMacOS = process.platform === 'darwin';
+        const globs = dirs.map((d) => `"${d}"/*.jsonl`).join(' ');
+        // || true prevents non-zero exit when some globs have no .jsonl matches
+        const command = isMacOS
+            ? `stat -f '%B %N' ${globs} 2>/dev/null || true`
+            : `stat --format='%W %n' ${globs} 2>/dev/null || true`;
+
+        const output = execSync(command, { encoding: 'utf-8' });
+
+        return parseStatOutput(output);
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Parse stat output lines into SessionFile entries.
+ */
+function parseStatOutput(output: string): SessionFile[] {
+    const results: SessionFile[] = [];
+
+    for (const rawLine of output.trim().split('\n')) {
+        const line = rawLine.trim();
+        if (!line) continue;
+
+        // Format: "<epoch_seconds> <filepath>"
+        const spaceIdx = line.indexOf(' ');
+        if (spaceIdx === -1) continue;
+
+        const epochStr = line.slice(0, spaceIdx);
+        const filePath = line.slice(spaceIdx + 1).trim();
+
+        const epochSeconds = parseInt(epochStr, 10);
+        if (!Number.isFinite(epochSeconds) || epochSeconds <= 0) continue;
+
+        const fileName = path.basename(filePath);
+        if (!fileName.endsWith('.jsonl')) continue;
+
+        const sessionId = fileName.replace(/\.jsonl$/, '');
+
+        results.push({
+            sessionId,
+            filePath,
+            projectDir: path.dirname(filePath),
+            birthtimeMs: epochSeconds * 1000,
+            resolvedCwd: '',
+        });
+    }
+
+    return results;
+}

package/dist/utils/file.d.ts

@@ -1,52 +0,0 @@
-/**
- * File Utilities
- *
- * Helper functions for reading files efficiently
- */
-/**
- * Read last N lines from a file efficiently
- *
- * @param filePath Path to the file
- * @param lineCount Number of lines to read from the end (default: 100)
- * @returns Array of lines
- *
- * @example
- * ```typescript
- * const lastLines = readLastLines('/path/to/log.txt', 50);
- * ```
- */
-export declare function readLastLines(filePath: string, lineCount?: number): string[];
-/**
- * Read a JSONL (JSON Lines) file and parse each line
- *
- * @param filePath Path to the JSONL file
- * @param maxLines Maximum number of lines to read from end (default: 1000)
- * @returns Array of parsed objects
- *
- * @example
- * ```typescript
- * const entries = readJsonLines<MyType>('/path/to/data.jsonl');
- * const recent = readJsonLines<MyType>('/path/to/data.jsonl', 100);
- * ```
- */
-export declare function readJsonLines<T = unknown>(filePath: string, maxLines?: number): T[];
-/**
- * Check if a file exists
- *
- * @param filePath Path to check
- * @returns True if file exists
- */
-export declare function fileExists(filePath: string): boolean;
-/**
- * Read a JSON file safely
- *
- * @param filePath Path to JSON file
- * @returns Parsed JSON object or null if error
- *
- * @example
- * ```typescript
- * const config = readJson<ConfigType>('/path/to/config.json');
- * ```
- */
-export declare function readJson<T = unknown>(filePath: string): T | null;
-//# sourceMappingURL=file.d.ts.map

package/dist/utils/file.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/utils/file.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,MAAM,EAAE,CAejF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAa,GAAG,CAAC,EAAE,CAUzF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAYhE"}