@ai-devkit/agent-manager 0.15.0 → 0.17.0

package/src/adapters/GeminiCliAdapter.ts

@@ -26,6 +26,7 @@ import { listAgentProcesses, enrichProcesses } from '../utils/process.js';
 import { isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session.js';
 import type { SessionFile } from '../utils/session.js';
 import { matchProcessesToSessions, generateAgentName } from '../utils/matching.js';
+import { AgentRegistry } from '../utils/AgentRegistry.js';
 
 /**
  * A single Gemini CLI message content part. Mirrors the `{text?: string}`
@@ -87,10 +88,12 @@ export class GeminiCliAdapter implements AgentAdapter {
     private static readonly TMP_DIR_NAME = 'tmp';
 
     private geminiTmpDir: string;
+    private registry: AgentRegistry;
 
-    constructor() {
+    constructor(registry: AgentRegistry = AgentRegistry.default()) {
         const homeDir = process.env.HOME || process.env.USERPROFILE || '';
         this.geminiTmpDir = path.join(homeDir, '.gemini', GeminiCliAdapter.TMP_DIR_NAME);
+        this.registry = registry;
     }
 
     canHandle(processInfo: ProcessInfo): boolean {
@@ -114,12 +117,18 @@ export class GeminiCliAdapter implements AgentAdapter {
         const processes = nodeProcesses.filter((proc) => this.isGeminiExecutable(proc.command));
         if (processes.length === 0) return [];
 
-        const { sessions, contentCache } = this.discoverSessions(processes);
+        const { cachedAgents, remaining } = this.tryRegistryCache(processes);
+        if (remaining.length === 0) return this.deduplicateSessionAgents(cachedAgents);
+
+        const { sessions, contentCache } = this.discoverSessions(remaining);
         if (sessions.length === 0) {
-            return processes.map((p) => this.mapProcessOnlyAgent(p));
+            return this.deduplicateSessionAgents([
+                ...cachedAgents,
+                ...remaining.map((p) => this.mapProcessOnlyAgent(p)),
+            ]);
         }
 
-        const matches = matchProcessesToSessions(processes, sessions);
+        const matches = matchProcessesToSessions(remaining, sessions);
         const matchedPids = new Set(matches.map((m) => m.process.pid));
         const agents: AgentInfo[] = [];
 
@@ -133,13 +142,82 @@ export class GeminiCliAdapter implements AgentAdapter {
             }
         }
 
-        for (const proc of processes) {
+        for (const proc of remaining) {
             if (!matchedPids.has(proc.pid)) {
                 agents.push(this.mapProcessOnlyAgent(proc));
             }
         }
 
-        return agents;
+        return this.deduplicateSessionAgents([...cachedAgents, ...agents]);
+    }
+
+    private deduplicateSessionAgents(agents: AgentInfo[]): AgentInfo[] {
+        const bySession = new Map<string, AgentInfo>();
+        const result: AgentInfo[] = [];
+
+        for (const agent of agents) {
+            const sessionKey = this.sessionDeduplicationKey(agent);
+            if (!sessionKey) {
+                result.push(agent);
+                continue;
+            }
+
+            const existing = bySession.get(sessionKey);
+            if (!existing) {
+                bySession.set(sessionKey, agent);
+                result.push(agent);
+                continue;
+            }
+
+            if (agent.pid > existing.pid) {
+                bySession.set(sessionKey, agent);
+                const index = result.indexOf(existing);
+                if (index >= 0) result[index] = agent;
+            }
+        }
+
+        return result;
+    }
+
+    private sessionDeduplicationKey(agent: AgentInfo): string | null {
+        if (agent.sessionFilePath) return `file:${agent.sessionFilePath}`;
+        if (agent.sessionId && !agent.sessionId.startsWith('pid-')) {
+            return `session:${agent.sessionId}`;
+        }
+        return null;
+    }
+
+    private tryRegistryCache(processes: ProcessInfo[]): {
+        cachedAgents: AgentInfo[];
+        remaining: ProcessInfo[];
+    } {
+        const cachedAgents: AgentInfo[] = [];
+        const remaining: ProcessInfo[] = [];
+        const byPid = new Map(this.registry.list().map((e) => [e.pid, e]));
+
+        for (const proc of processes) {
+            const entry = byPid.get(proc.pid);
+            if (
+                !entry ||
+                entry.type !== this.type ||
+                !entry.sessionFilePath ||
+                !fs.existsSync(entry.sessionFilePath)
+            ) {
+                remaining.push(proc);
+                continue;
+            }
+
+            const content = safeReadFile(entry.sessionFilePath);
+            const sessionData = this.parseSession(content, entry.sessionFilePath);
+            if (!sessionData) {
+                remaining.push(proc);
+                continue;
+            }
+
+            cachedAgents.push(this.mapSessionToAgent(sessionData, proc, entry.sessionFilePath));
+        }
+
+        return { cachedAgents, remaining };
     }
 
     /**

package/src/adapters/index.ts

@@ -1,5 +1,6 @@
 export { ClaudeCodeAdapter } from './ClaudeCodeAdapter.js';
 export { CodexAdapter } from './CodexAdapter.js';
+export { CopilotAdapter } from './CopilotAdapter.js';
 export { GeminiCliAdapter } from './GeminiCliAdapter.js';
 export { OpenCodeAdapter } from './OpenCodeAdapter.js';
 export { AgentStatus } from './AgentAdapter.js';

package/src/index.ts

@@ -2,6 +2,7 @@ export { AgentManager } from './AgentManager.js';
 
 export { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter.js';
 export { CodexAdapter } from './adapters/CodexAdapter.js';
+export { CopilotAdapter } from './adapters/CopilotAdapter.js';
 export { GeminiCliAdapter } from './adapters/GeminiCliAdapter.js';
 export { OpenCodeAdapter } from './adapters/OpenCodeAdapter.js';
 export { AgentStatus } from './adapters/AgentAdapter.js';
@@ -22,3 +23,9 @@ export { TtyWriter } from './terminal/TtyWriter.js';
 export { getProcessTty } from './utils/process.js';
 export type { AgentSortKey } from './utils/sortAgents.js';
 export type { ListAgentsOptions } from './AgentManager.js';
+
+export { AgentRegistry, RenameNotFoundError, RenameConflictError } from './utils/AgentRegistry.js';
+export type { RegistryEntry } from './utils/AgentRegistry.js';
+export { TmuxManager } from './terminal/TmuxManager.js';
+export { AGENTS } from './utils/agents.js';
+export type { AgentConfig, StartableAgentType } from './utils/agents.js';

package/src/terminal/TmuxManager.ts

@@ -0,0 +1,118 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+
+const execFileAsync = promisify(execFile);
+
+export class TmuxManager {
+    async isAvailable(): Promise<boolean> {
+        try {
+            await execFileAsync('tmux', ['-V']);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    async sessionExists(name: string): Promise<boolean> {
+        try {
+            await execFileAsync('tmux', ['has-session', '-t', name]);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    async createSession(name: string, cwd: string): Promise<void> {
+        await execFileAsync('tmux', ['new-session', '-d', '-s', name, '-c', cwd]);
+    }
+
+    async sendKeys(session: string, keys: string): Promise<void> {
+        await execFileAsync('tmux', ['send-keys', '-t', session, keys, 'Enter']);
+    }
+
+    async killSession(name: string): Promise<void> {
+        try {
+            await execFileAsync('tmux', ['kill-session', '-t', name]);
+        } catch {
+            // Already gone — ignore
+        }
+    }
+
+    /**
+     * Find the actual agent process PID inside a tmux pane.
+     *
+     * Strategy: BFS the process tree, return the deepest descendant whose
+     * `ps` command line is accepted by `matches`. The caller supplies the
+     * matcher so this method has no agent-type knowledge.
+     *
+     * This handles two real-world process shapes:
+     * - Wrapper case: shell → claude-wrapper (matches) → claude (matches, deeper)
+     *   → returns the deeper one
+     * - Subprocess case: shell → claude (matches) → MCP server child (doesn't match)
+     *   → returns claude, not the subprocess
+     *
+     * Returns null when no descendant matches yet (agent still starting); the
+     * caller's poll loop retries.
+     */
+    async findAgentPid(session: string, matches: (psCommand: string) => boolean): Promise<number | null> {
+        const panePid = await this.getPanePid(session);
+        if (panePid === null) return null;
+
+        const visited = new Set<number>();
+        const queue: number[] = [panePid];
+        let deepestMatch: number | null = null;
+
+        while (queue.length > 0) {
+            const pid = queue.shift()!;
+            if (visited.has(pid)) continue;
+            visited.add(pid);
+
+            if (pid !== panePid) {
+                const command = await this.getProcessCommand(pid);
+                if (command && matches(command)) {
+                    deepestMatch = pid;
+                }
+            }
+
+            const children = await this.pgrepChildren(pid);
+            queue.push(...children);
+        }
+
+        return deepestMatch;
+    }
+
+    private async getPanePid(session: string): Promise<number | null> {
+        try {
+            const { stdout } = await execFileAsync('tmux', [
+                'list-panes', '-t', session, '-F', '#{pane_pid}',
+            ]);
+            const panePid = parseInt(stdout.trim().split('\n')[0], 10);
+            return isNaN(panePid) ? null : panePid;
+        } catch {
+            return null;
+        }
+    }
+
+    private async pgrepChildren(pid: number): Promise<number[]> {
+        try {
+            const { stdout } = await execFileAsync('pgrep', ['-P', String(pid)]);
+            return stdout
+                .trim()
+                .split('\n')
+                .map((s) => parseInt(s, 10))
+                .filter((n) => !isNaN(n));
+        } catch {
+            return [];
+        }
+    }
+
+    private async getProcessCommand(pid: number): Promise<string | null> {
+        try {
+            const { stdout } = await execFileAsync('ps', ['-p', String(pid), '-o', 'command=']);
+            const trimmed = stdout.trim();
+            return trimmed || null;
+        } catch {
+            return null;
+        }
+    }
+}

package/src/utils/AgentRegistry.ts

@@ -0,0 +1,139 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { AgentType } from '../adapters/AgentAdapter.js';
+
+export class RenameNotFoundError extends Error {
+    constructor(public agentName: string) {
+        super(`Agent "${agentName}" not found in registry.`);
+        this.name = 'RenameNotFoundError';
+    }
+}
+
+export class RenameConflictError extends Error {
+    constructor(public agentName: string) {
+        super(`Agent "${agentName}" is already in use.`);
+        this.name = 'RenameConflictError';
+    }
+}
+
+export interface RegistryEntry {
+    name: string;
+    type: AgentType;
+    pid: number;
+    tmuxSession: string;
+    cwd: string;
+    startedAt: string;  // ISO 8601
+    sessionId: string;
+    sessionFilePath: string;
+}
+
+interface RegistryFile {
+    entries: RegistryEntry[];
+}
+
+const DEFAULT_REGISTRY_PATH = path.join(os.homedir(), '.ai-devkit', 'agents.json');
+
+let defaultInstance: AgentRegistry | null = null;
+
+export class AgentRegistry {
+    private filePath: string;
+
+    constructor(filePath: string = DEFAULT_REGISTRY_PATH) {
+        this.filePath = filePath;
+    }
+
+    static default(): AgentRegistry {
+        if (!defaultInstance) {
+            defaultInstance = new AgentRegistry();
+        }
+        return defaultInstance;
+    }
+
+    private readFile(): RegistryFile {
+        try {
+            const raw = fs.readFileSync(this.filePath, 'utf8');
+            const parsed = JSON.parse(raw) as RegistryFile;
+            return { entries: Array.isArray(parsed.entries) ? parsed.entries : [] };
+        } catch {
+            return { entries: [] };
+        }
+    }
+
+    private writeFile(data: RegistryFile): void {
+        const dir = path.dirname(this.filePath);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmp = `${this.filePath}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+        fs.renameSync(tmp, this.filePath);
+    }
+
+    private mergeEntry(incoming: RegistryEntry, existing: RegistryEntry | undefined): RegistryEntry {
+        if (!existing) return incoming;
+        return {
+            ...incoming,
+            tmuxSession: incoming.tmuxSession || existing.tmuxSession,
+        };
+    }
+
+    isAlive(entry: RegistryEntry): boolean {
+        try {
+            process.kill(entry.pid, 0);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    prune(): void {
+        const data = this.readFile();
+        const live = data.entries.filter((e) => this.isAlive(e));
+        if (live.length !== data.entries.length) {
+            this.writeFile({ entries: live });
+        }
+    }
+
+    register(entry: RegistryEntry): void {
+        this.registerBatch([entry]);
+    }
+
+    registerBatch(entries: RegistryEntry[]): void {
+        if (entries.length === 0) return;
+        const data = this.readFile();
+        for (const incoming of entries) {
+            const idx = data.entries.findIndex((e) => e.name === incoming.name);
+            if (idx >= 0) {
+                data.entries[idx] = this.mergeEntry(incoming, data.entries[idx]);
+            } else {
+                data.entries.push(incoming);
+            }
+        }
+        this.writeFile(data);
+    }
+
+    rename(currentName: string, newName: string): void {
+        const data = this.readFile();
+        const idx = data.entries.findIndex((e) => e.name === currentName);
+        if (idx < 0) {
+            throw new RenameNotFoundError(currentName);
+        }
+        const liveEntries = data.entries.filter((e) => this.isAlive(e));
+        const conflict = liveEntries.find((e) => e.name === newName);
+        if (conflict) {
+            throw new RenameConflictError(newName);
+        }
+        const pruned = liveEntries.map((e) =>
+            e.name === currentName ? { ...e, name: newName } : e,
+        );
+        this.writeFile({ entries: pruned });
+    }
+
+    lookup(name: string): RegistryEntry | null {
+        const data = this.readFile();
+        return data.entries.find((e) => e.name === name) ?? null;
+    }
+
+    list(): RegistryEntry[] {
+        return this.readFile().entries;
+    }
+}

package/src/utils/ClaudeSessionParser.ts

@@ -51,8 +51,23 @@ export interface ClaudeSession {
     firstUserMessage?: string;
 }
 
-/** Entry types that are metadata, not conversation state. */
-const METADATA_ENTRY_TYPES = new Set(['last-prompt', 'file-history-snapshot']);
+/**
+ * Top-level JSONL entry types that represent conversation/agent state.
+ *
+ * Only these types update `lastEntryType` for status determination. All
+ * other types Claude Code emits (`attachment`, `permission-mode`,
+ * `ai-title`, `queued_command`, `tools_changed`, `model_changed`,
+ * `hook_progress`, …) are UI-state events that must not overwrite the
+ * last conversation turn — otherwise polling between writes lands on a
+ * UI-state entry and `determineStatus` falls through to UNKNOWN.
+ */
+const CONVERSATION_ENTRY_TYPES = new Set([
+    'user',
+    'assistant',
+    'system',
+    'progress',
+    'thinking',
+]);
 
 /**
  * Parses Claude Code session JSONL files into structured data.
@@ -110,7 +125,7 @@ export class ClaudeSessionParser {
                     lastCwd = entry.cwd;
                 }
 
-                if (entry.type && !METADATA_ENTRY_TYPES.has(entry.type)) {
+                if (entry.type && CONVERSATION_ENTRY_TYPES.has(entry.type)) {
                     lastEntryType = entry.type;
 
                     if (entry.type === 'user') {
@@ -220,16 +235,12 @@ export class ClaudeSessionParser {
                 continue;
             }
 
-            const entryType = entry.type;
-            if (!entryType || METADATA_ENTRY_TYPES.has(entryType)) continue;
-            if (entryType === 'progress' || entryType === 'thinking') continue;
-
             let role: ConversationMessage['role'];
-            if (entryType === 'user') {
+            if (entry.type === 'user') {
                 role = 'user';
-            } else if (entryType === 'assistant') {
+            } else if (entry.type === 'assistant') {
                 role = 'assistant';
-            } else if (entryType === 'system') {
+            } else if (entry.type === 'system') {
                 role = 'system';
             } else {
                 continue;

package/src/utils/agents.ts

@@ -0,0 +1,41 @@
+import path from 'path';
+import type { AgentType } from '../adapters/AgentAdapter.js';
+
+export type StartableAgentType = Extract<AgentType, 'claude' | 'codex' | 'gemini_cli' | 'opencode'>;
+
+export interface AgentConfig {
+    /** Shell command to launch the agent (sent to tmux via `send-keys`). */
+    command: string;
+    /** Returns true if the given `ps` command line belongs to this agent. */
+    matches: (psCommand: string) => boolean;
+}
+
+/**
+ * Per-agent configuration: launch command plus a matcher that recognizes the
+ * agent's process in `ps` output. Each matcher knows that agent's distribution
+ * quirks (e.g. gemini ships as a Node script so its real binary is in argv[1..]).
+ */
+export const AGENTS: Record<StartableAgentType, AgentConfig> = {
+    claude:     { command: 'claude',   matches: matchArgv0('claude') },
+    codex:      { command: 'codex',    matches: matchArgv0('codex') },
+    opencode:   { command: 'opencode', matches: matchArgv0('opencode') },
+    gemini_cli: { command: 'gemini',   matches: matchAnyToken('gemini') },
+};
+
+function matchArgv0(name: string): (psCommand: string) => boolean {
+    const lower = name.toLowerCase();
+    return (psCommand) => {
+        const token = psCommand.trim().split(/\s+/)[0];
+        return token ? path.basename(token).toLowerCase() === lower : false;
+    };
+}
+
+function matchAnyToken(name: string): (psCommand: string) => boolean {
+    const lower = name.toLowerCase();
+    return (psCommand) => {
+        for (const token of psCommand.trim().split(/\s+/)) {
+            if (path.basename(token).toLowerCase() === lower) return true;
+        }
+        return false;
+    };
+}