@quantiya/codevibe-core 1.0.18 → 2.0.0

package/dist/reviewer/index.d.ts

@@ -0,0 +1,15 @@
+export type { AgentKind, ReviewerRole, ReviewerVerdict, VerdictId, VerdictKind, } from './types.js';
+export type { ReviewerError, ReviewerProvider, ReviewerSpec, } from './provider.js';
+export { ReviewerErrorClass } from './provider.js';
+export type { ParseResult, ParsedVerdict, VerdictParseError, } from './output-parser.js';
+export { parseVerdictOutput, VerdictParseErrorClass } from './output-parser.js';
+export type { RunReviewerOptions, SubprocessError, SubprocessOutcome, } from './subprocess.js';
+export { runReviewer, SubprocessErrorClass } from './subprocess.js';
+export type { ClaudeReviewerProviderOptions } from './providers/claude.js';
+export { ClaudeReviewerProvider } from './providers/claude.js';
+export type { GeminiEnvelope, GeminiModelStats, GeminiReviewerProviderOptions, GeminiStats, } from './providers/gemini.js';
+export { GeminiReviewerProvider } from './providers/gemini.js';
+export type { CodexReviewerProviderOptions } from './providers/codex.js';
+export { CodexReviewerProvider } from './providers/codex.js';
+export { ReviewerRegistry, createSubprocessReviewerRegistry, } from './registry.js';
+export { MockReviewerSpawner, StaticReviewerMock } from './mocks.js';

package/dist/reviewer/mocks.d.ts

@@ -0,0 +1,80 @@
+import { type ReviewerProvider, type ReviewerSpec } from './provider.js';
+import type { AgentKind, ReviewerVerdict, VerdictKind } from './types.js';
+import { type ReviewerError } from './provider.js';
+/**
+ * Scripted `ReviewerProvider` for tests. Each `evaluate(spec, gateId)`
+ * pops the next response from the FIFO queue keyed by
+ * `(spec.agent, gateId)`. If no script remains, returns a SpawnFailed
+ * error with a diagnostic so test setup bugs surface loudly.
+ *
+ * Use the `script_*` methods to queue responses before tests call
+ * `evaluate`.
+ */
+export declare class MockReviewerSpawner implements ReviewerProvider {
+    private readonly scripts;
+    private static key;
+    /**
+     * Script a verdict (with empty `suggested_changes`) for the next
+     * `evaluate(agent, gateId)` call. Use `scriptVerdictWithChanges`
+     * when `kind === 'REVISE'` (the parser-locked invariant requires
+     * non-empty changes for REVISE).
+     */
+    scriptVerdict(agent: AgentKind, gateId: string, kind: VerdictKind, reasoning: string): void;
+    /**
+     * Script a verdict with explicit `suggested_changes`. Required when
+     * `kind === 'REVISE'`.
+     */
+    scriptVerdictWithChanges(agent: AgentKind, gateId: string, kind: VerdictKind, reasoning: string, suggested_changes: string[]): void;
+    /** Script an error to return on the next `evaluate(agent, gateId)` call. */
+    scriptError(agent: AgentKind, gateId: string, error: ReviewerError): void;
+    /**
+     * How many scripted responses remain for the given key. Useful for
+     * test post-conditions ("all scripts were consumed").
+     */
+    remaining(agent: AgentKind, gateId: string): number;
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}
+/**
+ * Stateless `ReviewerProvider` for engine-level integration tests and
+ * smoke tests. Ignores `gateId`; returns a fixed verdict per agent
+ * (or a global default).
+ *
+ * Construct via static factories:
+ * - `StaticReviewerMock.allApprove()` / `.allReject()` / `.allRevise(changes)`
+ *   / `.allEscalate()` — global default, every agent returns the same.
+ * - `StaticReviewerMock.allError(err)` — every agent returns the same error.
+ *
+ * Stack per-agent overrides on top:
+ * - `.withAgentVerdict(agent, kind)` — override one agent's verdict.
+ * - `.withAgentError(agent, err)` — override one agent's error.
+ *
+ * Stacking models mixed-verdict scenarios: e.g.
+ * `StaticReviewerMock.allApprove().withAgentVerdict('gemini', 'REJECT')`
+ * → Claude approves + Gemini rejects + Codex approves → engine escalates.
+ */
+export declare class StaticReviewerMock implements ReviewerProvider {
+    private defaultResponse;
+    private readonly perAgent;
+    /** Empty mock. Returns SpawnFailed with a diagnostic on every
+     *  `evaluate` call until a default or per-agent override is set. */
+    static new(): StaticReviewerMock;
+    /** All reviewers return APPROVE. */
+    static allApprove(): StaticReviewerMock;
+    /** All reviewers return REJECT. */
+    static allReject(): StaticReviewerMock;
+    /** All reviewers return REVISE with the given suggested changes.
+     *  Empty `changes` falls back to a placeholder. */
+    static allRevise(changes: string[]): StaticReviewerMock;
+    /** All reviewers return ESCALATE. */
+    static allEscalate(): StaticReviewerMock;
+    /** All reviewers return the given error. */
+    static allError(err: ReviewerError): StaticReviewerMock;
+    /**
+     * Override the response for one agent. Stacks on top of whatever
+     * default was configured. Returns `this` for fluent chaining.
+     */
+    withAgentVerdict(agent: AgentKind, kind: VerdictKind): this;
+    /** Override to return an error for one specific agent. */
+    withAgentError(agent: AgentKind, err: ReviewerError): this;
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}

package/dist/reviewer/output-parser.d.ts

@@ -0,0 +1,95 @@
+import type { VerdictKind } from './types.js';
+/**
+ * Successfully parsed reviewer reply. The engine's fan-out layer lifts
+ * these fields into a `ReviewerVerdict` alongside telemetry (agent, tokens,
+ * latency, model) supplied by the subprocess layer.
+ */
+export interface ParsedVerdict {
+    /** The verdict the reviewer returned. */
+    kind: VerdictKind;
+    /**
+     * Free-form reasoning text (joined with blank-line paragraph separators
+     * preserved). Never empty by the time we reach here — reviewers that
+     * return only a verdict line fail parsing via `reasoning_missing`.
+     */
+    reasoning: string;
+    /**
+     * Ordered list of specific changes. Always non-empty when
+     * `kind === 'REVISE'`; always empty otherwise (enforced by the parser
+     * via `revise_missing_changes` / `suggested_changes_require_revise`).
+     */
+    suggested_changes: string[];
+}
+/**
+ * Why a reviewer's reply failed the locked-format check. Discriminated
+ * union; the subprocess layer maps any of these into `ReviewerError` with
+ * `kind: 'parse_failure'` and the raw output attached.
+ *
+ * Mirrors Rust's `VerdictParseError` enum 1:1.
+ */
+export type VerdictParseError = {
+    /** The entire reply was whitespace or empty. A reviewer that wrote
+     *  nothing has effectively timed out. */
+    kind: 'empty_output';
+} | {
+    /**
+     * The first non-blank line did not start with one of the four
+     * verdict keywords (case-insensitive). Includes any leading markdown
+     * formatting, quotation, or `VERDICT:` prefix that makes the line
+     * diverge from the locked contract.
+     *
+     * Also fired when a non-blank, non-indented line of prose appears
+     * after the bullet section starts (the format reserves post-bullet
+     * lines for blank lines or indented continuations only).
+     */
+    kind: 'invalid_verdict';
+    /** The offending line, trimmed but otherwise verbatim. */
+    found: string;
+} | {
+    /** Verdict was parsed but no reasoning followed. The locked contract
+     *  requires reasoning text so the audit record and user-facing
+     *  disagreement UI have something to show; a bare APPROVE / REJECT
+     *  line is a parse failure. */
+    kind: 'reasoning_missing';
+} | {
+    /** Verdict was REVISE but no bulleted suggested-changes list followed.
+     *  Design-locked: REVISE requires at least one concrete change. */
+    kind: 'revise_missing_changes';
+} | {
+    /** A non-REVISE verdict was followed by a bulleted list, which the
+     *  locked contract reserves for REVISE only. */
+    kind: 'suggested_changes_require_revise';
+    /** The non-REVISE verdict that erroneously had bullets. */
+    found: VerdictKind;
+};
+/**
+ * Class wrapper around a `VerdictParseError` so callers can `throw`/`catch`
+ * structured errors via JS idioms. `.detail` carries the discriminated
+ * union; `Error.message` is a human-readable formatting.
+ */
+export declare class VerdictParseErrorClass extends Error {
+    readonly detail: VerdictParseError;
+    constructor(detail: VerdictParseError);
+}
+/**
+ * Result type for `parseVerdictOutput`. Discriminated by `ok`. Mirrors
+ * Rust's `Result<ParsedVerdict, VerdictParseError>` without forcing TS
+ * callers to `try/catch` — most call sites want to inspect failure types
+ * directly to feed the audit log.
+ */
+export type ParseResult = {
+    ok: true;
+    verdict: ParsedVerdict;
+} | {
+    ok: false;
+    error: VerdictParseError;
+};
+/**
+ * Parse a reviewer reply. Strict: any deviation from the locked format
+ * returns `{ ok: false, error: ... }` which the subprocess layer routes to
+ * a parse-failure `ReviewerError`.
+ *
+ * Mirrors Rust's `parse_verdict_output` byte-for-byte. Test coverage
+ * matches the Rust unit-test set verbatim.
+ */
+export declare function parseVerdictOutput(raw: string): ParseResult;

package/dist/reviewer/provider.d.ts

@@ -0,0 +1,153 @@
+import type { AgentKind, ReviewerRole, ReviewerVerdict } from './types.js';
+/**
+ * Spec for spawning one reviewer at one gate. Constructed by the engine
+ * from `ReviewerAgentSpec` (from `PolicySnapshot`) + the context bundle for
+ * the gate.
+ *
+ * # Identity
+ *
+ * Per the 2026-04-23 seat/role pivot, the spec's primary identity is
+ * `seat_id` — position in the review panel — NOT `agent`. `agent` may
+ * repeat across seats within a single gate (single-vendor case: two Claude
+ * seats with different roles). Downstream consensus + verdict validation
+ * dedup on `seat_id`, never on `agent`. Providers echo `seat_id` + `role`
+ * back on the returned `ReviewerVerdict` so the audit trail can attribute
+ * verdicts by lens rather than by agent kind.
+ */
+export interface ReviewerSpec {
+    /**
+     * Position in the review panel, 0-indexed. For an N-seat policy this is
+     * in `0..N`. The primary identity key for this reviewer across the
+     * engine, audit log, and FFI — providers MUST echo this value back on
+     * the produced `ReviewerVerdict.seat_id`.
+     */
+    seat_id: number;
+    /**
+     * The lens this seat reviews through — Architecture / Correctness /
+     * Security for code; Accuracy / Clarity / Completeness for docs;
+     * composites for mixed. Drives the role-specific prompt prefix and is
+     * echoed back on the verdict for audit attribution. Unique within a
+     * policy (a duplicate role defeats the orthogonality purpose).
+     */
+    role: ReviewerRole;
+    /**
+     * Which agent to spawn. MAY repeat across seats when roles differ — the
+     * single-vendor case the 2026-04-23 pivot enables.
+     */
+    agent: AgentKind;
+    /**
+     * Tool names the reviewer is allowed to invoke. Typically
+     * `["Read", "Grep", "Glob"]` per the read-only reviewer invariant. Shape
+     * is agent-agnostic here; each provider enforces the sandbox in its own
+     * way:
+     * - Claude: `--allowed-tools Read,Grep,Glob` CLI flag.
+     * - Gemini: `--approval-mode plan` (Gemini's first-class read-only mode).
+     *   The `tool_allowlist` is intentionally unused by the Gemini provider;
+     *   plan mode is the sandbox contract. 2.0.x task #62 tracks adding
+     *   `--policy <tempfile>` as defense-in-depth.
+     * - Codex: `--sandbox read-only --skip-git-repo-check` flags + per-spawn
+     *   ephemeral output file.
+     */
+    tool_allowlist: string[];
+    /**
+     * Pre-rendered reviewer prompt. Engine renders per artifact type
+     * (code / docs / mixed) with a role-specific prefix prepended before
+     * calling `evaluate`.
+     */
+    prompt_template: string;
+    /**
+     * Wall-clock timeout for one reviewer's verdict. After this elapses the
+     * provider should throw `ReviewerError` with `kind: 'timeout'` and
+     * cancel the underlying process.
+     */
+    timeout_ms: number;
+    /**
+     * Optional per-reviewer model preference. `null` defers to the agent's
+     * CLI default.
+     */
+    model_hint: string | null;
+}
+/**
+ * Typed error thrown by `ReviewerProvider.evaluate`. Discriminated union
+ * matching Rust's `#[serde(tag = "kind", rename_all = "snake_case")]` enum.
+ *
+ * The engine's consensus path treats any thrown error as equivalent to a
+ * `VerdictKind::Escalate` for routing (so safety-defaults-to-escalation
+ * holds), but the distinct variants matter for the audit log and the
+ * user-facing error message.
+ */
+export type ReviewerError = {
+    /** Reviewer exceeded its `timeout_ms` budget. */
+    kind: 'timeout';
+    /** Which agent timed out (carried so the audit entry can attribute
+     *  cost / reliability back to the specific agent). */
+    agent: AgentKind;
+    /** Wall-clock ms elapsed before timeout fired. */
+    elapsed_ms: number;
+} | {
+    /** Reviewer process could not be launched (CLI missing, spawn syscall
+     *  failed, etc.). */
+    kind: 'spawn_failed';
+    agent: AgentKind;
+    /** Human-readable cause. */
+    reason: string;
+} | {
+    /** Reviewer returned but its output couldn't be parsed into a valid
+     *  verdict. Raw output is preserved for the audit log. */
+    kind: 'parse_failure';
+    agent: AgentKind;
+    /** Raw output (truncated to a reasonable length by the caller if
+     *  needed). */
+    raw_output: string;
+} | {
+    /** Reviewer was cancelled by the engine before completing (e.g.,
+     *  user abort, a sibling reviewer already hard-rejected). No
+     *  per-agent attribution because cancellation can fire on any
+     *  reviewer in flight. */
+    kind: 'cancelled';
+} | {
+    /** A reviewer's task panicked or was aborted before returning a
+     *  verdict. Mirror of the Rust `InternalJoinFailure` variant. The
+     *  variant deliberately has no `agent` field — attributing a panic
+     *  to a specific agent would be a telemetry lie. */
+    kind: 'internal_join_failure';
+    reason: string;
+};
+/**
+ * Class wrapper around a `ReviewerError` so callers can `throw` typed
+ * errors and `try { ... } catch (e) { if (e instanceof ReviewerErrorClass) {
+ * /* type-narrow on e.detail.kind *\/ } }` from JS-idiom code paths.
+ *
+ * The `.detail` property carries the discriminated union; `Error.message`
+ * is a human-readable formatting matching Rust's `#[error(...)]` strings.
+ */
+export declare class ReviewerErrorClass extends Error {
+    /** The structured error detail. Use `.kind` to narrow. */
+    readonly detail: ReviewerError;
+    constructor(detail: ReviewerError);
+}
+/**
+ * Engine's contract with reviewer implementations.
+ *
+ * **Engine owns lifecycle:** implementations must spawn, await verdict,
+ * enforce timeout, cancel, and capture logs internally. The engine calls
+ * `evaluate` and awaits — it never holds a handle that could outlive the
+ * call.
+ *
+ * Errors are thrown as `ReviewerErrorClass` instances; callers narrow via
+ * the `.detail.kind` discriminator.
+ */
+export interface ReviewerProvider {
+    /**
+     * Spawn one reviewer per the spec, collect its verdict, enforce timeout.
+     *
+     * @param spec - the reviewer to spawn (seat_id + role + agent + prompt + timeout)
+     * @param gateId - the `ReviewGate` UUID this verdict attaches to. Stored
+     *                 on the returned `ReviewerVerdict.gate_id`.
+     * @returns the parsed `ReviewerVerdict` on success.
+     * @throws `ReviewerErrorClass` on timeout, spawn failure, parse failure,
+     *         cancellation, or internal join failure. Use `e.detail.kind` to
+     *         narrow.
+     */
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}

package/dist/reviewer/providers/__tests__/claude-live-smoke.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/reviewer/providers/__tests__/claude.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/reviewer/providers/__tests__/codex-live-smoke.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/reviewer/providers/__tests__/codex.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/reviewer/providers/__tests__/gemini-live-smoke.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/reviewer/providers/__tests__/gemini.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/reviewer/providers/claude.d.ts

@@ -0,0 +1,59 @@
+import { type ReviewerProvider, type ReviewerSpec } from '../provider.js';
+import { type SubprocessOutcome } from '../subprocess.js';
+import type { ReviewerVerdict } from '../types.js';
+/**
+ * Built command shape — split out so tests can inspect args / env without
+ * spawning a process. `runReviewer` consumes this shape directly.
+ */
+export interface BuiltCommand {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+}
+/** Construction options. */
+export interface ClaudeReviewerProviderOptions {
+    /** Override the `claude` executable path. Production callers pass nothing
+     *  (PATH lookup); integration tests can stub Claude with a shell-script
+     *  fixture. */
+    executable?: string;
+}
+/**
+ * Real Claude Code reviewer provider. Wraps the `claude` CLI.
+ *
+ * Construct with `new ClaudeReviewerProvider()` for the standard `claude`
+ * binary, or `new ClaudeReviewerProvider({ executable: '/opt/bin/mock-claude' })`
+ * for tests that point at a fixture CLI on a controlled PATH.
+ */
+export declare class ClaudeReviewerProvider implements ReviewerProvider {
+    private readonly executable;
+    constructor(opts?: ClaudeReviewerProviderOptions);
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}
+/**
+ * Construct the Claude CLI invocation. Split out from `evaluate` so unit
+ * tests can assert on the built arg list + env without actually spawning a
+ * process.
+ *
+ * Locked flag set:
+ * - `--print` — non-interactive mode; emit the response and exit, rather
+ *   than waiting for further turns. Required so the subprocess actually
+ *   terminates on its own.
+ * - `--allowed-tools <CSV>` — design-locked sandbox. `ReviewerSpec.tool_allowlist`
+ *   is populated from the engine's policy; the provider trusts the spec
+ *   rather than hard-coding the list.
+ * - `--model <hint>` — optional; omitted when `spec.model_hint` is `null`,
+ *   deferring to Claude's default.
+ *
+ * # QUORUM_REVIEWER_SUBPROCESS env var
+ *
+ * Set unconditionally to `'1'` in the child's environment. See module docs
+ * for the rationale and why `--bare` was rejected as the primary defense.
+ */
+export declare function buildCommand(executable: string, spec: ReviewerSpec): BuiltCommand;
+/**
+ * Map the raw subprocess outcome into a `ReviewerVerdict` or throw a
+ * structured `ReviewerErrorClass`. Exit code is checked first — a crashed
+ * CLI that happened to print something valid on stdout should still be
+ * treated as a spawn failure, not a silently-accepted verdict.
+ */
+export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome): ReviewerVerdict;

package/dist/reviewer/providers/codex.d.ts

@@ -0,0 +1,67 @@
+import { type ReviewerProvider, type ReviewerSpec } from '../provider.js';
+import { type SubprocessOutcome } from '../subprocess.js';
+import type { ReviewerVerdict } from '../types.js';
+import type { BuiltCommand } from './claude.js';
+/** Construction options. */
+export interface CodexReviewerProviderOptions {
+    /** Override the `codex` executable path. Production callers pass nothing
+     *  (PATH lookup); integration tests can stub Codex with a shell-script
+     *  fixture. */
+    executable?: string;
+}
+/**
+ * Real Codex CLI reviewer provider. Wraps the `codex exec` subcommand.
+ */
+export declare class CodexReviewerProvider implements ReviewerProvider {
+    private readonly executable;
+    constructor(opts?: CodexReviewerProviderOptions);
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}
+/**
+ * Construct the Codex CLI invocation. Split out from `evaluate` so unit
+ * tests can assert on the built arg list without actually spawning a
+ * process.
+ *
+ * Locked flag set:
+ * - `exec` — the non-interactive subcommand (the interactive default
+ *   would block forever waiting for user input).
+ * - `--sandbox read-only` — design-locked read-only sandbox.
+ * - `--skip-git-repo-check` — reviewer subprocesses must run in any cwd,
+ *   not just git working trees.
+ * - `--color never` — strip ANSI escapes from any incidental stdout
+ *   output (the JSONL stream is not affected, but logs and error
+ *   messages are).
+ * - `--json` — emit JSONL events to stdout for token-count parsing.
+ * - `--ephemeral` — do NOT write a session JSONL under
+ *   `~/.codex/sessions/`.
+ * - `--output-last-message <path>` — write the model's final agent
+ *   message verbatim to `path`.
+ * - `--model <hint>` — optional; omitted when `spec.model_hint` is `null`.
+ * - `-` (final arg) — read prompt from stdin.
+ */
+export declare function buildCommand(executable: string, spec: ReviewerSpec, lastMessagePath: string): BuiltCommand;
+/**
+ * Map the raw subprocess outcome + the file Codex wrote into a
+ * `ReviewerVerdict` or throw a structured `ReviewerErrorClass`. See
+ * `claude.ts::buildVerdict` for the shared safety rule (non-zero exit
+ * overrides any parseable stdout / file).
+ */
+export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, lastMessage: string): ReviewerVerdict;
+/**
+ * Sum `usage.input_tokens + usage.output_tokens` across every
+ * `turn.completed` JSONL event in `stdout`. Returns `null` when no
+ * `turn.completed` event reported any token count, so dashboards can
+ * distinguish "no data" from a real zero.
+ *
+ * Lenient: malformed JSONL lines are silently skipped (Codex's stream is
+ * designed to be append-only, so partial flushes during timeout could
+ * leave a final truncated line).
+ */
+export declare function sumCodexTokens(stdout: string): number | null;
+/**
+ * Generate a unique-per-spawn path for `--output-last-message`. Lives in
+ * the OS temp dir; we own its lifecycle (create on codex's side, read +
+ * delete on ours). Per-process pid + UUID is enough — no race risk across
+ * concurrent reviewers in the same engine run.
+ */
+export declare function makeLastMessagePath(): string;

package/dist/reviewer/providers/common.d.ts

@@ -0,0 +1,25 @@
+import type { AgentKind } from '../types.js';
+import type { ReviewerError } from '../provider.js';
+import type { SubprocessError } from '../subprocess.js';
+/**
+ * Map a subprocess-layer error into a `ReviewerError` for the given agent.
+ * Mirrors Rust's `providers::claude::map_subprocess_error` byte-for-byte:
+ *
+ * - `spawn_failed` → `ReviewerError::SpawnFailed { agent, reason }`
+ * - `timeout` → `ReviewerError::Timeout { agent, elapsed_ms }`
+ * - `io` → `ReviewerError::SpawnFailed { agent, reason: "io error: <msg>" }`
+ *   (deliberate; an IO failure during spawn is a spawn failure from the
+ *   audit log's perspective — the reviewer never produced a verdict)
+ * - `cancelled` → `ReviewerError` cancelled (no agent attribution; the
+ *   Rust enum omits the agent field on Cancelled because cancellation
+ *   can fire on any reviewer in flight)
+ *
+ * The Rust source's `map_subprocess_error` handles only three variants
+ * (`SpawnFailed`, `Timeout`, `Io`) because the Rust subprocess layer
+ * doesn't have a Cancelled variant — engine-driven cancellation in Rust
+ * is handled at a higher layer via `tokio::select!` against the abort
+ * future, never surfacing as a `SubprocessError`. The TS port carries
+ * cancellation in the subprocess layer (via `AbortSignal`), so we
+ * include it here.
+ */
+export declare function mapSubprocessError(agent: AgentKind, err: SubprocessError): ReviewerError;

package/dist/reviewer/providers/gemini.d.ts

@@ -0,0 +1,108 @@
+import { type ReviewerProvider, type ReviewerSpec } from '../provider.js';
+import { type SubprocessOutcome } from '../subprocess.js';
+import type { ReviewerVerdict } from '../types.js';
+import type { BuiltCommand } from './claude.js';
+/** Construction options. */
+export interface GeminiReviewerProviderOptions {
+    /** Override the `gemini` executable path. Production callers pass nothing
+     *  (PATH lookup); integration tests can stub Gemini with a shell-script
+     *  fixture. */
+    executable?: string;
+}
+/**
+ * JSON envelope shape emitted by `gemini --output-format json`. We only care
+ * about `response`; the other fields (`session_id`, `stats`) are consumed by
+ * the JSON deserializer but not surfaced on `ReviewerVerdict` directly.
+ *
+ * Tolerates missing or extra top-level keys for cross-version compatibility.
+ */
+export interface GeminiEnvelope {
+    response: string;
+    /** Gemini 0.38.2 emits this; older versions may not. */
+    session_id?: string;
+    stats?: GeminiStats;
+}
+export interface GeminiStats {
+    /** Map of model name → per-model stats. Token usage MUST be summed across
+     *  every entry (R2 "telemetry timebomb" lesson — picking an arbitrary one
+     *  via `Object.values()[0]` would under-report when Gemini reports
+     *  auxiliary models). */
+    models?: Record<string, GeminiModelStats>;
+}
+export interface GeminiModelStats {
+    tokens?: {
+        /** Prompt + response tokens combined. Populated by Gemini's
+         *  `stats.models.<name>.tokens.total`; used for cost telemetry. */
+        total?: number;
+    };
+}
+/**
+ * Real Gemini CLI reviewer provider. Wraps the `gemini` binary.
+ */
+export declare class GeminiReviewerProvider implements ReviewerProvider {
+    private readonly executable;
+    constructor(opts?: GeminiReviewerProviderOptions);
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}
+/**
+ * Construct the Gemini CLI invocation. Split out from `evaluate` so unit
+ * tests can assert on the built arg list + env without actually spawning a
+ * process.
+ *
+ * Locked flag set:
+ * - `-p ''` — non-interactive mode, empty inline prompt so the full prompt
+ *   is read from stdin (consistent with Claude path).
+ * - `--approval-mode plan` — read-only sandbox.
+ * - `--output-format json` — structured reply envelope that survives
+ *   user-hook stdout pollution.
+ * - `--model <hint>` — optional; omitted when `spec.model_hint` is `null`.
+ *
+ * `spec.tool_allowlist` is **intentionally unused** for Gemini. Plan mode
+ * is the design-locked sandbox; mapping the Claude-style allowlist to
+ * Gemini's (deprecated) `--allowed-tools` flag would hit the known
+ * non-interactive bugs flagged in the module docs.
+ *
+ * # QUORUM_REVIEWER_SUBPROCESS env var
+ *
+ * Set unconditionally to `'1'` in the child's environment. The user's
+ * Gemini plugin checks this at the top of `hooks/common.sh` and
+ * short-circuits every hook — without this gate, reviewer spawns would
+ * each create a new backend session and mark the user's primary Gemini
+ * session INACTIVE (empirically observed 2026-04-21 during Phase 2c.2
+ * local testing).
+ */
+export declare function buildCommand(executable: string, spec: ReviewerSpec): BuiltCommand;
+/**
+ * Map the raw subprocess outcome into a `ReviewerVerdict` or throw a
+ * structured `ReviewerErrorClass`. See `claude.ts::buildVerdict` for the
+ * shared safety rule (non-zero exit overrides any parseable stdout).
+ */
+export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome): ReviewerVerdict;
+/**
+ * Parse the FIRST complete JSON object in `stdout`, discarding any trailing
+ * bytes. User-level hooks (e.g., CodeVibe's own Gemini plugin hooks
+ * installed in `~/.gemini/settings.json`) append log lines to stdout AFTER
+ * the model's reply envelope. This walks the text byte-by-byte tracking
+ * brace depth + string escapes to find where the first JSON object ends,
+ * then `JSON.parse` that slice — the equivalent of Rust's
+ * `serde_json::Deserializer::into_iter().next()` for our purposes.
+ *
+ * Returns `null` if stdout contains no valid JSON value at all, the
+ * extracted slice fails strict JSON parsing, OR the parsed value isn't a
+ * shape-conformant `GeminiEnvelope` (i.e. missing or non-string
+ * `response`). The caller routes any of these to ParseFailure with raw
+ * stdout — matching Rust's serde-deserialization-failure path.
+ *
+ * # Why runtime shape validation
+ *
+ * Rust's `serde_json::Deserializer` rejects `{}` or `{"response":123}`
+ * during deserialization because `GeminiEnvelope { response: String, ... }`
+ * makes the field required at the type-system layer. TypeScript's
+ * `JSON.parse(slice) as GeminiEnvelope` is a compile-time-only assertion
+ * with no runtime check, so we reproduce serde's behavior with an
+ * explicit `validateGeminiEnvelope` step. Without this, a syntactically-
+ * valid-but-shape-bad envelope would land an `undefined.replace()`
+ * TypeError up the call stack instead of a structured ParseFailure
+ * (R1 finding on Phase 2f.1.b round 1).
+ */
+export declare function parseFirstJsonEnvelope(stdout: string): GeminiEnvelope | null;