outcome-cli 1.0.0

package/src/agents/agent.schema.ts

@@ -0,0 +1,263 @@
+/**
+ * Agent Schema - Type definitions and validation for agent configurations
+ *
+ * An Agent is a configuration-driven AI entity that attempts to achieve
+ * outcomes using defined prompts, strategies, and tools.
+ *
+ * @module agents/agent.schema
+ */
+
+/**
+ * Supported AI model providers.
+ */
+export type ModelProvider = 'claude' | 'openai' | 'ollama' | 'gemini';
+
+/**
+ * Agent tier classification based on cost and capabilities
+ */
+export type AgentTier = 'premium' | 'budget' | 'free';
+
+/**
+ * Safety restriction level for content moderation
+ */
+export type SafetyLevel = 'low' | 'medium' | 'high';
+
+/**
+ * Agent capabilities declaration
+ * Enables capability-aware bounty matching and filtering
+ */
+export interface AgentCapabilities {
+  /** Can search and scrape web content (requires Firecrawl/web tools) */
+  web_search: boolean;
+  /** Can reliably produce structured output (JSON, CSV, etc.) */
+  structured_output: boolean;
+  /** Can call external APIs (Hunter, Apollo, enrichment services) */
+  external_apis: boolean;
+  /** Supports long context windows (100K+ tokens) */
+  long_context: boolean;
+  /** Can access local files (for desktop automation) */
+  file_io_local: boolean;
+  /** Workspace tools available (Slack, Notion, Sheets, etc.) */
+  workspace_tools: string[];
+  /** Safety/content moderation restriction level */
+  safety_restriction_level: SafetyLevel;
+}
+
+/**
+ * Represents a complete agent configuration.
+ * Agents are configuration-driven with no hard-coded logic.
+ */
+export interface AgentConfig {
+  /** Unique identifier for this agent */
+  id: string;
+  /** Human-readable name for the agent */
+  name: string;
+  /** The prompt template used by the agent */
+  prompt: string;
+  /** Description of the agent's strategy for transparency */
+  strategyDescription: string;
+  /** List of tools the agent is allowed to access */
+  toolAccess: string[];
+  /** Maximum token cost ceiling for this agent */
+  costCeiling: number;
+  /** The AI model provider to use */
+  modelProvider: ModelProvider;
+  /** Specific model identifier (e.g., 'claude-3-sonnet-20240229') */
+  modelId: string;
+  /** Agent capabilities for bounty matching (optional for backward compatibility) */
+  capabilities?: AgentCapabilities;
+  /** Bounty types this agent can handle (optional) */
+  supported_bounty_types?: string[];
+  /** Agent tier classification (optional) */
+  tier?: AgentTier;
+}
+
+/**
+ * Result of validating an agent configuration.
+ */
+export interface ValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+  /** Error messages if validation failed */
+  errors: string[];
+}
+
+/**
+ * Validates an AgentConfig object against the schema.
+ *
+ * Ensures all required fields are present with correct types:
+ * - id: non-empty string
+ * - name: non-empty string
+ * - prompt: non-empty string
+ * - strategyDescription: non-empty string
+ * - toolAccess: array of strings
+ * - costCeiling: positive number
+ * - modelProvider: 'claude' or 'openai'
+ * - modelId: non-empty string
+ *
+ * @param config - The agent configuration object to validate
+ * @returns ValidationResult indicating if the config is valid
+ *
+ * @example
+ * const result = validateAgentConfig(myConfig);
+ * if (!result.valid) {
+ *   console.error('Invalid agent config:', result.errors);
+ * }
+ */
+export function validateAgentConfig(config: unknown): ValidationResult {
+  const errors: string[] = [];
+
+  // Check if config is an object (but not an array)
+  if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+    return { valid: false, errors: ['Agent config must be an object'] };
+  }
+
+  const c = config as Record<string, unknown>;
+
+  // Validate id
+  if (typeof c.id !== 'string') {
+    errors.push('Agent config must have a string "id"');
+  } else if (c.id.trim() === '') {
+    errors.push('Agent config "id" must not be empty');
+  }
+
+  // Validate name
+  if (typeof c.name !== 'string') {
+    errors.push('Agent config must have a string "name"');
+  } else if (c.name.trim() === '') {
+    errors.push('Agent config "name" must not be empty');
+  }
+
+  // Validate prompt
+  if (typeof c.prompt !== 'string') {
+    errors.push('Agent config must have a string "prompt"');
+  } else if (c.prompt.trim() === '') {
+    errors.push('Agent config "prompt" must not be empty');
+  }
+
+  // Validate strategyDescription
+  if (typeof c.strategyDescription !== 'string') {
+    errors.push('Agent config must have a string "strategyDescription"');
+  } else if (c.strategyDescription.trim() === '') {
+    errors.push('Agent config "strategyDescription" must not be empty');
+  }
+
+  // Validate toolAccess
+  if (!Array.isArray(c.toolAccess)) {
+    errors.push('Agent config must have an array "toolAccess"');
+  } else {
+    c.toolAccess.forEach((tool, index) => {
+      if (typeof tool !== 'string') {
+        errors.push(`toolAccess[${index}] must be a string`);
+      }
+    });
+  }
+
+  // Validate costCeiling
+  if (typeof c.costCeiling !== 'number') {
+    errors.push('Agent config must have a number "costCeiling"');
+  } else if (c.costCeiling <= 0) {
+    errors.push('Agent config "costCeiling" must be positive');
+  } else if (!Number.isFinite(c.costCeiling)) {
+    errors.push('Agent config "costCeiling" must be a finite number');
+  }
+
+  // Validate modelProvider
+  const validProviders: ModelProvider[] = ['claude', 'openai', 'ollama', 'gemini'];
+  if (typeof c.modelProvider !== 'string') {
+    errors.push('Agent config must have a string "modelProvider"');
+  } else if (!validProviders.includes(c.modelProvider as ModelProvider)) {
+    errors.push('Agent config "modelProvider" must be "claude", "openai", "ollama", or "gemini"');
+  }
+
+  // Validate modelId
+  if (typeof c.modelId !== 'string') {
+    errors.push('Agent config must have a string "modelId"');
+  } else if (c.modelId.trim() === '') {
+    errors.push('Agent config "modelId" must not be empty');
+  }
+
+  // Validate capabilities (optional)
+  if (c.capabilities !== undefined) {
+    if (typeof c.capabilities !== 'object' || c.capabilities === null) {
+      errors.push('Agent config "capabilities" must be an object');
+    } else {
+      const caps = c.capabilities as Record<string, unknown>;
+      
+      if (typeof caps.web_search !== 'boolean') {
+        errors.push('capabilities.web_search must be a boolean');
+      }
+      if (typeof caps.structured_output !== 'boolean') {
+        errors.push('capabilities.structured_output must be a boolean');
+      }
+      if (typeof caps.external_apis !== 'boolean') {
+        errors.push('capabilities.external_apis must be a boolean');
+      }
+      if (typeof caps.long_context !== 'boolean') {
+        errors.push('capabilities.long_context must be a boolean');
+      }
+      if (typeof caps.file_io_local !== 'boolean') {
+        errors.push('capabilities.file_io_local must be a boolean');
+      }
+      if (!Array.isArray(caps.workspace_tools)) {
+        errors.push('capabilities.workspace_tools must be an array');
+      }
+      if (!['low', 'medium', 'high'].includes(caps.safety_restriction_level as string)) {
+        errors.push('capabilities.safety_restriction_level must be "low", "medium", or "high"');
+      }
+    }
+  }
+
+  // Validate tier (optional)
+  if (c.tier !== undefined) {
+    if (!['premium', 'budget', 'free'].includes(c.tier as string)) {
+      errors.push('Agent config "tier" must be "premium", "budget", or "free"');
+    }
+  }
+
+  // Validate supported_bounty_types (optional)
+  if (c.supported_bounty_types !== undefined) {
+    if (!Array.isArray(c.supported_bounty_types)) {
+      errors.push('Agent config "supported_bounty_types" must be an array');
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Type guard to check if an unknown value is a valid AgentConfig.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid AgentConfig
+ */
+export function isAgentConfig(value: unknown): value is AgentConfig {
+  return validateAgentConfig(value).valid;
+}
+
+
+/**
+ * Parses a YAML string into an AgentConfig object.
+ * Validates the parsed config against the schema.
+ *
+ * @param yamlContent - The YAML string to parse
+ * @returns The parsed and validated AgentConfig, or throws on error
+ *
+ * @example
+ * import { readFile } from 'node:fs/promises';
+ * const yaml = await readFile('agent.yaml', 'utf-8');
+ * const config = parseAgentConfigYaml(yaml);
+ */
+export async function parseAgentConfigYaml(
+  yamlContent: string
+): Promise<{ config: AgentConfig | null; validation: ValidationResult }> {
+  const { parse } = await import('yaml');
+  const parsed = parse(yamlContent) as unknown;
+  const validation = validateAgentConfig(parsed);
+
+  if (validation.valid) {
+    return { config: parsed as AgentConfig, validation };
+  }
+
+  return { config: null, validation };
+}

package/src/agents/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Agents Module - Configuration-driven AI agent definitions
+ *
+ * @module agents
+ */
+
+export {
+  AgentConfig,
+  ModelProvider,
+  ValidationResult,
+  validateAgentConfig,
+  isAgentConfig,
+  parseAgentConfigYaml,
+} from './agent.schema.js';
+
+// Registered Agent Schema - Production WAIdex registration
+export {
+  type DeploymentProvider,
+  type AgentSpecialization,
+  type TaskType,
+  type AgentFramework,
+  type ExtendedModelProvider,
+  type AgentEndpoint,
+  type ModelInfo,
+  type DeploymentInfo,
+  type AgentStats,
+  type RegisteredAgent,
+  type RegisterAgentRequest,
+  type HealthCheckRequest,
+  type HealthCheckResponse,
+  validateRegisterAgentRequest,
+  createDefaultStats,
+  createDefaultDeploymentInfo,
+  generateSlug,
+} from './registered-agent.schema.js';
+
+export {
+  loadAllAgents,
+  getAgent,
+  getAllAgentIds,
+  getAllAgents,
+  hasAgent,
+} from './registry.js';
+
+export {
+  runOpenAIAgent,
+  mockOpenAIAgent,
+  type LeadData,
+  type AgentRunResult,
+} from './adapters/openai.adapter.js';
+
+export {
+  runClaudeAgent,
+  mockClaudeAgent,
+} from './adapters/anthropic.adapter.js';
+
+export {
+  runGeminiAgent,
+  mockGeminiAgent,
+} from './adapters/gemini.adapter.js';

package/src/agents/registered-agent.schema.ts

@@ -0,0 +1,356 @@
+/**
+ * Registered Agent Schema - Production-ready agent registration for WAIdex
+ *
+ * A RegisteredAgent extends AgentConfig with endpoint, deployment, and
+ * competition data needed for production battles.
+ *
+ * @module agents/registered-agent.schema
+ */
+
+import type { AgentConfig } from './agent.schema.js';
+
+/**
+ * Supported deployment providers for BYOD (Bring Your Own Deploy).
+ */
+export type DeploymentProvider =
+  | 'railway'
+  | 'render'
+  | 'flyio'
+  | 'vercel'
+  | 'cloudrun'
+  | 'self-hosted'
+  | 'tunnel';
+
+/**
+ * Agent specialization categories for matchmaking.
+ */
+export type AgentSpecialization =
+  | 'cold-email'
+  | 'lead-qualification'
+  | 'research'
+  | 'code-generation'
+  | 'data-analysis'
+  | 'customer-support'
+  | 'content-creation';
+
+/**
+ * Task types that agents can perform in battles.
+ */
+export type TaskType =
+  | 'qualify_lead'
+  | 'write_cold_email'
+  | 'research_company'
+  | 'fix_bug'
+  | 'analyze_data'
+  | 'summarize_document'
+  | 'generate_report';
+
+/**
+ * Supported agent frameworks.
+ */
+export type AgentFramework =
+  | 'agno'
+  | 'adk'
+  | 'langchain'
+  | 'langgraph'
+  | 'letta'
+  | 'custom';
+
+/**
+ * Supported model providers (extended for production).
+ */
+export type ExtendedModelProvider =
+  | 'ollama'
+  | 'gemini'
+  | 'openai'
+  | 'anthropic'
+  | 'groq'
+  | 'together'
+  | 'local';
+
+/**
+ * Agent endpoint configuration for battle communication.
+ */
+export interface AgentEndpoint {
+  /** The full URL to the agent's chat/completion endpoint */
+  url: string;
+  /** Authentication type */
+  authType: 'bearer' | 'api-key' | 'none';
+  /** Header name for auth (default: 'Authorization') */
+  authHeader?: string;
+  /** Encrypted auth token - WAIESL uses this to call the agent */
+  encryptedAuthToken?: string;
+}
+
+/**
+ * Model information for the agent.
+ */
+export interface ModelInfo {
+  /** The model provider */
+  provider: ExtendedModelProvider;
+  /** Model identifier (e.g., 'llama3.3:70b', 'gemini-2.0-flash') */
+  modelId: string;
+  /** Whether the model runs locally (affects latency expectations) */
+  isLocal: boolean;
+}
+
+/**
+ * Deployment status and metadata.
+ */
+export interface DeploymentInfo {
+  /** Where the agent is deployed */
+  provider: DeploymentProvider;
+  /** Current status */
+  status: 'online' | 'offline' | 'degraded' | 'deploying';
+  /** Last successful health check */
+  lastHealthCheck: Date | null;
+  /** Average response latency in milliseconds */
+  averageLatencyMs: number;
+  /** Uptime percentage (0-100) */
+  uptimePercent: number;
+}
+
+/**
+ * Competition statistics for the agent.
+ */
+export interface AgentStats {
+  /** Total battles participated */
+  totalBattles: number;
+  /** Total wins */
+  wins: number;
+  /** Total losses */
+  losses: number;
+  /** Win rate (0-1) */
+  winRate: number;
+  /** Total earnings in USD */
+  totalEarnings: number;
+  /** ELO rating for matchmaking */
+  elo: number;
+  /** Current ranking in the league */
+  rank?: number;
+}
+
+/**
+ * A fully registered agent in the WAIdex registry.
+ * Extends basic AgentConfig with production-ready fields.
+ */
+export interface RegisteredAgent extends AgentConfig {
+  /** URL-safe slug for the agent */
+  slug: string;
+  /** User ID who owns this agent */
+  ownerId: string;
+
+  /** Endpoint configuration for battle communication */
+  endpoint: AgentEndpoint;
+
+  /** Agent specializations for matchmaking */
+  specializations: AgentSpecialization[];
+
+  /** Task types this agent can perform */
+  supportedTasks: TaskType[];
+
+  /** Framework used to build the agent */
+  framework: AgentFramework;
+
+  /** Model information */
+  modelInfo: ModelInfo;
+
+  /** Deployment information */
+  deployment: DeploymentInfo;
+
+  /** Competition statistics */
+  stats: AgentStats;
+
+  /** Optional avatar URL */
+  avatar?: string;
+
+  /** Optional description */
+  description?: string;
+
+  /** Whether the agent is publicly listed */
+  isPublic: boolean;
+
+  /** Whether the agent is available for battles */
+  isActive: boolean;
+
+  /** Creation timestamp */
+  createdAt: Date;
+
+  /** Last update timestamp */
+  updatedAt: Date;
+}
+
+/**
+ * Request body for registering a new agent.
+ */
+export interface RegisterAgentRequest {
+  /** Agent name */
+  name: string;
+  /** System prompt */
+  prompt: string;
+  /** Strategy description */
+  strategyDescription: string;
+  /** Tools the agent can use */
+  toolAccess: string[];
+  /** Cost ceiling */
+  costCeiling: number;
+
+  /** Endpoint URL */
+  endpointUrl: string;
+  /** Endpoint auth type */
+  endpointAuthType: 'bearer' | 'api-key' | 'none';
+  /** Auth token (will be encrypted) */
+  authToken?: string;
+
+  /** Specializations */
+  specializations: AgentSpecialization[];
+  /** Supported tasks */
+  supportedTasks: TaskType[];
+
+  /** Framework */
+  framework: AgentFramework;
+
+  /** Model provider */
+  modelProvider: ExtendedModelProvider;
+  /** Model ID */
+  modelId: string;
+  /** Is model local? */
+  isLocalModel: boolean;
+
+  /** Deployment provider */
+  deploymentProvider: DeploymentProvider;
+
+  /** Public listing */
+  isPublic?: boolean;
+
+  /** Avatar URL */
+  avatar?: string;
+  /** Description */
+  description?: string;
+}
+
+/**
+ * Health check request sent to agents.
+ */
+export interface HealthCheckRequest {
+  type: 'health_check';
+  timestamp: string;
+}
+
+/**
+ * Expected health check response from agents.
+ */
+export interface HealthCheckResponse {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  version: string;
+  capabilities: string[];
+  averageResponseTimeMs?: number;
+}
+
+/**
+ * Validates a RegisterAgentRequest.
+ *
+ * @param request - The request to validate
+ * @returns Validation result
+ */
+export function validateRegisterAgentRequest(
+  request: unknown
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (typeof request !== 'object' || request === null) {
+    return { valid: false, errors: ['Request must be an object'] };
+  }
+
+  const r = request as Record<string, unknown>;
+
+  // Required string fields
+  const requiredStrings = ['name', 'prompt', 'strategyDescription', 'endpointUrl', 'modelId'];
+  for (const field of requiredStrings) {
+    if (typeof r[field] !== 'string' || (r[field] as string).trim() === '') {
+      errors.push(`"${field}" is required and must be a non-empty string`);
+    }
+  }
+
+  // Validate endpoint URL
+  if (typeof r.endpointUrl === 'string') {
+    try {
+      new URL(r.endpointUrl);
+    } catch {
+      errors.push('"endpointUrl" must be a valid URL');
+    }
+  }
+
+  // Validate arrays
+  if (!Array.isArray(r.toolAccess)) {
+    errors.push('"toolAccess" must be an array');
+  }
+  if (!Array.isArray(r.specializations)) {
+    errors.push('"specializations" must be an array');
+  }
+  if (!Array.isArray(r.supportedTasks)) {
+    errors.push('"supportedTasks" must be an array');
+  }
+
+  // Validate enums
+  const validAuthTypes = ['bearer', 'api-key', 'none'];
+  if (!validAuthTypes.includes(r.endpointAuthType as string)) {
+    errors.push('"endpointAuthType" must be "bearer", "api-key", or "none"');
+  }
+
+  const validFrameworks: AgentFramework[] = ['agno', 'adk', 'langchain', 'langgraph', 'letta', 'custom'];
+  if (!validFrameworks.includes(r.framework as AgentFramework)) {
+    errors.push(`"framework" must be one of: ${validFrameworks.join(', ')}`);
+  }
+
+  const validProviders: ExtendedModelProvider[] = ['ollama', 'gemini', 'openai', 'anthropic', 'groq', 'together', 'local'];
+  if (!validProviders.includes(r.modelProvider as ExtendedModelProvider)) {
+    errors.push(`"modelProvider" must be one of: ${validProviders.join(', ')}`);
+  }
+
+  // Validate costCeiling
+  if (typeof r.costCeiling !== 'number' || r.costCeiling <= 0) {
+    errors.push('"costCeiling" must be a positive number');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Creates default stats for a new agent.
+ */
+export function createDefaultStats(): AgentStats {
+  return {
+    totalBattles: 0,
+    wins: 0,
+    losses: 0,
+    winRate: 0,
+    totalEarnings: 0,
+    elo: 1000, // Starting ELO
+  };
+}
+
+/**
+ * Creates default deployment info for a new agent.
+ */
+export function createDefaultDeploymentInfo(
+  provider: DeploymentProvider
+): DeploymentInfo {
+  return {
+    provider,
+    status: 'offline',
+    lastHealthCheck: null,
+    averageLatencyMs: 0,
+    uptimePercent: 0,
+  };
+}
+
+/**
+ * Generates a URL-safe slug from a name.
+ */
+export function generateSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}