nexus-agents 2.151.0 → 2.152.0

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

@@ -1,357 +0,0 @@
-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[];
-}
-
-/**
- * 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 AgentVoteSummary as A, type CliNameLiteral as C, type DecisionCostSummary as D, type ErrorPolicy as E, type InputModality as I, type ModelId as M, type OutputModality as O, type Pricing as P, type QualityScores as Q, type SpecialFeature as S, type ToolCapability as T, type VotingStrategy as V, type ConsensusVoteInput as a, ConsensusVoteInputSchema as b, type ConsensusVoteResponse as c, type VoteDecisionStatus as d, type VoteThreshold as e };