nexus-agents 2.151.0 → 2.152.0

package/dist/consensus-vote-types-B06ynHGk.d.ts

@@ -0,0 +1,841 @@
+import { z } from 'zod';
+
+/**
+ * nexus-agents/config - Model Capabilities Type Definitions
+ *
+ * Zod schemas and TypeScript interfaces for the model capabilities matrix.
+ * Defines output/input modalities, tool support, and special features
+ * for each supported AI model.
+ *
+ * @module config/model-capabilities-types
+ * (Source: Issue #683, Epic #682)
+ */
+
+/** Output modalities a model can produce. */
+declare const OUTPUT_MODALITIES: readonly ["text", "image_png", "image_jpeg", "audio_pcm", "audio_wav", "audio_mp3", "video_mp4", "svg", "structured_json", "code"];
+type OutputModality = (typeof OUTPUT_MODALITIES)[number];
+/** Input modalities a model can accept. */
+declare const INPUT_MODALITIES: readonly ["text", "image", "audio", "video", "pdf", "code"];
+type InputModality = (typeof INPUT_MODALITIES)[number];
+/** Tool capabilities a model supports. */
+declare const TOOL_CAPABILITIES: readonly ["mcp", "function_calling", "computer_use", "code_execution_sandbox", "web_search", "file_operations", "structured_output", "apply_patch"];
+type ToolCapability = (typeof TOOL_CAPABILITIES)[number];
+/** Special features beyond standard text generation. */
+declare const SPECIAL_FEATURES: readonly ["extended_thinking", "deep_research", "streaming", "grounding", "citations", "image_editing", "voice_cloning", "live_api", "context_caching"];
+type SpecialFeature = (typeof SPECIAL_FEATURES)[number];
+/** CLI tool names supported by the routing system. */
+declare const CLI_NAMES: readonly ["claude", "gemini", "codex", "opencode"];
+type CliNameLiteral = (typeof CLI_NAMES)[number];
+/**
+ * Canonical model id enum used for narrow `ModelId` typing and as the
+ * argument to `z.enum(MODEL_IDS)` in `ModelCapabilitySchema`.
+ *
+ * This is a hand-maintained narrow tuple rather than a derived view
+ * from `ModelRegistry` because the literal-union type is load-bearing:
+ * — Zod schemas (`ModelCapabilitySchema.id`, `replacedBy`) need a
+ *   closed enum at compile time.
+ * — Many function signatures across `src/` accept `ModelId` and rely
+ *   on the narrowed type for exhaustiveness.
+ *
+ * The runtime invariant — `MODEL_IDS` matches the in-tree registry
+ * entries — is asserted by `model-ids-invariant.test.ts`. If you add
+ * or remove a model in `DEFAULT_MODEL_CAPABILITIES.models`, you must
+ * also update this list (and the test will tell you when they drift).
+ *
+ * Slice E of #2546 will collapse `model-capabilities.ts` itself; at
+ * that point `MODEL_IDS` either moves to `model-config-helpers.ts` or
+ * its consumers are loosened to `string`. This narrow type stays
+ * until then.
+ */
+declare const MODEL_IDS: readonly ["claude-opus", "claude-sonnet", "claude-haiku", "gemini-3-pro", "gemini-pro", "gemini-3-flash", "gemini-flash", "codex-5.3", "codex-5.2", "codex-5.1-mini", "opencode-default", "opencode-custom-opus", "opencode-custom-sonnet", "openrouter-nemotron-super", "openrouter-qwen-coder"];
+type ModelId = (typeof MODEL_IDS)[number];
+/** Quality scores for model capability routing (0-10 scale). */
+declare const QualityScoresSchema: z.ZodObject<{
+    reasoning: z.ZodNumber;
+    codeGeneration: z.ZodNumber;
+    speed: z.ZodNumber;
+    cost: z.ZodNumber;
+}, z.core.$strip>;
+type QualityScores = z.infer<typeof QualityScoresSchema>;
+/** Pricing information (USD per 1M tokens). */
+declare const PricingSchema: z.ZodObject<{
+    inputPer1M: z.ZodNumber;
+    outputPer1M: z.ZodNumber;
+}, z.core.$strip>;
+type Pricing = z.infer<typeof PricingSchema>;
+
+/**
+ * decision-cost — per-DECISION cost aggregation over a governed panel's voters.
+ *
+ * Source: Issue #3855 (epic #3854 child, M4).
+ *
+ * A governed decision — a `consensus_vote` or `pr_review` run — fans out to N
+ * voter calls; each voter is one LLM call. Per-CALL usage telemetry already
+ * exists ({@link module:learning/usage-log} — token + cost per model call,
+ * PR #2479/#2480 era). This module is the AGGREGATION layer that rolls those
+ * per-call numbers UP into a single per-decision answer: "what did this
+ * governed decision cost?".
+ *
+ * It is a PURE rollup (no I/O, no clock, no env reads at the math layer):
+ * {@link rollupDecisionCost} takes the per-voter cost inputs + the billing mode
+ * and returns a {@link DecisionCostSummary} — total tokens, total USD, a
+ * per-voter breakdown, and a per-model breakdown. Persistence + the live
+ * `process.env` billing-mode read live in the callers (the store + the tools),
+ * mirroring the usage-log split between `computeCostUSD` (pure) and
+ * `recordUsageEvent` (I/O).
+ *
+ * Design decisions that the fixture tests pin (#3855 acceptance criteria):
+ *
+ *  - **Missing cost is UNMEASURED, not zero.** A voter with no token counts
+ *    (e.g. a CLI-subscription adapter that doesn't report usage, or an error
+ *    vote that never reached the model) is counted in `unmeasuredVoters` and
+ *    contributes 0 to the totals — but the summary records that the total is a
+ *    floor, not an exact figure (`measured` < `voterCount`). Treating unmeasured
+ *    as a true $0 would silently understate spend; this keeps the honesty.
+ *  - **Plan mode records 0-cost but keeps tokens.** Under `NEXUS_BILLING_MODE=plan`
+ *    the spend is pre-covered by a subscription, so cost is recorded as $0 while
+ *    token counts are preserved (so the operator can still see consumption and
+ *    a later `api`-mode reprice is possible). This mirrors how plan mode zeroes
+ *    cost in routing/scoring without dropping the token signal.
+ *
+ * @module observability/decision-cost
+ */
+
+/** Billing mode in effect for a decision. Mirrors `NEXUS_BILLING_MODE`. */
+type DecisionBillingMode = 'plan' | 'api';
+/** Per-voter line in the decision rollup. */
+interface VoterCostBreakdown {
+    readonly role: string;
+    readonly model: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    /** Effective cost after billing-mode application (0 in plan mode). */
+    readonly costUsd: number;
+    /**
+     * True when this voter reported NO usage at all (no tokens, no cost). Its
+     * zeros are placeholders, not a measured $0 / 0-token call.
+     */
+    readonly unmeasured: boolean;
+}
+/** Per-model rollup line within a single decision. */
+interface ModelCostBreakdown {
+    readonly model: string;
+    readonly voterCount: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly costUsd: number;
+}
+/**
+ * The per-decision cost rollup. Totals are a FLOOR when `unmeasuredVoters > 0`
+ * — read alongside `measuredVoters` / `voterCount` for the confidence.
+ */
+interface DecisionCostSummary {
+    /** Billing mode applied to produce `totalCostUsd` (and per-line `costUsd`). */
+    readonly billingMode: DecisionBillingMode;
+    /** Total voters folded into this decision. */
+    readonly voterCount: number;
+    /** Voters that reported usage (tokens and/or cost). */
+    readonly measuredVoters: number;
+    /** Voters that reported no usage at all (counted, not zeroed-as-fact). */
+    readonly unmeasuredVoters: number;
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly totalTokens: number;
+    /**
+     * Total cost in USD. 0 under `plan` mode by construction. A FLOOR when
+     * `unmeasuredVoters > 0` (unmeasured voters contribute 0, not their unknown
+     * real cost).
+     */
+    readonly totalCostUsd: number;
+    /** Per-voter breakdown, in input order. */
+    readonly perVoter: readonly VoterCostBreakdown[];
+    /** Per-model breakdown, sorted by total cost desc then total tokens desc. */
+    readonly perModel: readonly ModelCostBreakdown[];
+}
+
+/**
+ * nexus-agents/consensus - Core Type Definitions
+ *
+ * Core type definitions and Zod schemas for the consensus engine.
+ * Supports multiple voting strategies for multi-agent decisions.
+ */
+
+/**
+ * Consensus algorithm types.
+ * - simple_majority: >50% of votes required
+ * - supermajority: >=67% of votes required
+ * - unanimous: 100% approval required
+ * - proof_of_learning: weighted voting based on agent performance
+ * - opinion_wise: higher-order voting with correlation awareness (Issue #333)
+ * - higher_order: alias for opinion_wise (Issue #514)
+ */
+declare const ConsensusAlgorithmSchema: z.ZodEnum<{
+    simple_majority: "simple_majority";
+    supermajority: "supermajority";
+    unanimous: "unanimous";
+    proof_of_learning: "proof_of_learning";
+    opinion_wise: "opinion_wise";
+    higher_order: "higher_order";
+}>;
+type ConsensusAlgorithm = z.infer<typeof ConsensusAlgorithmSchema>;
+/**
+ * Vote decision options.
+ */
+declare const VoteDecisionSchema: z.ZodEnum<{
+    approve: "approve";
+    reject: "reject";
+    abstain: "abstain";
+}>;
+type VoteDecision = z.infer<typeof VoteDecisionSchema>;
+/**
+ * Proposal status in the lifecycle.
+ */
+declare const ProposalStatusSchema: z.ZodEnum<{
+    timeout: "timeout";
+    closed: "closed";
+    rejected: "rejected";
+    pending: "pending";
+    voting: "voting";
+    approved: "approved";
+}>;
+type ProposalStatus = z.infer<typeof ProposalStatusSchema>;
+/**
+ * Structured rejection feedback categories (Issue #1213).
+ * Enables reject→refine→re-vote feedback loops by classifying rejection reasons.
+ */
+declare const RejectionCategorySchema: z.ZodEnum<{
+    YAGNI: "YAGNI";
+    DRY_VIOLATION: "DRY_VIOLATION";
+    OVER_ENGINEERING: "OVER_ENGINEERING";
+    SCOPE_CREEP: "SCOPE_CREEP";
+    SECURITY_RISK: "SECURITY_RISK";
+    MISALIGNED: "MISALIGNED";
+    INSUFFICIENT_EVIDENCE: "INSUFFICIENT_EVIDENCE";
+}>;
+type RejectionCategory = z.infer<typeof RejectionCategorySchema>;
+/**
+ * All valid rejection category values, for runtime reference.
+ */
+declare const REJECTION_CATEGORIES: ("YAGNI" | "DRY_VIOLATION" | "OVER_ENGINEERING" | "SCOPE_CREEP" | "SECURITY_RISK" | "MISALIGNED" | "INSUFFICIENT_EVIDENCE")[];
+/**
+ * A vote cast by an agent.
+ */
+declare const VoteSchema: z.ZodObject<{
+    decision: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+        abstain: "abstain";
+    }>;
+    reasoning: z.ZodString;
+    confidence: z.ZodNumber;
+    conditions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    rejectionCategories: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        YAGNI: "YAGNI";
+        DRY_VIOLATION: "DRY_VIOLATION";
+        OVER_ENGINEERING: "OVER_ENGINEERING";
+        SCOPE_CREEP: "SCOPE_CREEP";
+        SECURITY_RISK: "SECURITY_RISK";
+        MISALIGNED: "MISALIGNED";
+        INSUFFICIENT_EVIDENCE: "INSUFFICIENT_EVIDENCE";
+    }>>>;
+    findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        summary: z.ZodString;
+        location: z.ZodString;
+        severity: z.ZodDefault<z.ZodEnum<{
+            critical: "critical";
+            high: "high";
+            low: "low";
+            medium: "medium";
+        }>>;
+        gate: z.ZodObject<{
+            reread_cited_line: z.ZodDefault<z.ZodEnum<{
+                failed: "failed";
+                skipped: "skipped";
+                passed: "passed";
+            }>>;
+            traced_call_path: z.ZodDefault<z.ZodEnum<{
+                failed: "failed";
+                skipped: "skipped";
+                passed: "passed";
+            }>>;
+            named_assertion: z.ZodDefault<z.ZodString>;
+            ruled_out_language_non_issue: z.ZodDefault<z.ZodEnum<{
+                failed: "failed";
+                skipped: "skipped";
+                passed: "passed";
+            }>>;
+        }, z.core.$strip>;
+        claim: z.ZodString;
+    }, z.core.$strip>>>;
+    timestamp: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strip>;
+type Vote = z.infer<typeof VoteSchema>;
+/**
+ * A proposal submitted for consensus.
+ */
+declare const ProposalSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    description: z.ZodString;
+    algorithm: z.ZodEnum<{
+        simple_majority: "simple_majority";
+        supermajority: "supermajority";
+        unanimous: "unanimous";
+        proof_of_learning: "proof_of_learning";
+        opinion_wise: "opinion_wise";
+        higher_order: "higher_order";
+    }>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    requiredVoters: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    createdAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strip>;
+type Proposal = z.infer<typeof ProposalSchema>;
+/**
+ * Unique identifier for a proposal.
+ */
+type ProposalId = string;
+/**
+ * Vote counts summary.
+ */
+interface VoteCounts {
+    approve: number;
+    reject: number;
+    abstain: number;
+    total: number;
+}
+/**
+ * Weighted vote counts for proof-of-learning.
+ */
+interface WeightedVoteCounts {
+    approve: number;
+    reject: number;
+    abstain: number;
+    totalWeight: number;
+}
+/**
+ * Result of a consensus decision.
+ */
+interface ConsensusResult {
+    proposalId: ProposalId;
+    proposal: Proposal;
+    outcome: ProposalStatus;
+    votes: Map<string, Vote>;
+    voteCounts: VoteCounts;
+    weightedCounts?: WeightedVoteCounts | undefined;
+    approvalPercentage: number;
+    quorumReached: boolean;
+    startedAt: string;
+    closedAt: string;
+    durationMs: number;
+}
+/**
+ * Consensus result schema for validation.
+ */
+declare const ConsensusResultSchema: z.ZodObject<{
+    proposalId: z.ZodString;
+    proposal: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        description: z.ZodString;
+        algorithm: z.ZodEnum<{
+            simple_majority: "simple_majority";
+            supermajority: "supermajority";
+            unanimous: "unanimous";
+            proof_of_learning: "proof_of_learning";
+            opinion_wise: "opinion_wise";
+            higher_order: "higher_order";
+        }>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+        requiredVoters: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        createdAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strip>;
+    outcome: z.ZodEnum<{
+        timeout: "timeout";
+        closed: "closed";
+        rejected: "rejected";
+        pending: "pending";
+        voting: "voting";
+        approved: "approved";
+    }>;
+    votes: z.ZodMap<z.ZodString, z.ZodObject<{
+        decision: z.ZodEnum<{
+            approve: "approve";
+            reject: "reject";
+            abstain: "abstain";
+        }>;
+        reasoning: z.ZodString;
+        confidence: z.ZodNumber;
+        conditions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        rejectionCategories: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            YAGNI: "YAGNI";
+            DRY_VIOLATION: "DRY_VIOLATION";
+            OVER_ENGINEERING: "OVER_ENGINEERING";
+            SCOPE_CREEP: "SCOPE_CREEP";
+            SECURITY_RISK: "SECURITY_RISK";
+            MISALIGNED: "MISALIGNED";
+            INSUFFICIENT_EVIDENCE: "INSUFFICIENT_EVIDENCE";
+        }>>>;
+        findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            summary: z.ZodString;
+            location: z.ZodString;
+            severity: z.ZodDefault<z.ZodEnum<{
+                critical: "critical";
+                high: "high";
+                low: "low";
+                medium: "medium";
+            }>>;
+            gate: z.ZodObject<{
+                reread_cited_line: z.ZodDefault<z.ZodEnum<{
+                    failed: "failed";
+                    skipped: "skipped";
+                    passed: "passed";
+                }>>;
+                traced_call_path: z.ZodDefault<z.ZodEnum<{
+                    failed: "failed";
+                    skipped: "skipped";
+                    passed: "passed";
+                }>>;
+                named_assertion: z.ZodDefault<z.ZodString>;
+                ruled_out_language_non_issue: z.ZodDefault<z.ZodEnum<{
+                    failed: "failed";
+                    skipped: "skipped";
+                    passed: "passed";
+                }>>;
+            }, z.core.$strip>;
+            claim: z.ZodString;
+        }, z.core.$strip>>>;
+        timestamp: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+    voteCounts: z.ZodObject<{
+        approve: z.ZodNumber;
+        reject: z.ZodNumber;
+        abstain: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strip>;
+    weightedCounts: z.ZodOptional<z.ZodObject<{
+        approve: z.ZodNumber;
+        reject: z.ZodNumber;
+        abstain: z.ZodNumber;
+        totalWeight: z.ZodNumber;
+    }, z.core.$strip>>;
+    approvalPercentage: z.ZodNumber;
+    quorumReached: z.ZodBoolean;
+    startedAt: z.ZodISODateTime;
+    closedAt: z.ZodISODateTime;
+    durationMs: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Agent performance record for proof-of-learning.
+ */
+interface AgentPerformance {
+    agentId: string;
+    totalVotes: number;
+    correctVotes: number;
+    successRate: number;
+    lastUpdated: string;
+}
+/**
+ * Agent performance schema.
+ */
+declare const AgentPerformanceSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    totalVotes: z.ZodNumber;
+    correctVotes: z.ZodNumber;
+    successRate: z.ZodNumber;
+    lastUpdated: z.ZodISODateTime;
+}, z.core.$strip>;
+/**
+ * Proposal content caching configuration for determinism. (Issue #589)
+ */
+interface ProposalCacheConfig {
+    /** Enable content-based caching for repeated proposals */
+    enabled: boolean;
+    /** TTL in milliseconds (default: 1 hour) */
+    ttlMs: number;
+    /** Maximum cached entries (default: 500) */
+    maxEntries: number;
+}
+/**
+ * Incremental quorum configuration (Issue #1408).
+ * When enabled, ambiguous votes trigger voter pool expansion.
+ */
+interface IncrementalQuorumConfig {
+    /** Enable incremental quorum expansion. Default: false */
+    enabled: boolean;
+    /** Maximum expansion rounds (5→7→9). Default: 2 */
+    maxExpansionRounds: number;
+    /** Voters to add per expansion round. Default: 2 */
+    votersPerExpansion: number;
+    /** Minimum average confidence to avoid expansion. Default: 0.6 */
+    confidenceThreshold: number;
+    /** Ambiguity band: if approval rate is within this of threshold, expand. Default: 0.15 */
+    ambiguityBand: number;
+}
+/**
+ * Callback to request additional voters for incremental quorum.
+ * Returns the IDs of newly added voters.
+ */
+type VoterExpansionCallback = (proposalId: ProposalId, currentVoterCount: number, requestedCount: number) => Promise<readonly string[]>;
+/**
+ * Consensus engine configuration.
+ */
+interface ConsensusEngineConfig {
+    defaultTimeout: number;
+    minVotersForQuorum: number;
+    maxActiveProposals: number;
+    enablePerformanceTracking: boolean;
+    /** Maximum number of closed proposals to retain. Oldest are evicted when exceeded. (Issue #549) */
+    maxClosedProposals: number;
+    /** Content-based proposal caching for determinism (Issue #589) */
+    proposalCache?: ProposalCacheConfig;
+    /** Incremental quorum configuration (Issue #1408) */
+    incrementalQuorum?: IncrementalQuorumConfig;
+}
+/**
+ * Consensus engine configuration schema.
+ */
+declare const ConsensusEngineConfigSchema: z.ZodObject<{
+    defaultTimeout: z.ZodDefault<z.ZodNumber>;
+    minVotersForQuorum: z.ZodDefault<z.ZodNumber>;
+    maxActiveProposals: z.ZodDefault<z.ZodNumber>;
+    enablePerformanceTracking: z.ZodDefault<z.ZodBoolean>;
+    maxClosedProposals: z.ZodDefault<z.ZodNumber>;
+    proposalCache: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        ttlMs: z.ZodDefault<z.ZodNumber>;
+        maxEntries: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Default configuration values.
+ */
+declare const DEFAULT_CONSENSUS_CONFIG: ConsensusEngineConfig;
+/**
+ * Voting thresholds for each algorithm.
+ */
+declare const VOTING_THRESHOLDS: Record<ConsensusAlgorithm, number>;
+/**
+ * Internal proposal state managed by the engine.
+ */
+interface ProposalState {
+    proposal: Proposal;
+    status: ProposalStatus;
+    votes: Map<string, Vote>;
+    voteWeights: Map<string, number>;
+    startedAt: Date;
+    timeoutId?: ReturnType<typeof setTimeout>;
+    /** Number of incremental quorum expansions applied (Issue #1408). */
+    expansionRounds?: number;
+    /**
+     * True while a quorum expansion is awaiting its callback for this
+     * proposal. Concurrent `vote()` calls check this to avoid double-
+     * expanding across the `await` gap (Issue #2861). Per-proposal so
+     * independent proposals never block each other.
+     */
+    expansionInFlight?: boolean;
+}
+/**
+ * Consensus metrics for monitoring.
+ */
+interface ConsensusMetrics {
+    totalProposals: number;
+    approvedProposals: number;
+    rejectedProposals: number;
+    timedOutProposals: number;
+    averageDurationMs: number;
+    averageVotesPerProposal: number;
+    algorithmUsage: Record<ConsensusAlgorithm, number>;
+}
+/**
+ * Consensus metrics schema.
+ */
+declare const ConsensusMetricsSchema: z.ZodObject<{
+    totalProposals: z.ZodNumber;
+    approvedProposals: z.ZodNumber;
+    rejectedProposals: z.ZodNumber;
+    timedOutProposals: z.ZodNumber;
+    averageDurationMs: z.ZodNumber;
+    averageVotesPerProposal: z.ZodNumber;
+    algorithmUsage: z.ZodRecord<z.ZodEnum<{
+        simple_majority: "simple_majority";
+        supermajority: "supermajority";
+        unanimous: "unanimous";
+        proof_of_learning: "proof_of_learning";
+        opinion_wise: "opinion_wise";
+        higher_order: "higher_order";
+    }>, z.ZodNumber>;
+}, z.core.$strip>;
+
+/**
+ * nexus-agents vote command types
+ *
+ * Type definitions for the consensus voting CLI command.
+ *
+ * (Source: Issue #212, Process Automation Epic #209)
+ */
+
+/**
+ * #4135: how the `vote` command maps a `no_quorum` decision — a quorum void
+ * (a missing/errored voice under the opt-in `absolute_quorum` error policy, or an
+ * error-policy short-circuit), which is DISTINCT from a genuine rejection.
+ *
+ * - `fail` (default): exit 1, exactly as a rejection would — back-compat.
+ * - `exit2`: exit with a distinct code 2 so scripts can tell a quorum void apart
+ *   from an approval (0) or a rejection (1).
+ * - `retry`: re-run the vote ONCE (the plan is fine, a voice was missing); if it
+ *   still cannot reach quorum, fall back to `fail` (exit 1).
+ */
+type NoQuorumPolicy = 'fail' | 'exit2' | 'retry';
+/**
+ * Voter agent role definitions.
+ *
+ * `scope_steward` (#2185) was added 2026-04-25 to address a build-vs-buy
+ * blind spot in the original 6-role panel: the panel approved a proposal
+ * to build a USB-flasher CLI without flagging that Rufus already solves
+ * the problem. The scope-steward role explicitly checks for existing tools
+ * + biases toward "don't build."
+ */
+type VoterRole = 'architect' | 'security' | 'devex' | 'ai_ml' | 'pm' | 'catfish' | 'scope_steward';
+/**
+ * Individual agent vote with metadata.
+ */
+interface AgentVoteResult {
+    readonly role: VoterRole;
+    readonly vote: Vote;
+    readonly processingTimeMs: number;
+    /**
+     * Source of the vote:
+     * - 'llm': Real LLM execution
+     * - 'simulation': Fallback simulation (opt-in only)
+     * - 'error': Error during execution (Issue #523)
+     */
+    readonly source: 'llm' | 'simulation' | 'error';
+    /** CLI that executed this vote (for adaptive routing feedback). */
+    readonly cli?: string | undefined;
+    /**
+     * Model id that executed this vote, when known (e.g. 'claude-sonnet'). Carried
+     * so per-decision cost aggregation can attribute spend per model (#3855). Absent
+     * for error/simulation votes that never reached a model.
+     */
+    readonly model?: string | undefined;
+    /**
+     * Input tokens the adapter reported for this voter's LLM call, when known
+     * (#3910). Propagated from `CompletionResponse.usage` so per-decision cost
+     * aggregation resolves from `unmeasured` to MEASURED. Absent for
+     * error/simulation votes that never reached a model, or for adapters that do
+     * not report usage (CLI subscriptions) — those stay honestly `unmeasured`.
+     */
+    readonly inputTokens?: number | undefined;
+    /**
+     * Output tokens the adapter reported for this voter's LLM call, when known
+     * (#3910). See {@link AgentVoteResult.inputTokens}.
+     */
+    readonly outputTokens?: number | undefined;
+    /** Error message if vote fell back to simulation or encountered an error */
+    readonly error?: string;
+}
+
+/**
+ * Types, schemas, and response helpers for the consensus_vote MCP tool.
+ * Extracted from consensus-vote.ts for file size compliance (Issue #708).
+ *
+ * @module mcp/tools/consensus-vote-types
+ */
+
+/**
+ * Available consensus voting strategies.
+ *
+ * - `simple_majority`: Standard majority voting (>50%)
+ * - `supermajority`: Requires >=67% approval
+ * - `unanimous`: Requires 100% approval
+ * - `proof_of_learning`: Weighted by agent performance (Issue #103)
+ * - `higher_order`: Bayesian-optimal with correlation awareness (Issue #514)
+ * - `opinion_wise`: Alias for higher_order (Issue #333)
+ */
+type VotingStrategy = 'simple_majority' | 'supermajority' | 'unanimous' | 'proof_of_learning' | 'higher_order' | 'opinion_wise';
+/**
+ * How error-source votes (timed-out or crashed voters) are counted toward
+ * the threshold (#2630).
+ *
+ * - `reduce_denominator` (default for non-strict strategies): errors are
+ *   filtered out before the engine sees votes — denominator = non-error
+ *   votes. Best for operational decisions where you trust the responding
+ *   voters and infrastructure flake should not block the vote.
+ * - `count_as_abstain`: error votes reach the engine as abstain. Behaves
+ *   conservatively — a timed-out voter effectively withholds approval
+ *   relative to the threshold. Use when you can't tell what the error
+ *   voter would have decided and want the math to reflect uncertainty.
+ * - `fail_closed` (default for unanimous / higher_order): any error voids
+ *   the vote. Threshold math is not run. Use for security-critical or
+ *   breaking-change decisions where every voter must be heard.
+ * - `absolute_quorum` (opt-in, #4132): an errored voter DEGRADES the panel
+ *   verdict to `no_quorum` instead of being silently dropped from the
+ *   denominator. Unlike `fail_closed` (which reports a rejection-flavored void),
+ *   `absolute_quorum` reports `no_quorum` — a recoverable "re-run the missing
+ *   voice" state that never manufactures `approved` NOR `rejected` from an
+ *   induced error. An approval requires ZERO errors, the contrarian (catfish)
+ *   present and non-error (unless quick-mode drops it), and an ABSOLUTE approval
+ *   count (`ceil(fraction * panelSize)` over the full requested panel — not just
+ *   a majority of the responders). A genuine reject (zero errors) still blocks.
+ *   The anti-DoS point: a voter you can knock offline can only ever force a
+ *   re-run, never flip the verdict.
+ *
+ * Regardless of policy, a hard floor applies: when errors exceed 50% of
+ * total voters, the vote always fails. Catches "all CLIs are down" — a
+ * 2-voter consensus is not a real consensus.
+ */
+declare const ErrorPolicySchema: z.ZodEnum<{
+    reduce_denominator: "reduce_denominator";
+    count_as_abstain: "count_as_abstain";
+    fail_closed: "fail_closed";
+    absolute_quorum: "absolute_quorum";
+}>;
+type ErrorPolicy = z.infer<typeof ErrorPolicySchema>;
+/**
+ * Threshold values accepted by the `--threshold` CLI flag and the
+ * \`threshold\` MCP input field (#2638 — single source of truth).
+ *
+ * Maps to consensus algorithms via:
+ * `majority → simple_majority`, `supermajority → supermajority`, `unanimous → unanimous`.
+ *
+ * Used as the canonical Zod schema for CLI parsing
+ * (`cli.ts:parseThreshold`), validation (`cli-commands-validators.ts:isValidThreshold`),
+ * and the `ConsensusVoteInputSchema.threshold` field.
+ */
+declare const VoteThresholdSchema: z.ZodEnum<{
+    supermajority: "supermajority";
+    unanimous: "unanimous";
+    majority: "majority";
+}>;
+type VoteThreshold = z.infer<typeof VoteThresholdSchema>;
+declare const ConsensusVoteInputSchema: z.ZodObject<{
+    proposal: z.ZodString;
+    threshold: z.ZodOptional<z.ZodEnum<{
+        supermajority: "supermajority";
+        unanimous: "unanimous";
+        majority: "majority";
+    }>>;
+    strategy: z.ZodOptional<z.ZodEnum<{
+        simple_majority: "simple_majority";
+        supermajority: "supermajority";
+        unanimous: "unanimous";
+        proof_of_learning: "proof_of_learning";
+        opinion_wise: "opinion_wise";
+        higher_order: "higher_order";
+    }>>;
+    errorPolicy: z.ZodOptional<z.ZodEnum<{
+        reduce_denominator: "reduce_denominator";
+        count_as_abstain: "count_as_abstain";
+        fail_closed: "fail_closed";
+        absolute_quorum: "absolute_quorum";
+    }>>;
+    quickMode: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    simulateVotes: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        async: "async";
+        sync: "sync";
+    }>>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    ratifies: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ConsensusVoteInput = z.infer<typeof ConsensusVoteInputSchema>;
+interface AgentVoteSummary {
+    role: string;
+    decision: 'approve' | 'reject' | 'abstain';
+    confidence: number;
+    reasoning: string;
+    simulated: boolean;
+    /** True when this vote was generated from an error (Issue #815). */
+    error: boolean;
+    /** Model used for this agent's vote (Issue #817). */
+    modelUsed?: string;
+    /** Structured rejection categories for reject→refine→re-vote loops (Issue #1213). */
+    rejectionCategories?: readonly string[];
+}
+/**
+ * Canonical set of decision statuses a vote response can carry. Single source
+ * of truth: the `consensus_vote` MCP `outputSchema` reuses
+ * {@link VoteDecisionStatusSchema} so the advertised enum can never be narrower
+ * than what {@link buildResponse} emits (all five are reachable —
+ * `no_quorum` on an all-error/no-quorum panel, the rest via
+ * {@link mapOutcomeToDecision}). A narrower schema made strict MCP clients
+ * reject `timeout`/`pending` votes with a `-32602`-class error (#4032).
+ */
+declare const VoteDecisionStatusSchema: z.ZodEnum<{
+    timeout: "timeout";
+    rejected: "rejected";
+    pending: "pending";
+    approved: "approved";
+    no_quorum: "no_quorum";
+}>;
+type VoteDecisionStatus = z.infer<typeof VoteDecisionStatusSchema>;
+/** Higher-Order Voting metadata (Issue #514). */
+interface HigherOrderMetadata {
+    posteriorApproval: number;
+    posteriorRejection: number;
+    effectiveVoteCount: number;
+    method: 'ow' | 'isp' | 'simple';
+    usedCorrelationData: boolean;
+    improvementOverBaseline: number;
+    downweightedAgents: readonly string[];
+    reasoning: string;
+}
+interface ConsensusVoteResponse {
+    proposal: string;
+    threshold?: VoteThreshold;
+    strategy: VotingStrategy;
+    decision: VoteDecisionStatus;
+    approvalPercentage: number;
+    voteCounts: {
+        approve: number;
+        reject: number;
+        abstain: number;
+        error: number;
+    };
+    votes: AgentVoteSummary[];
+    durationMs: number;
+    simulateVotes: boolean;
+    higherOrderMetadata?: HigherOrderMetadata;
+    /**
+     * Set when an error policy short-circuited the vote (#2630/#3124). Explains a
+     * `rejected` decision that may coexist with a high `approvalPercentage` — e.g.
+     * `fail_closed: 1 voter(s) errored`. Absent on normally-tallied votes.
+     */
+    policyReason?: string;
+    /**
+     * Set when the panel was DEGRADED (#3587): some voters errored, so the
+     * decision rests on fewer than the requested number of voters. Surfaces a
+     * silently-shrunk panel so the result isn't read as a full-strength consensus.
+     * Absent when every requested voter returned a real vote.
+     */
+    panelWarning?: string;
+    /**
+     * Per-decision cost rollup (#3855): per-voter / per-model token + USD totals
+     * for this governed decision. Rides the existing response — no new MCP tool.
+     * Totals are a floor when `costSummary.unmeasuredVoters > 0` (voters whose
+     * adapter reported no usage are counted as unmeasured, not a measured $0).
+     */
+    costSummary?: DecisionCostSummary;
+    /**
+     * #3991: whether the authentic vote record (#3897) was persisted at vote time.
+     * Post-#3991 the runtime ledger routes through `nexusDataPath` under
+     * `governance/`, so a writable `.nexus-agents/governance/` location almost
+     * always exists and `true` is the normal case. `false` means the persist was
+     * skipped (all votes simulated) or the write failed (data dir unwritable) —
+     * see {@link voteRecordNote}. Surfaces to the MCP caller what was previously
+     * only a server-side WARN.
+     */
+    voteRecordPersisted: boolean;
+    /**
+     * #3991: present only when {@link voteRecordPersisted} is `false` — the
+     * actionable reason the record was not written (e.g. the data dir is unwritable
+     * → fix permissions or set `NEXUS_VOTE_RECORDS_PATH` to a writable path).
+     */
+    voteRecordNote?: string;
+}
+
+export { type AgentPerformance as A, type RejectionCategory as B, type CliNameLiteral as C, type DecisionCostSummary as D, RejectionCategorySchema as E, VOTING_THRESHOLDS as F, type VoteDecisionStatus as G, VoteSchema as H, type InputModality as I, type VoteThreshold as J, type ErrorPolicy as K, type ModelId as M, type NoQuorumPolicy as N, type OutputModality as O, type Pricing as P, type QualityScores as Q, REJECTION_CATEGORIES as R, type SpecialFeature as S, type ToolCapability as T, type Vote as V, type WeightedVoteCounts as W, type VoteDecision as a, type VoterRole as b, type ConsensusAlgorithm as c, type VoteCounts as d, type ProposalState as e, type ProposalId as f, type ConsensusEngineConfig as g, type ConsensusResult as h, type ProposalStatus as i, type Proposal as j, type ConsensusMetrics as k, type VoterExpansionCallback as l, type AgentVoteResult as m, type VotingStrategy as n, AgentPerformanceSchema as o, type AgentVoteSummary as p, ConsensusAlgorithmSchema as q, ConsensusEngineConfigSchema as r, ConsensusMetricsSchema as s, ConsensusResultSchema as t, type ConsensusVoteInput as u, ConsensusVoteInputSchema as v, type ConsensusVoteResponse as w, DEFAULT_CONSENSUS_CONFIG as x, ProposalSchema as y, ProposalStatusSchema as z };