muonroi-cli 1.8.3 → 1.8.5

package/dist/src/council/debate.d.ts

@@ -1,5 +1,5 @@
-import type { StreamChunk } from "../types/index.js";
-import type { ClarifiedSpec, CouncilConfig, CouncilLLM, DebateState } from "./types.js";
+import type { CouncilQuestionOption, StreamChunk } from "../types/index.js";
+import type { ClarifiedSpec, CouncilConfig, CouncilLLM, DebateStance, DebateState, IsolatedTaskRunner, QuestionResponder } from "./types.js";
 /**
  * Resolve the initial round budget + hard ceiling from the plan's output-shape kind
  * and the planner-proposed round count. Pure + exported for unit testing the cap.
@@ -9,5 +9,172 @@ export declare function resolveDebateRoundBudget(planKind: string | undefined, p
     effectiveCeiling: number;
     kindCapped: boolean;
 };
+export declare function researchWithFallback(llm: CouncilLLM, primaryModel: string, topic: string, conversationContext: string, signal: AbortSignal | undefined, traceCb: (t: string) => void, options: {
+    internetFirst?: boolean;
+}, fallbackPool: string[], runIsolatedTask?: IsolatedTaskRunner): Promise<string>;
 export declare function runDebate(spec: ClarifiedSpec, config: CouncilConfig, llm: CouncilLLM): AsyncGenerator<StreamChunk, DebateState, unknown>;
 export declare function evaluateResearchNeed(spec: ClarifiedSpec, leaderModelId: string, conversationContext: string, llm: CouncilLLM, costAware?: boolean): AsyncGenerator<StreamChunk, boolean, unknown>;
+/**
+ * F3b — robustly extract the leader-evaluation JSON object from a model's raw
+ * output. Replaces a greedy `/\{[\s\S]*\}/` match that could swallow prose,
+ * multiple objects, or a trailing partial object into an unparseable span.
+ *
+ * Strategy: strip code fences, then brace-scan and return the LAST fully
+ * balanced top-level `{…}` object (the eval schema is emitted last, after any
+ * chain-of-thought prose). Returns null only when no balanced object exists.
+ * Deterministic, no LLM call. Braces inside string values are rare in the
+ * machine-emitted eval payload; a real tokenizer would be overkill here.
+ */
+export declare function extractEvalJson(raw: string): string | null;
+/**
+ * Format a speaker list as newline-joined "Name — lens" rows for the composing
+ * placeholder (A: live debate preview). Prefers the concrete `focus`, falls back
+ * to the one-sentence `lens`, then to bare name. Dedups identical rows so a
+ * speaker in multiple pairs renders once. Returns undefined when nothing useful
+ * is available so the UI falls back to label-only.
+ */
+/**
+ * Project a leader evaluation's `criteriaStatus` onto the PINNED spec criteria,
+ * returning a boolean[] index-aligned to `pinned` (B2/B3). The eval prompt asks
+ * for one entry per criterion in order, so index alignment is the primary path;
+ * when the model drifts (wrong count/order) we fall back to a case-insensitive
+ * substring match either direction, defaulting unmatched criteria to not-met so
+ * a hallucinated "all met" never silently marks an untouched criterion done.
+ */
+export declare function alignCriteriaMet(pinned: string[], status: Array<{
+    criterion?: string;
+    met?: boolean;
+}>): boolean[];
+/**
+ * B5 leader-conductor visibility. Default ON; opt out with
+ * MUONROI_LEADER_CONDUCTOR=0 (fallback = pre-B5 behavior, no directive/verdict
+ * messages — keeps headless/legacy transcripts unchanged).
+ */
+export declare function leaderConductorEnabled(): boolean;
+/**
+ * B4 leader auto-remedy. When pinned criteria remain unmet at the round budget's
+ * end, the leader auto-extends toward them (up to the hard ceiling) instead of
+ * stopping at the initial plan — "done = all criteria met", ceiling is a managed
+ * budget. Default ON under the conductor; opt out with
+ * MUONROI_COUNCIL_AUTO_REMEDY=0 (fallback = only leader-requested extensions).
+ */
+export declare function leaderAutoRemedyEnabled(): boolean;
+/**
+ * #3 — grounding-verify pass. When a debate ends with weak evidence density
+ * (< GROUNDING_VERIFY_THRESHOLD, i.e. debaters barely tagged any [CONFIRMED]/
+ * [REFUTED] claims — the common case since each debater is capped at
+ * stepCountIs(2)), an isolated explore sub-agent verifies the load-bearing
+ * claims against the codebase and emits authoritative tags that raise the
+ * density metric council uses for confidence. Default ON when an isolated-task
+ * bridge is wired; opt out with MUONROI_COUNCIL_GROUNDING_VERIFY=0.
+ */
+export declare function groundingVerifyEnabled(): boolean;
+/**
+ * #3 — run an isolated explore sub-agent that fact-checks the debate's
+ * load-bearing claims and emits `[CONFIRMED via file:line]` / `[REFUTED via …]`
+ * tags (the exact shape `countCitations` recognises). Returns the tagged output
+ * on success, or "" on any failure (caller only folds it in when it actually
+ * raised the citation count).
+ */
+export declare function runGroundingVerify(runIsolatedTask: IsolatedTaskRunner, model: string, problemStatement: string, exchangeText: string, traceCb: (t: string) => void): Promise<string>;
+/**
+ * B4: does auto-remedy want to extend the budget this round? True while pinned
+ * criteria remain unmet AND progress is still being made (a new criterion was
+ * met within the last 2 rounds). A stuck debate (roundsSinceProgress ≥ 2) returns
+ * false so the ceiling isn't burned chasing a criterion that isn't moving.
+ */
+export declare function autoRemedyWantsExtend(pinnedUnmet: number, roundsSinceProgress: number): boolean;
+/**
+ * B4: the diagnostic closing-remedy line for a debate that ended with unmet
+ * pinned criteria — distinguishes a stuck criterion (needs evidence/rescope)
+ * from a genuine ceiling hit (needs a higher budget) from an ordinary early
+ * stop, so the leader's final word is an actionable next move, not a shrug.
+ */
+export declare function diagnoseUnmetRemedy(opts: {
+    stuck: boolean;
+    atCeiling: boolean;
+    effectiveCeiling: number;
+    roundsSinceProgress: number;
+}): string;
+/**
+ * B4 interactive escalation. When the debate is about to stop with pinned
+ * criteria unmet AND auto-remedy can't help (stuck / at ceiling), hand the
+ * decision to the user instead of silently synthesizing a partial outcome.
+ * Default ON under the conductor; opt out with MUONROI_COUNCIL_ESCALATE=0
+ * (fallback = diagnostic closing verdict only, no askcard).
+ */
+export declare function leaderEscalationEnabled(): boolean;
+/**
+ * B4: should we interrupt to ask the user at this stop boundary? True only when
+ * pinned criteria remain unmet AND the leader can no longer self-remedy — it is
+ * stuck (no progress for ≥2 rounds) or has hit the round ceiling. While progress
+ * is still being made under the ceiling, auto-remedy handles it silently and we
+ * don't nag the user.
+ */
+export declare function escalationWanted(opts: {
+    pinnedUnmet: number;
+    stuck: boolean;
+    atCeiling: boolean;
+}): boolean;
+/**
+ * B4: the three escalation choices. When the debate is already at the absolute
+ * safety ceiling, the "extend" option degrades to a disabled-looking accept
+ * (label says so) — we never let the user push past ABSOLUTE_MAX_ROUNDS.
+ */
+export declare function buildEscalationOptions(unmetCount: number, atAbsoluteMax: boolean): CouncilQuestionOption[];
+/**
+ * B4: emit the escalation askcard and resolve the user's choice. Yields the
+ * council_question chunk (rendered by the same consumer as clarifier/post-debate
+ * askcards), awaits the responder, echoes the choice, and returns the decision.
+ * `grantedRounds` is pre-computed here (bounded by ABSOLUTE_MAX_ROUNDS) so the
+ * caller only mutates loop state. Any unmatched / empty answer is treated as
+ * "accept" — never a silent hang.
+ */
+export declare function runEscalationPrompt(opts: {
+    respondToQuestion: QuestionResponder;
+    openCriteria: string[];
+    pinnedUnmet: number;
+    stuck: boolean;
+    atAbsoluteMax: boolean;
+    currentMax: number;
+}): AsyncGenerator<StreamChunk, {
+    action: "extend" | "accept" | "rescope";
+    grantedRounds: number;
+}, unknown>;
+/** One-line criterion label for directive/verdict bodies. */
+export declare function shortCriterion(c: string, max?: number): string;
+/**
+ * B5: build the leader's pre-round DIRECTIVE body — the round goal plus the
+ * criteria still unmet going into this round. `metSoFar` is the prior round's
+ * aligned criteriaMet (empty before round 1 → everything is unmet).
+ */
+export declare function buildLeaderDirective(round: number, criteria: string[], metSoFar: boolean[], focus?: string): string;
+/**
+ * B5: build the leader's post-round VERDICT body — per-criterion ✓/○ against the
+ * pinned outcome, the leader's reason, and the focus it hands to the next round.
+ */
+export declare function buildLeaderVerdict(criteria: string[], met: boolean[], reason: string, nextFocus?: string): string;
+export declare function formatSpeakerRoster(list: Array<{
+    stance?: DebateStance;
+    model: string;
+}>): string | undefined;
+export declare function countCitations(text: string): number;
+/**
+ * Evidence density = verified / (verified + unverified).
+ *
+ * Previous definition was `citations / total-sentences`, which fundamentally
+ * couldn't exceed ~0.05 because most debate sentences are not citable claims
+ * (opinions, transitions, questions). Session ea13da132dec hit "Low
+ * confidence 0.00" despite having 2 real [CONFIRMED via web_fetch] tags
+ * because they were drowned in ~700 sentences of debate prose.
+ *
+ * New definition only counts claims that participants explicitly FLAGGED as
+ * needing evidence — either by verifying them ([CONFIRMED]/[REFUTED]) or by
+ * marking them unverified ([UNVERIFIED:…]). This measures how much of the
+ * debate's own factual claim-tagging was actually backed up.
+ *
+ * If participants tagged zero claims, density is 0 — no evidence awareness
+ * shown, low confidence is correct. This biases participants (via the
+ * EVIDENCE_RULE prompt) to either verify or explicitly mark unverified.
+ */
+export declare function computeEvidenceDensity(text: string): number;