@smartergpt/lexrunner 1.0.0 → 1.3.0

package/src/governance/mcpStatus.ts

@@ -1,258 +0,0 @@
-/**
- * MCP Status Governance Integration
- *
- * Implements acceptance criteria 4: "Tier Metrics in MCP Server"
- *
- * Provides governance status for MCP status tool:
- * - Tier distribution
- * - Escalation rate with threshold warnings
- * - Turn Cost summary
- * - Hostility score
- */
-
-import type { TierMetrics } from "../tiers/metrics.js";
-import { TIER_METRIC_TARGETS, meetsGovernanceTargets } from "../tiers/metrics.js";
-import type { HostilityScore } from "../hostility/score.js";
-import type { TurnCostSummary } from "../metrics/turncost.js";
-
-/**
- * Governance status for MCP status output
- */
-export interface GovernanceStatus {
-  /** Tier distribution and metrics */
-  tiers?: {
-    /** Count by tier */
-    distribution: {
-      senior: number;
-      mid: number;
-      junior: number;
-    };
-    /** Escalation rate (0-1) */
-    escalationRate: number;
-    /** Whether escalation rate exceeds threshold */
-    escalationWarning: boolean;
-    /** Tier match rate (0-1) */
-    tierMatchRate: number;
-    /** Whether governance targets are met */
-    meetsTargets: boolean;
-  };
-  /** Turn Cost summary */
-  turnCost?: {
-    /** Weighted score */
-    weightedScore: number;
-    /** Event count */
-    eventCount: number;
-    /** Whether there's a regression */
-    hasRegression: boolean;
-    /** Comparison to prior run */
-    priorRunScore?: number;
-  };
-  /** Environmental hostility */
-  hostility?: {
-    /** Overall score (0-1) */
-    score: number;
-    /** Status (low/medium/high) */
-    status: "low" | "medium" | "high";
-    /** Number of recommendations */
-    recommendationCount: number;
-  };
-  /** Overall governance health */
-  health: "healthy" | "warning" | "critical";
-  /** Summary warnings */
-  warnings: string[];
-}
-
-/**
- * Build governance status from component metrics.
- *
- * @param tierMetrics - Optional tier metrics from execution
- * @param turnCostSummary - Optional Turn Cost summary
- * @param hostilityScore - Optional hostility score
- * @param priorTurnCostScore - Optional prior run Turn Cost for comparison
- * @returns Complete governance status
- */
-export function buildGovernanceStatus(
-  tierMetrics?: TierMetrics,
-  turnCostSummary?: TurnCostSummary,
-  hostilityScore?: HostilityScore,
-  priorTurnCostScore?: number
-): GovernanceStatus {
-  const warnings: string[] = [];
-  let health: GovernanceStatus["health"] = "healthy";
-
-  // Build tier status if available
-  let tiers: GovernanceStatus["tiers"] | undefined;
-  if (tierMetrics) {
-    const targetsMet = meetsGovernanceTargets(tierMetrics);
-    const escalationWarning = tierMetrics.escalationRate > TIER_METRIC_TARGETS.escalationRate;
-
-    if (escalationWarning) {
-      warnings.push(
-        `Escalation rate (${(tierMetrics.escalationRate * 100).toFixed(1)}%) ` +
-          `exceeds threshold (${TIER_METRIC_TARGETS.escalationRate * 100}%)`
-      );
-      health = "warning";
-    }
-
-    if (!targetsMet.tierMatchRate) {
-      warnings.push(
-        `Tier match rate (${(tierMetrics.tierMatchRate * 100).toFixed(1)}%) ` +
-          `below target (${TIER_METRIC_TARGETS.tierMatchRate * 100}%)`
-      );
-      health = "warning";
-    }
-
-    tiers = {
-      distribution: {
-        senior: tierMetrics.byActualTier.senior,
-        mid: tierMetrics.byActualTier.mid,
-        junior: tierMetrics.byActualTier.junior,
-      },
-      escalationRate: tierMetrics.escalationRate,
-      escalationWarning,
-      tierMatchRate: tierMetrics.tierMatchRate,
-      meetsTargets: targetsMet.meetsAll,
-    };
-  }
-
-  // Build Turn Cost status if available
-  let turnCost: GovernanceStatus["turnCost"] | undefined;
-  if (turnCostSummary) {
-    let hasRegression = false;
-
-    if (priorTurnCostScore !== undefined && priorTurnCostScore > 0) {
-      const percentageChange =
-        (turnCostSummary.weightedScore - priorTurnCostScore) / priorTurnCostScore;
-      hasRegression = percentageChange > 0.2; // 20% threshold
-
-      if (hasRegression) {
-        warnings.push(
-          `Turn Cost regression: +${(percentageChange * 100).toFixed(0)}% from prior run`
-        );
-        health = "warning";
-      }
-    }
-
-    turnCost = {
-      weightedScore: turnCostSummary.weightedScore,
-      eventCount: turnCostSummary.eventCount,
-      hasRegression,
-      priorRunScore: priorTurnCostScore,
-    };
-  }
-
-  // Build hostility status if available
-  let hostility: GovernanceStatus["hostility"] | undefined;
-  if (hostilityScore) {
-    hostility = {
-      score: hostilityScore.total,
-      status: hostilityScore.status,
-      recommendationCount: hostilityScore.recommendations.length,
-    };
-
-    if (hostilityScore.status === "high") {
-      warnings.push(`Environment hostility is high (${(hostilityScore.total * 100).toFixed(0)}%)`);
-      health = health === "healthy" ? "warning" : health;
-    }
-
-    // Critical if hostility is very high
-    if (hostilityScore.total > 0.8) {
-      health = "critical";
-    }
-  }
-
-  // Check for critical conditions
-  if (warnings.length > 3) {
-    health = "critical";
-  }
-
-  return {
-    tiers,
-    turnCost,
-    hostility,
-    health,
-    warnings,
-  };
-}
-
-/**
- * Format governance status for human-readable display.
- *
- * @param status - Governance status
- * @returns Formatted string
- */
-export function formatGovernanceStatus(status: GovernanceStatus): string {
-  const lines: string[] = [];
-
-  lines.push("Governance Status");
-  lines.push("═════════════════");
-  lines.push("");
-
-  // Health indicator
-  const healthIcon = status.health === "healthy" ? "✅" : status.health === "warning" ? "⚠️" : "❌";
-  lines.push(`Overall Health: ${healthIcon} ${status.health.toUpperCase()}`);
-  lines.push("");
-
-  // Tier distribution
-  if (status.tiers) {
-    lines.push("Tier Distribution:");
-    lines.push(`  Senior: ${status.tiers.distribution.senior}`);
-    lines.push(`  Mid:    ${status.tiers.distribution.mid}`);
-    lines.push(`  Junior: ${status.tiers.distribution.junior}`);
-    lines.push("");
-    lines.push(
-      `Escalation Rate: ${(status.tiers.escalationRate * 100).toFixed(1)}%${status.tiers.escalationWarning ? " ⚠️" : ""}`
-    );
-    lines.push(`Tier Match Rate: ${(status.tiers.tierMatchRate * 100).toFixed(1)}%`);
-    lines.push(`Targets Met:     ${status.tiers.meetsTargets ? "✅" : "❌"}`);
-    lines.push("");
-  }
-
-  // Turn Cost
-  if (status.turnCost) {
-    lines.push("Turn Cost:");
-    lines.push(`  Weighted Score: ${status.turnCost.weightedScore.toFixed(2)}`);
-    lines.push(`  Event Count:    ${status.turnCost.eventCount}`);
-    if (status.turnCost.priorRunScore !== undefined) {
-      lines.push(`  Prior Score:    ${status.turnCost.priorRunScore.toFixed(2)}`);
-      lines.push(`  Regression:     ${status.turnCost.hasRegression ? "⚠️ Yes" : "No"}`);
-    }
-    lines.push("");
-  }
-
-  // Hostility
-  if (status.hostility) {
-    const hostilityIcon =
-      status.hostility.status === "low" ? "✅" : status.hostility.status === "medium" ? "⚠️" : "❌";
-    lines.push("Environment Hostility:");
-    lines.push(`  Score:  ${(status.hostility.score * 100).toFixed(0)}% ${hostilityIcon}`);
-    lines.push(`  Status: ${status.hostility.status}`);
-    if (status.hostility.recommendationCount > 0) {
-      lines.push(`  Recommendations: ${status.hostility.recommendationCount}`);
-    }
-    lines.push("");
-  }
-
-  // Warnings
-  if (status.warnings.length > 0) {
-    lines.push("Warnings:");
-    for (const warning of status.warnings) {
-      lines.push(`  ⚠️ ${warning}`);
-    }
-  }
-
-  return lines.join("\n");
-}
-
-/**
- * Convert governance status to JSON-serializable format
- */
-export function governanceStatusToJSON(status: GovernanceStatus): Record<string, unknown> {
-  return {
-    health: status.health,
-    tiers: status.tiers,
-    turnCost: status.turnCost,
-    hostility: status.hostility,
-    warnings: status.warnings,
-  };
-}

package/src/governance/timeoutAdjustment.ts

@@ -1,149 +0,0 @@
-/**
- * Gate Timeout Adjustment based on Environmental Hostility
- *
- * Implements acceptance criteria 1: "Hostility → Gate Timeout Adjustment"
- *
- * When hostility score is high, increase gate timeouts to give more time
- * for operations that may be running in a challenging environment.
- * When hostility is low, use standard timeouts.
- */
-
-import type { HostilityScore, HostilityStatus } from "../hostility/score.js";
-
-/**
- * Default gate timeout in milliseconds (30 seconds)
- */
-export const DEFAULT_GATE_TIMEOUT_MS = 30000;
-
-/**
- * Maximum multiplier for timeout adjustment (3x)
- */
-export const MAX_TIMEOUT_MULTIPLIER = 3.0;
-
-/**
- * Minimum multiplier for timeout adjustment (1x - never reduce)
- */
-export const MIN_TIMEOUT_MULTIPLIER = 1.0;
-
-/**
- * Timeout adjustment result with auditability
- */
-export interface TimeoutAdjustment {
-  /** Original timeout in milliseconds */
-  originalTimeoutMs: number;
-  /** Adjusted timeout in milliseconds */
-  adjustedTimeoutMs: number;
-  /** Multiplier applied */
-  multiplier: number;
-  /** Reason for adjustment */
-  reason: string;
-  /** Hostility status that triggered adjustment */
-  hostilityStatus: HostilityStatus | "low" | "medium" | "high";
-  /** Hostility score (0-1) */
-  hostilityScore: number;
-}
-
-/**
- * Calculate adjusted timeout based on hostility score.
- *
- * Timeout adjustment logic:
- * - Low hostility (score < 0.3): No adjustment (multiplier = 1.0)
- * - Medium hostility (0.3 <= score < 0.6): 1.5x multiplier
- * - High hostility (score >= 0.6): Linear scale from 2.0x to 3.0x
- *
- * @param baseTimeoutMs - Base timeout in milliseconds
- * @param hostilityScore - Hostility score object with total and status
- * @returns TimeoutAdjustment with adjusted timeout and audit information
- */
-export function calculateHostilityAdjustedTimeout(
-  baseTimeoutMs: number,
-  hostilityScore: HostilityScore
-): TimeoutAdjustment {
-  const score = hostilityScore.total;
-  const status = hostilityScore.status;
-
-  let multiplier: number;
-  let reason: string;
-
-  if (score < 0.3) {
-    // Low hostility - no adjustment
-    multiplier = 1.0;
-    reason = "Environment is well-configured; using standard timeout";
-  } else if (score < 0.6) {
-    // Medium hostility - moderate increase
-    multiplier = 1.5;
-    reason = "Environment needs attention; increased timeout for reliability";
-  } else {
-    // High hostility - significant increase
-    // Scale linearly from 2.0 at 0.6 to 3.0 at 1.0
-    multiplier = 2.0 + ((score - 0.6) / 0.4) * 1.0;
-    multiplier = Math.min(multiplier, MAX_TIMEOUT_MULTIPLIER);
-    reason = `High environment hostility (${(score * 100).toFixed(0)}%); using extended timeout`;
-  }
-
-  const adjustedTimeoutMs = Math.round(baseTimeoutMs * multiplier);
-
-  return {
-    originalTimeoutMs: baseTimeoutMs,
-    adjustedTimeoutMs,
-    multiplier,
-    reason,
-    hostilityStatus: status,
-    hostilityScore: score,
-  };
-}
-
-/**
- * Log timeout adjustment decision for auditability.
- *
- * @param adjustment - The timeout adjustment to log
- * @param gateName - Name of the gate being adjusted
- * @param itemName - Name of the item being processed
- */
-export function logTimeoutAdjustment(
-  adjustment: TimeoutAdjustment,
-  gateName: string,
-  itemName?: string
-): void {
-  const context = itemName ? `${gateName}@${itemName}` : gateName;
-
-  // Only log if adjustment was made
-  if (adjustment.multiplier === 1.0) {
-    return;
-  }
-
-  console.log(
-    JSON.stringify({
-      event: "timeout_adjustment",
-      gate: gateName,
-      item: itemName,
-      context,
-      originalTimeoutMs: adjustment.originalTimeoutMs,
-      adjustedTimeoutMs: adjustment.adjustedTimeoutMs,
-      multiplier: adjustment.multiplier,
-      reason: adjustment.reason,
-      hostilityStatus: adjustment.hostilityStatus,
-      hostilityScore: adjustment.hostilityScore,
-      timestamp: new Date().toISOString(),
-    })
-  );
-}
-
-/**
- * Calculate timeout with optional hostility-based adjustment.
- *
- * If hostilityScore is not provided, returns the base timeout unchanged.
- *
- * @param baseTimeoutMs - Base timeout in milliseconds
- * @param hostilityScore - Optional hostility score for adjustment
- * @returns Adjusted timeout in milliseconds
- */
-export function getAdjustedTimeout(baseTimeoutMs: number, hostilityScore?: HostilityScore): number {
-  if (!hostilityScore) {
-    return baseTimeoutMs;
-  }
-
-  const adjustment = calculateHostilityAdjustedTimeout(baseTimeoutMs, hostilityScore);
-
-  return adjustment.adjustedTimeoutMs;
-}

package/src/governance/turnCostSummary.ts

@@ -1,182 +0,0 @@
-/**
- * Turn Cost Summary Integration
- *
- * Implements acceptance criteria 3: "Turn Cost in Merge-Weave Summary"
- *
- * Provides formatted summaries of Turn Cost metrics, comparison with
- * prior runs, and regression detection for end-of-run reporting.
- */
-
-import type { TurnCostSummary, TurnCostComponents } from "../metrics/turncost.js";
-
-/**
- * Threshold for flagging a significant Turn Cost regression (20% increase)
- */
-export const TURN_COST_REGRESSION_THRESHOLD = 0.2;
-
-/**
- * Turn Cost comparison result
- */
-export interface TurnCostComparison {
-  /** Current run's weighted score */
-  currentScore: number;
-  /** Prior run's weighted score (if available) */
-  priorScore?: number;
-  /** Percentage change (positive = worse, negative = improvement) */
-  percentageChange?: number;
-  /** Whether this represents a significant regression */
-  isRegression: boolean;
-  /** Human-readable summary of the comparison */
-  summary: string;
-}
-
-/**
- * Format Turn Cost summary for end-of-run display.
- *
- * @param summary - Turn Cost summary from the tracker
- * @returns Formatted string for display
- */
-export function formatTurnCostSummary(summary: TurnCostSummary): string {
-  const lines: string[] = [];
-
-  lines.push("Turn Cost Summary");
-  lines.push("─────────────────");
-  lines.push("");
-
-  // Component breakdown
-  lines.push("Component Breakdown:");
-  lines.push(`  Latency:           ${formatDuration(summary.components.latencyMs)}`);
-  lines.push(`  Renegotiations:    ${summary.components.renegotiationCount}`);
-  lines.push(`  Token Bloat:       ${summary.components.tokenBloat}`);
-  lines.push(`  Attention Switches: ${summary.components.attentionSwitchCount}`);
-  lines.push("");
-
-  // Weighted score
-  lines.push(`Weighted Score: ${summary.weightedScore.toFixed(2)}`);
-  lines.push(`Total Events:   ${summary.eventCount}`);
-
-  // Prior run comparison if available
-  if (summary.priorRunScore !== undefined) {
-    lines.push("");
-    lines.push(`Prior Run Score: ${summary.priorRunScore.toFixed(2)}`);
-    lines.push(`Change:          ${summary.improvement}`);
-
-    // Flag significant regressions
-    const comparison = compareTurnCosts(summary.weightedScore, summary.priorRunScore);
-    if (comparison.isRegression) {
-      lines.push("");
-      lines.push("⚠️  SIGNIFICANT REGRESSION DETECTED");
-      lines.push(
-        `   Current score is ${(comparison.percentageChange! * 100).toFixed(0)}% higher than prior run`
-      );
-    }
-  }
-
-  return lines.join("\n");
-}
-
-/**
- * Compare current Turn Cost to a prior run.
- *
- * @param currentScore - Current run's weighted score
- * @param priorScore - Prior run's weighted score (optional)
- * @returns Comparison result with regression detection
- */
-export function compareTurnCosts(currentScore: number, priorScore?: number): TurnCostComparison {
-  if (priorScore === undefined || priorScore === 0) {
-    return {
-      currentScore,
-      isRegression: false,
-      summary: "No prior run for comparison",
-    };
-  }
-
-  const percentageChange = (currentScore - priorScore) / priorScore;
-  const isRegression = percentageChange > TURN_COST_REGRESSION_THRESHOLD;
-
-  let summary: string;
-  if (isRegression) {
-    summary = `Turn Cost increased by ${(percentageChange * 100).toFixed(0)}% (threshold: ${(TURN_COST_REGRESSION_THRESHOLD * 100).toFixed(0)}%)`;
-  } else if (percentageChange < 0) {
-    summary = `Turn Cost improved by ${(Math.abs(percentageChange) * 100).toFixed(0)}%`;
-  } else {
-    summary = `Turn Cost stable (${(percentageChange * 100).toFixed(0)}% change)`;
-  }
-
-  return {
-    currentScore,
-    priorScore,
-    percentageChange,
-    isRegression,
-    summary,
-  };
-}
-
-/**
- * Format a Turn Cost comparison for display.
- *
- * @param comparison - Comparison result
- * @returns Formatted comparison string
- */
-export function formatTurnCostComparison(comparison: TurnCostComparison): string {
-  const lines: string[] = [];
-
-  lines.push("Turn Cost Comparison");
-  lines.push("────────────────────");
-  lines.push(`Current Score: ${comparison.currentScore.toFixed(2)}`);
-
-  if (comparison.priorScore !== undefined) {
-    lines.push(`Prior Score:   ${comparison.priorScore.toFixed(2)}`);
-
-    if (comparison.percentageChange !== undefined) {
-      const sign = comparison.percentageChange >= 0 ? "+" : "";
-      lines.push(`Change:        ${sign}${(comparison.percentageChange * 100).toFixed(1)}%`);
-    }
-  }
-
-  lines.push("");
-  lines.push(comparison.isRegression ? `⚠️  ${comparison.summary}` : comparison.summary);
-
-  return lines.join("\n");
-}
-
-/**
- * Helper to format duration in milliseconds to human-readable string
- */
-function formatDuration(ms: number): string {
-  if (ms < 1000) {
-    return `${ms}ms`;
-  }
-  if (ms < 60000) {
-    return `${(ms / 1000).toFixed(2)}s`;
-  }
-  const minutes = Math.floor(ms / 60000);
-  const seconds = ((ms % 60000) / 1000).toFixed(1);
-  return `${minutes}m ${seconds}s`;
-}
-
-/**
- * Convert Turn Cost summary to JSON-serializable format for Frame emission
- */
-export function turnCostSummaryToJSON(
-  summary: TurnCostSummary,
-  priorScore?: number
-): Record<string, unknown> {
-  const comparison = compareTurnCosts(summary.weightedScore, priorScore);
-
-  return {
-    components: {
-      ...summary.components,
-    },
-    weightedScore: summary.weightedScore,
-    eventCount: summary.eventCount,
-    comparison:
-      priorScore !== undefined
-        ? {
-            priorScore,
-            percentageChange: comparison.percentageChange,
-            isRegression: comparison.isRegression,
-          }
-        : null,
-  };
-}