@ai-devkit/agent-manager 0.14.0 → 0.16.0

package/src/index.ts

@@ -1,10 +1,10 @@
-export { AgentManager } from './AgentManager';
+export { AgentManager } from './AgentManager.js';
 
-export { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter';
-export { CodexAdapter } from './adapters/CodexAdapter';
-export { GeminiCliAdapter } from './adapters/GeminiCliAdapter';
-export { OpenCodeAdapter } from './adapters/OpenCodeAdapter';
-export { AgentStatus } from './adapters/AgentAdapter';
+export { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter.js';
+export { CodexAdapter } from './adapters/CodexAdapter.js';
+export { GeminiCliAdapter } from './adapters/GeminiCliAdapter.js';
+export { OpenCodeAdapter } from './adapters/OpenCodeAdapter.js';
+export { AgentStatus } from './adapters/AgentAdapter.js';
 export type {
     AgentAdapter,
     AgentType,
@@ -13,10 +13,18 @@ export type {
     ConversationMessage,
     SessionSummary,
     ListSessionsOptions,
-} from './adapters/AgentAdapter';
+} from './adapters/AgentAdapter.js';
 
-export { TerminalFocusManager, TerminalType } from './terminal/TerminalFocusManager';
-export type { TerminalLocation } from './terminal/TerminalFocusManager';
-export { TtyWriter } from './terminal/TtyWriter';
+export { TerminalFocusManager, TerminalType } from './terminal/TerminalFocusManager.js';
+export type { TerminalLocation } from './terminal/TerminalFocusManager.js';
+export { TtyWriter } from './terminal/TtyWriter.js';
 
-export { getProcessTty } from './utils/process';
+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/TerminalFocusManager.ts

@@ -1,7 +1,7 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { getProcessTty } from '../utils/process';
-import { escapeAppleScript } from '../utils/applescript';
+import { getProcessTty } from '../utils/process.js';
+import { escapeAppleScript } from '../utils/applescript.js';
 
 const execFileAsync = promisify(execFile);
 

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/terminal/TtyWriter.ts

@@ -1,8 +1,8 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import type { TerminalLocation } from './TerminalFocusManager';
-import { TerminalType } from './TerminalFocusManager';
-import { escapeAppleScript } from '../utils/applescript';
+import type { TerminalLocation } from './TerminalFocusManager.js';
+import { TerminalType } from './TerminalFocusManager.js';
+import { escapeAppleScript } from '../utils/applescript.js';
 
 const execFileAsync = promisify(execFile);
 

package/src/terminal/index.ts

@@ -1,4 +1,4 @@
-export { TerminalFocusManager } from './TerminalFocusManager';
-export { TerminalType } from './TerminalFocusManager';
-export type { TerminalLocation } from './TerminalFocusManager';
-export { TtyWriter } from './TtyWriter';
+export { TerminalFocusManager } from './TerminalFocusManager.js';
+export { TerminalType } from './TerminalFocusManager.js';
+export type { TerminalLocation } from './TerminalFocusManager.js';
+export { TtyWriter } from './TtyWriter.js';

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

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import type { ConversationMessage } from '../adapters/AgentAdapter';
-import { AgentStatus } from '../adapters/AgentAdapter';
+import type { ConversationMessage } from '../adapters/AgentAdapter.js';
+import { AgentStatus } from '../adapters/AgentAdapter.js';
 
 /**
  * Content block within a Claude Code JSONL message entry.
@@ -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 = Exclude<AgentType, 'other'>;
+
+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;
+    };
+}

package/src/utils/index.ts

@@ -1,6 +1,6 @@
-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';
+export { listAgentProcesses, batchGetProcessCwds, batchGetProcessStartTimes, enrichProcesses } from './process.js';
+export { getProcessTty } from './process.js';
+export { batchGetSessionFileBirthtimes } from './session.js';
+export type { SessionFile } from './session.js';
+export { matchProcessesToSessions, generateAgentName } from './matching.js';
+export type { MatchResult } from './matching.js';

package/src/utils/matching.ts

@@ -6,8 +6,8 @@
  */
 
 import * as path from 'path';
-import type { ProcessInfo } from '../adapters/AgentAdapter';
-import type { SessionFile } from './session';
+import type { ProcessInfo } from '../adapters/AgentAdapter.js';
+import type { SessionFile } from './session.js';
 
 /** Maximum allowed delta between process start time and session file birth time. */
 const TOLERANCE_MS = 3 * 60 * 1000; // 3 minutes

package/src/utils/process.ts

@@ -7,7 +7,7 @@
 
 import * as path from 'path';
 import { execFileSync } from 'child_process';
-import type { ProcessInfo } from '../adapters/AgentAdapter';
+import type { ProcessInfo } from '../adapters/AgentAdapter.js';
 
 /**
  * List running processes matching an agent executable name.

package/src/utils/sortAgents.ts

@@ -0,0 +1,52 @@
+import { AgentStatus, type AgentInfo } from '../adapters/AgentAdapter.js';
+
+export type AgentSortKey = 'name' | 'status' | 'pid' | 'lastActive';
+
+const STATUS_PRIORITY: Record<AgentStatus, number> = {
+    [AgentStatus.WAITING]: 0,
+    [AgentStatus.RUNNING]: 1,
+    [AgentStatus.IDLE]: 2,
+    [AgentStatus.UNKNOWN]: 3,
+};
+
+function compareByName(a: AgentInfo, b: AgentInfo): number {
+    return a.name.localeCompare(b.name);
+}
+
+function compareByStatus(a: AgentInfo, b: AgentInfo): number {
+    const pa = STATUS_PRIORITY[a.status] ?? 999;
+    const pb = STATUS_PRIORITY[b.status] ?? 999;
+    if (pa !== pb) return pa - pb;
+    return compareByName(a, b);
+}
+
+function compareByPid(a: AgentInfo, b: AgentInfo): number {
+    if (a.pid !== b.pid) return a.pid - b.pid;
+    return compareByName(a, b);
+}
+
+function compareByLastActive(a: AgentInfo, b: AgentInfo): number {
+    const ta = a.lastActive instanceof Date ? a.lastActive.getTime() : new Date(a.lastActive).getTime();
+    const tb = b.lastActive instanceof Date ? b.lastActive.getTime() : new Date(b.lastActive).getTime();
+    if (tb !== ta) return tb - ta; // most recent first
+    return compareByName(a, b);
+}
+
+export function sortAgents(agents: AgentInfo[], by: AgentSortKey): AgentInfo[] {
+    const copy = agents.slice();
+    switch (by) {
+        case 'name':
+            copy.sort(compareByName);
+            break;
+        case 'status':
+            copy.sort(compareByStatus);
+            break;
+        case 'pid':
+            copy.sort(compareByPid);
+            break;
+        case 'lastActive':
+            copy.sort(compareByLastActive);
+            break;
+    }
+    return copy;
+}

package/tsconfig.json

@@ -1,8 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-    "module": "commonjs",
-    "moduleResolution": "node",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
     "rootDir": "./src",
     "outDir": "./dist"
   },

package/vitest.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: 'node',
+        include: ['src/**/__tests__/**/*.test.ts'],
+        coverage: {
+            provider: 'v8',
+            include: ['src/**/*.ts'],
+            exclude: ['src/index.ts', 'src/**/*.d.ts'],
+            thresholds: {
+                branches: 70,
+                functions: 70,
+                lines: 70,
+                statements: 70,
+            },
+        },
+    },
+});

package/jest.config.js

@@ -1,21 +0,0 @@
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  roots: ['<rootDir>/src'],
-  testMatch: ['**/__tests__/**/*.test.ts', '**/?(*.)+(spec|test).ts'],
-  collectCoverageFrom: [
-    'src/**/*.{ts,js}',
-    '!src/**/*.d.ts',
-    '!src/index.ts'
-  ],
-  coverageDirectory: 'coverage',
-  coverageReporters: ['text', 'lcov', 'html'],
-  coverageThreshold: {
-    global: {
-      branches: 80,
-      functions: 80,
-      lines: 80,
-      statements: 80
-    }
-  }
-};