@defai.digital/discussion-domain 13.0.3 → 13.1.1

package/src/budget-manager.ts

@@ -0,0 +1,272 @@
+/**
+ * Discussion Budget Manager
+ *
+ * Manages timeout budgets across recursive discussions using configurable strategies.
+ * Supports fixed, cascade, and budget allocation strategies.
+ *
+ * Invariants:
+ * - INV-DISC-610: Child timeout ≤ parent remaining budget
+ * - INV-DISC-611: Minimum time reserved for synthesis
+ * - INV-DISC-612: Total timeout includes all nested calls
+ * - INV-DISC-613: Strategy applied consistently
+ */
+
+import {
+  type TimeoutConfig,
+  type TimeoutStrategy,
+  getTimeoutForLevel,
+  DEFAULT_TOTAL_BUDGET_MS,
+  MIN_SYNTHESIS_TIME_MS,
+  MAX_DISCUSSION_DEPTH,
+} from '@defai.digital/contracts';
+
+/**
+ * Budget allocation result for a discussion level
+ */
+export interface BudgetAllocation {
+  /** Timeout for provider calls at this level */
+  providerTimeoutMs: number;
+
+  /** Time reserved for synthesis at this level */
+  synthesisTimeMs: number;
+
+  /** Total budget for this level */
+  totalLevelBudgetMs: number;
+
+  /** Budget available for sub-discussions */
+  subDiscussionBudgetMs: number;
+}
+
+/**
+ * Budget status snapshot
+ */
+export interface BudgetStatus {
+  /** Total budget configured */
+  totalBudgetMs: number;
+
+  /** Time elapsed since start */
+  elapsedMs: number;
+
+  /** Remaining budget */
+  remainingMs: number;
+
+  /** Current depth */
+  currentDepth: number;
+
+  /** Budget used per level */
+  usageByLevel: Map<number, number>;
+
+  /** Whether budget is exhausted */
+  exhausted: boolean;
+
+  /** Utilization percentage */
+  utilizationPercent: number;
+}
+
+/**
+ * Discussion budget manager interface
+ */
+export interface DiscussionBudgetManager {
+  /** Get budget allocation for a specific depth */
+  getAllocation(depth: number): BudgetAllocation;
+
+  /** Get current budget status */
+  getStatus(): BudgetStatus;
+
+  /** Record time spent at a level */
+  recordUsage(depth: number, elapsedMs: number): void;
+
+  /** Get remaining budget for a depth */
+  getRemainingBudget(depth: number): number;
+
+  /** Check if budget allows sub-discussion at depth */
+  canAllocateSubDiscussion(depth: number): boolean;
+
+  /** Get timeout for provider call at depth */
+  getProviderTimeout(depth: number): number;
+
+  /** Get the configured strategy */
+  getStrategy(): TimeoutStrategy;
+
+  /** Create a child budget manager for sub-discussion */
+  createChildManager(startingBudgetMs: number): DiscussionBudgetManager;
+}
+
+/**
+ * Creates a discussion budget manager
+ */
+export function createBudgetManager(
+  config: Partial<TimeoutConfig> = {},
+  maxDepth = MAX_DISCUSSION_DEPTH
+): DiscussionBudgetManager {
+  // Apply defaults
+  const timeoutConfig: TimeoutConfig = {
+    strategy: config.strategy ?? 'cascade',
+    totalBudgetMs: config.totalBudgetMs ?? DEFAULT_TOTAL_BUDGET_MS,
+    minSynthesisMs: config.minSynthesisMs ?? MIN_SYNTHESIS_TIME_MS,
+    levelTimeouts: config.levelTimeouts,
+  };
+
+  const startTime = Date.now();
+  const usageByLevel = new Map<number, number>();
+
+  // Pre-calculate allocations for each level
+  const allocations = new Map<number, BudgetAllocation>();
+
+  for (let depth = 0; depth <= maxDepth; depth++) {
+    const levelTimeout = getTimeoutForLevel(timeoutConfig, depth, maxDepth);
+    const synthesisTime = timeoutConfig.minSynthesisMs;
+    const providerTime = Math.max(synthesisTime, levelTimeout - synthesisTime);
+
+    // Calculate sub-discussion budget (for next level)
+    let subBudget = 0;
+    if (depth < maxDepth) {
+      subBudget = getTimeoutForLevel(timeoutConfig, depth + 1, maxDepth);
+    }
+
+    allocations.set(depth, {
+      providerTimeoutMs: providerTime,
+      synthesisTimeMs: synthesisTime,
+      totalLevelBudgetMs: levelTimeout,
+      subDiscussionBudgetMs: subBudget,
+    });
+  }
+
+  return {
+    getAllocation(depth: number): BudgetAllocation {
+      const allocation = allocations.get(Math.min(depth, maxDepth));
+      if (!allocation) {
+        // Fallback for unexpected depth
+        return {
+          providerTimeoutMs: timeoutConfig.minSynthesisMs,
+          synthesisTimeMs: timeoutConfig.minSynthesisMs,
+          totalLevelBudgetMs: timeoutConfig.minSynthesisMs * 2,
+          subDiscussionBudgetMs: 0,
+        };
+      }
+      return { ...allocation };
+    },
+
+    getStatus(): BudgetStatus {
+      const elapsedMs = Date.now() - startTime;
+      const remainingMs = Math.max(0, timeoutConfig.totalBudgetMs - elapsedMs);
+
+      // Find current depth (highest level with usage)
+      let currentDepth = 0;
+      for (const [depth] of usageByLevel) {
+        if (depth > currentDepth) {
+          currentDepth = depth;
+        }
+      }
+
+      return {
+        totalBudgetMs: timeoutConfig.totalBudgetMs,
+        elapsedMs,
+        remainingMs,
+        currentDepth,
+        usageByLevel: new Map(usageByLevel),
+        exhausted: remainingMs <= 0,
+        utilizationPercent: (elapsedMs / timeoutConfig.totalBudgetMs) * 100,
+      };
+    },
+
+    recordUsage(depth: number, elapsedMs: number): void {
+      const current = usageByLevel.get(depth) ?? 0;
+      usageByLevel.set(depth, current + elapsedMs);
+    },
+
+    getRemainingBudget(depth: number): number {
+      const elapsedMs = Date.now() - startTime;
+      const totalRemaining = Math.max(0, timeoutConfig.totalBudgetMs - elapsedMs);
+
+      // Get level allocation
+      const allocation = allocations.get(depth);
+      if (!allocation) {
+        return 0;
+      }
+
+      // Usage at this level
+      const levelUsage = usageByLevel.get(depth) ?? 0;
+      const levelRemaining = Math.max(0, allocation.totalLevelBudgetMs - levelUsage);
+
+      // Return minimum of total remaining and level remaining
+      return Math.min(totalRemaining, levelRemaining);
+    },
+
+    canAllocateSubDiscussion(depth: number): boolean {
+      // Check if we can go deeper
+      if (depth >= maxDepth) {
+        return false;
+      }
+
+      // Check remaining budget
+      const remaining = this.getRemainingBudget(depth);
+      const minRequired = timeoutConfig.minSynthesisMs * 2; // Min for sub-discussion
+
+      return remaining >= minRequired;
+    },
+
+    getProviderTimeout(depth: number): number {
+      const allocation = this.getAllocation(depth);
+      const remaining = this.getRemainingBudget(depth);
+
+      // Don't exceed remaining budget
+      return Math.min(allocation.providerTimeoutMs, remaining);
+    },
+
+    getStrategy(): TimeoutStrategy {
+      return timeoutConfig.strategy;
+    },
+
+    createChildManager(startingBudgetMs: number): DiscussionBudgetManager {
+      // Create a new manager with reduced budget
+      return createBudgetManager(
+        {
+          ...timeoutConfig,
+          totalBudgetMs: startingBudgetMs,
+        },
+        maxDepth
+      );
+    },
+  };
+}
+
+/**
+ * Utility to format budget status for logging
+ */
+export function formatBudgetStatus(status: BudgetStatus): string {
+  const lines = [
+    `Budget Status:`,
+    `  Total: ${status.totalBudgetMs}ms`,
+    `  Elapsed: ${status.elapsedMs}ms`,
+    `  Remaining: ${status.remainingMs}ms`,
+    `  Utilization: ${status.utilizationPercent.toFixed(1)}%`,
+    `  Current Depth: ${status.currentDepth}`,
+    `  Exhausted: ${status.exhausted}`,
+  ];
+
+  if (status.usageByLevel.size > 0) {
+    lines.push(`  Usage by Level:`);
+    for (const [depth, usage] of status.usageByLevel) {
+      lines.push(`    Level ${depth}: ${usage}ms`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Calculate recommended providers based on remaining budget
+ */
+export function recommendProvidersForBudget(
+  remainingMs: number,
+  perProviderEstimateMs: number,
+  minProviders = 2,
+  maxProviders = 6
+): number {
+  // Calculate how many providers we can fit
+  const possibleProviders = Math.floor(remainingMs / perProviderEstimateMs);
+
+  // Clamp to valid range
+  return Math.max(minProviders, Math.min(maxProviders, possibleProviders));
+}

package/src/confidence-extractor.ts

@@ -0,0 +1,321 @@
+/**
+ * Confidence Extractor
+ *
+ * Extracts confidence scores from provider responses for early exit decisions.
+ * Supports cascading confidence where high-confidence first responses can
+ * short-circuit the discussion.
+ *
+ * Invariants:
+ * - INV-DISC-622: Confidence threshold configurable (default 0.9)
+ * - INV-DISC-623: Minimum 2 providers for quality
+ */
+
+import type { CascadingConfidenceConfig } from '@defai.digital/contracts';
+
+/**
+ * Result of confidence extraction from a response
+ */
+export interface ExtractedConfidence {
+  /** Confidence score 0-1, or null if not extractable */
+  score: number | null;
+
+  /** Method used to extract confidence */
+  method: 'explicit' | 'heuristic' | 'none';
+
+  /** Explanation of confidence assessment */
+  explanation?: string;
+}
+
+/**
+ * Result of early exit evaluation
+ */
+export interface EarlyExitDecision {
+  /** Whether to exit early */
+  shouldExit: boolean;
+
+  /** Reason for decision */
+  reason: string;
+
+  /** Confidence score that triggered decision */
+  confidence?: number;
+
+  /** Number of providers that responded */
+  providerCount: number;
+}
+
+/**
+ * Default cascading confidence config
+ */
+export const DEFAULT_CASCADING_CONFIDENCE: Required<CascadingConfidenceConfig> = {
+  enabled: true,
+  threshold: 0.9,
+  minProviders: 2,
+};
+
+/**
+ * Patterns for extracting explicit confidence from responses
+ */
+const CONFIDENCE_PATTERNS = [
+  // "Confidence: 95%" or "Confidence: 0.95"
+  /confidence[:\s]+(\d+(?:\.\d+)?)\s*%?/i,
+  // "I am 95% confident" or "95% certain"
+  /(?:am|is)\s+(\d+(?:\.\d+)?)\s*%?\s*(?:confident|certain|sure)/i,
+  // "[HIGH CONFIDENCE]" markers
+  /\[(?:very\s+)?high\s+confidence\]/i,
+  /\[medium\s+confidence\]/i,
+  /\[low\s+confidence\]/i,
+];
+
+/**
+ * Heuristic confidence indicators
+ */
+const HIGH_CONFIDENCE_PHRASES = [
+  'definitely',
+  'certainly',
+  'absolutely',
+  'without a doubt',
+  'clearly',
+  'obviously',
+  'undoubtedly',
+  'i am confident',
+  'i am certain',
+  'i strongly believe',
+];
+
+const LOW_CONFIDENCE_PHRASES = [
+  'perhaps',
+  'maybe',
+  'might',
+  'could be',
+  'not sure',
+  'uncertain',
+  'possibly',
+  'it depends',
+  'hard to say',
+  'difficult to determine',
+  'i think',
+  'it seems',
+];
+
+/**
+ * Extract confidence score from a provider response
+ */
+export function extractConfidence(content: string): ExtractedConfidence {
+  if (!content || content.trim().length === 0) {
+    return { score: null, method: 'none' };
+  }
+
+  const normalizedContent = content.toLowerCase();
+
+  // Try explicit patterns first
+  for (const pattern of CONFIDENCE_PATTERNS) {
+    const match = pattern.exec(content);
+    if (match) {
+      // Check for marker-based confidence
+      if (match[0].includes('high confidence')) {
+        return {
+          score: 0.9,
+          method: 'explicit',
+          explanation: 'Explicit high confidence marker found',
+        };
+      }
+      if (match[0].includes('medium confidence')) {
+        return {
+          score: 0.6,
+          method: 'explicit',
+          explanation: 'Explicit medium confidence marker found',
+        };
+      }
+      if (match[0].includes('low confidence')) {
+        return {
+          score: 0.3,
+          method: 'explicit',
+          explanation: 'Explicit low confidence marker found',
+        };
+      }
+
+      // Numeric confidence
+      if (match[1]) {
+        let score = parseFloat(match[1]);
+        // Normalize percentage to 0-1
+        if (score > 1) {
+          score = score / 100;
+        }
+        // Clamp to valid range
+        score = Math.max(0, Math.min(1, score));
+        return {
+          score,
+          method: 'explicit',
+          explanation: `Explicit confidence: ${(score * 100).toFixed(0)}%`,
+        };
+      }
+    }
+  }
+
+  // Fall back to heuristic analysis
+  const highCount = HIGH_CONFIDENCE_PHRASES.filter(phrase =>
+    normalizedContent.includes(phrase)
+  ).length;
+
+  const lowCount = LOW_CONFIDENCE_PHRASES.filter(phrase =>
+    normalizedContent.includes(phrase)
+  ).length;
+
+  if (highCount > 0 || lowCount > 0) {
+    // Calculate heuristic score based on phrase counts
+    const netConfidence = highCount - lowCount;
+    let score: number;
+
+    if (netConfidence >= 2) {
+      score = 0.85;
+    } else if (netConfidence === 1) {
+      score = 0.75;
+    } else if (netConfidence === 0) {
+      score = 0.6;
+    } else if (netConfidence === -1) {
+      score = 0.45;
+    } else {
+      score = 0.3;
+    }
+
+    return {
+      score,
+      method: 'heuristic',
+      explanation: `Heuristic: ${highCount} high-confidence phrases, ${lowCount} low-confidence phrases`,
+    };
+  }
+
+  // Response length heuristic - longer, more detailed responses often indicate confidence
+  const wordCount = content.split(/\s+/).length;
+  if (wordCount > 200) {
+    return {
+      score: 0.7,
+      method: 'heuristic',
+      explanation: 'Detailed response suggests moderate-high confidence',
+    };
+  }
+
+  return { score: null, method: 'none' };
+}
+
+/**
+ * Evaluate whether to exit early based on provider responses
+ */
+export function evaluateEarlyExit(
+  responses: Array<{ provider: string; content: string; confidence: number | undefined }>,
+  config: CascadingConfidenceConfig = DEFAULT_CASCADING_CONFIDENCE
+): EarlyExitDecision {
+  // Early exit disabled
+  if (!config.enabled) {
+    return {
+      shouldExit: false,
+      reason: 'Cascading confidence disabled',
+      providerCount: responses.length,
+    };
+  }
+
+  // Not enough providers yet
+  if (responses.length < config.minProviders) {
+    return {
+      shouldExit: false,
+      reason: `Need at least ${config.minProviders} providers, have ${responses.length}`,
+      providerCount: responses.length,
+    };
+  }
+
+  // Check if all responses have high confidence
+  const confidences: number[] = [];
+
+  for (const response of responses) {
+    // Use provided confidence or extract it
+    const confidence = response.confidence ?? extractConfidence(response.content).score;
+    if (confidence !== null) {
+      confidences.push(confidence);
+    }
+  }
+
+  if (confidences.length === 0) {
+    return {
+      shouldExit: false,
+      reason: 'No confidence scores available',
+      providerCount: responses.length,
+    };
+  }
+
+  // Calculate average confidence
+  const avgConfidence = confidences.reduce((a, b) => a + b, 0) / confidences.length;
+
+  // Check if average exceeds threshold
+  if (avgConfidence >= config.threshold) {
+    return {
+      shouldExit: true,
+      reason: `Average confidence ${(avgConfidence * 100).toFixed(0)}% exceeds threshold ${(config.threshold * 100).toFixed(0)}%`,
+      confidence: avgConfidence,
+      providerCount: responses.length,
+    };
+  }
+
+  // Check if first provider has high confidence (cascading pattern)
+  const firstConfidence = confidences[0];
+  if (firstConfidence !== undefined && firstConfidence >= config.threshold && responses.length >= config.minProviders) {
+    return {
+      shouldExit: true,
+      reason: `First provider confidence ${(firstConfidence * 100).toFixed(0)}% exceeds threshold`,
+      confidence: firstConfidence,
+      providerCount: responses.length,
+    };
+  }
+
+  return {
+    shouldExit: false,
+    reason: `Average confidence ${(avgConfidence * 100).toFixed(0)}% below threshold ${(config.threshold * 100).toFixed(0)}%`,
+    confidence: avgConfidence,
+    providerCount: responses.length,
+  };
+}
+
+/**
+ * Calculate agreement score between provider responses
+ * Higher score = more agreement = higher effective confidence
+ */
+export function calculateAgreementScore(
+  responses: Array<{ content: string }>
+): number {
+  if (responses.length < 2) {
+    return 1.0; // Single response has perfect "agreement"
+  }
+
+  // Simple heuristic: check for common key phrases/conclusions
+  const keywords = new Map<string, number>();
+
+  for (const response of responses) {
+    const words = response.content
+      .toLowerCase()
+      .split(/\s+/)
+      .filter(w => w.length > 4); // Only meaningful words
+
+    for (const word of words) {
+      keywords.set(word, (keywords.get(word) || 0) + 1);
+    }
+  }
+
+  // Count words that appear in multiple responses
+  let sharedCount = 0;
+  const totalUniqueWords = keywords.size;
+
+  for (const count of keywords.values()) {
+    if (count > 1) {
+      sharedCount++;
+    }
+  }
+
+  if (totalUniqueWords === 0) {
+    return 0.5; // Default for empty responses
+  }
+
+  // Calculate agreement ratio (0-1)
+  const agreementRatio = sharedCount / totalUniqueWords;
+
+  // Scale to reasonable range (0.3 - 1.0)
+  return 0.3 + agreementRatio * 0.7;
+}

package/src/consensus/synthesis.ts

@@ -124,6 +124,8 @@ export class SynthesisConsensus implements ConsensusExecutor {
         provider: r.provider,
         content: r.content,
         role: r.role,
+        // Indicate if this is an agent with domain expertise (INV-DISC-642)
+        isAgent: r.isAgent,
       }))
     );
   }

package/src/consensus/voting.ts

@@ -3,6 +3,9 @@
  *
  * Tallies votes from all providers and determines winner based on
  * raw counts or confidence-weighted scores.
+ *
+ * Invariants:
+ * - INV-DISC-642: Agent responses weighted by agentWeightMultiplier (default 1.5x)
  */
 
 import type { VotingResults, VoteRecord } from '@defai.digital/contracts';
@@ -14,6 +17,11 @@ import {
   getProviderSystemPrompt,
 } from '../prompts/templates.js';
 
+/**
+ * Default agent weight multiplier (INV-DISC-642)
+ */
+const DEFAULT_AGENT_WEIGHT = 1.5;
+
 export class VotingConsensus implements ConsensusExecutor {
   readonly method = 'voting' as const;
 
@@ -36,8 +44,8 @@ export class VotingConsensus implements ConsensusExecutor {
       };
     }
 
-    // Tally votes
-    const votingResults = this.tallyVotes(votes, config.threshold);
+    // Tally votes with agent weight multiplier (INV-DISC-642)
+    const votingResults = this.tallyVotes(votes, context.agentWeightMultiplier);
 
     // Generate synthesis summary
     const synthesizerId = config.synthesizer ||
@@ -73,8 +81,8 @@ export class VotingConsensus implements ConsensusExecutor {
     };
   }
 
-  private extractVotes(rounds: ConsensusExecutionContext['rounds']): VoteRecord[] {
-    const votes: VoteRecord[] = [];
+  private extractVotes(rounds: ConsensusExecutionContext['rounds']): Array<VoteRecord & { isAgent: boolean }> {
+    const votes: Array<VoteRecord & { isAgent: boolean }> = [];
 
     for (const round of rounds) {
       for (const response of round.responses) {
@@ -84,6 +92,7 @@ export class VotingConsensus implements ConsensusExecutor {
             choice: response.vote,
             confidence: response.confidence,
             reasoning: this.extractReasoning(response.content),
+            isAgent: response.isAgent ?? false,
           });
         }
       }
@@ -97,14 +106,21 @@ export class VotingConsensus implements ConsensusExecutor {
     return reasoningMatch?.[1] ? reasoningMatch[1].trim() : '';
   }
 
-  private tallyVotes(votes: VoteRecord[], _threshold: number): VotingResults {
+  private tallyVotes(
+    votes: Array<VoteRecord & { isAgent: boolean }>,
+    agentWeightMultiplier: number = DEFAULT_AGENT_WEIGHT
+  ): VotingResults {
     // Count raw votes
     const rawVotes: Record<string, number> = {};
     const weightedVotes: Record<string, number> = {};
 
     for (const vote of votes) {
+      // Apply agent weight multiplier (INV-DISC-642)
+      const weight = vote.isAgent ? agentWeightMultiplier : 1.0;
+      const weightedConfidence = vote.confidence * weight;
+
       rawVotes[vote.choice] = (rawVotes[vote.choice] || 0) + 1;
-      weightedVotes[vote.choice] = (weightedVotes[vote.choice] || 0) + vote.confidence;
+      weightedVotes[vote.choice] = (weightedVotes[vote.choice] || 0) + weightedConfidence;
     }
 
     // Determine winner (by weighted votes)