@lcv-ideas-software/cross-review 4.0.0

package/dist/src/core/types.d.ts

@@ -0,0 +1,604 @@
+export declare const PEERS: readonly ["codex", "claude", "gemini", "deepseek", "grok", "perplexity"];
+export type PeerId = (typeof PEERS)[number];
+export declare const STATUSES: readonly ["READY", "NOT_READY", "NEEDS_EVIDENCE"];
+export type ReviewStatus = (typeof STATUSES)[number];
+export type Confidence = "verified" | "inferred" | "unknown";
+export type SessionOutcome = "converged" | "aborted" | "max-rounds";
+export type SessionMode = "ship" | "review" | "circular";
+export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type SessionControlStatus = "running" | "cancel_requested" | "cancelled" | "recovered_after_restart";
+export type DecisionQuality = "clean" | "format_warning" | "recovered" | "needs_operator_review" | "failed";
+export interface ModelCandidate {
+    id: string;
+    display_name?: string;
+    source: "api" | "documented-priority" | "env-override";
+    metadata?: Record<string, unknown>;
+}
+export interface ModelSelection {
+    peer: PeerId;
+    selected: string;
+    candidates: ModelCandidate[];
+    source_url: string;
+    reason: string;
+    confidence: Confidence;
+}
+export interface TokenUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    reasoning_tokens?: number;
+    cache_read_tokens?: number;
+    cache_write_tokens?: number;
+    cache_provider_mode?: "auto" | "explicit" | "implicit" | "not_supported";
+    cache_key_hash?: string;
+    citation_tokens?: number;
+    num_search_queries?: number;
+    provider_reported_total_cost_usd?: number;
+    search_performed?: boolean;
+}
+export interface CostEstimate {
+    currency: "USD";
+    input_cost?: number;
+    output_cost?: number;
+    total_cost?: number;
+    estimated: boolean;
+    source: "configured-rate" | "unknown-rate" | "stub";
+    cache_savings_usd?: number;
+    cache_savings_unknown?: boolean;
+    cache_read_cost?: number;
+    cache_write_cost?: number;
+    tier_used?: "base" | "extended" | "promo" | "promo_extended";
+    request_cost?: number;
+    citation_tokens_cost?: number;
+    deep_research_reasoning_tokens_cost?: number;
+    search_queries_cost?: number;
+}
+export interface CacheManifestEntry {
+    ts: string;
+    round: number;
+    peer: PeerId;
+    provider: string;
+    model: string;
+    cache_key_hash: string;
+    cache_provider_mode: "auto" | "explicit" | "implicit" | "not_supported";
+    read_tokens?: number;
+    write_tokens?: number;
+    hit: boolean;
+    latency_ms: number;
+    estimated_savings_usd?: number;
+    savings_unknown?: boolean;
+}
+export interface CacheManifest {
+    session_id: string;
+    cache_schema_version: string;
+    created_at: string;
+    updated_at: string;
+    entries: CacheManifestEntry[];
+}
+export interface PeerStructuredStatus {
+    status: ReviewStatus;
+    summary?: string;
+    confidence?: Confidence;
+    evidence_sources?: string[];
+    caller_requests?: string[];
+    follow_ups?: string[];
+}
+export interface PeerResult {
+    peer: PeerId;
+    provider: string;
+    model: string;
+    model_reported?: string;
+    model_match?: boolean;
+    status: ReviewStatus | null;
+    structured: PeerStructuredStatus | null;
+    text: string;
+    raw: unknown;
+    usage?: TokenUsage;
+    cost?: CostEstimate;
+    latency_ms: number;
+    attempts: number;
+    parser_warnings: string[];
+    decision_quality: DecisionQuality;
+    fallback?: FallbackEvent;
+}
+export interface GenerationResult {
+    peer: PeerId;
+    provider: string;
+    model: string;
+    model_reported?: string;
+    model_match?: boolean;
+    text: string;
+    raw: unknown;
+    usage?: TokenUsage;
+    cost?: CostEstimate;
+    latency_ms: number;
+    attempts: number;
+    fallback?: FallbackEvent;
+    parser_warnings?: string[];
+}
+export interface FallbackEvent {
+    peer: PeerId;
+    provider: string;
+    from_model: string;
+    to_model: string;
+    reason: string;
+    ts: string;
+}
+export interface PeerFailure {
+    peer: PeerId;
+    provider: string;
+    model?: string;
+    failure_class: "auth" | "rate_limit" | "prompt_flagged_by_moderation" | "silent_model_downgrade" | "provider_error" | "network" | "timeout" | "schema" | "unparseable_after_recovery" | "budget_exceeded" | "budget_preflight" | "cancelled" | "fallback_exhausted" | "format_recovery_exhausted" | "stream_buffer_overflow" | "unknown";
+    message: string;
+    retryable: boolean;
+    recovery_hint?: "wait_and_retry" | "reformulate_and_retry" | "consult_docs_then_revise";
+    reformulation_advice?: string;
+    retry_after_ms?: number;
+    attempts: number;
+    latency_ms: number;
+    docs_hint?: {
+        parameter: string;
+        docs_url?: string;
+    };
+}
+export interface InFlightRound {
+    round: number;
+    peers: PeerId[];
+    started_at: string;
+    status: "running";
+}
+export interface ConvergenceScope {
+    petitioner?: PeerId | "operator";
+    caller: PeerId | "operator";
+    acting_peer?: PeerId | "operator";
+    caller_status: ReviewStatus;
+    expected_peers: PeerId[];
+    reviewer_peers: PeerId[];
+    lead_peer?: PeerId;
+    lead_peer_role?: "relator_non_voting";
+    voting_peers?: PeerId[];
+    quorum_basis?: "all_non_lead_panel_peers_ready" | "all_panel_peers_ready";
+    anti_self_review_exclusion_reason?: "lead_peer_authored_or_revised_artifact_under_review";
+    skipped_peers?: PeerId[];
+}
+export interface ConvergenceHealth {
+    state: "idle" | "running" | "converged" | "blocked" | "stale";
+    last_event_at: string;
+    detail: string;
+    idle_ms?: number;
+}
+export interface EvidenceAttachment {
+    ts: string;
+    label: string;
+    path: string;
+    content_type?: string;
+}
+export type EvidenceChecklistStatus = "open" | "addressed" | "not_resurfaced" | "satisfied" | "deferred" | "rejected";
+export interface EvidenceChecklistItem {
+    id: string;
+    peer: PeerId;
+    first_round: number;
+    last_round: number;
+    round_count: number;
+    ask: string;
+    first_seen_at: string;
+    last_seen_at: string;
+    status?: EvidenceChecklistStatus;
+    addressed_at_round?: number;
+    address_method?: "resurfacing" | "judge";
+    judge_rationale?: string;
+}
+export interface EvidenceStatusHistoryEntry {
+    ts: string;
+    item_id: string;
+    from: EvidenceChecklistStatus;
+    to: EvidenceChecklistStatus;
+    by: "runtime" | "operator";
+    round?: number;
+    note?: string;
+}
+export interface GenerationArtifact {
+    ts: string;
+    round: number;
+    label: string;
+    peer: PeerId;
+    path: string;
+    usage?: TokenUsage;
+    cost?: CostEstimate;
+    latency_ms?: number;
+}
+export interface OperatorEscalation {
+    ts: string;
+    reason: string;
+    severity: "info" | "warning" | "critical";
+}
+export interface SessionControl {
+    status: SessionControlStatus;
+    reason?: string;
+    job_id?: string;
+    requested_at?: string;
+    updated_at: string;
+}
+export interface RuntimeCapabilities {
+    stable_release: boolean;
+    api_only: boolean;
+    cli_execution: false;
+    durable_sessions: true;
+    async_jobs: true;
+    cancellation: true;
+    restart_recovery: true;
+    event_streaming: true;
+    token_streaming: boolean;
+    budget_preflight: true;
+    model_fallback: boolean;
+    metrics: true;
+}
+export interface PeerAdapter {
+    id: PeerId;
+    provider: string;
+    model: string;
+    call(prompt: string, context: PeerCallContext): Promise<PeerResult>;
+    generate(prompt: string, context: PeerCallContext): Promise<GenerationResult>;
+    judgeEvidenceAsk(ask: string, draft: string, context: PeerCallContext): Promise<EvidenceAskJudgment>;
+    probe(): Promise<PeerProbeResult>;
+}
+export interface EvidenceAskJudgment {
+    peer: PeerId;
+    provider: string;
+    model: string;
+    satisfied: boolean;
+    confidence: Confidence;
+    rationale: string;
+    raw: unknown;
+    usage?: TokenUsage;
+    cost?: CostEstimate;
+    latency_ms: number;
+    attempts: number;
+    parser_warnings: string[];
+}
+export interface PeerCallContext {
+    session_id: string;
+    round: number;
+    task: string;
+    signal?: AbortSignal;
+    stream?: boolean;
+    stream_tokens?: boolean;
+    emit(event: RuntimeEvent): void;
+    reasoning_effort_override?: ReasoningEffort;
+    caller?: PeerId | "operator";
+}
+export interface PeerProbeResult {
+    peer: PeerId;
+    provider: string;
+    model: string;
+    available: boolean;
+    auth_present: boolean;
+    latency_ms: number;
+    model_selection?: ModelSelection;
+    message?: string;
+}
+export interface RuntimeEvent {
+    seq?: number;
+    type: string;
+    ts?: string;
+    session_id?: string;
+    round?: number;
+    peer?: PeerId;
+    message?: string;
+    data?: Record<string, unknown>;
+}
+export interface SessionEvent extends RuntimeEvent {
+    seq: number;
+}
+export interface SessionMeta {
+    session_id: string;
+    version: string;
+    created_at: string;
+    updated_at: string;
+    task: string;
+    review_focus?: string;
+    caller: PeerId | "operator";
+    outcome?: SessionOutcome;
+    outcome_reason?: string;
+    capability_snapshot: PeerProbeResult[];
+    in_flight?: InFlightRound;
+    convergence_scope?: ConvergenceScope;
+    convergence_health?: ConvergenceHealth;
+    failed_attempts?: Array<PeerFailure & {
+        round: number;
+    }>;
+    evidence_files?: EvidenceAttachment[];
+    evidence_checklist?: EvidenceChecklistItem[];
+    evidence_status_history?: EvidenceStatusHistoryEntry[];
+    generation_files?: GenerationArtifact[];
+    operator_escalations?: OperatorEscalation[];
+    control?: SessionControl;
+    fallback_events?: FallbackEvent[];
+    rounds: ReviewRound[];
+    totals: {
+        usage: TokenUsage;
+        cost: CostEstimate;
+    };
+    contestation?: {
+        contested_at: string;
+        reason: string;
+        original_outcome: SessionOutcome | null;
+        new_session_id: string;
+    };
+    contests_session_id?: string;
+    circular_state?: {
+        rotation_order: PeerId[];
+        consecutive_no_change_count: number;
+        last_revision_round: number | null;
+    };
+    cost_ceiling_usd?: number | null;
+    costs_per_round?: number[];
+    budget_warning_emitted?: boolean;
+    requested_max_cost_usd?: number | null;
+    effective_cost_ceiling_usd?: number | null;
+    cost_ceiling_source?: "call_arg" | "env_default" | "config_default";
+    requested_max_rounds?: number | null;
+    effective_max_rounds?: number | null;
+}
+export interface ReviewRound {
+    round: number;
+    started_at: string;
+    completed_at?: string;
+    caller_status: ReviewStatus;
+    draft_file?: string;
+    prompt_file: string;
+    peers: PeerResult[];
+    rejected: PeerFailure[];
+    convergence: ConvergenceResult;
+}
+export interface ConvergenceResult {
+    converged: boolean;
+    reason: string;
+    latest_round_converged?: boolean;
+    session_quorum_converged?: boolean;
+    recovery_converged?: boolean;
+    quorum_peers?: PeerId[];
+    ready_peers: PeerId[];
+    not_ready_peers: PeerId[];
+    needs_evidence_peers: PeerId[];
+    rejected_peers: PeerId[];
+    skipped_peers: PeerId[];
+    decision_quality: Record<PeerId, DecisionQuality>;
+    blocking_details: string[];
+}
+export interface AppConfig {
+    version: string;
+    data_dir: string;
+    log_level: string;
+    stub: boolean;
+    dashboard_port: number;
+    retry: {
+        max_attempts: number;
+        base_delay_ms: number;
+        max_delay_ms: number;
+        timeout_ms: number;
+    };
+    budget: {
+        max_session_cost_usd?: number;
+        until_stopped_max_cost_usd?: number;
+        preflight_max_round_cost_usd?: number;
+        require_rates_for_budget: boolean;
+        default_max_rounds: number;
+        circular_max_rotations: number;
+    };
+    prompt: {
+        max_task_chars: number;
+        max_review_focus_chars: number;
+        max_history_chars: number;
+        max_draft_chars: number;
+        max_prior_rounds: number;
+        max_peer_requests: number;
+        max_attached_evidence_chars: number;
+    };
+    max_output_tokens: number;
+    evidence_preflight_enabled: boolean;
+    streaming: {
+        events: boolean;
+        tokens: boolean;
+        include_text: boolean;
+    };
+    models: Record<PeerId, string>;
+    fallback_models: Partial<Record<PeerId, string[]>>;
+    reasoning_effort: Partial<Record<PeerId, ReasoningEffort>>;
+    model_selection: Partial<Record<PeerId, ModelSelection>>;
+    api_keys: Record<PeerId, string | undefined>;
+    cost_rates: Partial<Record<PeerId, {
+        input_per_million: number;
+        output_per_million: number;
+        input_extended_per_million?: number;
+        output_extended_per_million?: number;
+        cache_read_per_million?: number;
+        cache_write_per_million?: number;
+        cache_read_extended_per_million?: number;
+        cache_write_extended_per_million?: number;
+        promo_input_per_million?: number;
+        promo_output_per_million?: number;
+        promo_input_extended_per_million?: number;
+        promo_output_extended_per_million?: number;
+        promo_cache_read_per_million?: number;
+        promo_cache_write_per_million?: number;
+        promo_cache_read_extended_per_million?: number;
+        promo_cache_write_extended_per_million?: number;
+        promo_expires_at?: string;
+        threshold_tokens?: number;
+        request_fee_low_per_1000?: number;
+        request_fee_medium_per_1000?: number;
+        request_fee_high_per_1000?: number;
+        citation_tokens_per_million?: number;
+        deep_research_reasoning_tokens_per_million?: number;
+        search_queries_per_1000?: number;
+    }>>;
+    evidence_judge_autowire: EvidenceJudgeAutowireConfig;
+    peer_enabled: Record<PeerId, boolean>;
+    cache: {
+        schema_version: string;
+        enabled: boolean;
+        ttl: {
+            anthropic: "5m" | "1h";
+            openai: "5m" | "1h";
+        };
+        disable_per_peer: Record<PeerId, boolean>;
+    };
+    perplexity: {
+        search_context_size: "low" | "medium" | "high";
+        disable_search: boolean;
+    };
+}
+export type EvidenceJudgeAutowireMode = "off" | "shadow" | "active";
+export interface EvidenceJudgeAutowireConfig {
+    mode: EvidenceJudgeAutowireMode | string;
+    peer: PeerId | undefined;
+    active: boolean;
+    max_items_per_pass: number;
+    configured_mode_raw: string;
+    configured_peer_raw: string;
+    consensus_peers: PeerId[];
+    configured_consensus_peers_raw: string;
+}
+export interface PeerHealthSummary {
+    peer: PeerId;
+    results_total: number;
+    ready_count: number;
+    not_ready_count: number;
+    needs_evidence_count: number;
+    unresolved_count: number;
+    ready_rate: number;
+    needs_evidence_rate: number;
+    avg_cost_usd: number | null;
+    total_cost_usd: number | null;
+    parser_warnings_total: number;
+    rejected_total: number;
+    failures_by_class: Partial<Record<PeerFailure["failure_class"], number>>;
+}
+export interface ShadowJudgmentRollup {
+    decisions_total: number;
+    would_promote_total: number;
+    by_judge_peer: Partial<Record<PeerId, ShadowJudgmentPeerStats>>;
+}
+export interface JudgmentPrecisionPeerStats {
+    judge_peer: PeerId;
+    decisions_total: number;
+    decisions_with_ground_truth: number;
+    decisions_skipped_no_ground_truth: number;
+    true_positive: number;
+    false_positive: number;
+    true_negative: number;
+    false_negative: number;
+    precision: number | null;
+    recall: number | null;
+    f1: number | null;
+    by_confidence: Partial<Record<Confidence, {
+        tp: number;
+        fp: number;
+        tn: number;
+        fn: number;
+    }>>;
+}
+export interface JudgmentPrecisionReport {
+    generated_at: string;
+    peer_filter?: PeerId;
+    since_filter?: string;
+    session_filter?: string;
+    decisions_total: number;
+    decisions_with_ground_truth: number;
+    decisions_skipped_no_ground_truth: number;
+    by_judge_peer: Partial<Record<PeerId, JudgmentPrecisionPeerStats>>;
+}
+export interface ShadowJudgmentPeerStats {
+    judge_peer: PeerId;
+    decisions_total: number;
+    would_promote: number;
+    would_skip_satisfied_unverified: number;
+    would_skip_not_satisfied: number;
+    by_confidence: Partial<Record<Confidence, number>>;
+    first_seen_at: string | null;
+    last_seen_at: string | null;
+}
+export interface RuntimeMetrics {
+    generated_at: string;
+    scope: "all" | "session";
+    session_id?: string;
+    sessions: {
+        total: number;
+        converged: number;
+        aborted: number;
+        max_rounds: number;
+        unfinished: number;
+    };
+    rounds: number;
+    peer_results: Partial<Record<PeerId, number>>;
+    peer_failures: Partial<Record<PeerFailure["failure_class"], number>>;
+    decision_quality: Partial<Record<DecisionQuality, number>>;
+    moderation_recoveries: number;
+    fallback_events: number;
+    total_usage: TokenUsage;
+    total_cost: CostEstimate;
+    latency_ms: {
+        peer_average: number | null;
+        generation_average: number | null;
+    };
+    per_peer_health: Partial<Record<PeerId, PeerHealthSummary>>;
+    shadow_judgment: ShadowJudgmentRollup;
+}
+export interface SessionDoctorEntry {
+    session_id: string;
+    version?: string;
+    caller?: PeerId | "operator";
+    petitioner?: PeerId | "operator";
+    lead_peer?: PeerId;
+    outcome?: SessionOutcome;
+    outcome_reason?: string;
+    health_state?: ConvergenceHealth["state"];
+    health_detail?: string;
+    rounds: number;
+    updated_at: string;
+    open_evidence_items?: number;
+    grok_provider_errors?: number;
+    event_read_error?: string;
+    item_types?: Partial<Record<PeerId, number>>;
+    chronic_blockers?: string[];
+}
+export interface SessionDoctorReport {
+    generated_at: string;
+    scope: "all";
+    limit: number;
+    totals: {
+        sessions: number;
+        open: number;
+        stale: number;
+        blocked: number;
+        max_rounds: number;
+        self_lead_metadata: number;
+        open_evidence_sessions: number;
+        grok_provider_error_sessions: number;
+        event_read_error_sessions: number;
+    };
+    findings: {
+        open_sessions: SessionDoctorEntry[];
+        stale_sessions: SessionDoctorEntry[];
+        blocked_sessions: SessionDoctorEntry[];
+        max_rounds_sessions: SessionDoctorEntry[];
+        self_lead_metadata: SessionDoctorEntry[];
+        open_evidence_sessions: SessionDoctorEntry[];
+        grok_provider_error_sessions: SessionDoctorEntry[];
+        event_read_error_sessions: SessionDoctorEntry[];
+    };
+    event_noise: {
+        events_total: number;
+        token_delta_events: number;
+        token_completed_events: number;
+        token_delta_ratio: number | null;
+    };
+    recommendations: string[];
+    repaired?: Array<{
+        session_id: string;
+        from_health_state: ConvergenceHealth["state"] | undefined;
+        to_health_state: ConvergenceHealth["state"];
+        reason: string;
+    }>;
+}

package/dist/src/core/types.js

@@ -0,0 +1,36 @@
+// v2.14.0 (item 5, operator directive 2026-05-04): Grok joined the
+// quarteto, making it a quinteto. Per `project_cross_review_v2_grok_integration_pending.md`,
+// xAI's Grok uses the OpenAI Responses API surface at base URL
+// `https://api.x.ai/v1`. Auth is via GROK_API_KEY. Operators may choose
+// `grok-4-latest` / `grok-4.3` (xAI automatic reasoning, no
+// reasoning.effort body field) or `grok-4.20-multi-agent` (explicit
+// reasoning.effort supported).
+// Adapter at `peers/grok.ts` inherits the same Responses API code path
+// the OpenAI adapter uses.
+//
+// v3.0.0 (operator directive 2026-05-12): Perplexity joined the
+// quinteto, making it a sexteto. Per
+// `project_cross_review_v2_v300_perplexity_sixth_peer.md`, Perplexity's
+// Sonar API is OpenAI-Chat-Completions-compatible but lives at a
+// distinct endpoint `https://api.perplexity.ai/v1/sonar`. Auth is via
+// PERPLEXITY_API_KEY. Operators may choose `sonar` / `sonar-pro` /
+// `sonar-reasoning-pro` (default; reasoning + grounding) /
+// `sonar-deep-research` (multi-hop research; minutes per call).
+// Distinct architectural traits vs the other 5 peers: (1) EVERY call
+// performs web search by default — peer becomes a real-time fact-check
+// channel; (2) system prompts ONLY shape tone/style of the final
+// answer — the search component does not attend to them; (3) pricing
+// has a third dimension (per-1000-request fee that scales with
+// `search_context_size` low/medium/high) beyond input/output tokens;
+// (4) usage.cost is reported per-call by the API in USD breakdown
+// (a built-in we read directly for FinOps reconciliation, distinct
+// from the config-driven cost layer); (5) `reasoning_effort` enum is
+// `minimal|low|medium|high` only (no `xhigh`/`max`/`none`). All 6
+// peers remain symmetric in role assignment — caller / lead_peer /
+// reviewer — only the workspace HARD GATE rules apply uniformly
+// (caller != lead_peer != reviewer).
+// Adapter at `peers/perplexity.ts` reuses the shared `loadOpenAICtor`
+// helper introduced in v2.27.1.
+export const PEERS = ["codex", "claude", "gemini", "deepseek", "grok", "perplexity"];
+export const STATUSES = ["READY", "NOT_READY", "NEEDS_EVIDENCE"];
+//# sourceMappingURL=types.js.map

package/dist/src/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/types.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,6FAA6F;AAC7F,+DAA+D;AAC/D,wEAAwE;AACxE,4DAA4D;AAC5D,oEAAoE;AACpE,+BAA+B;AAC/B,uEAAuE;AACvE,2BAA2B;AAC3B,EAAE;AACF,gEAAgE;AAChE,qCAAqC;AACrC,wEAAwE;AACxE,iEAAiE;AACjE,sEAAsE;AACtE,mEAAmE;AACnE,2DAA2D;AAC3D,gEAAgE;AAChE,qEAAqE;AACrE,uEAAuE;AACvE,iEAAiE;AACjE,qEAAqE;AACrE,+DAA+D;AAC/D,qEAAqE;AACrE,kEAAkE;AAClE,mEAAmE;AACnE,qEAAqE;AACrE,kEAAkE;AAClE,mEAAmE;AACnE,gEAAgE;AAChE,qCAAqC;AACrC,sEAAsE;AACtE,gCAAgC;AAChC,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,CAAU,CAAC;AAG9F,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,gBAAgB,CAAU,CAAC"}

package/dist/src/dashboard/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};