outcome-cli 1.0.0

package/src/league/health-check.ts

@@ -0,0 +1,353 @@
+/**
+ * Health Check System - Monitors agent availability
+ *
+ * Periodically checks registered agents to verify they are online
+ * and responsive. Updates agent deployment status accordingly.
+ *
+ * @module league/health-check
+ */
+
+import type {
+  RegisteredAgent,
+  HealthCheckResponse,
+  DeploymentInfo,
+} from '../agents/registered-agent.schema.js';
+
+/**
+ * Health check result for a single agent.
+ */
+export interface HealthCheckResult {
+  agentId: string;
+  agentName: string;
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  latencyMs: number;
+  checkedAt: Date;
+  error?: string;
+  response?: HealthCheckResponse;
+}
+
+/**
+ * Configuration for the health check service.
+ */
+export interface HealthCheckConfig {
+  /** Timeout for health check requests in milliseconds */
+  timeoutMs: number;
+  /** Number of consecutive failures before marking offline */
+  failureThreshold: number;
+  /** Interval between health checks in milliseconds */
+  checkIntervalMs: number;
+}
+
+/**
+ * Default health check configuration.
+ */
+export const DEFAULT_HEALTH_CHECK_CONFIG: HealthCheckConfig = {
+  timeoutMs: 5000,
+  failureThreshold: 3,
+  checkIntervalMs: 60000, // 1 minute
+};
+
+/**
+ * Tracks consecutive failures per agent.
+ */
+const failureCounters: Map<string, number> = new Map();
+
+/**
+ * Perform a health check on a single agent.
+ *
+ * @param agent - The agent to check
+ * @param config - Health check configuration
+ * @returns Health check result
+ */
+export async function checkAgentHealth(
+  agent: RegisteredAgent,
+  config: HealthCheckConfig = DEFAULT_HEALTH_CHECK_CONFIG
+): Promise<HealthCheckResult> {
+  const startTime = Date.now();
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+
+  try {
+    // Determine health endpoint URL
+    const healthUrl = getHealthEndpoint(agent.endpoint.url);
+
+    const response = await fetch(healthUrl, {
+      method: 'GET',
+      headers: buildHeaders(agent),
+      signal: controller.signal,
+    });
+
+    const latencyMs = Date.now() - startTime;
+
+    if (!response.ok) {
+      return createUnhealthyResult(agent, latencyMs, `HTTP ${response.status}`);
+    }
+
+    const data: HealthCheckResponse = await response.json();
+
+    // Reset failure counter on success
+    failureCounters.set(agent.id, 0);
+
+    return {
+      agentId: agent.id,
+      agentName: agent.name,
+      status: data.status,
+      latencyMs,
+      checkedAt: new Date(),
+      response: data,
+    };
+  } catch (error) {
+    const latencyMs = Date.now() - startTime;
+    const errorMessage =
+      error instanceof Error ? error.message : 'Unknown error';
+
+    // Increment failure counter
+    const currentFailures = (failureCounters.get(agent.id) ?? 0) + 1;
+    failureCounters.set(agent.id, currentFailures);
+
+    return createUnhealthyResult(agent, latencyMs, errorMessage);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Check health of multiple agents in parallel.
+ *
+ * @param agents - Array of agents to check
+ * @param config - Health check configuration
+ * @returns Array of health check results
+ */
+export async function checkMultipleAgents(
+  agents: RegisteredAgent[],
+  config: HealthCheckConfig = DEFAULT_HEALTH_CHECK_CONFIG
+): Promise<HealthCheckResult[]> {
+  const results = await Promise.all(
+    agents.map((agent) => checkAgentHealth(agent, config))
+  );
+  return results;
+}
+
+/**
+ * Determine if an agent should be marked offline based on failure count.
+ *
+ * @param agentId - The agent ID
+ * @param config - Health check configuration
+ * @returns True if agent should be marked offline
+ */
+export function shouldMarkOffline(
+  agentId: string,
+  config: HealthCheckConfig = DEFAULT_HEALTH_CHECK_CONFIG
+): boolean {
+  const failures = failureCounters.get(agentId) ?? 0;
+  return failures >= config.failureThreshold;
+}
+
+/**
+ * Get current failure count for an agent.
+ *
+ * @param agentId - The agent ID
+ * @returns Number of consecutive failures
+ */
+export function getFailureCount(agentId: string): number {
+  return failureCounters.get(agentId) ?? 0;
+}
+
+/**
+ * Reset failure counter for an agent.
+ *
+ * @param agentId - The agent ID
+ */
+export function resetFailureCount(agentId: string): void {
+  failureCounters.set(agentId, 0);
+}
+
+/**
+ * Update deployment info based on health check result.
+ *
+ * @param currentInfo - Current deployment info
+ * @param result - Health check result
+ * @param config - Health check configuration
+ * @returns Updated deployment info
+ */
+export function updateDeploymentInfo(
+  currentInfo: DeploymentInfo,
+  result: HealthCheckResult,
+  config: HealthCheckConfig = DEFAULT_HEALTH_CHECK_CONFIG
+): DeploymentInfo {
+  const shouldBeOffline = shouldMarkOffline(result.agentId, config);
+
+  let newStatus: DeploymentInfo['status'];
+  if (shouldBeOffline) {
+    newStatus = 'offline';
+  } else if (result.status === 'healthy') {
+    newStatus = 'online';
+  } else if (result.status === 'degraded') {
+    newStatus = 'degraded';
+  } else {
+    newStatus = currentInfo.status; // Keep current if single failure
+  }
+
+  // Calculate rolling average latency
+  const avgLatency =
+    currentInfo.averageLatencyMs === 0
+      ? result.latencyMs
+      : Math.round((currentInfo.averageLatencyMs + result.latencyMs) / 2);
+
+  // Calculate uptime percentage (simplified)
+  const wasOnline = currentInfo.status === 'online';
+  const isNowOnline = newStatus === 'online';
+  const uptimeChange = isNowOnline ? 1 : wasOnline ? -5 : 0;
+  const newUptime = Math.max(
+    0,
+    Math.min(100, currentInfo.uptimePercent + uptimeChange)
+  );
+
+  return {
+    ...currentInfo,
+    status: newStatus,
+    lastHealthCheck: result.checkedAt,
+    averageLatencyMs: avgLatency,
+    uptimePercent: newUptime,
+  };
+}
+
+/**
+ * Get the health endpoint URL from a chat endpoint URL.
+ */
+function getHealthEndpoint(chatUrl: string): string {
+  const url = new URL(chatUrl);
+
+  // Try common health check paths
+  if (url.pathname.endsWith('/chat')) {
+    url.pathname = url.pathname.replace(/\/chat$/, '/health');
+  } else if (url.pathname.endsWith('/v1/chat/completions')) {
+    url.pathname = url.pathname.replace(/\/v1\/chat\/completions$/, '/health');
+  } else {
+    // Append /health to the base
+    url.pathname = url.pathname.replace(/\/$/, '') + '/health';
+  }
+
+  return url.toString();
+}
+
+/**
+ * Build authentication headers for an agent.
+ */
+function buildHeaders(agent: RegisteredAgent): Record<string, string> {
+  if (agent.endpoint.authType === 'none') {
+    return {};
+  }
+
+  // Note: In production, this would decrypt the token
+  const token = agent.endpoint.encryptedAuthToken ?? '';
+  const headerName = agent.endpoint.authHeader ?? 'Authorization';
+  const headerValue =
+    agent.endpoint.authType === 'bearer' ? `Bearer ${token}` : token;
+
+  return { [headerName]: headerValue };
+}
+
+/**
+ * Create an unhealthy result.
+ */
+function createUnhealthyResult(
+  agent: RegisteredAgent,
+  latencyMs: number,
+  error: string
+): HealthCheckResult {
+  return {
+    agentId: agent.id,
+    agentName: agent.name,
+    status: 'unhealthy',
+    latencyMs,
+    checkedAt: new Date(),
+    error,
+  };
+}
+
+/**
+ * Health Check Service class for managing periodic checks.
+ */
+export class HealthCheckService {
+  private config: HealthCheckConfig;
+  private intervalId: NodeJS.Timeout | null = null;
+  private onStatusChange?: (
+    agentId: string,
+    oldStatus: string,
+    newStatus: string
+  ) => void;
+
+  constructor(
+    config: Partial<HealthCheckConfig> = {},
+    onStatusChange?: (
+      agentId: string,
+      oldStatus: string,
+      newStatus: string
+    ) => void
+  ) {
+    this.config = { ...DEFAULT_HEALTH_CHECK_CONFIG, ...config };
+    this.onStatusChange = onStatusChange;
+  }
+
+  /**
+   * Start periodic health checks.
+   *
+   * @param getAgents - Function to get current list of agents
+   * @param updateAgent - Function to update agent deployment info
+   */
+  start(
+    getAgents: () => RegisteredAgent[],
+    updateAgent: (agentId: string, deployment: DeploymentInfo) => void
+  ): void {
+    if (this.intervalId) {
+      this.stop();
+    }
+
+    const runChecks = async () => {
+      const agents = getAgents();
+      const results = await checkMultipleAgents(agents, this.config);
+
+      for (const result of results) {
+        const agent = agents.find((a) => a.id === result.agentId);
+        if (!agent) continue;
+
+        const oldStatus = agent.deployment.status;
+        const newDeployment = updateDeploymentInfo(
+          agent.deployment,
+          result,
+          this.config
+        );
+
+        if (oldStatus !== newDeployment.status && this.onStatusChange) {
+          this.onStatusChange(agent.id, oldStatus, newDeployment.status);
+        }
+
+        updateAgent(agent.id, newDeployment);
+      }
+    };
+
+    // Run immediately
+    runChecks();
+
+    // Then run periodically
+    this.intervalId = setInterval(runChecks, this.config.checkIntervalMs);
+  }
+
+  /**
+   * Stop periodic health checks.
+   */
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  /**
+   * Check if the service is running.
+   */
+  isRunning(): boolean {
+    return this.intervalId !== null;
+  }
+}

package/src/league/index.ts

@@ -0,0 +1,93 @@
+/**
+ * League Module - Parallel agent competition system
+ *
+ * @module league
+ */
+
+export {
+  type LeagueConfig,
+  type AgentResult,
+  type LeagueResult,
+  runLeague,
+  runLeagueMock,
+} from './runLeague.js';
+
+export {
+  type KillReason,
+  type AgentLimits,
+  type RunningAgent,
+  shouldKillAgent,
+  killAgent,
+  checkAllAgents,
+} from './killAgent.js';
+
+export {
+  type AgentMetrics,
+  type AgentScore,
+  scoreAgent,
+  determineWinner,
+  rankAgents,
+  calculateLeagueStats,
+} from './scoreAgent.js';
+
+// Battle Orchestrator - Production battle management
+export {
+  type BattleConfig,
+  type BattleTask,
+  type BattleResult,
+  type AgentBattleRequest,
+  type AgentBattleResponse,
+  type AgentBattleResult,
+  BattleOrchestrator,
+  AgentOfflineError,
+  createBattleOrchestrator,
+} from './battle-orchestrator.js';
+
+// Health Check System - Agent availability monitoring
+export {
+  type HealthCheckResult,
+  type HealthCheckConfig,
+  DEFAULT_HEALTH_CHECK_CONFIG,
+  checkAgentHealth,
+  checkMultipleAgents,
+  shouldMarkOffline,
+  getFailureCount,
+  resetFailureCount,
+  updateDeploymentInfo,
+  HealthCheckService,
+} from './health-check.js';
+
+// Team Coordinator - Team battle management
+export {
+  type TeamConfig,
+  type TeamState,
+  type StateUpdateResult,
+  type MemberContribution,
+  type TeamPayoutDistribution,
+  type TeamStateChangeEvent,
+  type TeamStateChangeListener,
+  StateConflictError,
+  TeamNotFoundError,
+  NotTeamMemberError,
+  TeamCoordinator,
+  createTeamCoordinator,
+} from './team-coordinator.js';
+
+// Multi-Step Orchestrator - Multi-step bounty execution
+export {
+  type TaskNode,
+  type MultiStepBounty,
+  type TaskExecutionResult,
+  type MultiStepResult,
+  type TaskContext,
+  type MultiStepAgent,
+  CyclicDependencyError,
+  InvalidDependencyError,
+  InvalidFinalTaskError,
+  TaskExecutionError,
+  validateTaskGraph,
+  validateMultiStepBounty,
+  getTopologicalOrder,
+  MultiStepOrchestrator,
+  createMultiStepOrchestrator,
+} from './multi-step-orchestrator.js';

package/src/league/killAgent.ts

@@ -0,0 +1,151 @@
+/**
+ * Kill Agent - Agent termination logic
+ *
+ * Handles agent termination conditions and cleanup.
+ *
+ * @module league/killAgent
+ * @see Requirements 4.3, 4.4, 10.2
+ */
+
+import type { CostTracker } from '../runtime/costTracker.js';
+
+/**
+ * Reason for agent termination.
+ */
+export interface KillReason {
+  /** Type of termination */
+  type: 'cost_exceeded' | 'attempts_exceeded' | 'timeout' | 'competitor_won';
+  /** Human-readable details */
+  details: string;
+}
+
+/**
+ * Limits that trigger agent termination.
+ */
+export interface AgentLimits {
+  /** Maximum tokens allowed */
+  maxTokens: number;
+  /** Maximum attempts allowed */
+  maxAttempts: number;
+  /** Maximum runtime in milliseconds */
+  maxRuntimeMs: number;
+}
+
+/**
+ * State of a running agent.
+ */
+export interface RunningAgent {
+  /** Agent ID */
+  agentId: string;
+  /** Current attempt count */
+  attempts: number;
+  /** Cost tracker for the agent */
+  costTracker: CostTracker;
+  /** Start time of the agent run */
+  startTime: number;
+  /** Whether a competitor has already won */
+  competitorWon: boolean;
+}
+
+/**
+ * Checks if an agent should be terminated based on current state.
+ *
+ * @param agent - Current agent state
+ * @param limits - Termination limits
+ * @returns KillReason if agent should be killed, null otherwise
+ *
+ * @example
+ * const reason = shouldKillAgent(agent, {
+ *   maxTokens: 10000,
+ *   maxAttempts: 5,
+ *   maxRuntimeMs: 300000
+ * });
+ * if (reason) {
+ *   await killAgent(agent.agentId, reason);
+ * }
+ *
+ * @see Requirements 4.3, 4.4, 10.2
+ */
+export function shouldKillAgent(
+  agent: RunningAgent,
+  limits: AgentLimits
+): KillReason | null {
+  // Check if competitor already won (Requirement 4.5)
+  if (agent.competitorWon) {
+    return {
+      type: 'competitor_won',
+      details: `Another agent achieved success first`,
+    };
+  }
+
+  // Check cost ceiling (Requirement 4.4, 10.1)
+  if (agent.costTracker.tokensSpent > limits.maxTokens) {
+    return {
+      type: 'cost_exceeded',
+      details: `Token usage ${agent.costTracker.tokensSpent} exceeded ceiling ${limits.maxTokens}`,
+    };
+  }
+
+  // Check attempt limit (Requirement 4.3)
+  if (agent.attempts >= limits.maxAttempts) {
+    return {
+      type: 'attempts_exceeded',
+      details: `Attempt count ${agent.attempts} reached limit ${limits.maxAttempts}`,
+    };
+  }
+
+  // Check runtime limit (Requirement 10.2)
+  const elapsed = Date.now() - agent.startTime;
+  if (elapsed >= limits.maxRuntimeMs) {
+    return {
+      type: 'timeout',
+      details: `Runtime ${elapsed}ms exceeded limit ${limits.maxRuntimeMs}ms`,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Terminates an agent with the given reason.
+ *
+ * @param agentId - ID of the agent to terminate
+ * @param reason - Reason for termination
+ *
+ * @see Requirements 4.3, 4.4
+ */
+export async function killAgent(
+  agentId: string,
+  reason: KillReason
+): Promise<void> {
+  // Log termination
+  console.log(`🔴 Agent ${agentId} terminated: ${reason.type} - ${reason.details}`);
+
+  // In production, this would:
+  // 1. Send termination signal to the agent
+  // 2. Clean up any resources
+  // 3. Record termination in Durable Objects
+}
+
+/**
+ * Checks multiple agents and returns which ones should be killed.
+ *
+ * @param agents - Array of running agents
+ * @param limits - Termination limits
+ * @returns Map of agentId to KillReason for agents that should be killed
+ */
+export function checkAllAgents(
+  agents: RunningAgent[],
+  limits: AgentLimits
+): Map<string, KillReason> {
+  const toKill = new Map<string, KillReason>();
+
+  for (const agent of agents) {
+    const reason = shouldKillAgent(agent, limits);
+    if (reason) {
+      toKill.set(agent.agentId, reason);
+    }
+  }
+
+  return toKill;
+}