outcome-cli 1.0.0

package/src/agents/registry.ts

@@ -0,0 +1,97 @@
+/**
+ * Agent Registry - Loads and manages all available agents
+ * 
+ * This module discovers all agent configurations in the configs directory
+ * and provides a centralized registry for accessing them.
+ * 
+ * @module agents/registry
+ */
+
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import type { AgentConfig } from './agent.schema.js';
+import { parseAgentConfigYaml } from './agent.schema.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Registry of all loaded agent configurations
+ */
+const agentRegistry: Map<string, AgentConfig> = new Map();
+
+/**
+ * Loads all agent configurations from the configs directory
+ * 
+ * @returns Array of loaded agent configs
+ */
+export async function loadAllAgents(): Promise<AgentConfig[]> {
+  const configsDir = join(__dirname, 'configs');
+  const agents: AgentConfig[] = [];
+
+  try {
+    const files = readdirSync(configsDir);
+    const yamlFiles = files.filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+
+    for (const file of yamlFiles) {
+      const filePath = join(configsDir, file);
+      const yamlContent = readFileSync(filePath, 'utf-8');
+      
+      const { config, validation } = await parseAgentConfigYaml(yamlContent);
+      
+      if (config && validation.valid) {
+        agentRegistry.set(config.id, config);
+        agents.push(config);
+        console.log(`✓ Loaded agent: ${config.name} (${config.id})`);
+      } else {
+        console.error(`✗ Failed to load ${file}:`, validation.errors);
+      }
+    }
+
+    console.log(`\n📦 Agent Registry: ${agents.length} agents loaded\n`);
+    return agents;
+  } catch (error) {
+    console.error('Error loading agents:', error);
+    return [];
+  }
+}
+
+/**
+ * Gets an agent configuration by ID
+ * 
+ * @param agentId - The agent ID to retrieve
+ * @returns The agent config or undefined if not found
+ */
+export function getAgent(agentId: string): AgentConfig | undefined {
+  return agentRegistry.get(agentId);
+}
+
+/**
+ * Gets all registered agent IDs
+ * 
+ * @returns Array of agent IDs
+ */
+export function getAllAgentIds(): string[] {
+  return Array.from(agentRegistry.keys());
+}
+
+/**
+ * Gets all registered agent configurations
+ * 
+ * @returns Array of all agent configs
+ */
+export function getAllAgents(): AgentConfig[] {
+  return Array.from(agentRegistry.values());
+}
+
+/**
+ * Checks if an agent with the given ID exists
+ * 
+ * @param agentId - The agent ID to check
+ * @returns True if agent exists in registry
+ */
+export function hasAgent(agentId: string): boolean {
+  return agentRegistry.has(agentId);
+}

package/src/agents/tournament-configs.property.test.ts

@@ -0,0 +1,266 @@
+/**
+ * Property-based tests for Tournament Agent Configuration Schema Validation
+ *
+ * **Feature: tournament-seed-bounties, Property 10: Agent Configuration Schema Validation**
+ * **Validates: Requirements 6.5, 8.3, 8.4**
+ *
+ * Property 10: Agent Configuration Schema Validation
+ * *For any* agent configuration loaded from YAML, the configuration SHALL validate 
+ * successfully against the AgentSchema, or the system SHALL throw a descriptive error.
+ *
+ * @module agents/tournament-configs.property.test
+ */
+
+import { describe, test, expect } from 'vitest';
+import * as fc from 'fast-check';
+import { readFile } from 'node:fs/promises';
+import { parse } from 'yaml';
+import { validateAgentConfig, type AgentConfig } from './agent.schema.js';
+
+// Tournament agent configuration files
+const TOURNAMENT_CONFIG_FILES = [
+  'src/agents/configs/tournament-coderabbit.yaml',
+  'src/agents/configs/tournament-claude-sonnet.yaml', 
+  'src/agents/configs/tournament-gpt4o.yaml',
+  'src/agents/configs/tournament-llama3.yaml'
+];
+
+/**
+ * Arbitrary for generating valid agent configurations
+ */
+const validAgentConfigArb = fc.record({
+  id: fc.string({ minLength: 3, maxLength: 50 }).filter(s => /^[a-z0-9-]+$/.test(s)),
+  name: fc.string({ minLength: 3, maxLength: 100 }).filter(s => s.trim().length >= 3),
+  prompt: fc.string({ minLength: 20, maxLength: 2000 }).filter(s => s.trim().length >= 20),
+  strategyDescription: fc.string({ minLength: 20, maxLength: 500 }).filter(s => s.trim().length >= 20),
+  toolAccess: fc.array(fc.string({ minLength: 1, maxLength: 50 }), { maxLength: 10 }),
+  costCeiling: fc.integer({ min: 1000, max: 50000 }),
+  modelProvider: fc.constantFrom('claude', 'openai'),
+  modelId: fc.string({ minLength: 3, maxLength: 100 }).filter(s => s.trim().length >= 3)
+});
+
+/**
+ * Arbitrary for generating invalid agent configurations
+ */
+const invalidAgentConfigArb = fc.oneof(
+  // Missing required fields
+  fc.record({
+    name: fc.string(),
+    prompt: fc.string()
+    // Missing id, strategyDescription, etc.
+  }),
+  // Invalid field types
+  fc.record({
+    id: fc.integer(), // Should be string
+    name: fc.string(),
+    prompt: fc.string(),
+    strategyDescription: fc.string(),
+    toolAccess: fc.array(fc.string()),
+    costCeiling: fc.string(), // Should be number
+    modelProvider: fc.constantFrom('claude', 'openai'),
+    modelId: fc.string()
+  }),
+  // Invalid field values
+  fc.record({
+    id: fc.string(),
+    name: fc.string(),
+    prompt: fc.string(),
+    strategyDescription: fc.string(),
+    toolAccess: fc.array(fc.string()),
+    costCeiling: fc.integer({ min: -1000, max: 0 }), // Invalid cost ceiling
+    modelProvider: fc.constantFrom('invalid-provider'), // Invalid provider
+    modelId: fc.string()
+  })
+);
+
+describe('Tournament Agent Configuration Schema Validation - Property Tests', () => {
+  // **Feature: tournament-seed-bounties, Property 10: Agent Configuration Schema Validation**
+  test('all tournament agent configs validate against schema', async () => {
+    for (const configFile of TOURNAMENT_CONFIG_FILES) {
+      const yamlContent = await readFile(configFile, 'utf-8');
+      const config = parse(yamlContent) as AgentConfig;
+      
+      const result = validateAgentConfig(config);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    }
+  });
+
+  // **Feature: tournament-seed-bounties, Property 10: Agent Configuration Schema Validation**
+  test('valid agent configurations pass validation', () => {
+    fc.assert(
+      fc.property(validAgentConfigArb, (config) => {
+        const result = validateAgentConfig(config);
+        expect(result.valid).toBe(true);
+        expect(result.errors).toHaveLength(0);
+      }),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: tournament-seed-bounties, Property 10: Agent Configuration Schema Validation**
+  test('invalid agent configurations fail validation with descriptive errors', () => {
+    fc.assert(
+      fc.property(invalidAgentConfigArb, (config) => {
+        const result = validateAgentConfig(config);
+        expect(result.valid).toBe(false);
+        expect(result.errors.length).toBeGreaterThan(0);
+        
+        // Errors should be descriptive strings
+        expect(result.errors.every(error => typeof error === 'string')).toBe(true);
+        expect(result.errors.every(error => error.length > 0)).toBe(true);
+      }),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: tournament-seed-bounties, Property 10: Agent Configuration Schema Validation**
+  test('validation is deterministic', () => {
+    fc.assert(
+      fc.property(validAgentConfigArb, (config) => {
+        const result1 = validateAgentConfig(config);
+        const result2 = validateAgentConfig(config);
+        
+        expect(result1.valid).toBe(result2.valid);
+        expect(result1.errors).toEqual(result2.errors);
+      }),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: tournament-seed-bounties, Property 10: Agent Configuration Schema Validation**
+  test('tournament configs have required tournament-specific fields', async () => {
+    for (const configFile of TOURNAMENT_CONFIG_FILES) {
+      const yamlContent = await readFile(configFile, 'utf-8');
+      const config = parse(yamlContent) as AgentConfig;
+      
+      // Tournament configs should have specific characteristics
+      expect(config.id).toMatch(/^tournament-/);
+      expect(config.name).toBeTruthy();
+      expect(config.prompt).toBeTruthy();
+      expect(config.strategyDescription).toBeTruthy();
+      expect(Array.isArray(config.toolAccess)).toBe(true);
+      expect(typeof config.costCeiling).toBe('number');
+      expect(config.costCeiling).toBeGreaterThan(0);
+      expect(['claude', 'openai', 'ollama'].includes(config.modelProvider)).toBe(true);
+      expect(config.modelId).toBeTruthy();
+    }
+  });
+
+  // **Feature: tournament-seed-bounties, Property 10: Agent Configuration Schema Validation**
+  test('tournament configs are outcome-aware', async () => {
+    for (const configFile of TOURNAMENT_CONFIG_FILES) {
+      const yamlContent = await readFile(configFile, 'utf-8');
+      const config = parse(yamlContent) as AgentConfig;
+      
+      // Tournament configs should mention tournament-specific concepts
+      const promptLower = config.prompt.toLowerCase();
+      const descriptionLower = config.strategyDescription.toLowerCase();
+      
+      const hasTournamentConcepts = 
+        promptLower.includes('tournament') ||
+        promptLower.includes('code review') ||
+        promptLower.includes('lead gen') ||
+        promptLower.includes('security') ||
+        promptLower.includes('performance') ||
+        promptLower.includes('linkedin') ||
+        descriptionLower.includes('tournament') ||
+        descriptionLower.includes('code review') ||
+        descriptionLower.includes('lead gen');
+        
+      expect(hasTournamentConcepts).toBe(true);
+    }
+  });
+
+  // **Feature: tournament-seed-bounties, Property 10: Agent Configuration Schema Validation**
+  test('validation result structure is consistent', () => {
+    fc.assert(
+      fc.property(
+        fc.oneof(validAgentConfigArb, invalidAgentConfigArb),
+        (config) => {
+          const result = validateAgentConfig(config);
+          
+          // Must have valid boolean and errors array
+          expect(typeof result.valid).toBe('boolean');
+          expect(Array.isArray(result.errors)).toBe(true);
+          
+          // If valid, errors should be empty; if invalid, errors should have content
+          if (result.valid) {
+            expect(result.errors).toHaveLength(0);
+          } else {
+            expect(result.errors.length).toBeGreaterThan(0);
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: tournament-seed-bounties, Property 10: Agent Configuration Schema Validation**
+  test('cost ceiling validation works correctly', () => {
+    fc.assert(
+      fc.property(
+        fc.integer({ min: -10000, max: 100000 }),
+        (costCeiling) => {
+          const config = {
+            id: 'test-agent',
+            name: 'Test Agent',
+            prompt: 'Test prompt for validation',
+            strategyDescription: 'Test strategy description',
+            toolAccess: [],
+            costCeiling,
+            modelProvider: 'claude' as const,
+            modelId: 'claude-3-sonnet'
+          };
+          
+          const result = validateAgentConfig(config);
+          
+          if (costCeiling > 0) {
+            expect(result.valid).toBe(true);
+          } else {
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(error => 
+              error.toLowerCase().includes('cost') || 
+              error.toLowerCase().includes('ceiling')
+            )).toBe(true);
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: tournament-seed-bounties, Property 10: Agent Configuration Schema Validation**
+  test('model provider validation works correctly', () => {
+    fc.assert(
+      fc.property(
+        fc.string(),
+        (modelProvider) => {
+          const config = {
+            id: 'test-agent',
+            name: 'Test Agent',
+            prompt: 'Test prompt for validation',
+            strategyDescription: 'Test strategy description',
+            toolAccess: [],
+            costCeiling: 5000,
+            modelProvider: modelProvider as any,
+            modelId: 'test-model'
+          };
+          
+          const result = validateAgentConfig(config);
+          
+          if (['claude', 'openai'].includes(modelProvider)) {
+            expect(result.valid).toBe(true);
+          } else {
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(error => 
+              error.toLowerCase().includes('provider') || 
+              error.toLowerCase().includes('model')
+            )).toBe(true);
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+});

package/src/cli/README.md

@@ -0,0 +1,145 @@
+# CLI Module
+
+Command-line interface for the Earnd Bounty Engine using Commander.js.
+
+## Installation
+
+The CLI is included with the package. After building, it can be run via:
+
+```bash
+npx ts-node src/cli/index.ts
+# or after compilation
+node dist/cli/index.js
+```
+
+## Commands
+
+### outcome run
+
+Start a league run with N agents competing for an outcome.
+
+```bash
+earnd outcome run <name> [options]
+
+Arguments:
+  name                     Outcome name to run (e.g., qualified_sales_interest)
+
+Options:
+  -a, --agents <number>    Number of agents to run in parallel (default: "3")
+  -c, --ceiling <number>   Global spend ceiling in tokens (default: "50000")
+  --mock                   Run in mock mode without real API calls
+  --provider <provider>    Model provider: claude or openai (default: "claude")
+  --model <model>          Model ID to use (default: "claude-3-sonnet-20240229")
+```
+
+**Examples:**
+
+```bash
+# Run with 3 agents in mock mode
+earnd outcome run qualified_sales_interest --mock
+
+# Run with 5 agents using real API
+earnd outcome run qualified_sales_interest --agents 5
+
+# Run with OpenAI
+earnd outcome run qualified_sales_interest --provider openai --model gpt-4
+```
+
+### outcome logs
+
+Display all logs for an outcome.
+
+```bash
+earnd outcome logs <name> [options]
+
+Arguments:
+  name                Outcome name to show logs for
+
+Options:
+  -a, --agent <id>    Filter logs by agent ID
+  --json              Output logs in JSON format
+```
+
+**Examples:**
+
+```bash
+# Show all logs for an outcome
+earnd outcome logs qualified_sales_interest
+
+# Show logs for specific agent
+earnd outcome logs qualified_sales_interest --agent agent-0
+
+# Output as JSON
+earnd outcome logs qualified_sales_interest --json
+```
+
+### outcome payout
+
+Trigger payout for a winning agent.
+
+```bash
+earnd outcome payout <name> --agent <id> [options]
+
+Arguments:
+  name                Outcome name
+
+Options:
+  --agent <id>        Agent ID to trigger payout for (required)
+  --dry-run           Show payout details without executing
+```
+
+**Examples:**
+
+```bash
+# Check payout eligibility (dry run)
+earnd outcome payout qualified_sales_interest --agent agent-0 --dry-run
+
+# Execute payout
+earnd outcome payout qualified_sales_interest --agent agent-0
+```
+
+## Environment Variables
+
+For real API calls (non-mock mode), set the appropriate API key:
+
+```bash
+# For Claude
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# For OpenAI  
+export OPENAI_API_KEY=sk-...
+```
+
+## Requirements Reference
+
+- **7.1** - `outcome run <name> --agents=N` starts a league run
+- **7.2** - `outcome logs <name>` displays all logs for the outcome
+- **7.3** - `outcome payout <name> --agent=<id>` triggers payout
+- **7.4** - CLI output is readable and demo-friendly
+
+## Output Format
+
+The CLI uses emoji and formatting for demo-friendly output:
+
+```text
+🚀 Earnd Bounty Engine - League Run
+══════════════════════════════════════════════════
+📋 Outcome: qualified_sales_interest
+👥 Agents: 3
+💰 Global Ceiling: 50,000 tokens
+🤖 Provider: claude
+══════════════════════════════════════════════════
+
+🏃 Starting league run...
+
+✅ Agent:agent-0 | SUCCESS
+❌ Agent:agent-1 | FAILURE | Reason: Competitor won first
+❌ Agent:agent-2 | FAILURE | Reason: Competitor won first
+
+══════════════════════════════════════════════════
+📊 League Results
+══════════════════════════════════════════════════
+
+🏆 Winner: agent-0
+💵 Payout: $250
+```

package/src/cli/commands/define.ts

@@ -0,0 +1,79 @@
+/**
+ * Outcome Define Command
+ *
+ * Defines a new outcome with custom success criteria.
+ * Useful for creating domain-specific outcomes for leagues.
+ */
+
+import { Command } from 'commander';
+import { writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { Outcome, SuccessCriterion } from '../../outcomes/outcome.schema.js';
+
+export function createDefineCommand(): Command {
+  const defineCmd = new Command('define');
+
+  defineCmd
+    .description('Define a new custom outcome')
+    .argument('<name>', 'Name of the new outcome')
+    .argument('<description>', 'Description of what the outcome achieves')
+    .option('-f, --file <file>', 'Output file path (default: outcomes/<name>.json)', (name) => `outcomes/${name}.json`)
+    .option('-p, --payout <amount>', 'Payout amount in dollars (default: 100)', parseFloat, 100)
+    .option('-t, --timeout <minutes>', 'Time limit in minutes (default: 30)', parseFloat, 30)
+    .option('--validator <validator>', 'Validator function name to use', 'validateSuccess')
+    .option('--params <json>', 'JSON string of validator parameters', '{}')
+    .action(async (name: string, description: string, options: {
+      file?: string;
+      payout?: number;
+      timeout?: number;
+      validator?: string;
+      params?: string;
+    }) => {
+      try {
+        // Parse validator params
+        let validatorParams: Record<string, any> = {};
+        try {
+          validatorParams = JSON.parse(options.params || '{}');
+        } catch (e) {
+          console.error('Error parsing validator params JSON');
+          process.exit(1);
+        }
+
+        // Create success criteria
+        const criteria: SuccessCriterion[] = [{
+          name: `${name} Success`,
+          description: description,
+          validator: options.validator || 'validateSuccess',
+          params: validatorParams,
+        }];
+
+        // Create the outcome
+        const outcome: Outcome = {
+          name,
+          description,
+          payoutAmount: options.payout || 100,
+          timeLimitMs: (options.timeout || 30) * 60 * 1000,
+          successCriteria: criteria,
+        };
+
+        // Write to file
+        const outputPath = resolve(options.file || `outcomes/${name}.json`);
+        writeFileSync(outputPath, JSON.stringify(outcome, null, 2));
+
+        console.log(`✅ Created outcome "${name}"`);
+        console.log(`📁 Saved to: ${outputPath}`);
+        console.log(`💰 Payout: $${outcome.payoutAmount}`);
+        console.log(`⏱️  Time limit: ${options.timeout || 30} minutes`);
+        console.log(`📋 Criteria: ${criteria.length} (${criteria[0].validator})`);
+
+        console.log('\nTo use this outcome:');
+        console.log(`  outcome run ${name} --config your-config.json`);
+
+      } catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+      }
+    });
+
+  return defineCmd;
+}

package/src/cli/commands/list.ts

@@ -0,0 +1,46 @@
+/**
+ * List Command - Show available outcomes (sales + code delivery)
+ */
+import { Command } from 'commander';
+import { CODE_DELIVERY_OUTCOMES } from '../../outcomes/code-delivery-outcomes.js';
+import { CODE_OUTCOMES } from '../../outcomes/code-outcomes.js';
+import { qualifiedSalesInterest } from '../../outcomes/qualified_sales_interest.js';
+import { codeReviewBattle } from '../../outcomes/code_review_battle.js';
+import { leadGenBattle } from '../../outcomes/lead_gen_battle.js';
+
+export const listCommand = new Command('list')
+  .description('List available outcomes and presets')
+  .action(() => {
+    const entries: Array<{ name: string; description: string; category: string }> = [];
+
+    entries.push({
+      name: qualifiedSalesInterest.name,
+      description: qualifiedSalesInterest.description,
+      category: 'sales',
+    });
+    entries.push({
+      name: codeReviewBattle.name,
+      description: codeReviewBattle.description,
+      category: 'code-review',
+    });
+    entries.push({
+      name: leadGenBattle.name,
+      description: leadGenBattle.description,
+      category: 'lead-gen',
+    });
+
+    Object.values(CODE_DELIVERY_OUTCOMES).forEach((o) =>
+      entries.push({ name: o.name, description: o.description, category: 'code-delivery' })
+    );
+
+    Object.values(CODE_OUTCOMES).forEach((o) =>
+      entries.push({ name: o.name, description: o.description, category: `code-${o.category}` })
+    );
+
+    console.log('\nAvailable outcomes:\n');
+    for (const e of entries) {
+      console.log(`- ${e.name} [${e.category}]`);
+      console.log(`  ${e.description}`);
+    }
+    console.log('');
+  });