@studio-foundation/ralph 0.3.0-beta.1 → 0.3.0-beta.5

package/src/loop.ts

@@ -1,122 +0,0 @@
-// RALPH loop - main function
-import type { ValidationResult } from '@studio-foundation/contracts';
-
-export interface ExecutionContext {
-  attempt: number;
-  previousFailures: string[];
-}
-
-export interface RetryEvent<T> {
-  attempt: number;
-  result: T;
-  validation: ValidationResult;
-  allFailures: string[];
-}
-
-export interface RetryStrategy {
-  getDelay(attempt: number): number;
-}
-
-export interface RalphConfig<T> {
-  executor: (context: ExecutionContext) => Promise<T>;
-  validator: (result: T) => ValidationResult | Promise<ValidationResult>;
-  maxAttempts: number;
-  retryStrategy: RetryStrategy;
-  onRetry?: (event: RetryEvent<T>) => void | Promise<void>;
-  onSuccess?: (result: T, attempts: number) => void | Promise<void>;
-  onExhausted?: (lastResult: T, allFailures: string[]) => void | Promise<void>;
-  signal?: AbortSignal;
-}
-
-export type RalphResult<T> =
-  | { status: 'success'; result: T; attempts: number }
-  | { status: 'exhausted'; lastResult: T; failures: string[]; attempts: number }
-  | { status: 'cancelled'; lastResult?: T; attempts: number };
-
-export async function ralph<T>(config: RalphConfig<T>): Promise<RalphResult<T>> {
-  const { executor, validator, maxAttempts, retryStrategy, onRetry, onSuccess, onExhausted, signal } = config;
-
-  let attempt = 1;
-  const allFailures: string[] = [];
-  let lastResult: T | undefined;
-
-  while (attempt <= maxAttempts) {
-    // Check cancellation before each attempt
-    if (signal?.aborted) {
-      return { status: 'cancelled', lastResult, attempts: attempt };
-    }
-
-    // 1. Execute avec contexte
-    const context: ExecutionContext = {
-      attempt,
-      previousFailures: [...allFailures]
-    };
-
-    let result: T;
-    try {
-      result = await executor(context);
-    } catch (err) {
-      // If signal was aborted, the executor likely threw an AbortError
-      if (signal?.aborted) {
-        return { status: 'cancelled', lastResult, attempts: attempt };
-      }
-      throw err; // Re-throw non-abort errors
-    }
-
-    lastResult = result;
-
-    // 2. Validate
-    const validation = await Promise.resolve(validator(result));
-
-    // 3. Si valide → SUCCESS
-    if (validation.valid) {
-      await onSuccess?.(result, attempt);
-      return { status: 'success', result, attempts: attempt };
-    }
-
-    // 4. Si invalide → accumuler erreurs
-    allFailures.push(...validation.errors);
-
-    // 5. Si dernière tentative → EXHAUSTED
-    if (attempt >= maxAttempts) {
-      await onExhausted?.(result, allFailures);
-      return { status: 'exhausted', lastResult: result, attempts: attempt, failures: allFailures };
-    }
-
-    // Check cancellation before retry
-    if (signal?.aborted) {
-      return { status: 'cancelled', lastResult: result, attempts: attempt };
-    }
-
-    // 6. Callback + delay + retry
-    const retryEvent: RetryEvent<T> = {
-      attempt,
-      result,
-      validation,
-      allFailures: [...allFailures]
-    };
-    await onRetry?.(retryEvent);
-
-    const delay = retryStrategy.getDelay(attempt);
-    if (delay > 0) {
-      await abortableDelay(delay, signal);
-    }
-
-    attempt++;
-  }
-
-  // Unreachable mais TypeScript est content
-  throw new Error('ralph loop should have returned');
-}
-
-/** Sleep that resolves immediately if signal is aborted */
-function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
-  if (signal?.aborted) return Promise.resolve();
-  return new Promise((resolve) => {
-    const timer = setTimeout(resolve, ms);
-    signal?.addEventListener('abort', () => {
-      clearTimeout(timer);
-      resolve();
-    }, { once: true });
-  });
-}

package/src/retry-strategy.ts

@@ -1,23 +0,0 @@
-// Retry strategies
-import type { RetryStrategy } from './loop.js';
-
-export function noDelay(): RetryStrategy {
-  return {
-    getDelay: () => 0,
-  };
-}
-
-export function fixedDelay(ms: number): RetryStrategy {
-  return {
-    getDelay: () => ms,
-  };
-}
-
-export function exponentialBackoff(baseMs: number, maxMs: number): RetryStrategy {
-  return {
-    getDelay: (attempt: number) => {
-      const delay = baseMs * Math.pow(2, attempt - 1);
-      return Math.min(delay, maxMs);
-    },
-  };
-}

package/src/validator.ts

@@ -1,160 +0,0 @@
-// Validation engine
-import type { ValidationResult, OutputContract, ToolCall, ToolCallRequirements } from '@studio-foundation/contracts';
-
-export type { ToolCallRequirements } from '@studio-foundation/contracts';
-
-export type Validator<T> = (result: T) => ValidationResult | Promise<ValidationResult>;
-
-export interface AgentRunResult {
-  output: unknown;
-  tool_calls: ToolCall[];
-}
-
-export function validateSchema(output: unknown, contract: OutputContract): ValidationResult {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  // If no schema defined, consider it valid
-  if (!contract.schema || !contract.schema.required_fields) {
-    return { valid: true, errors, warnings };
-  }
-
-  const requiredFields = contract.schema.required_fields as string[];
-
-  // Output must be an object to check fields
-  if (output === null || typeof output !== 'object') {
-    errors.push(`Expected object output, got ${output === null ? 'null' : typeof output}`);
-    return { valid: false, errors, warnings };
-  }
-
-  const outputObj = output as Record<string, unknown>;
-
-  // Check each required field
-  for (const field of requiredFields) {
-    if (!(field in outputObj)) {
-      errors.push(`Missing required field: ${field}`);
-    }
-  }
-
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings
-  };
-}
-
-function isSuccessfulToolCall(tc: ToolCall): boolean {
-  return !tc.error;
-}
-
-export function validateToolCalls(toolCalls: ToolCall[], requirements?: ToolCallRequirements): ValidationResult {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  const successfulCount = toolCalls.filter(isSuccessfulToolCall).length;
-  const failedCount = toolCalls.length - successfulCount;
-
-  if (requirements?.minimum !== undefined) {
-    if (successfulCount < requirements.minimum) {
-      const plural = requirements.minimum === 1 ? '' : 's';
-      const excluded = failedCount > 0 ? ` (${failedCount} failed excluded)` : '';
-      errors.push(
-        `Expected at least ${requirements.minimum} successful tool call${plural}, got ${successfulCount} successful${excluded}`
-      );
-    }
-  }
-
-  if (requirements?.maximum !== undefined) {
-    if (successfulCount > requirements.maximum) {
-      const plural = successfulCount === 1 ? '' : 's';
-      errors.push(
-        `Tool call limit exceeded: made ${successfulCount} successful call${plural}, maximum is ${requirements.maximum}. ` +
-        `This may indicate a loop. Check that the agent is not repeating the same operation.`
-      );
-    }
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
-
-/** Normalize tool name: dots → hyphens so both conventions match */
-function normalizeToolName(name: string): string {
-  return name.replace(/\./g, '-');
-}
-
-export function validateRequiredTools(toolCalls: ToolCall[], requirements?: ToolCallRequirements): ValidationResult {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  if (requirements?.required_tools && requirements.required_tools.length > 0) {
-    for (const requiredTool of requirements.required_tools) {
-      const normalizedRequired = normalizeToolName(requiredTool);
-      const matchingCalls = toolCalls.filter(tc => normalizeToolName(tc.name) === normalizedRequired);
-
-      if (matchingCalls.length === 0) {
-        errors.push(`Required tool '${requiredTool}' was not called`);
-      } else if (!matchingCalls.some(isSuccessfulToolCall)) {
-        errors.push(`Required tool '${requiredTool}' has no successful calls (called ${matchingCalls.length} time${matchingCalls.length === 1 ? '' : 's'}, all failed)`);
-      }
-    }
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
-
-export function validateCountedTools(toolCalls: ToolCall[], requirements?: ToolCallRequirements): ValidationResult {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  if (requirements?.counted_tools && requirements.counted_tools.length > 0 && requirements?.minimum !== undefined) {
-    const countedSet = new Set(requirements.counted_tools.map(normalizeToolName));
-    const count = toolCalls.filter(
-      tc => countedSet.has(normalizeToolName(tc.name)) && isSuccessfulToolCall(tc)
-    ).length;
-
-    if (count < requirements.minimum) {
-      const toolNames = requirements.counted_tools.join(', ');
-      errors.push(
-        `Expected at least ${requirements.minimum} successful call${requirements.minimum === 1 ? '' : 's'} to counted tools [${toolNames}], got ${count}`
-      );
-    }
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
-
-export function validateToolGroups(toolCalls: ToolCall[], requirements?: ToolCallRequirements): ValidationResult {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  if (requirements?.required_tool_groups) {
-    for (const group of requirements.required_tool_groups) {
-      if (group.length === 0) continue;
-      const normalizedGroup = new Set(group.map(normalizeToolName));
-      const satisfied = toolCalls.some(
-        tc => normalizedGroup.has(normalizeToolName(tc.name)) && isSuccessfulToolCall(tc)
-      );
-      if (!satisfied) {
-        errors.push(
-          `Expected at least one successful call from [${group.join(', ')}], got none`
-        );
-      }
-    }
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
-
-export function compose<T>(...validators: Validator<T>[]): Validator<T> {
-  return async (result: T): Promise<ValidationResult> => {
-    const results = await Promise.all(
-      validators.map(v => Promise.resolve(v(result)))
-    );
-
-    return {
-      valid: results.every(r => r.valid),
-      errors: results.flatMap(r => r.errors),
-      warnings: results.flatMap(r => r.warnings)
-    };
-  };
-}

package/tests/loop.test.ts

@@ -1,355 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { ralph, type ExecutionContext } from '../src/loop.js';
-import { noDelay } from '../src/retry-strategy.js';
-
-describe('ralph loop', () => {
-  it('returns success on first attempt when valid', async () => {
-    const executor = vi.fn().mockResolvedValue('result');
-    const validator = vi.fn().mockReturnValue({ valid: true, errors: [], warnings: [] });
-
-    const result = await ralph({
-      executor,
-      validator,
-      maxAttempts: 3,
-      retryStrategy: noDelay()
-    });
-
-    expect(result.status).toBe('success');
-    expect(result.attempts).toBe(1);
-    expect(executor).toHaveBeenCalledTimes(1);
-    if (result.status === 'success') {
-      expect(result.result).toBe('result');
-    }
-  });
-
-  it('retries and succeeds on second attempt', async () => {
-    const validator = vi.fn()
-      .mockReturnValueOnce({ valid: false, errors: ['fail 1'], warnings: [] })
-      .mockReturnValueOnce({ valid: true, errors: [], warnings: [] });
-
-    const result = await ralph({
-      executor: async () => 'result',
-      validator,
-      maxAttempts: 3,
-      retryStrategy: noDelay()
-    });
-
-    expect(result.status).toBe('success');
-    expect(result.attempts).toBe(2);
-    expect(validator).toHaveBeenCalledTimes(2);
-  });
-
-  it('returns exhausted after max attempts', async () => {
-    const validator = vi.fn().mockReturnValue({
-      valid: false,
-      errors: ['always fails'],
-      warnings: []
-    });
-
-    const result = await ralph({
-      executor: async () => 'result',
-      validator,
-      maxAttempts: 3,
-      retryStrategy: noDelay()
-    });
-
-    expect(result.status).toBe('exhausted');
-    expect(result.attempts).toBe(3);
-    if (result.status === 'exhausted') {
-      expect(result.failures).toHaveLength(3);
-      expect(result.failures).toEqual(['always fails', 'always fails', 'always fails']);
-    }
-  });
-
-  it('passes execution context with previousFailures', async () => {
-    const executorCalls: ExecutionContext[] = [];
-
-    const executor = vi.fn(async (ctx: ExecutionContext) => {
-      executorCalls.push({ ...ctx });
-      return 'result';
-    });
-
-    const validator = vi.fn()
-      .mockReturnValueOnce({ valid: false, errors: ['error 1'], warnings: [] })
-      .mockReturnValueOnce({ valid: false, errors: ['error 2'], warnings: [] })
-      .mockReturnValueOnce({ valid: true, errors: [], warnings: [] });
-
-    await ralph({
-      executor,
-      validator,
-      maxAttempts: 5,
-      retryStrategy: noDelay()
-    });
-
-    // First call: no previous failures
-    expect(executorCalls[0]).toEqual({ attempt: 1, previousFailures: [] });
-
-    // Second call: has first error
-    expect(executorCalls[1]).toEqual({ attempt: 2, previousFailures: ['error 1'] });
-
-    // Third call: has both errors
-    expect(executorCalls[2]).toEqual({ attempt: 3, previousFailures: ['error 1', 'error 2'] });
-  });
-
-  it('calls onRetry callback on each retry', async () => {
-    const onRetry = vi.fn();
-    const validator = vi.fn()
-      .mockReturnValueOnce({ valid: false, errors: ['fail'], warnings: [] })
-      .mockReturnValueOnce({ valid: true, errors: [], warnings: [] });
-
-    await ralph({
-      executor: async () => 'result',
-      validator,
-      maxAttempts: 3,
-      retryStrategy: noDelay(),
-      onRetry
-    });
-
-    expect(onRetry).toHaveBeenCalledTimes(1);
-    expect(onRetry.mock.calls[0][0]).toMatchObject({
-      attempt: 1,
-      result: 'result',
-      validation: { valid: false, errors: ['fail'], warnings: [] },
-      allFailures: ['fail']
-    });
-  });
-
-  it('calls onSuccess on successful completion', async () => {
-    const onSuccess = vi.fn();
-
-    await ralph({
-      executor: async () => 'result',
-      validator: () => ({ valid: true, errors: [], warnings: [] }),
-      maxAttempts: 3,
-      retryStrategy: noDelay(),
-      onSuccess
-    });
-
-    expect(onSuccess).toHaveBeenCalledWith('result', 1);
-  });
-
-  it('calls onExhausted when max attempts reached', async () => {
-    const onExhausted = vi.fn();
-
-    await ralph({
-      executor: async () => 'result',
-      validator: () => ({ valid: false, errors: ['fail'], warnings: [] }),
-      maxAttempts: 2,
-      retryStrategy: noDelay(),
-      onExhausted
-    });
-
-    expect(onExhausted).toHaveBeenCalledWith('result', ['fail', 'fail']);
-  });
-
-  it('does not call onRetry on last failed attempt', async () => {
-    const onRetry = vi.fn();
-
-    await ralph({
-      executor: async () => 'result',
-      validator: () => ({ valid: false, errors: ['fail'], warnings: [] }),
-      maxAttempts: 2,
-      retryStrategy: noDelay(),
-      onRetry
-    });
-
-    // Should only retry once (between attempt 1 and 2)
-    expect(onRetry).toHaveBeenCalledTimes(1);
-  });
-
-  it('accumulates errors from multiple validation failures', async () => {
-    const validator = vi.fn()
-      .mockReturnValueOnce({ valid: false, errors: ['error A', 'error B'], warnings: [] })
-      .mockReturnValueOnce({ valid: false, errors: ['error C'], warnings: [] });
-
-    const result = await ralph({
-      executor: async () => 'result',
-      validator,
-      maxAttempts: 2,
-      retryStrategy: noDelay()
-    });
-
-    if (result.status === 'exhausted') {
-      expect(result.failures).toEqual(['error A', 'error B', 'error C']);
-    }
-  });
-
-  it('supports async validators', async () => {
-    const validator = vi.fn(async () => {
-      await new Promise(resolve => setTimeout(resolve, 1));
-      return { valid: true, errors: [], warnings: [] };
-    });
-
-    const result = await ralph({
-      executor: async () => 'result',
-      validator,
-      maxAttempts: 3,
-      retryStrategy: noDelay()
-    });
-
-    expect(result.status).toBe('success');
-  });
-
-  it('supports async callbacks', async () => {
-    const onRetry = vi.fn(async () => {
-      await new Promise(resolve => setTimeout(resolve, 1));
-    });
-
-    const validator = vi.fn()
-      .mockReturnValueOnce({ valid: false, errors: ['fail'], warnings: [] })
-      .mockReturnValueOnce({ valid: true, errors: [], warnings: [] });
-
-    await ralph({
-      executor: async () => 'result',
-      validator,
-      maxAttempts: 3,
-      retryStrategy: noDelay(),
-      onRetry
-    });
-
-    expect(onRetry).toHaveBeenCalled();
-  });
-
-  it('returns cancelled immediately when signal is already aborted', async () => {
-    const controller = new AbortController();
-    controller.abort();
-
-    const executor = vi.fn().mockResolvedValue('result');
-    const validator = vi.fn().mockReturnValue({ valid: true, errors: [], warnings: [] });
-
-    const result = await ralph({
-      executor,
-      validator,
-      maxAttempts: 3,
-      retryStrategy: noDelay(),
-      signal: controller.signal,
-    });
-
-    expect(result.status).toBe('cancelled');
-    expect(executor).not.toHaveBeenCalled();
-  });
-
-  it('returns cancelled when signal aborts between attempts', async () => {
-    const controller = new AbortController();
-
-    const executor = vi.fn().mockResolvedValue('result');
-    const validator = vi.fn().mockReturnValueOnce({ valid: false, errors: ['fail'], warnings: [] });
-
-    // Abort after first validation
-    validator.mockImplementationOnce(() => {
-      controller.abort();
-      return { valid: false, errors: ['fail 2'], warnings: [] };
-    });
-
-    const result = await ralph({
-      executor,
-      validator,
-      maxAttempts: 5,
-      retryStrategy: noDelay(),
-      signal: controller.signal,
-    });
-
-    expect(result.status).toBe('cancelled');
-    expect(executor).toHaveBeenCalledTimes(2);
-  });
-
-  it('returns cancelled when executor throws AbortError', async () => {
-    const controller = new AbortController();
-
-    const executor = vi.fn().mockImplementation(async () => {
-      controller.abort();
-      const err = new DOMException('The operation was aborted', 'AbortError');
-      throw err;
-    });
-    const validator = vi.fn();
-
-    const result = await ralph({
-      executor,
-      validator,
-      maxAttempts: 3,
-      retryStrategy: noDelay(),
-      signal: controller.signal,
-    });
-
-    expect(result.status).toBe('cancelled');
-    expect(validator).not.toHaveBeenCalled();
-  });
-
-  it('cancellation resolves pending retry delay immediately', async () => {
-    const controller = new AbortController();
-
-    let attempt = 0;
-    const executor = vi.fn().mockImplementation(async () => {
-      attempt++;
-      if (attempt === 1) {
-        // After first attempt, schedule abort in 5ms (well before any real delay)
-        setTimeout(() => controller.abort(), 5);
-      }
-      return 'result';
-    });
-    const validator = vi.fn().mockReturnValue({ valid: false, errors: ['fail'], warnings: [] });
-
-    const start = Date.now();
-    const result = await ralph({
-      executor,
-      validator,
-      maxAttempts: 5,
-      retryStrategy: { getDelay: () => 60_000 }, // 60 second delay — should NOT wait
-      signal: controller.signal,
-    });
-
-    const elapsed = Date.now() - start;
-    expect(result.status).toBe('cancelled');
-    expect(elapsed).toBeLessThan(5000); // Way less than 60s
-  });
-
-  it('works with object result type (generic T)', async () => {
-    type Output = { value: number; label: string };
-
-    const result = await ralph<Output>({
-      executor: async () => ({ value: 42, label: 'ok' }),
-      validator: () => ({ valid: true, errors: [], warnings: [] }),
-      maxAttempts: 3,
-      retryStrategy: noDelay()
-    });
-
-    expect(result.status).toBe('success');
-    if (result.status === 'success') {
-      expect(result.result.value).toBe(42);
-      expect(result.result.label).toBe('ok');
-    }
-  });
-
-  it('exhausts immediately with maxAttempts=1 on first failure', async () => {
-    const validator = vi.fn().mockReturnValue({
-      valid: false,
-      errors: ['always fails'],
-      warnings: []
-    });
-
-    const result = await ralph({
-      executor: async () => 'result',
-      validator,
-      maxAttempts: 1,
-      retryStrategy: noDelay()
-    });
-
-    expect(result.status).toBe('exhausted');
-    expect(result.attempts).toBe(1);
-    if (result.status === 'exhausted') {
-      expect(result.failures).toEqual(['always fails']);
-    }
-    expect(validator).toHaveBeenCalledTimes(1);
-  });
-
-  it('propagates executor exceptions that are not abort errors', async () => {
-    const error = new Error('unexpected failure');
-
-    await expect(ralph({
-      executor: async () => { throw error; },
-      validator: () => ({ valid: true, errors: [], warnings: [] }),
-      maxAttempts: 3,
-      retryStrategy: noDelay()
-    })).rejects.toThrow('unexpected failure');
-  });
-});