outcome-cli 1.0.0

package/src/runtime/modelAdapter.ts

@@ -0,0 +1,144 @@
+/**
+ * Model Adapter - AI model abstraction for Claude and OpenAI
+ *
+ * Provides a unified interface for interacting with different AI model providers.
+ * Normalizes responses to a common format regardless of underlying provider.
+ *
+ * @module runtime/modelAdapter
+ */
+
+import type { ToolDefinition, ToolCall, ToolCallResult } from '../skills/skill.interface.js';
+
+/**
+ * Options for model completion requests.
+ */
+export interface ModelOptions {
+  /** Maximum tokens to generate in the response */
+  maxTokens?: number;
+  /** Temperature for response randomness (0-1) */
+  temperature?: number;
+  /** System prompt to set context */
+  systemPrompt?: string;
+  /** Tool definitions available to the model */
+  tools?: ToolDefinition[];
+}
+
+/**
+ * Normalized response from any model provider.
+ * Ensures consistent format regardless of Claude or OpenAI.
+ */
+export interface ModelResponse {
+  /** The generated text content */
+  content: string;
+  /** Total tokens used (input + output) */
+  tokensUsed: number;
+  /** The model identifier that generated the response */
+  model: string;
+  /** Tool calls requested by the model (if any) */
+  toolCalls?: ToolCall[];
+  /** Whether the model wants to continue after tool results */
+  requiresToolResponse?: boolean;
+}
+
+/**
+ * Message in a conversation for multi-turn tool use.
+ */
+export interface ConversationMessage {
+  role: 'user' | 'assistant' | 'tool';
+  content: string;
+  /** Tool call ID (for tool role messages) */
+  toolCallId?: string;
+  /** Tool calls made by assistant */
+  toolCalls?: ToolCall[];
+}
+
+// Re-export types for convenience
+export type { ToolDefinition, ToolCall, ToolCallResult };
+
+/**
+ * Unified interface for AI model adapters.
+ * Abstracts the underlying provider (Claude or OpenAI).
+ */
+export interface ModelAdapter {
+  /**
+   * Sends a completion request to the model.
+   *
+   * @param prompt - The user prompt to send
+   * @param options - Optional configuration for the request
+   * @returns Normalized model response
+   */
+  complete(prompt: string, options?: ModelOptions): Promise<ModelResponse>;
+
+  /**
+   * Continues a conversation with tool results.
+   * Used for multi-turn tool use interactions.
+   *
+   * @param messages - The conversation history including tool results
+   * @param options - Optional configuration for the request
+   * @returns Normalized model response
+   */
+  continueWithToolResults(
+    messages: ConversationMessage[],
+    options?: ModelOptions
+  ): Promise<ModelResponse>;
+
+  /**
+   * Estimates token count for a given text.
+   *
+   * @param text - The text to count tokens for
+   * @returns Estimated token count
+   */
+  countTokens(text: string): number;
+
+  /** The provider name ('claude' or 'openai') */
+  readonly provider: 'claude' | 'openai';
+
+  /** The specific model ID being used */
+  readonly modelId: string;
+}
+
+/**
+ * Configuration for creating a model adapter.
+ */
+export interface ModelAdapterConfig {
+  /** The AI provider to use */
+  provider: 'claude' | 'openai';
+  /** The specific model ID (e.g., 'claude-3-sonnet-20240229', 'gpt-4-turbo-preview') */
+  modelId: string;
+  /** API key for the provider */
+  apiKey: string;
+}
+
+
+/**
+ * Creates a model adapter based on the provided configuration.
+ *
+ * @param config - Configuration specifying provider, model, and API key
+ * @returns ModelAdapter for the specified provider
+ * @throws Error if provider is not supported
+ *
+ * @example
+ * const adapter = await createAdapter({
+ *   provider: 'claude',
+ *   modelId: 'claude-3-sonnet-20240229',
+ *   apiKey: process.env.ANTHROPIC_API_KEY!
+ * });
+ *
+ * @see Requirements 11.1, 11.2, 11.3
+ */
+export async function createAdapter(config: ModelAdapterConfig): Promise<ModelAdapter> {
+  switch (config.provider) {
+    case 'claude': {
+      const { createClaudeAdapter } = await import('./claudeAdapter.js');
+      return createClaudeAdapter(config.apiKey, config.modelId);
+    }
+    case 'openai': {
+      const { createOpenAIAdapter } = await import('./openaiAdapter.js');
+      return createOpenAIAdapter(config.apiKey, config.modelId);
+    }
+    default: {
+      const exhaustiveCheck: never = config.provider;
+      throw new Error(`Unsupported model provider: ${exhaustiveCheck}`);
+    }
+  }
+}

package/src/runtime/openaiAdapter.ts

@@ -0,0 +1,235 @@
+/**
+ * OpenAI Adapter - OpenAI API integration
+ *
+ * Implements the ModelAdapter interface for OpenAI models.
+ * Uses the official openai npm package following Chat Completions API.
+ *
+ * @module runtime/openaiAdapter
+ * @see https://platform.openai.com/docs/api-reference
+ */
+
+import OpenAI from 'openai';
+import type {
+  ModelAdapter,
+  ModelOptions,
+  ModelResponse,
+  ConversationMessage,
+  ToolDefinition,
+  ToolCall,
+} from './modelAdapter.js';
+
+/**
+ * Default max tokens for OpenAI responses.
+ */
+const DEFAULT_MAX_TOKENS = 1024;
+
+/**
+ * Approximate characters per token for estimation.
+ * OpenAI uses ~4 characters per token on average.
+ */
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Converts our tool definitions to OpenAI's tool format.
+ *
+ * @param tools - Our normalized tool definitions
+ * @returns OpenAI-formatted tools
+ */
+function toOpenAITools(tools: ToolDefinition[]): OpenAI.ChatCompletionTool[] {
+  return tools.map((tool) => ({
+    type: 'function' as const,
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: {
+        type: 'object',
+        properties: tool.inputSchema.properties,
+        required: tool.inputSchema.required,
+      },
+    },
+  }));
+}
+
+/**
+ * Converts our conversation messages to OpenAI's message format.
+ *
+ * @param messages - Our normalized conversation messages
+ * @returns OpenAI-formatted messages
+ */
+function toOpenAIMessages(messages: ConversationMessage[]): OpenAI.ChatCompletionMessageParam[] {
+  const openaiMessages: OpenAI.ChatCompletionMessageParam[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === 'user') {
+      openaiMessages.push({ role: 'user', content: msg.content });
+    } else if (msg.role === 'assistant') {
+      // Assistant message with potential tool calls
+      const assistantMsg: OpenAI.ChatCompletionAssistantMessageParam = {
+        role: 'assistant',
+        content: msg.content || null,
+      };
+      if (msg.toolCalls && msg.toolCalls.length > 0) {
+        assistantMsg.tool_calls = msg.toolCalls.map((tc) => ({
+          id: tc.id,
+          type: 'function' as const,
+          function: {
+            name: tc.name,
+            arguments: JSON.stringify(tc.arguments),
+          },
+        }));
+      }
+      openaiMessages.push(assistantMsg);
+    } else if (msg.role === 'tool') {
+      // Tool result
+      openaiMessages.push({
+        role: 'tool',
+        tool_call_id: msg.toolCallId!,
+        content: msg.content,
+      });
+    }
+  }
+
+  return openaiMessages;
+}
+
+/**
+ * Extracts tool calls from OpenAI's response.
+ *
+ * @param toolCalls - OpenAI tool calls from response
+ * @returns Array of normalized tool calls
+ */
+function extractToolCalls(
+  toolCalls: OpenAI.ChatCompletionMessageToolCall[] | undefined
+): ToolCall[] {
+  if (!toolCalls) return [];
+
+  return toolCalls
+    .filter((tc): tc is OpenAI.ChatCompletionMessageToolCall & { type: 'function' } => 
+      tc.type === 'function'
+    )
+    .map((tc) => ({
+      id: tc.id,
+      name: tc.function.name,
+      arguments: JSON.parse(tc.function.arguments) as Record<string, unknown>,
+    }));
+}
+
+/**
+ * Creates an OpenAI model adapter.
+ *
+ * @param apiKey - OpenAI API key
+ * @param modelId - OpenAI model ID (e.g., 'gpt-4-turbo-preview')
+ * @returns ModelAdapter implementation for OpenAI
+ *
+ * @example
+ * const adapter = createOpenAIAdapter(process.env.OPENAI_API_KEY!, 'gpt-4-turbo-preview');
+ * const response = await adapter.complete('Hello, GPT');
+ *
+ * @see Requirements 11.1, 11.3, 11.4
+ */
+export function createOpenAIAdapter(apiKey: string, modelId: string): ModelAdapter {
+  const client = new OpenAI({ apiKey });
+
+  return {
+    provider: 'openai',
+    modelId,
+
+    async complete(prompt: string, options?: ModelOptions): Promise<ModelResponse> {
+      const messages: OpenAI.ChatCompletionMessageParam[] = [];
+
+      // Add system message if provided
+      if (options?.systemPrompt) {
+        messages.push({ role: 'system', content: options.systemPrompt });
+      }
+
+      // Add user message
+      messages.push({ role: 'user', content: prompt });
+
+      const requestParams: OpenAI.ChatCompletionCreateParams = {
+        model: modelId,
+        max_tokens: options?.maxTokens ?? DEFAULT_MAX_TOKENS,
+        ...(options?.temperature !== undefined && { temperature: options.temperature }),
+        messages,
+      };
+
+      // Add tools if provided
+      if (options?.tools && options.tools.length > 0) {
+        requestParams.tools = toOpenAITools(options.tools);
+      }
+
+      const completion = await client.chat.completions.create(requestParams);
+
+      // Extract content from response
+      const content = completion.choices[0]?.message?.content ?? '';
+
+      // Extract tool calls if any
+      const toolCalls = extractToolCalls(completion.choices[0]?.message?.tool_calls);
+
+      // Calculate total tokens used
+      const tokensUsed = completion.usage?.total_tokens ?? 0;
+
+      // Check if model wants to use tools
+      const finishReason = completion.choices[0]?.finish_reason;
+
+      return {
+        content,
+        tokensUsed,
+        model: completion.model,
+        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+        requiresToolResponse: finishReason === 'tool_calls',
+      };
+    },
+
+    async continueWithToolResults(
+      messages: ConversationMessage[],
+      options?: ModelOptions
+    ): Promise<ModelResponse> {
+      const openaiMessages = toOpenAIMessages(messages);
+
+      // Add system message at the beginning if provided
+      if (options?.systemPrompt) {
+        openaiMessages.unshift({ role: 'system', content: options.systemPrompt });
+      }
+
+      const requestParams: OpenAI.ChatCompletionCreateParams = {
+        model: modelId,
+        max_tokens: options?.maxTokens ?? DEFAULT_MAX_TOKENS,
+        ...(options?.temperature !== undefined && { temperature: options.temperature }),
+        messages: openaiMessages,
+      };
+
+      // Add tools if provided
+      if (options?.tools && options.tools.length > 0) {
+        requestParams.tools = toOpenAITools(options.tools);
+      }
+
+      const completion = await client.chat.completions.create(requestParams);
+
+      // Extract content from response
+      const content = completion.choices[0]?.message?.content ?? '';
+
+      // Extract tool calls if any
+      const toolCalls = extractToolCalls(completion.choices[0]?.message?.tool_calls);
+
+      // Calculate total tokens used
+      const tokensUsed = completion.usage?.total_tokens ?? 0;
+
+      // Check if model wants to use tools
+      const finishReason = completion.choices[0]?.finish_reason;
+
+      return {
+        content,
+        tokensUsed,
+        model: completion.model,
+        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+        requiresToolResponse: finishReason === 'tool_calls',
+      };
+    },
+
+    countTokens(text: string): number {
+      // Approximate token count based on character length
+      // OpenAI uses ~4 characters per token on average
+      return Math.ceil(text.length / CHARS_PER_TOKEN);
+    },
+  };
+}

package/src/utils/README.md

@@ -0,0 +1,122 @@
+# Utils Module
+
+Shared utilities for the Earnd Bounty Engine, including structured logging.
+
+## Components
+
+### Logger (`logger.ts`)
+
+Mandatory structured logging for all agent attempts. Every agent attempt is logged for auditing and debugging.
+
+**Key Interfaces:**
+
+- `LogEntry` - Structured log entry with timestamp, agentId, outcomeId, promptVersion, tokensSpent, result, failureReason
+- `LogEntryInput` - Input for creating log entries (timestamp auto-generated)
+- `LogResult` - Result status: 'SUCCESS' | 'FAILURE' | 'PENDING'
+
+**Key Functions:**
+
+- `log(entry)` - Creates and stores a log entry
+- `getLogs(outcomeId)` - Retrieves all logs for an outcome
+- `getAgentLogs(outcomeId, agentId)` - Retrieves logs for a specific agent
+- `clearLogs(outcomeId)` - Clears logs for an outcome
+- `formatLogsForCli(outcomeId)` - Formats logs for CLI display
+
+**Convenience Functions:**
+
+- `logSuccess(...)` - Log a successful attempt
+- `logFailure(...)` - Log a failed attempt with reason
+- `logPending(...)` - Log a pending attempt
+
+**Usage:**
+
+```typescript
+import { log, getLogs, logSuccess, logFailure, formatLogsForCli } from './logger.js';
+
+// Log an attempt
+log({
+  agentId: 'agent-001',
+  outcomeId: 'qualified_sales_interest',
+  promptVersion: 'v1.0.0',
+  tokensSpent: 500,
+  result: 'SUCCESS'
+});
+
+// Or use convenience functions
+logSuccess('agent-001', 'qualified_sales_interest', 'v1.0.0', 500);
+logFailure('agent-002', 'qualified_sales_interest', 'v1.0.0', 300, 'Company too small');
+
+// Retrieve logs
+const logs = getLogs('qualified_sales_interest');
+console.log(`Found ${logs.length} log entries`);
+
+// Format for CLI display
+console.log(formatLogsForCli('qualified_sales_interest'));
+```
+
+**Output Format:**
+
+```text
+✅ [14:32:15] Agent:agent-001 | Outcome:qualified_sales_interest | Tokens:500 | SUCCESS
+❌ [14:32:18] Agent:agent-002 | Outcome:qualified_sales_interest | Tokens:300 | FAILURE | Reason: Company too small
+```
+
+## Requirements Reference
+
+- **6.1** - Record agent ID, outcome ID, prompt version, tokens spent, result, and failure reason
+- **6.2** - Provide logs viewable via CLI
+- **6.3** - Persist all attempt logs after agent run completes
+
+### Error Types (`errors.ts`)
+
+Custom error classes for structured error handling across the system.
+
+**Error Classes:**
+
+- `ValidationError` - Invalid schemas, malformed data (not recoverable)
+- `ExecutionError` - Model API failures, timeouts, network issues (may be recoverable)
+- `LimitError` - Cost ceiling, attempt limit, time limit exceeded (not recoverable)
+- `SystemError` - Infrastructure failures, state corruption (not recoverable)
+
+**Key Interfaces:**
+
+- `ErrorResponse` - Structured error format with code, message, details, recoverable flag
+- `ErrorCode` - Enum of all error codes for programmatic handling
+
+**Type Guards:**
+
+- `isEarndError(error)` - Check if error is any EarndError subclass
+- `isValidationError(error)` - Check if error is ValidationError
+- `isExecutionError(error)` - Check if error is ExecutionError
+- `isLimitError(error)` - Check if error is LimitError
+- `isSystemError(error)` - Check if error is SystemError
+
+**Usage:**
+
+```typescript
+import { ValidationError, LimitError, toErrorResponse } from './errors.js';
+
+// Create validation error
+throw ValidationError.missingField('email', 'Lead');
+
+// Create limit error
+throw LimitError.costExceeded('agent-1', 15000, 10000);
+
+// Convert any error to ErrorResponse
+try {
+  // ... code that may throw
+} catch (error) {
+  const response = toErrorResponse(error);
+  console.log(response.code, response.message, response.recoverable);
+}
+```
+
+## Design Principles
+
+1. **Mandatory Logging** - Every agent attempt must be logged
+2. **Structured Data** - All logs follow the LogEntry schema
+3. **Audit Trail** - Logs persist for debugging and compliance
+4. **CLI-Friendly** - Output formatted for terminal readability
+5. **No Silent Failures** - All errors and failures are logged with reasons
+6. **Fail Closed** - Limit errors terminate agents with no payout possibility
+7. **Typed Errors** - All errors have codes for programmatic handling

package/src/utils/command-runner.ts

@@ -0,0 +1,134 @@
+/**
+ * Safe Command Execution - Async command runner with timeouts and limits
+ *
+ * Safely executes shell commands with:
+ * - Timeouts to prevent hanging
+ * - Output size limits to prevent memory exhaustion
+ * - Proper error handling and cleanup
+ *
+ * Used for running tests, builds, linting, benchmarks, and security scans
+ * in the Outcome evaluation pipeline.
+ */
+
+import { spawn } from 'child_process';
+
+export interface CommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  truncated?: boolean;
+  timeout?: boolean;
+}
+
+export interface CommandOptions {
+  cwd?: string;
+  timeoutMs?: number;
+  maxOutputSize?: number; // max chars for stdout+stderr combined
+  env?: Record<string, string>;
+}
+
+/**
+ * Safely execute a shell command asynchronously.
+ *
+ * @param command - Command to execute (e.g., "npm test")
+ * @param args - Command arguments (if needed)
+ * @param options - Execution options
+ * @returns Promise resolving to CommandResult
+ */
+export async function runCommand(
+  command: string,
+  args: string[] = [],
+  options: CommandOptions = {}
+): Promise<CommandResult> {
+  const {
+    cwd,
+    timeoutMs = 30000, // 30 seconds default
+    maxOutputSize = 100000, // 100k chars
+    env = process.env,
+  } = options;
+
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let truncated = false;
+
+    const proc = spawn(command, args, {
+      cwd,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: true, // Allow shell commands like "npm test"
+    });
+
+    let timeoutId: NodeJS.Timeout | undefined;
+
+    const cleanup = () => {
+      if (timeoutId) clearTimeout(timeoutId);
+      proc.kill();
+    };
+
+    const checkTruncation = () => {
+      if (stdout.length + stderr.length > maxOutputSize) {
+        truncated = true;
+        stdout = stdout.slice(0, maxOutputSize / 2);
+        stderr = stderr.slice(0, maxOutputSize / 2);
+      }
+    };
+
+    // Set timeout
+    timeoutId = setTimeout(() => {
+      cleanup();
+      resolve({
+        exitCode: -1,
+        stdout,
+        stderr,
+        timeout: true,
+      });
+    }, timeoutMs);
+
+    proc.stdout?.on('data', (data) => {
+      stdout += data.toString();
+      checkTruncation();
+    });
+
+    proc.stderr?.on('data', (data) => {
+      stderr += data.toString();
+      checkTruncation();
+    });
+
+    proc.on('close', (code) => {
+      if (timeoutId) clearTimeout(timeoutId);
+      resolve({
+        exitCode: code ?? 0,
+        stdout,
+        stderr,
+        truncated,
+      });
+    });
+
+    proc.on('error', (error) => {
+      cleanup();
+      resolve({
+        exitCode: -1,
+        stdout,
+        stderr,
+        truncated,
+      });
+    });
+  });
+}
+
+/**
+ * Execute a single command string (convenience wrapper).
+ *
+ * @param commandLine - Full command line (e.g., "npm test --watchAll=false")
+ * @param options - Execution options
+ * @returns Promise resolving to CommandResult
+ */
+export async function runCommandLine(
+  commandLine: string,
+  options: CommandOptions = {}
+): Promise<CommandResult> {
+  // Simple split on spaces - not perfect but works for our use cases
+  const [cmd, ...args] = commandLine.split(' ');
+  return runCommand(cmd, args, options);
+}