@studio-foundation/ralph 0.3.0-beta.1

package/README.md

@@ -0,0 +1,71 @@
+# @studio-foundation/ralph
+
+The retry engine. Execute → validate → retry with escalated feedback → repeat.
+
+**RALPH** = Recursive Automated Loop for Persistent Handling.
+
+## Role
+
+ralph sits between the engine (orchestration) and runner (LLM execution). It knows nothing about LLMs — it takes a generic `executor` function and a contract, and loops until the output passes or max attempts is reached.
+
+```
+engine → ralph(executor, contract) → success | exhausted
+                 ↑
+         executor = () => runner.runAgent(...)
+```
+
+## Key exports
+
+```typescript
+import { ralph, RalphConfig, RalphResult } from '@studio-foundation/ralph';
+import { validateSchema, validateToolCalls, validateRequiredTools, compose } from '@studio-foundation/ralph';
+import { exponentialBackoff, fixedDelay, noDelay } from '@studio-foundation/ralph';
+
+const result = await ralph({
+  executor: async (context) => runner.runAgent(context),
+  validator: compose(
+    (r) => validateSchema(r.output, contract),
+    (r) => validateToolCalls(r.tool_calls_count, requirements),
+  ),
+  maxAttempts: 3,
+  retryStrategy: exponentialBackoff(1000, 30000),
+  onRetry: async (event) => { /* observability hook */ },
+  signal: abortController.signal,  // optional — enables cooperative cancellation
+});
+// result.status: 'success' | 'exhausted' | 'cancelled'
+```
+
+## How it works
+
+1. Calls `executor` with current context
+2. Validates the output using the `validator` function (composed validators)
+3. If pass → returns `{ status: 'success', result, attempts }`
+4. If fail → calls `onRetry`, waits (retry strategy), retries with failure context
+5. If max attempts reached → returns `{ status: 'exhausted', lastResult, failures, attempts }`
+6. If `signal` is aborted at any point → returns `{ status: 'cancelled', lastResult?, attempts }`
+
+## Validators
+
+ralph exports composable validators that the engine uses to build per-stage validation:
+
+| Validator | Purpose |
+|-----------|---------|
+| `validateSchema(output, contract)` | Check required fields are present |
+| `validateToolCalls(count, reqs)` | Check minimum tool call count |
+| `validateRequiredTools(calls, reqs)` | Check specific tools were called |
+| `validateCountedTools(calls, reqs)` | OR semantics — any of these count toward minimum |
+| `compose(...validators)` | Combine multiple validators (all must pass) |
+
+## Retry strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `exponentialBackoff(min, max)` | Exponential backoff with jitter |
+| `fixedDelay(ms)` | Fixed wait between attempts |
+| `noDelay()` | No wait (prompt escalation handled by runner) |
+
+## Rules
+
+- **ralph doesn't know runner.** The `executor` is `() => Promise<T>`. ralph doesn't care what's behind it.
+- **ralph doesn't know engine.** It takes config, it returns a result. No pipeline state, no events.
+- Validation logic is in exported validators — the engine composes them per stage.

package/configs/examples/analysis.contract.yaml

@@ -0,0 +1,19 @@
+name: analysis
+version: 1
+
+schema:
+  required_fields:
+    - summary
+    - recommendations
+  summary:
+    min_length: 50
+  recommendations:
+    min_items: 1
+
+tool_calls:
+  minimum: 0  # Analysis doesn't require tool calls
+
+custom_rules:
+  - name: actionable-recommendations
+    description: "Recommendations must be specific and actionable"
+    check: "recommendations.length > 0"

package/configs/examples/code-generation.contract.yaml

@@ -0,0 +1,21 @@
+name: code-generation
+version: 1
+
+schema:
+  required_fields:
+    - summary
+    - files_changed
+  files_changed:
+    min_items: 1
+    item_schema:
+      required: [path, action, content]
+
+tool_calls:
+  minimum: 1
+  required_tools:
+    - repo_manager.write_file
+
+custom_rules:
+  - name: no-theatre
+    description: "Agent must actually call tools, not just describe calling them"
+    check: "tool_calls_count > 0 OR stage_kind != code_generation"

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@studio-foundation/ralph",
+  "version": "0.3.0-beta.1",
+  "description": "RALPH loop engine - Recursive Automated Loop for Persistent Handling",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "studio",
+    "ralph",
+    "retry",
+    "validation"
+  ],
+  "author": "Ariane Guay",
+  "license": "AGPL-3.0-only",
+  "dependencies": {
+    "js-yaml": "^4.1.1",
+    "@studio-foundation/contracts": "0.3.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.2.3",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/context-enricher.ts

@@ -0,0 +1,9 @@
+// Enrich context between retries
+import type { ExecutionContext, RetryEvent } from './loop.js';
+
+export function buildRetryContext<T>(event: RetryEvent<T>): ExecutionContext {
+  return {
+    attempt: event.attempt + 1,
+    previousFailures: event.allFailures
+  };
+}

package/src/contracts.ts

@@ -0,0 +1,28 @@
+// Load and parse output contracts from YAML
+import { readFile } from 'node:fs/promises';
+import yaml from 'js-yaml';
+import type { OutputContract } from '@studio-foundation/contracts';
+
+export async function loadContract(path: string): Promise<OutputContract> {
+  const content = await readFile(path, 'utf-8');
+  return parseContract(content);
+}
+
+export function parseContract(yamlContent: string): OutputContract {
+  const parsed = yaml.load(yamlContent) as OutputContract;
+
+  // Validation basique
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('Invalid contract: expected object');
+  }
+
+  if (!parsed.name || typeof parsed.name !== 'string') {
+    throw new Error('Invalid contract: missing or invalid name');
+  }
+
+  if (parsed.version === undefined || typeof parsed.version !== 'number') {
+    throw new Error('Invalid contract: missing or invalid version');
+  }
+
+  return parsed;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// Export barrel for @studio/ralph
+
+export * from './loop.js';
+export * from './validator.js';
+export * from './contracts.js';
+export * from './retry-strategy.js';
+export * from './context-enricher.js';

package/src/loop.ts

@@ -0,0 +1,122 @@
+// 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

@@ -0,0 +1,23 @@
+// 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

@@ -0,0 +1,160 @@
+// 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)
+    };
+  };
+}