@simonren/quorum 0.7.0

package/dist/executor.js

@@ -0,0 +1,244 @@
+/**
+ * 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()
+ */
+import { spawn } from 'child_process';
+// =============================================================================
+// EXECUTOR
+// =============================================================================
+export class CliExecutor {
+    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.
+     */
+    currentInactivityMs;
+    /**
+     * Handle to the live inactivity timer (kept here so setInactivityTimeout
+     * can reset it from outside the Promise closure via the shared ref below).
+     */
+    inactivityTimer;
+    /**
+     * Injected by run() so setInactivityTimeout can restart the timer using
+     * the correct reject handle while the process is still running.
+     */
+    resetInactivityFn;
+    constructor(options) {
+        this.opts = {
+            command: options.command,
+            args: options.args,
+            cwd: options.cwd,
+            stdin: options.stdin,
+            env: options.env,
+            onLine: options.onLine,
+            onStderr: options.onStderr,
+            inactivityTimeoutMs: options.inactivityTimeoutMs ?? 120_000,
+            maxTimeoutMs: options.maxTimeoutMs ?? 3_600_000,
+            maxBufferSize: options.maxBufferSize ?? 1_048_576,
+        };
+        this.currentInactivityMs = this.opts.inactivityTimeoutMs;
+    }
+    /**
+     * 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) {
+        this.currentInactivityMs = ms;
+        // Restart the running timer (if any) with the new duration.
+        this.resetInactivityFn?.();
+    }
+    /**
+     * 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() {
+        return new Promise((resolve, reject) => {
+            // ------------------------------------------------------------------
+            // Settled guard — prevents double resolve/reject when, e.g., the
+            // inactivity timer fires and then the `close` event also fires.
+            // ------------------------------------------------------------------
+            let settled = false;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                fn();
+            };
+            // ------------------------------------------------------------------
+            // Spawn
+            // ------------------------------------------------------------------
+            const proc = spawn(this.opts.command, this.opts.args, {
+                cwd: this.opts.cwd,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: this.opts.env
+                    ? { ...process.env, ...this.opts.env }
+                    : { ...process.env },
+            });
+            // ------------------------------------------------------------------
+            // Stdin delivery
+            // ------------------------------------------------------------------
+            // Guard against EPIPE: log but do not reject — the close handler owns
+            // the final resolution. EPIPE means the child exited before consuming
+            // all of stdin, which is fine (e.g. the child crashed early).
+            proc.stdin.on('error', (err) => {
+                if (err.code === 'EPIPE') {
+                    console.error(`[executor] stdin EPIPE (child closed early): ${err.message}`);
+                }
+                else {
+                    console.error(`[executor] stdin error: ${err.message}`);
+                }
+            });
+            if (this.opts.stdin !== undefined) {
+                proc.stdin.write(this.opts.stdin);
+            }
+            proc.stdin.end();
+            // ------------------------------------------------------------------
+            // State
+            // ------------------------------------------------------------------
+            let rawStdout = '';
+            let stderr = '';
+            let truncated = false;
+            /** Partial line buffer — accumulates data until a '\n' is seen. */
+            let lineBuffer = '';
+            // ------------------------------------------------------------------
+            // Timers
+            // ------------------------------------------------------------------
+            const maxTimer = setTimeout(() => {
+                proc.kill('SIGTERM');
+                settle(() => reject(new Error('MAX_TIMEOUT')));
+            }, this.opts.maxTimeoutMs);
+            const resetInactivity = () => {
+                clearTimeout(this.inactivityTimer);
+                this.inactivityTimer = setTimeout(() => {
+                    proc.kill('SIGTERM');
+                    settle(() => reject(new Error('TIMEOUT')));
+                }, this.currentInactivityMs);
+            };
+            // Expose reset function so setInactivityTimeout() can restart it.
+            this.resetInactivityFn = resetInactivity;
+            // Start the inactivity clock.
+            resetInactivity();
+            // ------------------------------------------------------------------
+            // stdout handler — line buffering
+            // ------------------------------------------------------------------
+            proc.stdout.on('data', (chunk) => {
+                resetInactivity();
+                const incoming = chunk.toString();
+                // Buffer management: cap rawStdout at maxBufferSize.
+                if (!truncated) {
+                    const remaining = this.opts.maxBufferSize - rawStdout.length;
+                    if (incoming.length <= remaining) {
+                        rawStdout += incoming;
+                    }
+                    else {
+                        rawStdout += incoming.slice(0, remaining);
+                        truncated = true;
+                    }
+                }
+                // Line splitting — process complete lines from the combined buffer.
+                lineBuffer += incoming;
+                const newlineIdx = lineBuffer.lastIndexOf('\n');
+                if (newlineIdx === -1) {
+                    // No complete line yet — keep buffering.
+                    return;
+                }
+                // Extract all complete lines (everything up to and including the last '\n').
+                const completePart = lineBuffer.slice(0, newlineIdx + 1);
+                lineBuffer = lineBuffer.slice(newlineIdx + 1);
+                const lines = completePart.split('\n');
+                // The last element is always '' because split on a trailing '\n' produces
+                // an empty string — skip it.
+                for (let i = 0; i < lines.length - 1; i++) {
+                    const line = lines[i];
+                    if (this.opts.onLine) {
+                        try {
+                            this.opts.onLine(line);
+                        }
+                        catch {
+                            // Intentionally swallowed — callers must not break the executor.
+                        }
+                    }
+                }
+            });
+            // ------------------------------------------------------------------
+            // stderr handler
+            // ------------------------------------------------------------------
+            proc.stderr.on('data', (chunk) => {
+                resetInactivity();
+                const data = chunk.toString();
+                if (stderr.length < this.opts.maxBufferSize) {
+                    const remaining = this.opts.maxBufferSize - stderr.length;
+                    stderr += data.length <= remaining ? data : data.slice(0, remaining);
+                }
+                if (this.opts.onStderr) {
+                    try {
+                        this.opts.onStderr(data);
+                    }
+                    catch {
+                        // Intentionally swallowed.
+                    }
+                }
+            });
+            // ------------------------------------------------------------------
+            // close handler — normal resolution path
+            // ------------------------------------------------------------------
+            proc.on('close', (code) => {
+                clearTimeout(this.inactivityTimer);
+                clearTimeout(maxTimer);
+                this.resetInactivityFn = undefined;
+                // Flush any partial line still in the buffer.
+                if (lineBuffer.length > 0) {
+                    if (this.opts.onLine) {
+                        try {
+                            this.opts.onLine(lineBuffer);
+                        }
+                        catch {
+                            // Intentionally swallowed.
+                        }
+                    }
+                }
+                // Build the final lines array from rawStdout (split after the fact so
+                // the list is consistent with rawStdout even when truncated).
+                const rawLines = rawStdout.split('\n');
+                // Drop a trailing empty string produced by a final '\n'.
+                if (rawLines.length > 0 && rawLines[rawLines.length - 1] === '') {
+                    rawLines.pop();
+                }
+                settle(() => resolve({
+                    stdoutLines: rawLines,
+                    rawStdout,
+                    stderr,
+                    exitCode: code ?? -1,
+                    truncated,
+                }));
+            });
+            // ------------------------------------------------------------------
+            // error handler — spawn failures (e.g. ENOENT)
+            // ------------------------------------------------------------------
+            proc.on('error', (err) => {
+                clearTimeout(this.inactivityTimer);
+                clearTimeout(maxTimer);
+                this.resetInactivityFn = undefined;
+                settle(() => reject(err));
+            });
+        });
+    }
+}

package/dist/handoff.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Review Handoff Protocol
+ *
+ * Defines the minimal, targeted information that should flow from CC to reviewers.
+ *
+ * Philosophy:
+ * - Reviewers have filesystem access - don't duplicate what they can discover
+ * - Pass ONLY what CC uniquely knows: uncertainties, decisions, questions
+ * - Let reviewer use their tools (file reading) for actual code
+ * - Do NOT assume git — working directory may not be a git repo
+ */
+import { z } from 'zod';
+import { FocusArea } from './types.js';
+export { FocusArea } from './types.js';
+/**
+ * Uncertainty that CC has - things the reviewer should verify
+ */
+export declare const UncertaintySchema: z.ZodObject<{
+    topic: z.ZodString;
+    question: z.ZodString;
+    ccAssumption: z.ZodOptional<z.ZodString>;
+    relevantFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    severity: z.ZodOptional<z.ZodEnum<["critical", "important", "minor"]>>;
+}, "strip", z.ZodTypeAny, {
+    question: string;
+    topic: string;
+    relevantFiles?: string[] | undefined;
+    severity?: "critical" | "important" | "minor" | undefined;
+    ccAssumption?: string | undefined;
+}, {
+    question: string;
+    topic: string;
+    relevantFiles?: string[] | undefined;
+    severity?: "critical" | "important" | "minor" | undefined;
+    ccAssumption?: string | undefined;
+}>;
+export type Uncertainty = z.infer<typeof UncertaintySchema>;
+/**
+ * Decision CC made - for reviewer to evaluate
+ */
+export declare const DecisionSchema: z.ZodObject<{
+    decision: z.ZodString;
+    rationale: z.ZodString;
+    alternatives: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    tradeoffs: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    decision: string;
+    rationale: string;
+    alternatives?: string[] | undefined;
+    tradeoffs?: string | undefined;
+}, {
+    decision: string;
+    rationale: string;
+    alternatives?: string[] | undefined;
+    tradeoffs?: string | undefined;
+}>;
+export type Decision = z.infer<typeof DecisionSchema>;
+/**
+ * Question CC wants the reviewer to answer
+ */
+export declare const QuestionSchema: z.ZodObject<{
+    question: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    ccGuess: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    question: string;
+    context?: string | undefined;
+    ccGuess?: string | undefined;
+}, {
+    question: string;
+    context?: string | undefined;
+    ccGuess?: string | undefined;
+}>;
+export type Question = z.infer<typeof QuestionSchema>;
+/**
+ * The complete handoff from CC to reviewer
+ * Intentionally minimal - only what CC uniquely knows
+ */
+export declare const HandoffSchema: z.ZodObject<{
+    workingDir: z.ZodString;
+    summary: z.ZodString;
+    uncertainties: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        topic: z.ZodString;
+        question: z.ZodString;
+        ccAssumption: z.ZodOptional<z.ZodString>;
+        relevantFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        severity: z.ZodOptional<z.ZodEnum<["critical", "important", "minor"]>>;
+    }, "strip", z.ZodTypeAny, {
+        question: string;
+        topic: string;
+        relevantFiles?: string[] | undefined;
+        severity?: "critical" | "important" | "minor" | undefined;
+        ccAssumption?: string | undefined;
+    }, {
+        question: string;
+        topic: string;
+        relevantFiles?: string[] | undefined;
+        severity?: "critical" | "important" | "minor" | undefined;
+        ccAssumption?: string | undefined;
+    }>, "many">>;
+    decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        decision: z.ZodString;
+        rationale: z.ZodString;
+        alternatives: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        tradeoffs: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        decision: string;
+        rationale: string;
+        alternatives?: string[] | undefined;
+        tradeoffs?: string | undefined;
+    }, {
+        decision: string;
+        rationale: string;
+        alternatives?: string[] | undefined;
+        tradeoffs?: string | undefined;
+    }>, "many">>;
+    questions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        ccGuess: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        question: string;
+        context?: string | undefined;
+        ccGuess?: string | undefined;
+    }, {
+        question: string;
+        context?: string | undefined;
+        ccGuess?: string | undefined;
+    }>, "many">>;
+    priorityFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    focusAreas: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    customInstructions: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    workingDir: string;
+    summary: string;
+    confidence?: number | undefined;
+    uncertainties?: {
+        question: string;
+        topic: string;
+        relevantFiles?: string[] | undefined;
+        severity?: "critical" | "important" | "minor" | undefined;
+        ccAssumption?: string | undefined;
+    }[] | undefined;
+    decisions?: {
+        decision: string;
+        rationale: string;
+        alternatives?: string[] | undefined;
+        tradeoffs?: string | undefined;
+    }[] | undefined;
+    questions?: {
+        question: string;
+        context?: string | undefined;
+        ccGuess?: string | undefined;
+    }[] | undefined;
+    focusAreas?: string[] | undefined;
+    customInstructions?: string | undefined;
+    priorityFiles?: string[] | undefined;
+}, {
+    workingDir: string;
+    summary: string;
+    confidence?: number | undefined;
+    uncertainties?: {
+        question: string;
+        topic: string;
+        relevantFiles?: string[] | undefined;
+        severity?: "critical" | "important" | "minor" | undefined;
+        ccAssumption?: string | undefined;
+    }[] | undefined;
+    decisions?: {
+        decision: string;
+        rationale: string;
+        alternatives?: string[] | undefined;
+        tradeoffs?: string | undefined;
+    }[] | undefined;
+    questions?: {
+        question: string;
+        context?: string | undefined;
+        ccGuess?: string | undefined;
+    }[] | undefined;
+    focusAreas?: string[] | undefined;
+    customInstructions?: string | undefined;
+    priorityFiles?: string[] | undefined;
+}>;
+export type Handoff = z.infer<typeof HandoffSchema>;
+export interface ReviewerRole {
+    id: string;
+    name: string;
+    description: string;
+    isGeneric: boolean;
+    applicableFocusAreas: FocusArea[];
+    systemPrompt: string;
+}
+/**
+ * Strong generic role - when no specific focus is given
+ * This is NOT a weak fallback - it's a comprehensive reviewer
+ */
+export declare const COMPREHENSIVE_REVIEWER: ReviewerRole;
+/**
+ * Change-focused reviewer - specifically for reviewing diffs
+ */
+export declare const CHANGE_FOCUSED_REVIEWER: ReviewerRole;
+/**
+ * Specialized roles - when specific focus is requested
+ */
+export declare const SECURITY_REVIEWER: ReviewerRole;
+export declare const PERFORMANCE_REVIEWER: ReviewerRole;
+export declare const ARCHITECTURE_REVIEWER: ReviewerRole;
+export declare const CORRECTNESS_REVIEWER: ReviewerRole;
+export declare const ROLES: Record<string, ReviewerRole>;
+/**
+ * Select and compose roles based on focus areas.
+ *
+ * When multiple focus areas map to different roles (e.g. security + performance),
+ * composes them into a single role with merged prompts instead of picking one winner.
+ */
+export declare function selectRole(focusAreas?: FocusArea[]): ReviewerRole;
+export declare const ADVERSARIAL_REVIEWER: ReviewerRole;
+/**
+ * Build an adversarial handoff prompt with challenge-mode stance sections.
+ *
+ * Block structure ported from openai/codex-plugin-cc's adversarial-review
+ * prompt: tagged XML blocks (operating_stance, attack_surface, review_method,
+ * finding_bar, calibration_rules, grounding_rules, final_check) so the prompt
+ * has stable internal structure the reviewer can lean on. CC's handoff
+ * sections (uncertainties / decisions / questions / focus / files / focus
+ * instructions) are layered on after as our differentiator.
+ */
+export declare function buildAdversarialHandoffPrompt(options: PromptOptions): string;
+export interface PromptOptions {
+    handoff: Handoff;
+    role?: ReviewerRole;
+}
+/**
+ * Build the review prompt using minimal, targeted context.
+ * No output format constraints — reviewer responds naturally, CC interprets.
+ */
+export declare function buildHandoffPrompt(options: PromptOptions): string;
+/**
+ * Parse structured ccOutput into Handoff fields.
+ *
+ * The slash commands tell CC to format its output as:
+ *   SUMMARY:
+ *   <text>
+ *
+ *   UNCERTAINTIES (verify these):
+ *   1. <text>
+ *
+ *   QUESTIONS:
+ *   1. <text>
+ *
+ *   PRIORITY FILES:
+ *   - <file>
+ *
+ * If no sections detected, returns { summary: ccOutput } (graceful fallback).
+ */
+export declare function parseStructuredCcOutput(ccOutput: string): Pick<Handoff, 'summary'> & Partial<Handoff>;
+/**
+ * Build a handoff from MCP tool inputs.
+ *
+ * Parses structured sections (SUMMARY, UNCERTAINTIES, QUESTIONS, PRIORITY FILES)
+ * from ccOutput when present, populating typed Handoff fields so reviewers
+ * receive machine-usable context instead of a single summary blob.
+ */
+export declare function buildSimpleHandoff(workingDir: string, ccOutput: string, analyzedFiles?: string[], focusAreas?: string[], customPrompt?: string): Handoff;
+/**
+ * Enhance a simple handoff with uncertainties/questions
+ * CC should call this to add its specific concerns
+ */
+export declare function enhanceHandoff(handoff: Handoff, uncertainties?: Uncertainty[], questions?: Question[], decisions?: Decision[]): Handoff;