@quantiya/codevibe-core 1.0.17 → 2.0.0

package/dist/reviewer/registry.d.ts

@@ -0,0 +1,87 @@
+import { type ReviewerProvider, type ReviewerSpec } from './provider.js';
+import type { AgentKind, ReviewerVerdict } from './types.js';
+/**
+ * Per-agent reviewer dispatch.
+ *
+ * Build with the fluent `with()` builder for the common production
+ * case (register all known agents up front), or the mutating
+ * `register()` helper when the set is determined at runtime.
+ * `providerFor` exposes the underlying provider for callers (e.g.,
+ * test harnesses) that need direct access without going through the
+ * `evaluate` method.
+ *
+ * `ReviewerRegistry` itself implements `ReviewerProvider` so it
+ * slots into anything that takes a single provider — including
+ * another `ReviewerRegistry`. (Compose-of-compose works for free.)
+ */
+export declare class ReviewerRegistry implements ReviewerProvider {
+    private readonly providers;
+    /**
+     * Builder-style register: returns `this` with `agent` mapped to
+     * `provider`. Intended for the production "register all three at
+     * startup" pattern:
+     *
+     * ```ts
+     * const registry = new ReviewerRegistry()
+     *   .with('claude', new ClaudeReviewerProvider())
+     *   .with('gemini', new GeminiReviewerProvider())
+     *   .with('codex',  new CodexReviewerProvider());
+     * ```
+     *
+     * Re-registering the same agent overwrites the previous provider —
+     * useful for tests that swap in a fixture provider after construction.
+     */
+    with(agent: AgentKind, provider: ReviewerProvider): this;
+    /**
+     * Mutating register. Equivalent to `with()` but returns void; use
+     * when chaining isn't readable (e.g., conditional registration in
+     * a loop).
+     */
+    register(agent: AgentKind, provider: ReviewerProvider): void;
+    /**
+     * Lookup the provider for `agent`. Returns `undefined` if no
+     * provider is registered. Callers should prefer using the
+     * `evaluate` method on the registry itself, which handles the
+     * missing-provider case as a typed `ReviewerError`. This method
+     * is exposed for test harnesses that need direct provider access
+     * (e.g., to call provider methods that aren't part of the
+     * interface).
+     */
+    providerFor(agent: AgentKind): ReviewerProvider | undefined;
+    /**
+     * Returns the set of agents that have registered providers, in
+     * insertion order. Useful for callers that want to log the
+     * configured registry shape or for a future startup-time validator
+     * that checks the policy snapshot's reviewer_agents are all covered.
+     */
+    registeredAgents(): AgentKind[];
+    /**
+     * Dispatch by `spec.agent` to the registered provider. If no
+     * provider is registered for that agent, throw
+     * `ReviewerErrorClass` with `kind: 'spawn_failed'` so the engine's
+     * existing escalation path handles it. The `reason` field includes
+     * the agent name so audit can identify the misconfiguration.
+     */
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}
+/**
+ * Production factory: build a registry pre-populated with all three
+ * subprocess providers (Claude, Gemini, Codex) using the standard
+ * binaries from PATH. Equivalent of Rust's
+ * `withSubprocessProviders()` napi factory.
+ *
+ * Plugins call this once at startup and hand the registry to the
+ * engine fan-out path. Inert registrations cost nothing — no
+ * subprocess fires until the policy actually references that agent.
+ *
+ * For tests / dev environments that need to override binary paths,
+ * construct the providers manually:
+ *
+ * ```ts
+ * const registry = new ReviewerRegistry()
+ *   .with('claude', new ClaudeReviewerProvider({ executable: '/opt/bin/claude' }))
+ *   .with('gemini', new GeminiReviewerProvider({ executable: '/opt/bin/gemini' }))
+ *   .with('codex',  new CodexReviewerProvider({  executable: '/opt/bin/codex' }));
+ * ```
+ */
+export declare function createSubprocessReviewerRegistry(): ReviewerRegistry;

package/dist/reviewer/subprocess.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Successful subprocess run. Exit status may still be failure (non-zero
+ * code); the caller decides whether to treat that as a reviewer spawn error
+ * or as a parse failure with whatever stdout it produced.
+ */
+export interface SubprocessOutcome {
+    /** Captured stdout decoded as UTF-8. Reviewers that emit non-UTF-8 are
+     *  misbehaving by contract; lossy decode keeps the parser running rather
+     *  than returning an IO error for what is really a "reviewer is broken"
+     *  scenario. */
+    stdout: string;
+    /** Captured stderr (same lossy-decode policy). Surfaced to callers so
+     *  audit records can include it. */
+    stderr: string;
+    /** Wall-clock milliseconds from `spawn()` to exit. Populated even on
+     *  non-zero exit because per-reviewer latency is a cost / reliability
+     *  telemetry input. */
+    elapsed_ms: number;
+    /** Whether the process exited with status 0. Separate from the stdout
+     *  contents — a reviewer that printed its verdict and then crashed on
+     *  shutdown is still "failed" from an audit perspective even if the
+     *  verdict parses cleanly. */
+    exit_success: boolean;
+}
+/**
+ * Subprocess-layer errors. Discriminated union; callers (per-agent
+ * providers) map these into `ReviewerError` with their own `AgentKind`.
+ */
+export type SubprocessError = {
+    /** The child process could not be spawned at all (binary not on
+     *  PATH, permission denied, fork/exec failed). */
+    kind: 'spawn_failed';
+    reason: string;
+} | {
+    /** The child exceeded its `timeout_ms` budget. The child has been
+     *  (or will be) killed via SIGKILL by the time this error is
+     *  returned. */
+    kind: 'timeout';
+    /** The timeout budget in ms, for telemetry. */
+    elapsed_ms: number;
+} | {
+    /** A non-timeout IO failure occurred while running the subprocess
+     *  (stdin write failed, stdout read failed, etc.). */
+    kind: 'io';
+    reason: string;
+} | {
+    /** Caller signalled abort via the `signal` option before the child
+     *  exited. The child has been killed via SIGKILL. Distinct from
+     *  `timeout` so the audit log can attribute "reviewer cancelled by
+     *  engine" separately from "reviewer ran past budget." */
+    kind: 'cancelled';
+};
+/** Class wrapper so callers can `throw`/`catch` typed errors. */
+export declare class SubprocessErrorClass extends Error {
+    readonly detail: SubprocessError;
+    constructor(detail: SubprocessError);
+}
+/**
+ * Inputs to `runReviewer`. Callers (per-agent providers) build this struct
+ * with their agent-specific binary + args + env, then hand off lifecycle
+ * management to this module.
+ */
+export interface RunReviewerOptions {
+    /** Path or command name to spawn. */
+    command: string;
+    /** Arguments to pass to the command. */
+    args: readonly string[];
+    /**
+     * Environment variables to set. **MUST include
+     * `QUORUM_REVIEWER_SUBPROCESS: '1'`** — this is the plugin-isolation env
+     * guard that prevents reviewer hook fires from evicting the user's
+     * primary plugin session. Each provider is responsible for setting it;
+     * this module does NOT inject it automatically because providers may
+     * also need to forward `process.env` selectively.
+     */
+    env: NodeJS.ProcessEnv;
+    /** Working directory; falls back to `process.cwd()`. */
+    cwd?: string;
+    /**
+     * Prompt to write to the child's stdin. Always followed by stdin EOF.
+     * Most reviewer CLIs finish reading the prompt then begin emitting
+     * output — a reviewer that blocks on a stuck stdin pipe is the §3.1
+     * test scenario.
+     */
+    prompt: string;
+    /**
+     * Wall-clock timeout (ms) bounding the whole spawn-to-exit window,
+     * INCLUDING the stdin write. This is the load-bearing detail per §3.1:
+     * an earlier (Rust v1) implementation wrapped only the wait-for-exit,
+     * which let a child that refused to drain stdin block the parent in
+     * pipe-full back-pressure indefinitely. Wrapping write+wait under one
+     * timeout is the fix.
+     */
+    timeout_ms: number;
+    /**
+     * Optional `AbortSignal` for engine-driven cancellation (e.g., user
+     * abort, sibling reviewer hard-rejecting). Aborting after a clean exit
+     * is a no-op; aborting mid-flight teardown is a `cancelled` error.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Run a preconfigured command as a reviewer subprocess.
+ *
+ * Contract:
+ * - Stdin, stdout, stderr are piped (caller cannot override; output capture
+ *   is the whole purpose of the call).
+ * - `prompt` is written to the child's stdin then stdin is closed (EOF).
+ * - The whole spawn → write-stdin → wait-for-exit lifecycle races against
+ *   `timeout_ms` AND any `signal` abort. On timeout / abort the streams
+ *   are explicitly destroyed and the child is SIGKILL'd before throwing.
+ *
+ * Throws `SubprocessErrorClass` on failure; the `.detail.kind` discriminator
+ * tells the caller which path tripped (`spawn_failed` / `timeout` / `io` /
+ * `cancelled`).
+ */
+export declare function runReviewer(opts: RunReviewerOptions): Promise<SubprocessOutcome>;

package/dist/reviewer/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Three agent kinds the reviewer subprocess layer can spawn.
+ *
+ * Lowercase wire format matches `codevibe_policy::AgentKind`'s
+ * `#[serde(rename_all = "lowercase")]` attribute. **Append-only after launch**
+ * — adding a fourth agent (e.g. a hypothetical fourth CLI) is fine; renaming
+ * `claude` → `Claude` would break every audit chain entry that has serialised
+ * it.
+ */
+export type AgentKind = 'claude' | 'gemini' | 'codex';
+/**
+ * Review lens a reviewer seat evaluates through.
+ *
+ * snake_case wire format matches `codevibe_policy::ReviewerRole`'s
+ * `#[serde(rename_all = "snake_case")]` attribute, locked in Phase 2f.0.a.1.
+ * **Append-only post-launch** — these strings are cryptographically bound
+ * into the audit hash chain once used. Renaming or removing a value would
+ * break chain verification on every prior entry. Adding new values is fine
+ * (Custom roles slipped to 2.0.1 per the locked design).
+ *
+ * Code-artifact lenses: architecture, correctness, security.
+ * Docs-artifact lenses: accuracy, clarity, completeness.
+ * Mixed-artifact composite lenses: architecture_and_accuracy,
+ *   correctness_and_clarity, security_and_completeness.
+ *
+ * The AppSync-facing `ReviewerRole` enum in `src/types/reviewer.ts` uses
+ * UPPERCASE GraphQL convention; this snake_case version is for the Rust
+ * engine wire. Translation between the two layers is the AppSync resolver's
+ * job, not the reviewer module's.
+ */
+export type ReviewerRole = 'architecture' | 'correctness' | 'security' | 'accuracy' | 'clarity' | 'completeness' | 'architecture_and_accuracy' | 'correctness_and_clarity' | 'security_and_completeness';
+/**
+ * Reviewer verdict kinds. Four values, each maps to a different path through
+ * the consensus engine.
+ *
+ * UPPERCASE wire format matches `codevibe_reviewer::VerdictKind`'s
+ * `#[serde(rename_all = "UPPERCASE")]` attribute. Append-only post-launch.
+ *
+ * - `APPROVE` — plan/artifact is sound, proceed.
+ * - `REJECT` — plan/artifact has fundamental problems; do not proceed.
+ * - `REVISE` — plan/artifact is close but needs specific changes. Requires
+ *   populated `suggested_changes` per the parser's locked invariant.
+ * - `ESCALATE` — reviewer cannot decide confidently; surface to user.
+ */
+export type VerdictKind = 'APPROVE' | 'REJECT' | 'REVISE' | 'ESCALATE';
+/**
+ * Newtype-equivalent for `ReviewerVerdict.verdict_id`. Mirrors Rust's
+ * `VerdictId(pub Uuid)` with `#[serde(transparent)]` — wire form is just the
+ * UUID string, no envelope.
+ */
+export type VerdictId = string;
+/**
+ * One reviewer's verdict at one gate. Records reasoning plus perf/cost
+ * metadata for telemetry (review latency, token cost per task, etc.).
+ *
+ * `gate_id` is a plain UUID string (matches Rust's `Uuid` field — the engine
+ * wraps this in its own `GateId` newtype, but the reviewer crate stays
+ * agnostic to avoid an engine→reviewer→engine cycle).
+ *
+ * # Identity
+ *
+ * Per Phase 2f.0.a's seat/role pivot, verdicts are keyed on `seat_id` +
+ * `role`, NOT on `reviewer_agent`. Consensus dedup + audit attribution
+ * happen via `seat_id`; `reviewer_agent` stays for cost-attribution metadata
+ * only and is NOT a uniqueness key (two seats may share an agent in the
+ * single-vendor case).
+ *
+ * Field ordering + names match the Rust struct verbatim — the audit chain's
+ * SHA-256 hashes serialised JSON, so any change to field order or naming
+ * would invalidate every prior chain entry. Append-only after launch.
+ */
+export interface ReviewerVerdict {
+    /** Primary key. UUID v4 string. */
+    verdict_id: VerdictId;
+    /** Foreign key to `ReviewGate`. Plain UUID string per the reviewer crate's
+     *  agnostic-to-engine design. */
+    gate_id: string;
+    /** Seat that produced the verdict. Primary identity key for dedup +
+     *  audit attribution. Providers MUST copy this from `ReviewerSpec.seat_id`. */
+    seat_id: number;
+    /** Lens the seat reviewed through. Copied from `ReviewerSpec.role` verbatim. */
+    role: ReviewerRole;
+    /** Agent that produced the verdict. Descriptive metadata (cost attribution,
+     *  per-agent reliability); NOT an identity key. */
+    reviewer_agent: AgentKind;
+    /** The verdict itself. */
+    verdict: VerdictKind;
+    /** Reviewer's free-form reasoning. */
+    reasoning: string;
+    /** Ordered list of specific changes. **Required** when `verdict === 'REVISE'`;
+     *  empty for other verdicts (enforced by the output parser). */
+    suggested_changes: string[];
+    /** Model identifier used (for cost attribution). */
+    model_used: string | null;
+    /** Tokens consumed by this reviewer. */
+    tokens_used: number | null;
+    /** End-to-end latency for this reviewer's verdict (ms). */
+    latency_ms: number | null;
+    /** ISO 8601 UTC timestamp string when the reviewer returned the verdict. */
+    submitted_at: string;
+}

package/dist/types/index.d.ts

@@ -2,3 +2,4 @@ export * from './events';
 export * from './session';
 export * from './encryption';
 export * from './auth';
+export * from './reviewer';

package/dist/types/reviewer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Review lens a reviewer seat evaluates through. Mirrors
+ * codevibe-policy::ReviewerRole in the Rust engine.
+ *
+ * **Append-only post-launch** per the 2026-04-23 memory lock — these
+ * string values are cryptographically bound into the audit hash chain
+ * once used. Renaming or removing a value would break chain verification
+ * on every prior entry. Add new values freely; never rename or remove.
+ *
+ * UPPERCASE here (matches AppSync GraphQL enum convention). The Lambda
+ * translates to snake_case before writing to the audit chain / Rust
+ * engine wire.
+ */
+export declare enum ReviewerRole {
+    ARCHITECTURE = "ARCHITECTURE",
+    CORRECTNESS = "CORRECTNESS",
+    SECURITY = "SECURITY",
+    ACCURACY = "ACCURACY",
+    CLARITY = "CLARITY",
+    COMPLETENESS = "COMPLETENESS",
+    ARCHITECTURE_AND_ACCURACY = "ARCHITECTURE_AND_ACCURACY",
+    CORRECTNESS_AND_CLARITY = "CORRECTNESS_AND_CLARITY",
+    SECURITY_AND_COMPLETENESS = "SECURITY_AND_COMPLETENESS"
+}
+/**
+ * One seat in a user's reviewer panel. `seat_id` is the panel position
+ * (0-indexed: Pro has seats 0–1, Max has 0–2). `role` is the review lens
+ * — unique within a policy. `agent` (CLAUDE | GEMINI | CODEX) may repeat
+ * across seats — single-vendor users get multiple same-kind seats with
+ * distinct roles.
+ */
+export interface ReviewerAgentSpec {
+    seatId: number;
+    role: ReviewerRole;
+    agent: 'CLAUDE' | 'GEMINI' | 'CODEX';
+    modelHint?: string | null;
+}
+export interface ReviewerAgentSpecInput {
+    seatId: number;
+    role: ReviewerRole;
+    agent: 'CLAUDE' | 'GEMINI' | 'CODEX';
+    modelHint?: string | null;
+}
+/**
+ * Input for updateReviewerPolicy. Fields are independent:
+ * - orchestrationEnabledDefault: set to true/false to persist the user's
+ *   opt-in preference for new sessions. Null = leave unchanged.
+ * - reviewerSeats: non-empty array sets a custom panel. Empty array
+ *   resets to tier defaults. Null = leave unchanged.
+ */
+export interface UpdateReviewerPolicyInput {
+    orchestrationEnabledDefault?: boolean | null;
+    reviewerSeats?: ReviewerAgentSpecInput[] | null;
+}
+/**
+ * User record returned by updateAvailableAgents and updateReviewerPolicy.
+ * Subset of the full AppSync User type — only the fields the two mutations
+ * return. Use this in the AppSyncClient response typing, not as a general
+ * "User" replacement.
+ */
+export interface UserReviewerPolicySnapshot {
+    userId: string;
+    availableAgents?: Array<'CLAUDE' | 'GEMINI' | 'CODEX'> | null;
+    orchestrationEnabledDefault?: boolean | null;
+    reviewerSeats?: ReviewerAgentSpec[] | null;
+    updatedAt: string;
+}

package/dist/types/session.d.ts

@@ -32,6 +32,12 @@ export interface Session {
     creatorDeviceId?: string;
     encryptionVersion?: number;
     lastHeartbeatAt?: string;
+    /**
+     * Quorum 2.0 opt-in flag (2f.0.a.3). True routes the session to the
+     * 2.0 orchestration flow once 2f.3 Lambda is live; null/false keeps
+     * the 1.0 companion flow.
+     */
+    orchestrationEnabled?: boolean | null;
 }
 /**
  * GraphQL input for creating sessions
@@ -47,6 +53,11 @@ export interface CreateSessionInput {
     creatorDeviceId?: string;
     isEncrypted?: boolean;
     encryptionVersion?: number;
+    /**
+     * Quorum 2.0 (2f.0.a.3). Null/absent = server reads
+     * User.orchestrationEnabledDefault (option 6a auto-populate).
+     */
+    orchestrationEnabled?: boolean;
 }
 /**
  * GraphQL input for updating sessions
@@ -56,4 +67,9 @@ export interface UpdateSessionInput {
     status?: SessionStatus;
     metadata?: Record<string, any>;
     lastHeartbeatAt?: string;
+    /**
+     * Quorum 2.0 (2f.0.a.3). Per-session override for the orchestration
+     * opt-in. Plugin CLI --orchestration/--no-orchestration sets this.
+     */
+    orchestrationEnabled?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quantiya/codevibe-core",
-  "version": "1.0.17",
+  "version": "2.0.0",
   "description": "Core library for CodeVibe plugins - shared keychain, crypto, AppSync, and auth functionality",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,9 @@
     "build": "rm -rf dist && npm run emit-types && esbuild src/index.ts --bundle --platform=node --target=node18 --minify --packages=external --outfile=dist/index.js",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build",
-    "test": "echo \"No tests yet\" && exit 0"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:live": "QUORUM_LIVE_SMOKE=1 vitest run"
   },
   "dependencies": {
     "uuid": "^9.0.0",
@@ -32,7 +34,8 @@
     "@types/uuid": "^9.0.0",
     "@types/ws": "^8.5.0",
     "esbuild": "^0.28.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^1.6.1"
   },
   "engines": {
     "node": ">=18.0.0"