@simonren/quorum 0.7.0

package/dist/decoders/codex.js

@@ -0,0 +1,145 @@
+/**
+ * CodexEventDecoder
+ *
+ * Parses JSONL streaming events emitted by `codex exec --json` on stdout.
+ * Extracts the final agent_message text and usage statistics.
+ *
+ * Event stream format:
+ *   {"type":"thread.started","thread_id":"..."}
+ *   {"type":"turn.started"}
+ *   {"type":"item.started","item":{...}}
+ *   {"type":"item.completed","item":{...}}
+ *   {"type":"turn.completed","usage":{...}}
+ */
+// =============================================================================
+// DECODER
+// =============================================================================
+export class CodexEventDecoder {
+    /**
+     * Optional callback invoked for every successfully parsed event.
+     * @param eventType - The `type` field of the event (e.g. "item.completed").
+     * @param detail    - A human-readable detail string for logging (may be undefined).
+     */
+    onProgress;
+    // The text from the most recently seen item.completed with item.type === "agent_message"
+    _finalResponse = null;
+    // Token usage from the most recently seen turn.completed
+    _usage = null;
+    // Error message from error/turn.failed events
+    _error = null;
+    // Count of events received (0 = possible rate limit / instant rejection)
+    _eventCount = 0;
+    // =============================================================================
+    // PUBLIC API
+    // =============================================================================
+    /**
+     * Parse a single JSONL line. Silently skips malformed or empty input.
+     */
+    processLine(line) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            return;
+        let event;
+        try {
+            const parsed = JSON.parse(trimmed);
+            // Must be a plain object, not an array or primitive
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+                return;
+            event = parsed;
+        }
+        catch {
+            // Malformed JSON — silently skip
+            return;
+        }
+        this._handleEvent(event);
+    }
+    /**
+     * Returns the text from the LAST `item.completed` event whose item type is
+     * `"agent_message"`, or `null` if no such event has been seen.
+     */
+    getFinalResponse() {
+        return this._finalResponse;
+    }
+    /**
+     * Returns the usage stats from the most recent `turn.completed` event, or
+     * `null` if no such event has been seen.
+     */
+    getUsage() {
+        return this._usage;
+    }
+    /**
+     * Returns the error message from `error` or `turn.failed` events, or `null`.
+     */
+    getError() {
+        return this._error;
+    }
+    /**
+     * Returns true if events were received but no agent_message was produced.
+     * Combined with a fast exit, this indicates rate limiting or instant rejection.
+     */
+    hasNoOutput() {
+        return this._eventCount > 0 && this._finalResponse === null;
+    }
+    // =============================================================================
+    // PRIVATE HELPERS
+    // =============================================================================
+    _handleEvent(event) {
+        this._eventCount++;
+        // Track the last agent_message text
+        if (event.type === 'item.completed' &&
+            event.item?.type === 'agent_message' &&
+            typeof event.item.text === 'string') {
+            this._finalResponse = event.item.text;
+        }
+        // Track usage from turn completion
+        if (event.type === 'turn.completed' && event.usage != null) {
+            this._usage = event.usage;
+        }
+        // Capture errors from error/turn.failed events
+        if (event.type === 'error') {
+            this._error = event.message || 'Unknown error from Codex';
+        }
+        if (event.type === 'turn.failed') {
+            this._error = event.error?.message || 'Turn failed';
+        }
+        // Capture error items (e.g. model errors reported as item.completed with type=error)
+        if (event.type === 'item.completed' && event.item?.type === 'error') {
+            this._error = event.item.message || event.item.text || 'Model error';
+        }
+        // Notify caller
+        this.onProgress?.(event.type, describeEvent(event));
+    }
+}
+// =============================================================================
+// INTERNAL HELPERS
+// =============================================================================
+/**
+ * Returns a short human-readable description of an event for progress logging.
+ * Returns `undefined` for event types that carry no meaningful extra detail.
+ */
+function describeEvent(event) {
+    if (event.type === 'thread.started' && event.thread_id) {
+        return `thread: ${event.thread_id}`;
+    }
+    if ((event.type === 'item.started' || event.type === 'item.completed') &&
+        event.item != null) {
+        const { type: itemType, command, status } = event.item;
+        if (itemType === 'command_execution') {
+            const parts = [];
+            if (command)
+                parts.push(`command: ${command}`);
+            if (status)
+                parts.push(`status: ${status}`);
+            return parts.length > 0 ? parts.join(', ') : undefined;
+        }
+        if (itemType === 'agent_message') {
+            return 'agent message';
+        }
+        return itemType;
+    }
+    if (event.type === 'turn.completed' && event.usage) {
+        const { input_tokens, output_tokens } = event.usage;
+        return `tokens: ${input_tokens} in / ${output_tokens} out`;
+    }
+    return undefined;
+}

package/dist/decoders/gemini.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GeminiEventDecoder — Parses Gemini CLI stream-json JSONL events.
+ *
+ * Concatenates assistant message deltas into a final response,
+ * tracks stats from the result event, and emits progress callbacks.
+ */
+export interface GeminiEvent {
+    type: string;
+    session_id?: string;
+    model?: string;
+    role?: string;
+    content?: string;
+    delta?: boolean;
+    tool_name?: string;
+    tool_id?: string;
+    status?: string;
+    stats?: {
+        total_tokens: number;
+        input_tokens: number;
+        output_tokens: number;
+        duration_ms: number;
+        [key: string]: unknown;
+    };
+}
+export declare class GeminiEventDecoder {
+    private assistantChunks;
+    private _stats;
+    onProgress?: (eventType: string, detail?: string) => void;
+    processLine(line: string): void;
+    getFinalResponse(): string;
+    getStats(): GeminiEvent['stats'] | null;
+    private describeEvent;
+}

package/dist/decoders/gemini.js

@@ -0,0 +1,58 @@
+/**
+ * GeminiEventDecoder — Parses Gemini CLI stream-json JSONL events.
+ *
+ * Concatenates assistant message deltas into a final response,
+ * tracks stats from the result event, and emits progress callbacks.
+ */
+export class GeminiEventDecoder {
+    assistantChunks = [];
+    _stats = null;
+    onProgress;
+    processLine(line) {
+        let event;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+                return;
+            event = parsed;
+        }
+        catch {
+            return;
+        }
+        if (!event.type)
+            return;
+        this.onProgress?.(event.type, this.describeEvent(event));
+        switch (event.type) {
+            case 'message':
+                if (event.role === 'assistant' && event.delta && event.content) {
+                    this.assistantChunks.push(event.content);
+                }
+                break;
+            case 'result':
+                if (event.stats) {
+                    this._stats = event.stats;
+                }
+                break;
+        }
+    }
+    getFinalResponse() {
+        return this.assistantChunks.join('');
+    }
+    getStats() {
+        return this._stats;
+    }
+    describeEvent(event) {
+        switch (event.type) {
+            case 'init':
+                return `model: ${event.model || 'unknown'}`;
+            case 'tool_use':
+                return `tool: ${event.tool_name || 'unknown'}`;
+            case 'tool_result':
+                return `status: ${event.status || 'unknown'}`;
+            case 'result':
+                return `status: ${event.status || 'unknown'}`;
+            default:
+                return '';
+        }
+    }
+}

package/dist/decoders/index.d.ts

@@ -0,0 +1,6 @@
+export { CodexEventDecoder } from './codex.js';
+export type { CodexEvent } from './codex.js';
+export { GeminiEventDecoder } from './gemini.js';
+export type { GeminiEvent } from './gemini.js';
+export { ClaudeEventDecoder } from './claude.js';
+export type { ClaudeEvent } from './claude.js';

package/dist/decoders/index.js

@@ -0,0 +1,3 @@
+export { CodexEventDecoder } from './codex.js';
+export { GeminiEventDecoder } from './gemini.js';
+export { ClaudeEventDecoder } from './claude.js';

package/dist/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Error Handling for AI Reviewer MCP Server
+ */
+import { FeedbackError, CliType } from './types.js';
+/**
+ * Create a CLI not found error
+ */
+export declare function createCliNotFoundError(cli: CliType): FeedbackError;
+/**
+ * Create a timeout error
+ */
+export declare function createTimeoutError(cli: CliType, durationMs: number): FeedbackError;
+/**
+ * Create a rate limit error
+ */
+export declare function createRateLimitError(cli: CliType, retryAfterMs?: number): FeedbackError;
+/**
+ * Create an auth error
+ */
+export declare function createAuthError(cli: CliType, message: string): FeedbackError;
+/**
+ * Create an invalid response error
+ */
+export declare function createInvalidResponseError(cli: CliType, rawOutput: string): FeedbackError;
+/**
+ * Create a CLI crash error
+ */
+export declare function createCliError(cli: CliType, exitCode: number, stderr: string): FeedbackError;
+/**
+ * Format an error for user display
+ */
+export declare function formatErrorForUser(error: FeedbackError): string;
+/**
+ * Detect error type from CLI output and error messages
+ */
+export declare function detectErrorType(cli: CliType, error: Error & {
+    code?: string;
+}, stdout: string, stderr: string, exitCode: number | null): FeedbackError;
+/**
+ * Parse retry-after from error response
+ */
+export declare function parseRetryAfter(errorMessage: string): number | undefined;
+/**
+ * Generate suggestion based on error type
+ */
+export declare function getSuggestion(error: FeedbackError): string | undefined;

package/dist/errors.js

@@ -0,0 +1,192 @@
+/**
+ * Error Handling for AI Reviewer MCP Server
+ */
+// CLI installation commands
+// Codex: https://developers.openai.com/codex/cli/
+// Gemini: https://github.com/google-gemini/gemini-cli
+const INSTALL_COMMANDS = {
+    codex: 'npm install -g @openai/codex-cli',
+    gemini: 'npm install -g @google/gemini-cli',
+    claude: 'https://docs.anthropic.com/en/docs/claude-code'
+};
+// Environment variables for API keys
+const ENV_VARS = {
+    codex: 'OPENAI_API_KEY',
+    gemini: 'GEMINI_API_KEY',
+    claude: 'ANTHROPIC_API_KEY'
+};
+// Authentication commands
+const AUTH_COMMANDS = {
+    codex: 'codex login',
+    gemini: 'gemini (follow prompts)',
+    claude: 'claude auth'
+};
+/**
+ * Create a CLI not found error
+ */
+export function createCliNotFoundError(cli) {
+    return {
+        type: 'cli_not_found',
+        cli,
+        installCmd: INSTALL_COMMANDS[cli]
+    };
+}
+/**
+ * Create a timeout error
+ */
+export function createTimeoutError(cli, durationMs) {
+    return {
+        type: 'timeout',
+        cli,
+        durationMs
+    };
+}
+/**
+ * Create a rate limit error
+ */
+export function createRateLimitError(cli, retryAfterMs) {
+    return {
+        type: 'rate_limit',
+        cli,
+        retryAfterMs
+    };
+}
+/**
+ * Create an auth error
+ */
+export function createAuthError(cli, message) {
+    return {
+        type: 'auth_error',
+        cli,
+        message
+    };
+}
+/**
+ * Create an invalid response error
+ */
+export function createInvalidResponseError(cli, rawOutput) {
+    return {
+        type: 'invalid_response',
+        cli,
+        rawOutput
+    };
+}
+/**
+ * Create a CLI crash error
+ */
+export function createCliError(cli, exitCode, stderr) {
+    return {
+        type: 'cli_error',
+        cli,
+        exitCode,
+        stderr
+    };
+}
+/**
+ * Format an error for user display
+ */
+export function formatErrorForUser(error) {
+    const others = ['codex', 'gemini', 'claude'].filter(c => c !== error.cli);
+    const otherCli = others[0];
+    switch (error.type) {
+        case 'cli_not_found':
+            return `❌ ${error.cli} CLI not found.
+
+Install with: ${error.installCmd}
+
+Alternative: Use /${otherCli}-review instead`;
+        case 'timeout':
+            return `⏱️ ${error.cli} timed out after ${Math.round(error.durationMs / 1000)}s.
+
+This might happen with complex reviews. Try:
+• Reviewing a smaller scope
+• Using --focus to narrow the review`;
+        case 'rate_limit':
+            const retryMsg = error.retryAfterMs
+                ? `Try again in ${Math.ceil(error.retryAfterMs / 1000)}s`
+                : 'Wait a moment and try again';
+            return `🚫 ${error.cli} rate limit hit.
+
+${retryMsg}
+
+Alternative: Use /${otherCli}-review instead`;
+        case 'auth_error':
+            return `🔐 ${error.cli} authentication failed.
+
+${error.message}
+
+Check your API key: ${ENV_VARS[error.cli]}
+Run: ${AUTH_COMMANDS[error.cli]}`;
+        case 'invalid_response':
+            return `⚠️ ${error.cli} returned an unusable response.
+
+The output couldn't be parsed as valid feedback.
+Raw output (truncated): ${error.rawOutput.slice(0, 200)}...`;
+        case 'cli_error':
+            return `❌ ${error.cli} crashed (exit code ${error.exitCode}).
+
+${error.stderr}`;
+    }
+}
+/**
+ * Detect error type from CLI output and error messages
+ */
+export function detectErrorType(cli, error, stdout, stderr, exitCode) {
+    // CLI not found
+    if (error.code === 'ENOENT') {
+        return createCliNotFoundError(cli);
+    }
+    // Rate limit
+    if (stderr.toLowerCase().includes('rate limit') ||
+        stdout.toLowerCase().includes('rate limit')) {
+        const retryAfterMatch = stderr.match(/retry after (\d+)/i);
+        const retryAfterMs = retryAfterMatch ? parseInt(retryAfterMatch[1]) * 1000 : undefined;
+        return createRateLimitError(cli, retryAfterMs);
+    }
+    // Auth error
+    if (stderr.toLowerCase().includes('unauthorized') ||
+        stderr.toLowerCase().includes('authentication') ||
+        stderr.toLowerCase().includes('401') ||
+        stderr.toLowerCase().includes('403')) {
+        return createAuthError(cli, stderr);
+    }
+    // Generic CLI error
+    if (exitCode !== null && exitCode !== 0) {
+        return createCliError(cli, exitCode, stderr);
+    }
+    // Invalid response (fallback)
+    return createInvalidResponseError(cli, stdout);
+}
+/**
+ * Parse retry-after from error response
+ */
+export function parseRetryAfter(errorMessage) {
+    const match = errorMessage.match(/retry[- ]?after[:\s]+(\d+)/i);
+    if (match) {
+        return parseInt(match[1]) * 1000; // Convert to ms
+    }
+    return undefined;
+}
+/**
+ * Generate suggestion based on error type
+ */
+export function getSuggestion(error) {
+    switch (error.type) {
+        case 'cli_not_found':
+            return `Install ${error.cli} CLI or use the other model`;
+        case 'timeout':
+            return 'Try reviewing a smaller scope or using --focus';
+        case 'rate_limit':
+            return error.retryAfterMs
+                ? `Wait ${Math.ceil(error.retryAfterMs / 1000)}s and retry`
+                : 'Wait a moment and retry';
+        case 'auth_error':
+            return `Check your ${ENV_VARS[error.cli]} environment variable`;
+        case 'invalid_response':
+            return 'Retry with a more specific focus area';
+        case 'cli_error':
+            return 'Check the CLI documentation for troubleshooting';
+        default:
+            return undefined;
+    }
+}

package/dist/executor.d.ts

@@ -0,0 +1,103 @@
+/**
+ * CliExecutor — Shared process management for external AI CLI tools.
+ *
+ * Extracted from the duplicated spawn logic in codex.ts and gemini.ts to
+ * provide a single, well-tested implementation of:
+ *   - Child-process spawning with stdin delivery
+ *   - Line-buffered stdout parsing (JSONL-friendly)
+ *   - Inactivity and absolute-max timeouts
+ *   - Max buffer size enforcement with truncation flag
+ *   - Settled guard to prevent double resolve/reject
+ *   - Dynamic inactivity timeout adjustment via setInactivityTimeout()
+ */
+export interface CliExecutorOptions {
+    /** Executable to spawn (e.g. 'codex', 'gemini', 'bash'). */
+    command: string;
+    /** Arguments passed to the command. */
+    args: string[];
+    /** Working directory for the spawned process. */
+    cwd: string;
+    /** Optional content to write to the process's stdin then close it. */
+    stdin?: string;
+    /** Additional environment variables merged over process.env. */
+    env?: Record<string, string>;
+    /**
+     * Called for each complete newline-delimited line on stdout.
+     * Errors thrown inside are swallowed so they cannot break the executor.
+     */
+    onLine?: (line: string) => void;
+    /**
+     * Called whenever a chunk of data arrives on stderr.
+     * Errors thrown inside are swallowed so they cannot break the executor.
+     */
+    onStderr?: (data: string) => void;
+    /**
+     * Milliseconds of stdout/stderr inactivity before the process is killed
+     * and the promise rejects with Error('TIMEOUT').
+     * Default: 120_000 (2 minutes).
+     */
+    inactivityTimeoutMs?: number;
+    /**
+     * Absolute maximum runtime in milliseconds regardless of activity.
+     * Process is killed and the promise rejects with Error('MAX_TIMEOUT').
+     * Default: 3_600_000 (60 minutes).
+     */
+    maxTimeoutMs?: number;
+    /**
+     * Maximum number of bytes accumulated in rawStdout before truncation.
+     * Once exceeded, rawStdout is capped and truncated is set to true.
+     * Default: 1_048_576 (1 MB).
+     */
+    maxBufferSize?: number;
+}
+export interface CliResult {
+    /** Lines split on '\n', excluding the trailing empty string from a final newline. */
+    stdoutLines: string[];
+    /** Raw accumulated stdout string (may be truncated). */
+    rawStdout: string;
+    /** Accumulated stderr string. */
+    stderr: string;
+    /** Process exit code; -1 if the process was killed without an exit code. */
+    exitCode: number;
+    /** True when rawStdout was capped at maxBufferSize. */
+    truncated: boolean;
+}
+export declare class CliExecutor {
+    private readonly opts;
+    /**
+     * Mutable inactivity timeout — callers can tighten it after first streaming
+     * event via setInactivityTimeout(). Changing it clears and restarts the
+     * currently running inactivity timer immediately.
+     */
+    private currentInactivityMs;
+    /**
+     * Handle to the live inactivity timer (kept here so setInactivityTimeout
+     * can reset it from outside the Promise closure via the shared ref below).
+     */
+    private inactivityTimer;
+    /**
+     * Injected by run() so setInactivityTimeout can restart the timer using
+     * the correct reject handle while the process is still running.
+     */
+    private resetInactivityFn;
+    constructor(options: CliExecutorOptions);
+    /**
+     * Dynamically adjust the inactivity timeout.
+     *
+     * If the process is currently running, the active inactivity timer is
+     * cancelled and restarted with the new duration immediately. Subsequent
+     * activity resets will also use this new value.
+     *
+     * Typical use: tighten the timeout once the first streaming event arrives,
+     * so a stalled process is detected sooner after it starts responding.
+     */
+    setInactivityTimeout(ms: number): void;
+    /**
+     * Spawn the process and return a promise that resolves with CliResult on
+     * normal completion (any exit code) or rejects with:
+     *   - Error('TIMEOUT')     — inactivity timeout exceeded
+     *   - Error('MAX_TIMEOUT') — absolute max timeout exceeded
+     *   - ENOENT / other spawn errors propagated from child_process
+     */
+    run(): Promise<CliResult>;
+}