@ai-devkit/agent-manager 0.1.0

package/src/adapters/ClaudeCodeAdapter.ts

@@ -0,0 +1,344 @@
+/**
+ * Claude Code Adapter
+ * 
+ * Detects running Claude Code agents by reading session files
+ * from ~/.claude/ directory and correlating with running processes.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { AgentAdapter, AgentInfo, ProcessInfo } from './AgentAdapter';
+import { AgentStatus } from './AgentAdapter';
+import { listProcesses } from '../utils/process';
+import { readLastLines, readJsonLines, readJson } from '../utils/file';
+
+/**
+ * Structure of ~/.claude/projects/{path}/sessions-index.json
+ */
+interface SessionsIndex {
+    originalPath: string;
+}
+
+/**
+ * Entry in session JSONL file
+ */
+interface SessionEntry {
+    type?: 'assistant' | 'user' | 'progress' | 'thinking' | 'system' | 'message' | 'text';
+    timestamp?: string;
+    slug?: string;
+    cwd?: string;
+    sessionId?: string;
+    message?: {
+        content?: Array<{
+            type?: string;
+            text?: string;
+            content?: string;
+        }>;
+    };
+    [key: string]: unknown;
+}
+
+/**
+ * Entry in ~/.claude/history.jsonl
+ */
+interface HistoryEntry {
+    display: string;
+    timestamp: number;
+    project: string;
+    sessionId: string;
+}
+
+/**
+ * Claude Code session information
+ */
+interface ClaudeSession {
+    sessionId: string;
+    projectPath: string;
+    slug?: string;
+    sessionLogPath: string;
+    lastEntry?: SessionEntry;
+    lastActive?: Date;
+}
+
+/**
+ * Claude Code Adapter
+ * 
+ * Detects Claude Code agents by:
+ * 1. Finding running claude processes
+ * 2. Reading session files from ~/.claude/projects/
+ * 3. Matching sessions to processes via CWD
+ * 4. Extracting status from session JSONL
+ * 5. Extracting summary from history.jsonl
+ */
+export class ClaudeCodeAdapter implements AgentAdapter {
+    readonly type = 'claude' as const;
+
+    /** Threshold in minutes before considering a session idle */
+    private static readonly IDLE_THRESHOLD_MINUTES = 5;
+
+    private claudeDir: string;
+    private projectsDir: string;
+    private historyPath: string;
+
+    constructor() {
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        this.claudeDir = path.join(homeDir, '.claude');
+        this.projectsDir = path.join(this.claudeDir, 'projects');
+        this.historyPath = path.join(this.claudeDir, 'history.jsonl');
+    }
+
+    /**
+     * Check if this adapter can handle a given process
+     */
+    canHandle(processInfo: ProcessInfo): boolean {
+        return processInfo.command.toLowerCase().includes('claude');
+    }
+
+    /**
+     * Detect running Claude Code agents
+     */
+    async detectAgents(): Promise<AgentInfo[]> {
+        // 1. Find running claude processes
+        const claudeProcesses = listProcesses({ namePattern: 'claude' });
+
+        if (claudeProcesses.length === 0) {
+            return [];
+        }
+
+        // 2. Read all sessions
+        const sessions = this.readSessions();
+
+        // 3. Read history for summaries
+        const history = this.readHistory();
+
+        // 4. Group processes by CWD
+        const processesByCwd = new Map<string, ProcessInfo[]>();
+        for (const p of claudeProcesses) {
+            const list = processesByCwd.get(p.cwd) || [];
+            list.push(p);
+            processesByCwd.set(p.cwd, list);
+        }
+
+        // 5. Match sessions to processes
+        const agents: AgentInfo[] = [];
+
+        for (const [cwd, processes] of processesByCwd) {
+            // Find sessions for this project path
+            const projectSessions = sessions.filter(s => s.projectPath === cwd);
+
+            if (projectSessions.length === 0) {
+                continue;
+            }
+
+            // Sort sessions by last active time (newest first)
+            projectSessions.sort((a, b) => {
+                const timeA = a.lastActive?.getTime() || 0;
+                const timeB = b.lastActive?.getTime() || 0;
+                return timeB - timeA;
+            });
+
+            // Map processes to the most recent sessions
+            // If there are 2 processes, we take the 2 most recent sessions
+            const activeSessions = projectSessions.slice(0, processes.length);
+
+            for (let i = 0; i < activeSessions.length; i++) {
+                const session = activeSessions[i];
+                const process = processes[i]; // Assign process to session (arbitrary 1-to-1 mapping)
+
+                const historyEntry = [...history].reverse().find(
+                    h => h.sessionId === session.sessionId
+                );
+                const summary = historyEntry?.display || 'Session started';
+                const status = this.determineStatus(session);
+                const agentName = this.generateAgentName(session, agents); // Pass currently built agents for collision checks
+
+                agents.push({
+                    name: agentName,
+                    type: this.type,
+                    status,
+                    summary,
+                    pid: process.pid,
+                    projectPath: session.projectPath,
+                    sessionId: session.sessionId,
+                    slug: session.slug,
+                    lastActive: session.lastActive || new Date(),
+                });
+            }
+        }
+
+        return agents;
+    }
+
+    /**
+     * Read all Claude Code sessions
+     */
+    private readSessions(): ClaudeSession[] {
+        if (!fs.existsSync(this.projectsDir)) {
+            return [];
+        }
+
+        const sessions: ClaudeSession[] = [];
+        const projectDirs = fs.readdirSync(this.projectsDir);
+
+        for (const dirName of projectDirs) {
+            if (dirName.startsWith('.')) {
+                continue;
+            }
+
+            const projectDir = path.join(this.projectsDir, dirName);
+            if (!fs.statSync(projectDir).isDirectory()) {
+                continue;
+            }
+
+            // Read sessions-index.json to get original project path
+            const indexPath = path.join(projectDir, 'sessions-index.json');
+            if (!fs.existsSync(indexPath)) {
+                continue;
+            }
+
+            const sessionsIndex = readJson<SessionsIndex>(indexPath);
+            if (!sessionsIndex) {
+                console.error(`Failed to parse ${indexPath}`);
+                continue;
+            }
+
+            const sessionFiles = fs.readdirSync(projectDir).filter(f => f.endsWith('.jsonl'));
+
+            for (const sessionFile of sessionFiles) {
+                const sessionId = sessionFile.replace('.jsonl', '');
+                const sessionLogPath = path.join(projectDir, sessionFile);
+
+                try {
+                    const sessionData = this.readSessionLog(sessionLogPath);
+
+                    sessions.push({
+                        sessionId,
+                        projectPath: sessionsIndex.originalPath,
+                        slug: sessionData.slug,
+                        sessionLogPath,
+                        lastEntry: sessionData.lastEntry,
+                        lastActive: sessionData.lastActive,
+                    });
+                } catch (error) {
+                    console.error(`Failed to read session ${sessionId}:`, error);
+                    continue;
+                }
+            }
+        }
+
+        return sessions;
+    }
+
+    /**
+     * Read a session JSONL file
+     * Only reads last 100 lines for performance with large files
+     */
+    private readSessionLog(logPath: string): {
+        slug?: string;
+        lastEntry?: SessionEntry;
+        lastActive?: Date;
+    } {
+        const lines = readLastLines(logPath, 100);
+
+        let slug: string | undefined;
+        let lastEntry: SessionEntry | undefined;
+        let lastActive: Date | undefined;
+
+        for (const line of lines) {
+            try {
+                const entry: SessionEntry = JSON.parse(line);
+
+                if (entry.slug && !slug) {
+                    slug = entry.slug;
+                }
+
+                lastEntry = entry;
+
+                if (entry.timestamp) {
+                    lastActive = new Date(entry.timestamp);
+                }
+            } catch (error) {
+                continue;
+            }
+        }
+
+        return { slug, lastEntry, lastActive };
+    }
+
+    /**
+     * Read history.jsonl for user prompts
+     * Only reads last 100 lines for performance
+     */
+    private readHistory(): HistoryEntry[] {
+        return readJsonLines<HistoryEntry>(this.historyPath, 100);
+    }
+
+    /**
+     * Determine agent status from session entry
+     */
+    private determineStatus(session: ClaudeSession): AgentStatus {
+        if (!session.lastEntry) {
+            return AgentStatus.UNKNOWN;
+        }
+
+        const entryType = session.lastEntry.type;
+        const lastActive = session.lastActive || new Date(0);
+        const ageMinutes = (Date.now() - lastActive.getTime()) / 1000 / 60;
+
+        if (ageMinutes > ClaudeCodeAdapter.IDLE_THRESHOLD_MINUTES) {
+            return AgentStatus.IDLE;
+        }
+
+        if (entryType === 'user') {
+            // Check if user interrupted manually - this puts agent back in waiting state
+            const content = session.lastEntry.message?.content;
+            if (Array.isArray(content)) {
+                const isInterrupted = content.some(c =>
+                    (c.type === 'text' && c.text?.includes('[Request interrupted')) ||
+                    (c.type === 'tool_result' && c.content?.includes('[Request interrupted'))
+                );
+                if (isInterrupted) return AgentStatus.WAITING;
+            }
+            return AgentStatus.RUNNING;
+        }
+
+        if (entryType === 'progress' || entryType === 'thinking') {
+            return AgentStatus.RUNNING;
+        } else if (entryType === 'assistant') {
+            return AgentStatus.WAITING;
+        } else if (entryType === 'system') {
+            return AgentStatus.IDLE;
+        }
+
+        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);
+
+        const sameProjectAgents = existingAgents.filter(
+            a => a.projectPath === session.projectPath
+        );
+
+        if (sameProjectAgents.length === 0) {
+            return projectName;
+        }
+
+        // Multiple sessions for same project, append slug
+        if (session.slug) {
+            // Use first word of slug for brevity (with safety check for format)
+            const slugPart = session.slug.includes('-')
+                ? session.slug.split('-')[0]
+                : session.slug.slice(0, 8);
+            return `${projectName} (${slugPart})`;
+        }
+
+        // No slug available, use session ID prefix
+        return `${projectName} (${session.sessionId.slice(0, 8)})`;
+    }
+
+}

package/src/adapters/index.ts

@@ -0,0 +1,3 @@
+export { ClaudeCodeAdapter } from './ClaudeCodeAdapter';
+export { AgentStatus } from './AgentAdapter';
+export type { AgentAdapter, AgentType, AgentInfo, ProcessInfo } from './AgentAdapter';

package/src/index.ts

@@ -0,0 +1,12 @@
+export { AgentManager } from './AgentManager';
+
+export { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter';
+export { AgentStatus } from './adapters/AgentAdapter';
+export type { AgentAdapter, AgentType, AgentInfo, ProcessInfo } from './adapters/AgentAdapter';
+
+export { TerminalFocusManager } from './terminal/TerminalFocusManager';
+export type { TerminalLocation } from './terminal/TerminalFocusManager';
+
+export { listProcesses, getProcessCwd, getProcessTty, isProcessRunning, getProcessInfo } from './utils/process';
+export type { ListProcessesOptions } from './utils/process';
+export { readLastLines, readJsonLines, fileExists, readJson } from './utils/file';

package/src/terminal/TerminalFocusManager.ts

@@ -0,0 +1,206 @@
+import { exec, execFile } from 'child_process';
+import { promisify } from 'util';
+import { getProcessTty } from '../utils/process';
+
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+
+export interface TerminalLocation {
+    type: 'tmux' | 'iterm2' | 'terminal-app' | 'unknown';
+    identifier: string; // e.g., "session:window.pane" for tmux, or TTY for others
+    tty: string;        // e.g., "/dev/ttys030"
+}
+
+export class TerminalFocusManager {
+    /**
+     * Find the terminal location (emulator info) for a given process ID
+     */
+    async findTerminal(pid: number): Promise<TerminalLocation | null> {
+        const ttyShort = getProcessTty(pid);
+
+        // If no TTY or invalid, we can't find the terminal
+        if (!ttyShort || ttyShort === '?') {
+            return null;
+        }
+
+        const fullTty = `/dev/${ttyShort}`;
+
+        // 1. Check tmux (most specific if running inside it)
+        const tmuxLocation = await this.findTmuxPane(fullTty);
+        if (tmuxLocation) return tmuxLocation;
+
+        // 2. Check iTerm2
+        const itermLocation = await this.findITerm2Session(fullTty);
+        if (itermLocation) return itermLocation;
+
+        // 3. Check Terminal.app
+        const terminalAppLocation = await this.findTerminalAppWindow(fullTty);
+        if (terminalAppLocation) return terminalAppLocation;
+
+        // 4. Fallback: we know the TTY but not the emulator wrapper
+        return {
+            type: 'unknown',
+            identifier: '',
+            tty: fullTty
+        };
+    }
+
+    /**
+     * Focus the terminal identified by the location
+     */
+    async focusTerminal(location: TerminalLocation): Promise<boolean> {
+        try {
+            switch (location.type) {
+                case 'tmux':
+                    return await this.focusTmuxPane(location.identifier);
+                case 'iterm2':
+                    return await this.focusITerm2Session(location.tty);
+                case 'terminal-app':
+                    return await this.focusTerminalAppWindow(location.tty);
+                default:
+                    return false;
+            }
+        } catch (error) {
+            return false;
+        }
+    }
+
+    private async findTmuxPane(tty: string): Promise<TerminalLocation | null> {
+        try {
+            // List all panes with their TTYs and identifiers
+            // Format: /dev/ttys001|my-session:1.1
+            // using | as separator to handle spaces in session names
+            const { stdout } = await execAsync("tmux list-panes -a -F '#{pane_tty}|#{session_name}:#{window_index}.#{pane_index}'");
+
+            const lines = stdout.trim().split('\n');
+            for (const line of lines) {
+                if (!line.trim()) continue;
+                const [paneTty, identifier] = line.split('|');
+                if (paneTty === tty && identifier) {
+                    return {
+                        type: 'tmux',
+                        identifier,
+                        tty
+                    };
+                }
+            }
+        } catch (error) {
+            // tmux might not be installed or running
+        }
+        return null;
+    }
+
+    private async findITerm2Session(tty: string): Promise<TerminalLocation | null> {
+        try {
+            // Check if iTerm2 is running first to avoid launching it
+            const { stdout: isRunning } = await execAsync('pgrep -x iTerm2 || echo "no"');
+            if (isRunning.trim() === "no") return null;
+
+            const script = `
+        tell application "iTerm"
+          repeat with w in windows
+            repeat with t in tabs of w
+              repeat with s in sessions of t
+                if tty of s is "${tty}" then
+                  return "found"
+                end if
+              end repeat
+            end repeat
+          end repeat
+        end tell
+      `;
+
+            const { stdout } = await execAsync(`osascript -e '${script}'`);
+            if (stdout.trim() === "found") {
+                return {
+                    type: 'iterm2',
+                    identifier: tty,
+                    tty
+                };
+            }
+        } catch (error) {
+            // iTerm2 not found or script failed
+        }
+        return null;
+    }
+
+    private async findTerminalAppWindow(tty: string): Promise<TerminalLocation | null> {
+        try {
+            // Check if Terminal is running
+            const { stdout: isRunning } = await execAsync('pgrep -x Terminal || echo "no"');
+            if (isRunning.trim() === "no") return null;
+
+            const script = `
+        tell application "Terminal"
+          repeat with w in windows
+            repeat with t in tabs of w
+              if tty of t is "${tty}" then
+                return "found"
+              end if
+            end repeat
+          end repeat
+        end tell
+      `;
+
+            const { stdout } = await execAsync(`osascript -e '${script}'`);
+            if (stdout.trim() === "found") {
+                return {
+                    type: 'terminal-app',
+                    identifier: tty,
+                    tty
+                };
+            }
+        } catch (error) {
+            // Terminal not found or script failed
+        }
+        return null;
+    }
+
+    private async focusTmuxPane(identifier: string): Promise<boolean> {
+        try {
+            await execFileAsync('tmux', ['switch-client', '-t', identifier]);
+            return true;
+        } catch (error) {
+            return false;
+        }
+    }
+
+    private async focusITerm2Session(tty: string): Promise<boolean> {
+        const script = `
+       tell application "iTerm"
+         activate
+         repeat with w in windows
+           repeat with t in tabs of w
+             repeat with s in sessions of t
+               if tty of s is "${tty}" then
+                 select s
+                 return "true"
+               end if
+             end repeat
+           end repeat
+         end repeat
+       end tell
+     `;
+        const { stdout } = await execAsync(`osascript -e '${script}'`);
+        return stdout.trim() === "true";
+    }
+
+    private async focusTerminalAppWindow(tty: string): Promise<boolean> {
+        const script = `
+       tell application "Terminal"
+         activate
+         repeat with w in windows
+           repeat with t in tabs of w
+             if tty of t is "${tty}" then
+               set index of w to 1
+               set selected tab of w to t
+               return "true"
+             end if
+           end repeat
+         end repeat
+       end tell
+    `;
+        const { stdout } = await execAsync(`osascript -e '${script}'`);
+        return stdout.trim() === "true";
+    }
+}

package/src/terminal/index.ts

@@ -0,0 +1,2 @@
+export { TerminalFocusManager } from './TerminalFocusManager';
+export type { TerminalLocation } from './TerminalFocusManager';

package/src/utils/file.ts

@@ -0,0 +1,100 @@
+/**
+ * File Utilities
+ * 
+ * Helper functions for reading files efficiently
+ */
+
+import * as fs from 'fs';
+
+/**
+ * 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 function readLastLines(filePath: string, lineCount: number = 100): string[] {
+    if (!fs.existsSync(filePath)) {
+        return [];
+    }
+
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const allLines = content.trim().split('\n');
+
+        // Return last N lines (or all if file has fewer lines)
+        return allLines.slice(-lineCount);
+    } catch (error) {
+        console.error(`Failed to read ${filePath}:`, error);
+        return [];
+    }
+}
+
+/**
+ * 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 function readJsonLines<T = unknown>(filePath: string, maxLines: number = 1000): T[] {
+    const lines = readLastLines(filePath, maxLines);
+
+    return lines.map(line => {
+        try {
+            return JSON.parse(line) as T;
+        } catch {
+            return null;
+        }
+    }).filter((entry): entry is T => entry !== null);
+}
+
+/**
+ * Check if a file exists
+ * 
+ * @param filePath Path to check
+ * @returns True if file exists
+ */
+export function fileExists(filePath: string): boolean {
+    try {
+        return fs.existsSync(filePath);
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * 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 function readJson<T = unknown>(filePath: string): T | null {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content) as T;
+    } catch (error) {
+        console.error(`Failed to parse JSON from ${filePath}:`, error);
+        return null;
+    }
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export { listProcesses, getProcessCwd, getProcessTty, isProcessRunning, getProcessInfo } from './process';
+export type { ListProcessesOptions } from './process';
+export { readLastLines, readJsonLines, fileExists, readJson } from './file';