@ai-devkit/agent-manager 0.11.0 → 0.13.0

package/src/adapters/ClaudeCodeAdapter.ts

@@ -28,14 +28,29 @@ interface PidFileEntry {
     startedAt: number;
     kind: string;
     entrypoint: string;
+    /**
+     * Authoritative live status published by the Claude Code process
+     * (e.g., 'running', 'waiting', 'idle'). Preferred over JSONL-derived
+     * status because trailing entries like 'permission-mode' / 'ai-title'
+     * can mask the real conversational state.
+     */
+    status?: string;
+    /** Short description of what the agent is waiting on (e.g., "approve Read"). */
+    waitingFor?: string;
 }
 
 /**
  * A process directly matched to a session via PID file (authoritative path).
+ *
+ * When the matching PID file also exposes live status/waitingFor metadata,
+ * those values are carried here so `mapSessionToAgent` can prefer them
+ * over the JSONL-derived heuristic.
  */
 interface DirectMatch {
     process: ProcessInfo;
     sessionFile: SessionFile;
+    pidStatus?: AgentStatus;
+    waitingFor?: string;
 }
 
 /** Maximum allowed delta (ms) between process start time and PID file startedAt. */
@@ -81,10 +96,17 @@ export class ClaudeCodeAdapter implements AgentAdapter {
             return [];
         }
 
-        // Step 1: try authoritative PID-file matching for every process
-        const { direct, fallback } = this.tryPidFileMatching(processes);
+        // Step 1: extract `--resume <id>` from command line — authoritative for
+        // resumed sessions where the JSONL predates the process and PID-file/
+        // birthtime heuristics can't match it.
+        const { direct: resumeDirect, fallback: noResume } = this.tryResumeMatching(processes);
+
+        // Step 2: try authoritative PID-file matching for the rest
+        const { direct: pidDirect, fallback } = this.tryPidFileMatching(noResume);
 
-        // Step 2: run legacy CWD+birthtime matching only for processes without a PID file
+        const direct = [...resumeDirect, ...pidDirect];
+
+        // Step 3: 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
@@ -98,11 +120,15 @@ export class ClaudeCodeAdapter implements AgentAdapter {
 
         const agents: AgentInfo[] = [];
 
-        // Build agents from direct (PID-file) matches
-        for (const { process: proc, sessionFile } of direct) {
+        // Build agents from direct (resume + PID-file) matches
+        for (const match of direct) {
+            const { process: proc, sessionFile } = match;
             const sessionData = this.parser.readSession(sessionFile.filePath, sessionFile.resolvedCwd);
             if (sessionData) {
-                agents.push(this.mapSessionToAgent(sessionData, proc, sessionFile));
+                agents.push(this.mapSessionToAgent(sessionData, proc, sessionFile, {
+                    pidStatus: match.pidStatus,
+                    waitingFor: match.waitingFor,
+                }));
             } else {
                 matchedPids.delete(proc.pid);
             }
@@ -167,6 +193,111 @@ export class ClaudeCodeAdapter implements AgentAdapter {
         return files;
     }
 
+    /**
+     * Match processes via `claude --resume <uuid>` in their command line.
+     * This works for resumed sessions, where the JSONL was created earlier
+     * (so its birthtime is far from the process startTime and the legacy
+     * matcher can't pair them) and the PID file may also be misaligned.
+     */
+    private tryResumeMatching(processes: ProcessInfo[]): {
+        direct: DirectMatch[];
+        fallback: ProcessInfo[];
+    } {
+        const direct: DirectMatch[] = [];
+        const fallback: ProcessInfo[] = [];
+
+        for (const proc of processes) {
+            const sessionId = this.extractResumeSessionId(proc.command);
+            if (!sessionId || !proc.cwd) {
+                fallback.push(proc);
+                continue;
+            }
+
+            const projectDir = this.getProjectDir(proc.cwd);
+            const jsonlPath = path.join(projectDir, `${sessionId}.jsonl`);
+
+            const stat = safeStat(jsonlPath);
+            if (!stat) {
+                fallback.push(proc);
+                continue;
+            }
+
+            // Best-effort: the PID file (if present for this proc) is the
+            // authoritative source of live status. We still match the session
+            // via --resume, but we read the PID file alongside to capture
+            // status/waitingFor.
+            const pidEntry = this.readMatchingPidFile(proc.pid, proc.startTime);
+
+            direct.push({
+                process: proc,
+                sessionFile: {
+                    sessionId,
+                    filePath: jsonlPath,
+                    projectDir,
+                    birthtimeMs: stat.birthtimeMs,
+                    resolvedCwd: proc.cwd,
+                },
+                pidStatus: this.mapPidStatus(pidEntry?.status),
+                waitingFor: pidEntry?.waitingFor,
+            });
+        }
+
+        return { direct, fallback };
+    }
+
+    private extractResumeSessionId(command: string): string | null {
+        const match = command.match(/--resume\s+([0-9a-f-]{36})/i);
+        return match?.[1] ?? null;
+    }
+
+    /**
+     * Read and parse ~/.claude/sessions/<pid>.json, returning null on any
+     * I/O / parse failure or when the file is stale relative to the live
+     * process.
+     *
+     * "Stale" means the PID file's startedAt diverges from the process's
+     * start time by more than {@link PID_FILE_STALENESS_MS} — typically
+     * a previous Claude Code process recycled the same PID without cleanup.
+     */
+    private readMatchingPidFile(pid: number, procStartTime?: Date): PidFileEntry | null {
+        const pidFilePath = path.join(this.sessionsDir, `${pid}.json`);
+        try {
+            const entry = JSON.parse(
+                fs.readFileSync(pidFilePath, 'utf-8'),
+            ) as PidFileEntry;
+
+            if (procStartTime) {
+                const deltaMs = Math.abs(procStartTime.getTime() - entry.startedAt);
+                if (deltaMs > PID_FILE_STALENESS_MS) {
+                    return null;
+                }
+            }
+
+            return entry;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Map the PID file's live status string to {@link AgentStatus}.
+     *
+     * Returns undefined for missing / unrecognized values so the caller
+     * can fall back to JSONL-derived heuristics.
+     */
+    private mapPidStatus(status: string | undefined): AgentStatus | undefined {
+        switch (status) {
+            case 'running':
+                return AgentStatus.RUNNING;
+            case 'waiting':
+                return AgentStatus.WAITING;
+            case 'idle':
+                return AgentStatus.IDLE;
+            default:
+                return undefined;
+        }
+    }
+
     /**
      * Attempt to match each process to its session via ~/.claude/sessions/<pid>.json.
      *
@@ -185,43 +316,32 @@ export class ClaudeCodeAdapter implements AgentAdapter {
         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 > PID_FILE_STALENESS_MS) {
-                        fallback.push(proc);
-                        continue;
-                    }
-                }
+            const entry = this.readMatchingPidFile(proc.pid, proc.startTime);
+            if (!entry) {
+                fallback.push(proc);
+                continue;
+            }
 
-                const projectDir = this.getProjectDir(entry.cwd);
-                const jsonlPath = path.join(projectDir, `${entry.sessionId}.jsonl`);
+            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
+            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,
+                },
+                pidStatus: this.mapPidStatus(entry.status),
+                waitingFor: entry.waitingFor,
+            });
         }
 
         return { direct, fallback };
@@ -230,11 +350,18 @@ export class ClaudeCodeAdapter implements AgentAdapter {
     /**
      * 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/
+     * Claude Code encodes paths by replacing every non-alphanumeric
+     * character with '-', so '/', '_', '.', spaces, etc. all collapse:
+     *   /Users/foo/bar          → -Users-foo-bar
+     *   /Users/foo/my_project   → -Users-foo-my-project
+     *   /Users/foo/.worktrees/x → -Users-foo--worktrees-x
+     *
+     * The encoding is lossy — multiple real paths can collide on the
+     * same encoded dir. Callers that need to disambiguate must read the
+     * `cwd` field inside each session JSONL.
      */
     private getProjectDir(cwd: string): string {
-        const encoded = cwd.replace(/\//g, '-');
+        const encoded = cwd.replace(/[^a-zA-Z0-9]/g, '-');
         return path.join(this.projectsDir, encoded);
     }
 
@@ -242,12 +369,22 @@ export class ClaudeCodeAdapter implements AgentAdapter {
         session: ClaudeSession,
         processInfo: ProcessInfo,
         sessionFile: SessionFile,
+        liveInfo?: { pidStatus?: AgentStatus; waitingFor?: string },
     ): AgentInfo {
+        // Live PID-file status is authoritative when present — JSONL-derived
+        // status mis-classifies sessions whose latest entry is a UI-state
+        // event like `permission-mode` or `ai-title`.
+        const status = liveInfo?.pidStatus ?? this.parser.determineStatus(session);
+        const baseSummary = session.lastUserMessage || 'Session started';
+        const summary = status === AgentStatus.WAITING && liveInfo?.waitingFor
+            ? `${baseSummary} — waiting for ${liveInfo.waitingFor}`
+            : baseSummary;
+
         return {
             name: generateAgentName(processInfo.cwd, processInfo.pid),
             type: this.type,
-            status: this.parser.determineStatus(session),
-            summary: session.lastUserMessage || 'Session started',
+            status,
+            summary,
             pid: processInfo.pid,
             projectPath: sessionFile.resolvedCwd || processInfo.cwd || '',
             sessionId: sessionFile.sessionId,

package/src/adapters/OpenCodeAdapter.ts

@@ -0,0 +1,340 @@
+/**
+ * OpenCode Adapter
+ *
+ * Detects running OpenCode agents by:
+ * 1. Finding running opencode processes via shared listAgentProcesses()
+ * 2. Enriching with CWD and start times via shared enrichProcesses()
+ * 3. Querying OpenCode's SQLite DB (~/.local/share/opencode/opencode.db) to
+ *    find the session matching each process's CWD and read status from message.time.completed
+ *
+ * sessionFilePath encodes "<dbPath>::<sessionId>" so getConversation() can open the right
+ * DB row without extending the AgentAdapter interface.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import Database from 'better-sqlite3';
+import type {
+    AgentAdapter,
+    AgentInfo,
+    ProcessInfo,
+    ConversationMessage,
+    SessionSummary,
+    ListSessionsOptions,
+} from './AgentAdapter';
+import { AgentStatus } from './AgentAdapter';
+import { listAgentProcesses, enrichProcesses } from '../utils/process';
+import { generateAgentName } from '../utils/matching';
+
+const SESSION_REF_SEP = '::';
+
+function encodeSessionRef(dbPath: string, sessionId: string): string {
+    return `${dbPath}${SESSION_REF_SEP}${sessionId}`;
+}
+
+function decodeSessionRef(ref: string): { dbPath: string; sessionId: string } | null {
+    const idx = ref.lastIndexOf(SESSION_REF_SEP);
+    if (idx === -1) return null;
+    return { dbPath: ref.slice(0, idx), sessionId: ref.slice(idx + SESSION_REF_SEP.length) };
+}
+
+interface OpenCodeSession {
+    sessionId: string;
+    directory: string;
+    timeCreated: number;
+}
+
+interface OpenCodeSessionStats {
+    lastRole: string | null;
+    lastTimeUpdated: number;
+    /** OpenCode writes `time.completed` on the assistant message only when the turn finishes. */
+    lastAssistantCompleted: boolean;
+    lastAssistantErrored: boolean;
+    summary: string;
+}
+
+export class OpenCodeAdapter implements AgentAdapter {
+    readonly type = 'opencode' as const;
+
+    private static readonly IDLE_THRESHOLD_MINUTES = 5;
+
+    private readonly dbPath: string;
+    private db: Database.Database | null = null;
+
+    constructor() {
+        this.dbPath = OpenCodeAdapter.resolveDbPath();
+        const cleanup = (): void => this.close();
+        process.once('exit', cleanup);
+        process.once('SIGINT', cleanup);
+        process.once('SIGTERM', cleanup);
+    }
+
+    close(): void {
+        if (this.db) {
+            try { this.db.close(); } catch { /* ignore */ }
+            this.db = null;
+        }
+    }
+
+    private static resolveDbPath(): string {
+        const xdg = process.env.XDG_DATA_HOME;
+        const home = process.env.HOME || process.env.USERPROFILE || '';
+        const base = xdg || path.join(home, '.local', 'share');
+        return path.join(base, 'opencode', 'opencode.db');
+    }
+
+    canHandle(processInfo: ProcessInfo): boolean {
+        const exe = (processInfo.command.trim().split(/\s+/)[0] || '').toLowerCase();
+        const base = path.basename(exe);
+        return base === 'opencode' || base === 'opencode.exe';
+    }
+
+    async detectAgents(): Promise<AgentInfo[]> {
+        const processes = enrichProcesses(listAgentProcesses('opencode'));
+        if (processes.length === 0) return [];
+
+        const db = this.openDb();
+        if (!db) return processes.map((p) => this.mapProcessOnlyAgent(p));
+
+        const agents: AgentInfo[] = [];
+        for (const proc of processes) {
+            if (!proc.cwd) {
+                agents.push(this.mapProcessOnlyAgent(proc));
+                continue;
+            }
+
+            const session = this.findSessionForDirectory(db, proc.cwd);
+            if (!session) {
+                agents.push(this.mapProcessOnlyAgent(proc));
+                continue;
+            }
+
+            const stats = this.getSessionStats(db, session.sessionId);
+            agents.push(this.mapSessionToAgent(session, stats, proc));
+        }
+
+        return agents;
+    }
+
+    getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+        const verbose = options?.verbose ?? false;
+        const ref = decodeSessionRef(sessionFilePath);
+        if (!ref) return [];
+
+        const db = this.openDb();
+        if (!db) return [];
+
+        try {
+            const rows = db.prepare<[string], { role: string; partData: string; timeCreated: number }>(`
+                SELECT json_extract(m.data, '$.role') AS role,
+                       p.data AS partData,
+                       p.time_created AS timeCreated
+                FROM part p
+                JOIN message m ON p.message_id = m.id
+                WHERE p.session_id = ?
+                ORDER BY p.time_created ASC
+            `).all(ref.sessionId);
+
+            const messages: ConversationMessage[] = [];
+
+            for (const row of rows) {
+                let partData: { type?: string; text?: string; reasoning?: string; tool?: string } = {};
+                try {
+                    partData = JSON.parse(row.partData);
+                } catch {
+                    continue;
+                }
+
+                const role = row.role === 'user' ? 'user' : 'assistant';
+
+                if (partData.type === 'text' && partData.text) {
+                    messages.push({ role, content: partData.text });
+                } else if (partData.type === 'reasoning' && verbose) {
+                    const text = partData.reasoning || partData.text || '';
+                    if (text) messages.push({ role: 'assistant', content: `[thinking] ${text}` });
+                } else if (partData.type === 'tool' && verbose) {
+                    const toolName = partData.tool || 'tool';
+                    messages.push({ role: 'assistant', content: `[tool: ${toolName}]` });
+                }
+            }
+
+            return messages;
+        } catch {
+            this.close();
+            return [];
+        }
+    }
+
+    async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+        const db = this.openDb();
+        if (!db) return [];
+
+        try {
+            const rows = db.prepare<[], { id: string; directory: string; timeCreated: number }>(`
+                SELECT id, directory, time_created AS timeCreated
+                FROM session
+                ORDER BY time_created DESC
+            `).all();
+
+            const summaries: SessionSummary[] = [];
+
+            for (const row of rows) {
+                if (opts?.cwd !== undefined && row.directory !== opts.cwd) continue;
+
+                const stats = this.getSessionStats(db, row.id);
+                const lastActive = stats.lastTimeUpdated > 0
+                    ? new Date(stats.lastTimeUpdated)
+                    : new Date(row.timeCreated);
+                const startedAt = new Date(row.timeCreated);
+
+                summaries.push({
+                    type: 'opencode',
+                    sessionId: row.id,
+                    cwd: row.directory,
+                    firstUserMessage: stats.summary,
+                    lastActive,
+                    startedAt,
+                    sessionFilePath: encodeSessionRef(this.dbPath, row.id),
+                });
+            }
+
+            return summaries;
+        } catch {
+            this.close();
+            return [];
+        }
+    }
+
+    private findSessionForDirectory(db: Database.Database, directory: string): OpenCodeSession | null {
+        try {
+            const row = db.prepare<[string], { id: string; directory: string; time_created: number }>(`
+                SELECT id, directory, time_created
+                FROM session
+                WHERE directory = ?
+                ORDER BY time_created DESC
+                LIMIT 1
+            `).get(directory);
+
+            if (!row) return null;
+            return { sessionId: row.id, directory: row.directory, timeCreated: row.time_created };
+        } catch {
+            return null;
+        }
+    }
+
+    private getSessionStats(db: Database.Database, sessionId: string): OpenCodeSessionStats {
+        const empty: OpenCodeSessionStats = {
+            lastRole: null,
+            lastTimeUpdated: 0,
+            lastAssistantCompleted: false,
+            lastAssistantErrored: false,
+            summary: '',
+        };
+
+        try {
+            // Order by time_created — time_updated can lag when OpenCode appends
+            // metadata (e.g. summary diffs) to user messages after a turn finishes.
+            const last = db.prepare<[string], { role: string; timeUpdated: number }>(`
+                SELECT json_extract(data, '$.role') AS role,
+                       time_updated AS timeUpdated
+                FROM message
+                WHERE session_id = ?
+                ORDER BY time_created DESC
+                LIMIT 1
+            `).get(sessionId);
+
+            const heartbeat = db.prepare<[string], { maxUpdated: number }>(`
+                SELECT MAX(time_updated) AS maxUpdated FROM message WHERE session_id = ?
+            `).get(sessionId);
+
+            const lastAssistant = db.prepare<[string], {
+                completed: number | null;
+                errored: number | null;
+            }>(`
+                SELECT json_extract(data, '$.time.completed') AS completed,
+                       json_extract(data, '$.time.error') AS errored
+                FROM message
+                WHERE session_id = ? AND json_extract(data, '$.role') = 'assistant'
+                ORDER BY time_created DESC
+                LIMIT 1
+            `).get(sessionId);
+
+            const first = db.prepare<[string], { text: string }>(`
+                SELECT json_extract(p.data, '$.text') AS text
+                FROM part p
+                JOIN message m ON p.message_id = m.id
+                WHERE p.session_id = ?
+                  AND json_extract(m.data, '$.role') = 'user'
+                  AND json_extract(p.data, '$.type') = 'text'
+                  AND json_extract(p.data, '$.text') IS NOT NULL
+                ORDER BY p.time_created ASC
+                LIMIT 1
+            `).get(sessionId);
+
+            return {
+                lastRole: last?.role ?? null,
+                lastTimeUpdated: heartbeat?.maxUpdated ?? last?.timeUpdated ?? 0,
+                lastAssistantCompleted: lastAssistant?.completed != null,
+                lastAssistantErrored: lastAssistant?.errored != null,
+                summary: first?.text?.trim() ?? '',
+            };
+        } catch {
+            return empty;
+        }
+    }
+
+    private mapSessionToAgent(
+        session: OpenCodeSession,
+        stats: OpenCodeSessionStats,
+        proc: ProcessInfo,
+    ): AgentInfo {
+        const lastActive = stats.lastTimeUpdated > 0
+            ? new Date(stats.lastTimeUpdated)
+            : new Date(session.timeCreated);
+
+        return {
+            name: generateAgentName(session.directory || proc.cwd || '', proc.pid),
+            type: this.type,
+            status: this.determineStatus(stats, lastActive),
+            summary: stats.summary || 'OpenCode session active',
+            pid: proc.pid,
+            projectPath: session.directory || proc.cwd || '',
+            sessionId: session.sessionId,
+            lastActive,
+            sessionFilePath: encodeSessionRef(this.dbPath, session.sessionId),
+        };
+    }
+
+    private mapProcessOnlyAgent(proc: ProcessInfo): AgentInfo {
+        return {
+            name: generateAgentName(proc.cwd || '', proc.pid),
+            type: this.type,
+            status: AgentStatus.RUNNING,
+            summary: 'OpenCode process running',
+            pid: proc.pid,
+            projectPath: proc.cwd || '',
+            sessionId: `pid-${proc.pid}`,
+            lastActive: new Date(),
+        };
+    }
+
+    private determineStatus(stats: OpenCodeSessionStats, lastActive: Date): AgentStatus {
+        const ageMin = (Date.now() - lastActive.getTime()) / 60000;
+        if (ageMin > OpenCodeAdapter.IDLE_THRESHOLD_MINUTES) return AgentStatus.IDLE;
+
+        if (stats.lastRole === 'assistant' && !stats.lastAssistantCompleted) return AgentStatus.RUNNING;
+        if (stats.lastRole === 'assistant') return AgentStatus.WAITING;
+        return AgentStatus.RUNNING;
+    }
+
+    private openDb(): Database.Database | null {
+        if (this.db) return this.db;
+        if (!fs.existsSync(this.dbPath)) return null;
+        try {
+            this.db = new Database(this.dbPath, { readonly: true });
+            return this.db;
+        } catch {
+            return null;
+        }
+    }
+}

package/src/adapters/index.ts

@@ -1,5 +1,6 @@
 export { ClaudeCodeAdapter } from './ClaudeCodeAdapter';
 export { CodexAdapter } from './CodexAdapter';
 export { GeminiCliAdapter } from './GeminiCliAdapter';
+export { OpenCodeAdapter } from './OpenCodeAdapter';
 export { AgentStatus } from './AgentAdapter';
 export type { AgentAdapter, AgentType, AgentInfo, ProcessInfo } from './AgentAdapter';

package/src/index.ts

@@ -3,6 +3,7 @@ export { AgentManager } from './AgentManager';
 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 type {
     AgentAdapter,