@ai-devkit/agent-manager 0.22.1 → 0.25.0

package/src/adapters/GrokCliAdapter.ts

@@ -0,0 +1,394 @@
+import * as path from 'path';
+import type {
+    AgentAdapter,
+    AgentInfo,
+    ProcessInfo,
+    ConversationMessage,
+    SessionSummary,
+    ListSessionsOptions,
+} from './AgentAdapter.js';
+import { AgentStatus } from './AgentAdapter.js';
+import { listAgentProcesses, enrichProcesses } from '../utils/process.js';
+import { isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session.js';
+import { generateAgentName } from '../utils/matching.js';
+
+/**
+ * Grok Build CLI Adapter
+ *
+ * Detects running Grok Build CLI agents by:
+ * 1. Finding running `grok` processes via shared listAgentProcesses() — Grok is
+ *    a native binary at ~/.grok/bin/grok, so argv[0] basename is `grok`.
+ * 2. Resolving each live process to its working directory via
+ *    ~/.grok/active_sessions.json, which Grok maintains as a list of
+ *    { pid, cwd, opened_at } for every running session. The cwd is then encoded
+ *    into the session group dir ~/.grok/sessions/<encodeURIComponent(cwd)>/, and
+ *    the most recently active session subdirectory is picked from it. The
+ *    process cwd from lsof is only a fallback when the PID is not registered.
+ * 3. Reading the session transcript from chat_history.jsonl (the authoritative
+ *    record of the conversation). The last user turn (the text inside
+ *    <user_query>...</user_query>) is the summary; the file's mtime is the last
+ *    activity time. summary.json / updates.jsonl are intentionally not used.
+ */
+
+const CHAT_HISTORY_FILE = 'chat_history.jsonl';
+const ACTIVE_SESSIONS_FILE = 'active_sessions.json';
+const CWD_FILE = '.cwd';
+const IDLE_THRESHOLD_MINUTES = 5;
+
+/** One entry of ~/.grok/active_sessions.json. */
+interface ActiveSessionEntry {
+    pid?: number;
+    cwd?: string;
+    opened_at?: number | string;
+}
+
+/** One line of chat_history.jsonl. */
+interface ChatRecord {
+    type?: string;
+    content?: unknown;
+}
+
+interface ChatScan {
+    messages: ConversationMessage[];
+    firstUserMessage?: string;
+    lastUserMessage?: string;
+    lastRole?: ConversationMessage['role'];
+}
+
+/** Parsed state for a single ~/.grok/sessions/<cwd>/<id>/ directory. */
+interface GrokSession {
+    sessionId: string;
+    projectPath: string;
+    summary: string;
+    sessionStart: Date;
+    lastActive: Date;
+    firstUserMessage?: string;
+    lastUserMessage?: string;
+    lastRole?: ConversationMessage['role'];
+}
+
+export class GrokCliAdapter implements AgentAdapter {
+    readonly type = 'grok_cli' as const;
+
+    private base: string;
+    private sessionsDir: string;
+
+    constructor() {
+        // GROK_HOME overrides the ~/.grok base directory; sessions live under
+        // <base>/sessions/ and the active-session registry at
+        // <base>/active_sessions.json.
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        this.base = process.env.GROK_HOME || path.join(homeDir, '.grok');
+        this.sessionsDir = path.join(this.base, 'sessions');
+    }
+
+    canHandle(processInfo: ProcessInfo): boolean {
+        return this.isGrokExecutable(processInfo.command);
+    }
+
+    private isGrokExecutable(command: string): boolean {
+        const executable = command.trim().split(/\s+/)[0] || '';
+        const base = path.basename(executable).toLowerCase();
+        return base === 'grok' || base === 'grok.exe';
+    }
+
+    async detectAgents(): Promise<AgentInfo[]> {
+        const processes = enrichProcesses(listAgentProcesses('grok'));
+        if (processes.length === 0) {
+            return [];
+        }
+
+        // active_sessions.json is the authoritative pid -> cwd map for live
+        // sessions; the lsof-derived process cwd is only a fallback.
+        const pidToCwd = this.readActiveSessions();
+
+        const agents: AgentInfo[] = [];
+        for (const proc of processes) {
+            const cwd = pidToCwd.get(proc.pid) || proc.cwd || '';
+            const sessionDir = cwd ? this.latestSessionDir(cwd) : null;
+            const session = sessionDir ? this.readSession(sessionDir, cwd) : null;
+
+            if (session && sessionDir) {
+                agents.push(this.mapSessionToAgent(session, proc, sessionDir));
+            } else {
+                agents.push(this.mapProcessOnlyAgent(proc, cwd));
+            }
+        }
+
+        return agents;
+    }
+
+    /**
+     * Read ~/.grok/active_sessions.json into a pid -> cwd map. Grok writes one
+     * { pid, cwd, opened_at } entry per running session and removes it on exit,
+     * so this is the reliable way to learn a live process's working directory.
+     */
+    private readActiveSessions(): Map<number, string> {
+        const map = new Map<number, string>();
+        const content = safeReadFile(path.join(this.base, ACTIVE_SESSIONS_FILE));
+        if (content === undefined) return map;
+
+        let entries: unknown;
+        try {
+            entries = JSON.parse(content);
+        } catch {
+            return map;
+        }
+        if (!Array.isArray(entries)) return map;
+
+        for (const entry of entries as ActiveSessionEntry[]) {
+            if (typeof entry?.pid === 'number' && typeof entry?.cwd === 'string' && entry.cwd) {
+                map.set(entry.pid, entry.cwd);
+            }
+        }
+        return map;
+    }
+
+    /**
+     * Full paths of the session subdirectories directly under a group dir,
+     * skipping any non-directory entries. Shared by latestSessionDir() and
+     * listSessions() so both enumerate session dirs the same way.
+     */
+    private listSessionDirs(groupDir: string): string[] {
+        return safeReaddir(groupDir)
+            .map((sessionId) => path.join(groupDir, sessionId))
+            .filter((sessionDir) => isDirectory(sessionDir));
+    }
+
+    /**
+     * Return the most recently active session subdirectory for a cwd, i.e. the
+     * ~/.grok/sessions/<encodeURIComponent(cwd)>/<id>/ whose chat_history.jsonl
+     * was written last. Returns null when the group dir or any transcript is
+     * missing.
+     */
+    private latestSessionDir(cwd: string): string | null {
+        const groupDir = this.getProjectDir(cwd);
+        if (!isDirectory(groupDir)) return null;
+
+        let best: { dir: string; mtimeMs: number } | null = null;
+        for (const sessionDir of this.listSessionDirs(groupDir)) {
+            const stat = safeStat(path.join(sessionDir, CHAT_HISTORY_FILE));
+            if (!stat) continue;
+            if (!best || stat.mtimeMs > best.mtimeMs) {
+                best = { dir: sessionDir, mtimeMs: stat.mtimeMs };
+            }
+        }
+        return best?.dir ?? null;
+    }
+
+    private mapSessionToAgent(session: GrokSession, processInfo: ProcessInfo, sessionDir: string): AgentInfo {
+        const projectPath = session.projectPath || processInfo.cwd || '';
+        return {
+            name: generateAgentName(projectPath, processInfo.pid),
+            type: this.type,
+            status: this.determineStatus(session),
+            summary: session.summary || 'Grok CLI session active',
+            pid: processInfo.pid,
+            projectPath,
+            sessionId: session.sessionId,
+            lastActive: session.lastActive,
+            sessionFilePath: path.join(sessionDir, CHAT_HISTORY_FILE),
+        };
+    }
+
+    private mapProcessOnlyAgent(processInfo: ProcessInfo, cwd: string): AgentInfo {
+        const projectPath = cwd || processInfo.cwd || '';
+        return {
+            name: generateAgentName(projectPath, processInfo.pid),
+            type: this.type,
+            status: AgentStatus.RUNNING,
+            summary: 'Grok CLI process running',
+            pid: processInfo.pid,
+            projectPath,
+            sessionId: `pid-${processInfo.pid}`,
+            lastActive: new Date(),
+        };
+    }
+
+    getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+        return this.parseChatHistory(this.resolveChatPath(sessionFilePath), options?.verbose ?? false).messages;
+    }
+
+    async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+        if (!isDirectory(this.sessionsDir)) return [];
+
+        const filterCwd = opts?.cwd;
+        const summaries: SessionSummary[] = [];
+
+        for (const groupName of safeReaddir(this.sessionsDir)) {
+            const groupDir = path.join(this.sessionsDir, groupName);
+            if (!isDirectory(groupDir)) continue;
+
+            const decodedCwd = this.decodeGroupCwd(groupName, groupDir);
+
+            for (const sessionDir of this.listSessionDirs(groupDir)) {
+                const session = this.readSession(sessionDir, decodedCwd);
+                if (!session) continue;
+
+                const cwd = session.projectPath || decodedCwd;
+                if (filterCwd !== undefined && cwd !== filterCwd) continue;
+
+                summaries.push({
+                    type: this.type,
+                    sessionId: session.sessionId,
+                    cwd,
+                    firstUserMessage: session.firstUserMessage || '',
+                    lastActive: session.lastActive,
+                    startedAt: session.sessionStart,
+                    sessionFilePath: path.join(sessionDir, CHAT_HISTORY_FILE),
+                });
+            }
+        }
+
+        return summaries;
+    }
+
+    // --- Session parsing (chat_history.jsonl) ---
+
+    /**
+     * Parse a session directory into a {@link GrokSession} from its
+     * chat_history.jsonl transcript. Returns null when the transcript is
+     * missing — i.e. there is no real session to surface.
+     */
+    private readSession(sessionDir: string, defaultCwd: string): GrokSession | null {
+        const chatPath = path.join(sessionDir, CHAT_HISTORY_FILE);
+        const chatStat = safeStat(chatPath);
+        if (!chatStat) return null;
+
+        const scan = this.parseChatHistory(chatPath, false);
+        const dirStat = safeStat(sessionDir);
+        const lastActive = chatStat.mtime;
+
+        return {
+            sessionId: path.basename(sessionDir),
+            projectPath: defaultCwd || '',
+            summary: scan.lastUserMessage || 'Grok CLI session active',
+            sessionStart: dirStat?.birthtime || lastActive,
+            lastActive,
+            firstUserMessage: scan.firstUserMessage,
+            lastUserMessage: scan.lastUserMessage,
+            lastRole: scan.lastRole,
+        };
+    }
+
+    /**
+     * Determine agent status from parsed session state.
+     *
+     * - past the idle threshold → IDLE
+     * - last transcript turn is an assistant message → WAITING (awaiting user)
+     * - otherwise (last turn was a user message, or unknown) → RUNNING
+     */
+    private determineStatus(session: GrokSession): AgentStatus {
+        const diffMinutes = (Date.now() - session.lastActive.getTime()) / 60000;
+        if (diffMinutes > IDLE_THRESHOLD_MINUTES) {
+            return AgentStatus.IDLE;
+        }
+        if (session.lastRole === 'assistant') {
+            return AgentStatus.WAITING;
+        }
+        return AgentStatus.RUNNING;
+    }
+
+    /**
+     * Single pass over chat_history.jsonl. Each line is a
+     * { type: 'system' | 'user' | 'assistant', content } record where content is
+     * either a string or an array of { type: 'text', text } blocks.
+     *
+     * Grok wraps the real user prompt in <user_query>...</user_query>; the other
+     * user records are context injections (<user_info>, <system-reminder>, ...)
+     * and are skipped so the summary is the actual prompt, not boilerplate.
+     */
+    private parseChatHistory(chatPath: string, verbose: boolean): ChatScan {
+        const empty: ChatScan = { messages: [] };
+        const content = safeReadFile(chatPath);
+        if (content === undefined) return empty;
+
+        const messages: ConversationMessage[] = [];
+        let lastRole: ConversationMessage['role'] | undefined;
+
+        for (const line of content.trim().split('\n')) {
+            if (!line.trim()) continue;
+
+            let record: ChatRecord;
+            try {
+                record = JSON.parse(line);
+            } catch {
+                continue;
+            }
+
+            const text = this.extractText(record.content);
+            if (record.type === 'user') {
+                const query = this.extractUserQuery(text);
+                if (query === null) continue; // context injection, not a real prompt
+                messages.push({ role: 'user', content: query });
+                lastRole = 'user';
+            } else if (record.type === 'assistant') {
+                if (!text) continue;
+                messages.push({ role: 'assistant', content: text });
+                lastRole = 'assistant';
+            } else if (verbose && record.type === 'system') {
+                if (!text) continue;
+                messages.push({ role: 'system', content: text });
+            }
+        }
+
+        const userTurns = messages.filter((m) => m.role === 'user');
+        return {
+            messages,
+            firstUserMessage: userTurns[0]?.content,
+            lastUserMessage: userTurns[userTurns.length - 1]?.content,
+            lastRole,
+        };
+    }
+
+    /** Flatten a chat record's content (string or text-block array) to text. */
+    private extractText(content: unknown): string {
+        if (typeof content === 'string') return content;
+        if (Array.isArray(content)) {
+            return content
+                .map((block) =>
+                    block && typeof block === 'object' && typeof (block as { text?: unknown }).text === 'string'
+                        ? (block as { text: string }).text
+                        : '',
+                )
+                .join('');
+        }
+        return '';
+    }
+
+    /**
+     * Extract the prompt inside <user_query>...</user_query>. Returns null when
+     * the record has no such tag (a context injection rather than a prompt).
+     */
+    private extractUserQuery(text: string): string | null {
+        const match = text.match(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/);
+        return match ? match[1].trim() : null;
+    }
+
+    /** Resolve a session dir or an explicit chat_history.jsonl path to the file. */
+    private resolveChatPath(sessionPath: string): string {
+        return sessionPath.endsWith('.jsonl') ? sessionPath : path.join(sessionPath, CHAT_HISTORY_FILE);
+    }
+
+    private getProjectDir(cwd: string): string {
+        return path.join(this.sessionsDir, encodeURIComponent(cwd));
+    }
+
+    /**
+     * Resolve the working directory a session group dir was created for.
+     *
+     * The common case is `decodeURIComponent(<group-name>)`. For paths whose
+     * encoded form exceeds the filesystem limit Grok uses a slug+hash and records
+     * the original path in a `.cwd` file inside the group — prefer that when
+     * present.
+     */
+    private decodeGroupCwd(groupName: string, groupDir: string): string {
+        const fromFile = safeReadFile(path.join(groupDir, CWD_FILE));
+        if (fromFile !== undefined && fromFile.trim()) return fromFile.trim();
+        try {
+            return decodeURIComponent(groupName);
+        } catch {
+            return '';
+        }
+    }
+}

package/src/adapters/index.ts

@@ -2,6 +2,7 @@ export { ClaudeCodeAdapter } from './ClaudeCodeAdapter.js';
 export { CodexAdapter } from './CodexAdapter.js';
 export { CopilotAdapter } from './CopilotAdapter.js';
 export { GeminiCliAdapter } from './GeminiCliAdapter.js';
+export { GrokCliAdapter } from './GrokCliAdapter.js';
 export { OpenCodeAdapter } from './OpenCodeAdapter.js';
 export { PiAdapter } from './PiAdapter.js';
 export { AgentStatus } from './AgentAdapter.js';

package/src/index.ts

@@ -4,6 +4,7 @@ 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 { GrokCliAdapter } from './adapters/GrokCliAdapter.js';
 export { OpenCodeAdapter } from './adapters/OpenCodeAdapter.js';
 export { PiAdapter } from './adapters/PiAdapter.js';
 export { AgentStatus } from './adapters/AgentAdapter.js';
@@ -30,3 +31,6 @@ 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';
+
+export type { AgentRequest } from './utils/agent-requests.js';
+export { getAgentRequestPath, readLatestAgentRequest, writeAgentRequest } from './utils/agent-requests.js';

package/src/terminal/TerminalFocusManager.ts

@@ -7,6 +7,7 @@ const execFileAsync = promisify(execFile);
 
 export enum TerminalType {
     TMUX = 'tmux',
+    WEZTERM = 'wezterm',
     ITERM2 = 'iterm2',
     TERMINAL_APP = 'terminal-app',
     UNKNOWN = 'unknown',
@@ -14,11 +15,31 @@ export enum TerminalType {
 
 export interface TerminalLocation {
     type: TerminalType;
-    identifier: string; // e.g., "session:window.pane" for tmux, or TTY for others
+    identifier: string; // e.g., "session:window.pane" for tmux, WezTerm pane id, or TTY for others
     tty: string;        // e.g., "/dev/ttys030"
 }
 
+/**
+ * Subset of a `wezterm cli list --format json` entry. Only `pane_id` and
+ * `tty_name` are read; extra fields are ignored so schema additions across
+ * WezTerm versions don't break parsing. (The TTY is exposed as `tty_name` in
+ * the JSON, not `tty`.)
+ */
+interface WeztermPaneEntry {
+    pane_id?: number;
+    tty_name?: string | null;
+}
+
+/**
+ * Optional trace sink. When provided to {@link TerminalFocusManager}, each
+ * discovery/focus step reports a human-readable line so callers (e.g. the
+ * `agent open --debug` command) can inspect the matching/focus decision path.
+ */
+export type TerminalDebugLogger = (message: string) => void;
+
 export class TerminalFocusManager {
+    constructor(private readonly debug?: TerminalDebugLogger) {}
+
     /**
      * Find the terminal location (emulator info) for a given process ID
      */
@@ -27,24 +48,47 @@ export class TerminalFocusManager {
 
         // If no TTY or invalid, we can't find the terminal
         if (!ttyShort || ttyShort === '?') {
+            this.debug?.(`findTerminal(pid=${pid}): no usable TTY, cannot resolve terminal`);
             return null;
         }
 
         const fullTty = `/dev/${ttyShort}`;
+        this.debug?.(`findTerminal(pid=${pid}): resolving terminal for ${fullTty}`);
 
         // 1. Check tmux (most specific if running inside it)
         const tmuxLocation = await this.findTmuxPane(fullTty);
-        if (tmuxLocation) return tmuxLocation;
+        if (tmuxLocation) {
+            this.debug?.(`findTerminal: matched tmux (identifier=${tmuxLocation.identifier})`);
+            return tmuxLocation;
+        }
+        this.debug?.('findTerminal: tmux no match');
+
+        // 2. Check WezTerm (cross-platform, via its CLI — no AppleScript)
+        const weztermLocation = await this.findWeztermPane(fullTty);
+        if (weztermLocation) {
+            this.debug?.(`findTerminal: matched wezterm (pane_id=${weztermLocation.identifier})`);
+            return weztermLocation;
+        }
+        this.debug?.('findTerminal: wezterm no match');
 
-        // 2. Check iTerm2
+        // 3. Check iTerm2
         const itermLocation = await this.findITerm2Session(fullTty);
-        if (itermLocation) return itermLocation;
+        if (itermLocation) {
+            this.debug?.(`findTerminal: matched iTerm2 (tty=${itermLocation.tty})`);
+            return itermLocation;
+        }
+        this.debug?.('findTerminal: iTerm2 no match');
 
-        // 3. Check Terminal.app
+        // 4. Check Terminal.app
         const terminalAppLocation = await this.findTerminalAppWindow(fullTty);
-        if (terminalAppLocation) return terminalAppLocation;
+        if (terminalAppLocation) {
+            this.debug?.(`findTerminal: matched Terminal.app (tty=${terminalAppLocation.tty})`);
+            return terminalAppLocation;
+        }
+        this.debug?.('findTerminal: Terminal.app no match');
 
-        // 4. Fallback: we know the TTY but not the emulator wrapper
+        // 5. Fallback: we know the TTY but not the emulator wrapper
+        this.debug?.('findTerminal: no emulator matched; returning UNKNOWN');
         return {
             type: TerminalType.UNKNOWN,
             identifier: '',
@@ -56,17 +100,65 @@ export class TerminalFocusManager {
      * Focus the terminal identified by the location
      */
     async focusTerminal(location: TerminalLocation): Promise<boolean> {
+        this.debug?.(`focusTerminal: focusing ${location.type} (identifier=${location.identifier}, tty=${location.tty})`);
+        let success = false;
         try {
             switch (location.type) {
                 case TerminalType.TMUX:
-                    return await this.focusTmuxPane(location.identifier);
+                    success = await this.focusTmuxPane(location.identifier);
+                    break;
+                case TerminalType.WEZTERM:
+                    success = await this.focusWeztermPane(location.identifier);
+                    break;
                 case TerminalType.ITERM2:
-                    return await this.focusITerm2Session(location.tty);
+                    success = await this.focusITerm2Session(location.tty);
+                    break;
                 case TerminalType.TERMINAL_APP:
-                    return await this.focusTerminalAppWindow(location.tty);
+                    success = await this.focusTerminalAppWindow(location.tty);
+                    break;
                 default:
-                    return false;
+                    success = false;
+            }
+        } catch {
+            success = false;
+        }
+        this.debug?.(`focusTerminal: ${success ? 'succeeded' : 'failed'} for ${location.type}`);
+        return success;
+    }
+
+    private async findWeztermPane(tty: string): Promise<TerminalLocation | null> {
+        try {
+            const { stdout } = await execFileAsync('wezterm', [
+                'cli', 'list', '--format', 'json',
+            ]);
+
+            const panes = JSON.parse(stdout) as WeztermPaneEntry[];
+            if (!Array.isArray(panes)) return null;
+
+            for (const pane of panes) {
+                if (
+                    pane &&
+                    typeof pane.tty_name === 'string' &&
+                    pane.tty_name === tty &&
+                    pane.pane_id != null
+                ) {
+                    return {
+                        type: TerminalType.WEZTERM,
+                        identifier: String(pane.pane_id),
+                        tty,
+                    };
+                }
             }
+        } catch {
+            // wezterm not installed, not running, or returned invalid JSON
+        }
+        return null;
+    }
+
+    private async focusWeztermPane(paneId: string): Promise<boolean> {
+        try {
+            await execFileAsync('wezterm', ['cli', 'activate-pane', '--pane-id', paneId]);
+            return true;
         } catch {
             return false;
         }