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

package/dist/context-enricher.d.ts

@@ -0,0 +1,3 @@
+import type { ExecutionContext, RetryEvent } from './loop.js';
+export declare function buildRetryContext<T>(event: RetryEvent<T>): ExecutionContext;
+//# sourceMappingURL=context-enricher.d.ts.map

package/dist/context-enricher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-enricher.d.ts","sourceRoot":"","sources":["../src/context-enricher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE9D,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAK3E"}

package/dist/context-enricher.js

@@ -0,0 +1,7 @@
+export function buildRetryContext(event) {
+    return {
+        attempt: event.attempt + 1,
+        previousFailures: event.allFailures
+    };
+}
+//# sourceMappingURL=context-enricher.js.map

package/dist/context-enricher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-enricher.js","sourceRoot":"","sources":["../src/context-enricher.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,iBAAiB,CAAI,KAAoB;IACvD,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO,GAAG,CAAC;QAC1B,gBAAgB,EAAE,KAAK,CAAC,WAAW;KACpC,CAAC;AACJ,CAAC"}

package/dist/contracts.d.ts

@@ -0,0 +1,4 @@
+import type { OutputContract } from '@studio-foundation/contracts';
+export declare function loadContract(path: string): Promise<OutputContract>;
+export declare function parseContract(yamlContent: string): OutputContract;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAGxE;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAiBjE"}

package/dist/contracts.js

@@ -0,0 +1,22 @@
+// Load and parse output contracts from YAML
+import { readFile } from 'node:fs/promises';
+import yaml from 'js-yaml';
+export async function loadContract(path) {
+    const content = await readFile(path, 'utf-8');
+    return parseContract(content);
+}
+export function parseContract(yamlContent) {
+    const parsed = yaml.load(yamlContent);
+    // 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;
+}
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,SAAS,CAAC;AAG3B,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9C,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAmB,CAAC;IAExD,qBAAqB;IACrB,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './loop.js';
+export * from './validator.js';
+export * from './contracts.js';
+export * from './retry-strategy.js';
+export * from './context-enricher.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC"}

package/{src/index.ts → dist/index.js}

@@ -1,7 +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';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAElC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC"}

package/dist/loop.d.ts

@@ -0,0 +1,40 @@
+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 declare function ralph<T>(config: RalphConfig<T>): Promise<RalphResult<T>>;
+//# sourceMappingURL=loop.d.ts.map

package/dist/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,CAAC;IACV,UAAU,EAAE,gBAAgB,CAAC;IAC7B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,QAAQ,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACpD,SAAS,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IACrB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D,wBAAsB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA0E9E"}

package/dist/loop.js

@@ -0,0 +1,75 @@
+export async function ralph(config) {
+    const { executor, validator, maxAttempts, retryStrategy, onRetry, onSuccess, onExhausted, signal } = config;
+    let attempt = 1;
+    const allFailures = [];
+    let lastResult;
+    while (attempt <= maxAttempts) {
+        // Check cancellation before each attempt
+        if (signal?.aborted) {
+            return { status: 'cancelled', lastResult, attempts: attempt };
+        }
+        // 1. Execute avec contexte
+        const context = {
+            attempt,
+            previousFailures: [...allFailures]
+        };
+        let result;
+        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 = {
+            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, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+//# sourceMappingURL=loop.js.map

package/dist/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"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"}

package/dist/retry-strategy.d.ts

@@ -0,0 +1,5 @@
+import type { RetryStrategy } from './loop.js';
+export declare function noDelay(): RetryStrategy;
+export declare function fixedDelay(ms: number): RetryStrategy;
+export declare function exponentialBackoff(baseMs: number, maxMs: number): RetryStrategy;
+//# sourceMappingURL=retry-strategy.d.ts.map

package/dist/retry-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-strategy.d.ts","sourceRoot":"","sources":["../src/retry-strategy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,wBAAgB,OAAO,IAAI,aAAa,CAIvC;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,CAIpD;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAO/E"}

package/dist/retry-strategy.js

@@ -0,0 +1,19 @@
+export function noDelay() {
+    return {
+        getDelay: () => 0,
+    };
+}
+export function fixedDelay(ms) {
+    return {
+        getDelay: () => ms,
+    };
+}
+export function exponentialBackoff(baseMs, maxMs) {
+    return {
+        getDelay: (attempt) => {
+            const delay = baseMs * Math.pow(2, attempt - 1);
+            return Math.min(delay, maxMs);
+        },
+    };
+}
+//# sourceMappingURL=retry-strategy.js.map

package/dist/retry-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-strategy.js","sourceRoot":"","sources":["../src/retry-strategy.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,OAAO;IACrB,OAAO;QACL,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;KAClB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO;QACL,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE;KACnB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,KAAa;IAC9D,OAAO;QACL,QAAQ,EAAE,CAAC,OAAe,EAAE,EAAE;YAC5B,MAAM,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;YAChD,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/validator.d.ts

@@ -0,0 +1,14 @@
+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 declare function validateSchema(output: unknown, contract: OutputContract): ValidationResult;
+export declare function validateToolCalls(toolCalls: ToolCall[], requirements?: ToolCallRequirements): ValidationResult;
+export declare function validateRequiredTools(toolCalls: ToolCall[], requirements?: ToolCallRequirements): ValidationResult;
+export declare function validateCountedTools(toolCalls: ToolCall[], requirements?: ToolCallRequirements): ValidationResult;
+export declare function validateToolGroups(toolCalls: ToolCall[], requirements?: ToolCallRequirements): ValidationResult;
+export declare function compose<T>(...validators: Validator<T>[]): Validator<T>;
+//# sourceMappingURL=validator.d.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAErH,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAEvF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,GAAG,gBAAgB,CA+B1F;AAMD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,YAAY,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CA4B9G;AAOD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,YAAY,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAkBlH;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,YAAY,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAmBjH;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,YAAY,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAoB/G;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAYtE"}

package/dist/validator.js

@@ -0,0 +1,111 @@
+export function validateSchema(output, contract) {
+    const errors = [];
+    const warnings = [];
+    // 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;
+    // 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;
+    // 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) {
+    return !tc.error;
+}
+export function validateToolCalls(toolCalls, requirements) {
+    const errors = [];
+    const warnings = [];
+    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) {
+    return name.replace(/\./g, '-');
+}
+export function validateRequiredTools(toolCalls, requirements) {
+    const errors = [];
+    const warnings = [];
+    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, requirements) {
+    const errors = [];
+    const warnings = [];
+    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, requirements) {
+    const errors = [];
+    const warnings = [];
+    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(...validators) {
+    return async (result) => {
+        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)
+        };
+    };
+}
+//# sourceMappingURL=validator.js.map

package/dist/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studio-foundation/ralph",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.6",
   "description": "RALPH loop engine - Recursive Automated Loop for Persistent Handling",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,9 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "files": [
+    "dist"
+  ],
   "keywords": [
     "studio",
     "ralph",
@@ -21,7 +24,7 @@
   "license": "AGPL-3.0-only",
   "dependencies": {
     "js-yaml": "^4.1.1",
-    "@studio-foundation/contracts": "0.3.0-beta.1"
+    "@studio-foundation/contracts": "0.3.0-beta.6"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/ARCHITECTURE.md

@@ -1,41 +0,0 @@
-# @studio-foundation/ralph
-
-RALPH loop engine — retry intelligent avec validation.
-"Recursive Automated Loop for Persistent Handling"
-
-## Concept
-
-`ralph<T>()` prend un `executor` générique et un `validator`. Il exécute, valide, retry si fail, s'arrête sur AbortSignal.
-C'est tout. C'est générique. Ça marche pour n'importe quoi, pas juste des LLMs.
-
-## Règles
-
-- `ralph()` est UNE fonction. Pas une classe, pas un framework.
-- Le `executor` est `() => Promise<T>` — ralph ne sait pas que c'est un LLM derrière
-- La validation est composable via `compose(...validators)`
-- Les stratégies de retry sont pluggables (`exponentialBackoff`, `fixedDelay`, `noDelay`)
-- JAMAIS de dépendance sur `@studio-foundation/runner` ou `@studio-foundation/engine` — ralph est agnostique
-- Dépend UNIQUEMENT de `@studio-foundation/contracts`
-
-## Résultat
-
-```typescript
-type RalphResult<T> =
-  | { status: 'success';   result: T;     attempts: number }
-  | { status: 'exhausted'; lastResult: T; failures: string[]; attempts: number }
-  | { status: 'cancelled'; lastResult?: T; attempts: number }  // AbortSignal
-```
-
-## Fichiers clés
-
-- `loop.ts` — `ralph()` la fonction principale + `RalphConfig`, `RalphResult`
-- `validator.ts` — `validateSchema`, `validateToolCalls`, `validateRequiredTools`, `compose`
-- `retry-strategy.ts` — `exponentialBackoff(min, max)`, `fixedDelay(ms)`, `noDelay()`
-- `context-enricher.ts` — enrichir contexte entre retries
-- `contracts.ts` — types internes ralph
-
-## Anti-patterns
-
-- NE PAS mettre de logique LLM ici
-- NE PAS importer `@studio-foundation/runner`
-- NE PAS hardcoder des règles de validation — tout vient des contracts YAML

package/configs/examples/analysis.contract.yaml

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

@@ -1,21 +0,0 @@
-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/src/context-enricher.ts

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

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