@defai.digital/discussion-domain 13.0.3 → 13.1.0

package/src/context-tracker.ts

@@ -0,0 +1,307 @@
+/**
+ * Discussion Context Tracker
+ *
+ * Tracks recursive discussion state including depth, budget, and call counts.
+ * Prevents infinite recursion and enforces resource limits.
+ *
+ * Invariants:
+ * - INV-DISC-600: Depth never exceeds maxDepth
+ * - INV-DISC-601: No circular discussions
+ * - INV-DISC-610: Child timeout ≤ parent remaining budget
+ * - INV-DISC-620: Total calls ≤ maxTotalCalls
+ */
+
+import {
+  type DiscussionContext,
+  type TimeoutConfig,
+  type RecursiveConfig,
+  type CostControlConfig,
+  DiscussionErrorCodes,
+  createRootDiscussionContext,
+  createChildDiscussionContext,
+  canSpawnSubDiscussion,
+  getTimeoutForLevel,
+  DEFAULT_DISCUSSION_DEPTH,
+  DEFAULT_TOTAL_BUDGET_MS,
+  DEFAULT_MAX_TOTAL_CALLS,
+  MIN_SYNTHESIS_TIME_MS,
+} from '@defai.digital/contracts';
+
+/**
+ * Result of checking if sub-discussion can be spawned
+ */
+export interface SubDiscussionCheck {
+  allowed: boolean;
+  reason?: string;
+  errorCode?: string;
+  availableBudgetMs?: number;
+  remainingCalls?: number;
+}
+
+/**
+ * Configuration for the context tracker
+ */
+export interface ContextTrackerConfig {
+  recursive: RecursiveConfig;
+  timeout: TimeoutConfig;
+  cost: CostControlConfig;
+}
+
+/**
+ * Discussion context tracker for managing recursive discussion state
+ */
+export interface DiscussionContextTracker {
+  /** Get current context */
+  getContext(): DiscussionContext;
+
+  /** Check if sub-discussion can be spawned */
+  canSpawnSubDiscussion(estimatedDurationMs?: number): SubDiscussionCheck;
+
+  /** Create child context for sub-discussion */
+  createChildContext(childDiscussionId: string): DiscussionContext;
+
+  /** Record provider calls made */
+  recordCalls(count: number): void;
+
+  /** Record time elapsed */
+  recordElapsed(elapsedMs: number): void;
+
+  /** Get timeout for current depth level */
+  getTimeoutForCurrentLevel(): number;
+
+  /** Get timeout for a specific depth level */
+  getTimeoutForLevel(depth: number): number;
+
+  /** Check if at root level */
+  isRoot(): boolean;
+
+  /** Get remaining depth capacity */
+  getRemainingDepth(): number;
+
+  /** Get remaining call capacity */
+  getRemainingCalls(): number;
+
+  /** Get remaining budget in milliseconds */
+  getRemainingBudgetMs(): number;
+
+  /** Get elapsed time since start */
+  getElapsedMs(): number;
+}
+
+/**
+ * Creates a discussion context tracker
+ */
+export function createContextTracker(
+  discussionId: string,
+  config: Partial<ContextTrackerConfig> = {},
+  parentContext?: DiscussionContext
+): DiscussionContextTracker {
+  // Merge config with defaults
+  const recursiveConfig: RecursiveConfig = {
+    enabled: config.recursive?.enabled ?? false,
+    maxDepth: config.recursive?.maxDepth ?? DEFAULT_DISCUSSION_DEPTH,
+    allowedProviders: config.recursive?.allowedProviders,
+    allowSubDiscussions: config.recursive?.allowSubDiscussions ?? true,
+  };
+
+  const timeoutConfig: TimeoutConfig = {
+    strategy: config.timeout?.strategy ?? 'cascade',
+    totalBudgetMs: config.timeout?.totalBudgetMs ?? DEFAULT_TOTAL_BUDGET_MS,
+    minSynthesisMs: config.timeout?.minSynthesisMs ?? MIN_SYNTHESIS_TIME_MS,
+    levelTimeouts: config.timeout?.levelTimeouts,
+  };
+
+  const costConfig: CostControlConfig = {
+    maxTotalCalls: config.cost?.maxTotalCalls ?? DEFAULT_MAX_TOTAL_CALLS,
+    budgetUsd: config.cost?.budgetUsd,
+    cascadingConfidence: {
+      enabled: config.cost?.cascadingConfidence?.enabled ?? true,
+      threshold: config.cost?.cascadingConfidence?.threshold ?? 0.9,
+      minProviders: config.cost?.cascadingConfidence?.minProviders ?? 2,
+    },
+  };
+
+  // Initialize context
+  let context: DiscussionContext;
+
+  if (parentContext) {
+    // Create child context
+    const elapsed = Date.now() - new Date(parentContext.startedAt).getTime();
+    context = createChildDiscussionContext(parentContext, discussionId, elapsed, 0);
+  } else {
+    // Create root context
+    context = createRootDiscussionContext(discussionId, {
+      maxDepth: recursiveConfig.maxDepth,
+      totalBudgetMs: timeoutConfig.totalBudgetMs,
+      maxTotalCalls: costConfig.maxTotalCalls,
+    });
+  }
+
+  // Track mutable state
+  let totalCalls = context.totalCalls;
+  let elapsedSinceContextCreation = 0;
+
+  return {
+    getContext(): DiscussionContext {
+      return {
+        ...context,
+        totalCalls,
+        remainingBudgetMs: Math.max(0, context.remainingBudgetMs - elapsedSinceContextCreation),
+      };
+    },
+
+    canSpawnSubDiscussion(estimatedDurationMs?: number): SubDiscussionCheck {
+      // Check if recursion is enabled
+      if (!recursiveConfig.enabled) {
+        return {
+          allowed: false,
+          reason: 'Recursive discussions not enabled',
+          errorCode: DiscussionErrorCodes.INVALID_CONFIG,
+        };
+      }
+
+      // Check if sub-discussions allowed
+      if (!recursiveConfig.allowSubDiscussions) {
+        return {
+          allowed: false,
+          reason: 'Sub-discussions not allowed in configuration',
+          errorCode: DiscussionErrorCodes.INVALID_CONFIG,
+        };
+      }
+
+      // Use contract function for basic checks
+      const remainingBudget = context.remainingBudgetMs - elapsedSinceContextCreation;
+      const minBudget = estimatedDurationMs ?? timeoutConfig.minSynthesisMs * 2;
+
+      const checkContext: DiscussionContext = {
+        ...context,
+        totalCalls,
+        remainingBudgetMs: remainingBudget,
+      };
+
+      const check = canSpawnSubDiscussion(checkContext, minBudget);
+
+      if (!check.allowed) {
+        // Determine error code based on reason
+        const reason = check.reason ?? 'Sub-discussion not allowed';
+        let errorCode: string = DiscussionErrorCodes.INVALID_CONFIG;
+        if (reason.includes('depth')) {
+          errorCode = DiscussionErrorCodes.MAX_DEPTH_EXCEEDED;
+        } else if (reason.includes('budget')) {
+          errorCode = DiscussionErrorCodes.BUDGET_EXHAUSTED;
+        } else if (reason.includes('calls')) {
+          errorCode = DiscussionErrorCodes.MAX_CALLS_EXCEEDED;
+        }
+
+        return {
+          allowed: false,
+          reason,
+          errorCode,
+          availableBudgetMs: remainingBudget,
+          remainingCalls: context.maxTotalCalls - totalCalls,
+        };
+      }
+
+      return {
+        allowed: true,
+        availableBudgetMs: remainingBudget,
+        remainingCalls: context.maxTotalCalls - totalCalls,
+      };
+    },
+
+    createChildContext(childDiscussionId: string): DiscussionContext {
+      const elapsed = Date.now() - new Date(context.startedAt).getTime();
+      return createChildDiscussionContext(
+        { ...context, totalCalls },
+        childDiscussionId,
+        elapsed,
+        0
+      );
+    },
+
+    recordCalls(count: number): void {
+      totalCalls += count;
+    },
+
+    recordElapsed(elapsedMs: number): void {
+      elapsedSinceContextCreation += elapsedMs;
+    },
+
+    getTimeoutForCurrentLevel(): number {
+      return getTimeoutForLevel(timeoutConfig, context.depth, context.maxDepth);
+    },
+
+    getTimeoutForLevel(depth: number): number {
+      return getTimeoutForLevel(timeoutConfig, depth, context.maxDepth);
+    },
+
+    isRoot(): boolean {
+      return context.depth === 0;
+    },
+
+    getRemainingDepth(): number {
+      return context.maxDepth - context.depth;
+    },
+
+    getRemainingCalls(): number {
+      return Math.max(0, context.maxTotalCalls - totalCalls);
+    },
+
+    getRemainingBudgetMs(): number {
+      return Math.max(0, context.remainingBudgetMs - elapsedSinceContextCreation);
+    },
+
+    getElapsedMs(): number {
+      return Date.now() - new Date(context.startedAt).getTime();
+    },
+  };
+}
+
+/**
+ * Discussion context error
+ */
+export class DiscussionContextError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly context?: DiscussionContext
+  ) {
+    super(message);
+    this.name = 'DiscussionContextError';
+  }
+
+  static maxDepthExceeded(context: DiscussionContext): DiscussionContextError {
+    return new DiscussionContextError(
+      DiscussionErrorCodes.MAX_DEPTH_EXCEEDED,
+      `Maximum discussion depth ${context.maxDepth} exceeded at depth ${context.depth}`,
+      context
+    );
+  }
+
+  static circularDiscussion(
+    discussionId: string,
+    context: DiscussionContext
+  ): DiscussionContextError {
+    return new DiscussionContextError(
+      DiscussionErrorCodes.CIRCULAR_DISCUSSION,
+      `Circular discussion detected: ${discussionId} already in chain`,
+      context
+    );
+  }
+
+  static budgetExhausted(context: DiscussionContext): DiscussionContextError {
+    return new DiscussionContextError(
+      DiscussionErrorCodes.BUDGET_EXHAUSTED,
+      `Timeout budget exhausted: ${context.remainingBudgetMs}ms remaining`,
+      context
+    );
+  }
+
+  static maxCallsExceeded(context: DiscussionContext): DiscussionContextError {
+    return new DiscussionContextError(
+      DiscussionErrorCodes.MAX_CALLS_EXCEEDED,
+      `Maximum calls ${context.maxTotalCalls} exceeded`,
+      context
+    );
+  }
+}

package/src/cost-tracker.ts

@@ -0,0 +1,362 @@
+/**
+ * Discussion Cost Tracker
+ *
+ * Tracks costs and resource usage across discussion execution.
+ * Enforces budget limits and provides visibility into spending.
+ *
+ * Invariants:
+ * - INV-DISC-620: Total calls ≤ maxTotalCalls
+ * - INV-DISC-621: Abort if cost budget exceeded
+ */
+
+import type { CostControlConfig } from '@defai.digital/contracts';
+import { DEFAULT_MAX_TOTAL_CALLS } from '@defai.digital/contracts';
+
+/**
+ * Cost per provider (approximate, in USD per 1K tokens)
+ * These are rough estimates for planning purposes
+ */
+export const PROVIDER_COSTS: Record<string, { input: number; output: number }> = {
+  claude: { input: 0.003, output: 0.015 },
+  gemini: { input: 0.0005, output: 0.0015 },
+  codex: { input: 0.003, output: 0.006 },
+  qwen: { input: 0.001, output: 0.002 },
+  glm: { input: 0.001, output: 0.002 },
+  grok: { input: 0.002, output: 0.004 },
+};
+
+/**
+ * Default cost per provider if not in the map
+ */
+const DEFAULT_COST = { input: 0.002, output: 0.004 };
+
+/**
+ * Provider call record
+ */
+export interface ProviderCallRecord {
+  /** Provider ID */
+  providerId: string;
+
+  /** Input tokens */
+  inputTokens: number;
+
+  /** Output tokens */
+  outputTokens: number;
+
+  /** Duration in milliseconds */
+  durationMs: number;
+
+  /** Estimated cost in USD */
+  estimatedCostUsd: number;
+
+  /** Discussion depth where call occurred */
+  depth: number;
+
+  /** Timestamp */
+  timestamp: string;
+
+  /** Whether call succeeded */
+  success: boolean;
+}
+
+/**
+ * Cost tracking summary
+ */
+export interface CostSummary {
+  /** Total provider calls made */
+  totalCalls: number;
+
+  /** Total input tokens */
+  totalInputTokens: number;
+
+  /** Total output tokens */
+  totalOutputTokens: number;
+
+  /** Total estimated cost in USD */
+  totalCostUsd: number;
+
+  /** Cost breakdown by provider */
+  byProvider: Record<string, {
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+  }>;
+
+  /** Cost breakdown by depth level */
+  byDepth: Record<number, {
+    calls: number;
+    costUsd: number;
+  }>;
+
+  /** Whether budget limit was exceeded */
+  budgetExceeded: boolean;
+
+  /** Whether call limit was exceeded */
+  callLimitExceeded: boolean;
+
+  /** Remaining budget (if configured) */
+  remainingBudgetUsd: number | undefined;
+
+  /** Remaining calls */
+  remainingCalls: number;
+}
+
+/**
+ * Budget check result
+ */
+export interface BudgetCheckResult {
+  /** Whether operation is allowed */
+  allowed: boolean;
+
+  /** Reason if not allowed */
+  reason?: string;
+
+  /** Current usage metrics */
+  currentCalls: number;
+  currentCostUsd: number;
+
+  /** Estimated cost of proposed operation */
+  estimatedCostUsd?: number;
+}
+
+/**
+ * Discussion cost tracker interface
+ */
+export interface DiscussionCostTracker {
+  /** Record a provider call */
+  recordCall(record: Omit<ProviderCallRecord, 'estimatedCostUsd' | 'timestamp'>): void;
+
+  /** Check if a call is within budget */
+  checkBudget(providerId: string, estimatedTokens?: number): BudgetCheckResult;
+
+  /** Get current cost summary */
+  getSummary(): CostSummary;
+
+  /** Get total calls made */
+  getTotalCalls(): number;
+
+  /** Get remaining calls */
+  getRemainingCalls(): number;
+
+  /** Check if budget exceeded */
+  isBudgetExceeded(): boolean;
+
+  /** Check if call limit exceeded */
+  isCallLimitExceeded(): boolean;
+
+  /** Estimate cost for a provider call */
+  estimateCost(providerId: string, inputTokens: number, outputTokens: number): number;
+
+  /** Create child tracker for sub-discussion */
+  createChildTracker(depth: number): DiscussionCostTracker;
+}
+
+/**
+ * Create a cost tracker for a discussion
+ */
+export function createCostTracker(
+  config: CostControlConfig,
+  parentTracker?: DiscussionCostTracker
+): DiscussionCostTracker {
+  const calls: ProviderCallRecord[] = [];
+  const maxTotalCalls = config.maxTotalCalls ?? DEFAULT_MAX_TOTAL_CALLS;
+  const budgetUsd = config.budgetUsd;
+
+  // Track inherited calls from parent
+  const parentCalls = parentTracker?.getTotalCalls() ?? 0;
+
+  return {
+    recordCall(record): void {
+      const cost = estimateCallCost(
+        record.providerId,
+        record.inputTokens,
+        record.outputTokens
+      );
+
+      calls.push({
+        ...record,
+        estimatedCostUsd: cost,
+        timestamp: new Date().toISOString(),
+      });
+    },
+
+    checkBudget(providerId, estimatedTokens = 1000): BudgetCheckResult {
+      const currentCalls = calls.length + parentCalls;
+      const currentCost = calls.reduce((sum, c) => sum + c.estimatedCostUsd, 0);
+
+      // Check call limit
+      if (currentCalls >= maxTotalCalls) {
+        return {
+          allowed: false,
+          reason: `Call limit ${maxTotalCalls} reached`,
+          currentCalls,
+          currentCostUsd: currentCost,
+        };
+      }
+
+      // Check budget limit if configured
+      if (budgetUsd !== undefined) {
+        const estimatedCost = estimateCallCost(providerId, estimatedTokens, estimatedTokens);
+        if (currentCost + estimatedCost > budgetUsd) {
+          return {
+            allowed: false,
+            reason: `Budget limit $${budgetUsd.toFixed(2)} would be exceeded`,
+            currentCalls,
+            currentCostUsd: currentCost,
+            estimatedCostUsd: estimatedCost,
+          };
+        }
+      }
+
+      return {
+        allowed: true,
+        currentCalls,
+        currentCostUsd: currentCost,
+      };
+    },
+
+    getSummary(): CostSummary {
+      const byProvider: CostSummary['byProvider'] = {};
+      const byDepth: CostSummary['byDepth'] = {};
+
+      let totalInputTokens = 0;
+      let totalOutputTokens = 0;
+      let totalCostUsd = 0;
+
+      for (const call of calls) {
+        // Aggregate by provider
+        if (!byProvider[call.providerId]) {
+          byProvider[call.providerId] = {
+            calls: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            costUsd: 0,
+          };
+        }
+        const providerStats = byProvider[call.providerId]!;
+        providerStats.calls++;
+        providerStats.inputTokens += call.inputTokens;
+        providerStats.outputTokens += call.outputTokens;
+        providerStats.costUsd += call.estimatedCostUsd;
+
+        // Aggregate by depth
+        if (!byDepth[call.depth]) {
+          byDepth[call.depth] = { calls: 0, costUsd: 0 };
+        }
+        const depthStats = byDepth[call.depth]!;
+        depthStats.calls++;
+        depthStats.costUsd += call.estimatedCostUsd;
+
+        // Totals
+        totalInputTokens += call.inputTokens;
+        totalOutputTokens += call.outputTokens;
+        totalCostUsd += call.estimatedCostUsd;
+      }
+
+      const totalCalls = calls.length + parentCalls;
+
+      return {
+        totalCalls,
+        totalInputTokens,
+        totalOutputTokens,
+        totalCostUsd,
+        byProvider,
+        byDepth,
+        budgetExceeded: budgetUsd !== undefined && totalCostUsd > budgetUsd,
+        callLimitExceeded: totalCalls > maxTotalCalls,
+        remainingBudgetUsd: budgetUsd !== undefined ? Math.max(0, budgetUsd - totalCostUsd) : undefined,
+        remainingCalls: Math.max(0, maxTotalCalls - totalCalls),
+      };
+    },
+
+    getTotalCalls(): number {
+      return calls.length + parentCalls;
+    },
+
+    getRemainingCalls(): number {
+      return Math.max(0, maxTotalCalls - (calls.length + parentCalls));
+    },
+
+    isBudgetExceeded(): boolean {
+      if (budgetUsd === undefined) return false;
+      const totalCost = calls.reduce((sum, c) => sum + c.estimatedCostUsd, 0);
+      return totalCost > budgetUsd;
+    },
+
+    isCallLimitExceeded(): boolean {
+      return calls.length + parentCalls > maxTotalCalls;
+    },
+
+    estimateCost(providerId, inputTokens, outputTokens): number {
+      return estimateCallCost(providerId, inputTokens, outputTokens);
+    },
+
+    createChildTracker(depth: number): DiscussionCostTracker {
+      // Child tracker inherits call count from parent
+      const childConfig = { ...config };
+      const childTracker = createCostTracker(childConfig, this);
+
+      // Wrapper to set depth on all recorded calls
+      const originalRecord = childTracker.recordCall.bind(childTracker);
+      childTracker.recordCall = (record) => {
+        originalRecord({ ...record, depth });
+      };
+
+      return childTracker;
+    },
+  };
+}
+
+/**
+ * Estimate cost for a provider call
+ */
+function estimateCallCost(
+  providerId: string,
+  inputTokens: number,
+  outputTokens: number
+): number {
+  const costs = PROVIDER_COSTS[providerId] || DEFAULT_COST;
+
+  const inputCost = (inputTokens / 1000) * costs.input;
+  const outputCost = (outputTokens / 1000) * costs.output;
+
+  return inputCost + outputCost;
+}
+
+/**
+ * Format cost for display
+ */
+export function formatCost(costUsd: number): string {
+  if (costUsd < 0.01) {
+    return `$${(costUsd * 100).toFixed(2)}¢`;
+  }
+  return `$${costUsd.toFixed(4)}`;
+}
+
+/**
+ * Format cost summary for CLI/logs
+ */
+export function formatCostSummary(summary: CostSummary): string {
+  const lines: string[] = [
+    `Cost Summary:`,
+    `  Total Calls: ${summary.totalCalls}`,
+    `  Total Tokens: ${summary.totalInputTokens} in / ${summary.totalOutputTokens} out`,
+    `  Estimated Cost: ${formatCost(summary.totalCostUsd)}`,
+  ];
+
+  if (summary.remainingBudgetUsd !== undefined) {
+    lines.push(`  Remaining Budget: ${formatCost(summary.remainingBudgetUsd)}`);
+  }
+
+  lines.push(`  Remaining Calls: ${summary.remainingCalls}`);
+
+  if (Object.keys(summary.byProvider).length > 0) {
+    lines.push(`  By Provider:`);
+    for (const [provider, data] of Object.entries(summary.byProvider)) {
+      lines.push(`    ${provider}: ${data.calls} calls, ${formatCost(data.costUsd)}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/executor.ts

@@ -75,6 +75,7 @@ export class DiscussionExecutor {
       continueOnProviderFailure: true,
       minProviders: 2,
       temperature: 0.7,
+      agentWeightMultiplier: 1.5,
     };
 
     return this.execute(config, options);
@@ -141,6 +142,7 @@ export class DiscussionExecutor {
       abortSignal,
       traceId: this.traceId,
       onProgress,
+      // No cascading confidence for base executor (recursive executor handles this)
     };
 
     // Execute pattern
@@ -164,6 +166,7 @@ export class DiscussionExecutor {
       rounds: patternResult.rounds,
       participatingProviders: patternResult.participatingProviders,
       config: config.consensus,
+      agentWeightMultiplier: config.agentWeightMultiplier,
       providerExecutor: this.providerExecutor,
       abortSignal,
       onProgress,
@@ -195,6 +198,10 @@ export class DiscussionExecutor {
         startedAt,
         completedAt: new Date().toISOString(),
         traceId: this.traceId,
+        // Include early exit info if pattern triggered it
+        ...(patternResult.earlyExit?.triggered ? {
+          earlyExit: patternResult.earlyExit,
+        } : {}),
       },
     };
 
@@ -284,6 +291,7 @@ export class DiscussionExecutor {
       continueOnProviderFailure: false, // Debates require all participants
       minProviders: 3,
       temperature: 0.7,
+      agentWeightMultiplier: 1.5,
     };
 
     return this.execute(config, options);
@@ -318,6 +326,7 @@ export class DiscussionExecutor {
       continueOnProviderFailure: true,
       minProviders: 2,
       temperature: 0.5, // Lower temperature for more consistent voting
+      agentWeightMultiplier: 1.5,
     };
 
     return this.execute(config, options);