monomind 1.5.7 → 1.6.0

package/packages/@monomind/shared/dist/resilience/retry.js

@@ -0,0 +1,159 @@
+/**
+ * Retry with Exponential Backoff
+ *
+ * Production-ready retry logic with jitter, max retries, and error filtering.
+ *
+ * @module v1/shared/resilience/retry
+ */
+/**
+ * Retry error with attempt history
+ */
+export class RetryError extends Error {
+    attempts;
+    errors;
+    totalTime;
+    constructor(message, attempts, errors, totalTime) {
+        super(message);
+        this.attempts = attempts;
+        this.errors = errors;
+        this.totalTime = totalTime;
+        this.name = 'RetryError';
+    }
+}
+/**
+ * Default retry options
+ */
+const DEFAULT_OPTIONS = {
+    maxAttempts: 3,
+    initialDelay: 100,
+    maxDelay: 10000,
+    backoffMultiplier: 2,
+    jitter: 0.1,
+    timeout: 30000,
+};
+/**
+ * Retry a function with exponential backoff
+ *
+ * @param fn Function to retry
+ * @param options Retry configuration
+ * @returns Result with success/failure and metadata
+ *
+ * @example
+ * const result = await retry(
+ *   () => fetchData(),
+ *   { maxAttempts: 5, initialDelay: 200 }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Data:', result.result);
+ * } else {
+ *   console.log('Failed after', result.attempts, 'attempts');
+ * }
+ */
+export async function retry(fn, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const errors = [];
+    const startTime = Date.now();
+    for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
+        try {
+            // Execute with timeout
+            const result = await withTimeout(fn(), opts.timeout, attempt);
+            return {
+                success: true,
+                result,
+                attempts: attempt,
+                totalTime: Date.now() - startTime,
+                errors,
+            };
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            errors.push(err);
+            // Check if error is retryable
+            if (opts.retryableErrors && !opts.retryableErrors(err)) {
+                return {
+                    success: false,
+                    attempts: attempt,
+                    totalTime: Date.now() - startTime,
+                    errors,
+                };
+            }
+            // If this was the last attempt, don't delay
+            if (attempt >= opts.maxAttempts) {
+                break;
+            }
+            // Calculate delay with exponential backoff and jitter
+            const baseDelay = opts.initialDelay * Math.pow(opts.backoffMultiplier, attempt - 1);
+            const jitter = baseDelay * opts.jitter * (Math.random() * 2 - 1);
+            const delay = Math.min(baseDelay + jitter, opts.maxDelay);
+            // Callback before retry
+            if (opts.onRetry) {
+                opts.onRetry(err, attempt, delay);
+            }
+            // Wait before next attempt
+            await sleep(delay);
+        }
+    }
+    return {
+        success: false,
+        attempts: opts.maxAttempts,
+        totalTime: Date.now() - startTime,
+        errors,
+    };
+}
+/**
+ * Wrap a function with retry behavior
+ *
+ * @param fn Function to wrap
+ * @param options Retry configuration
+ * @returns Wrapped function that retries on failure
+ */
+export function withRetry(fn, options = {}) {
+    return async (...args) => {
+        return retry(() => fn(...args), options);
+    };
+}
+/**
+ * Execute with timeout
+ */
+async function withTimeout(promise, timeout, attempt) {
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new Error(`Attempt ${attempt} timed out after ${timeout}ms`));
+        }, timeout);
+    });
+    return Promise.race([promise, timeoutPromise]);
+}
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Common retryable error predicates
+ */
+export const RetryableErrors = {
+    /** Network errors (ECONNRESET, ETIMEDOUT, etc.) */
+    network: (error) => {
+        const networkCodes = ['ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN'];
+        return networkCodes.some((code) => error.message.includes(code));
+    },
+    /** Rate limit errors (429) */
+    rateLimit: (error) => {
+        return error.message.includes('429') || error.message.toLowerCase().includes('rate limit');
+    },
+    /** Server errors (5xx) */
+    serverError: (error) => {
+        return /5\d\d/.test(error.message) || error.message.includes('Internal Server Error');
+    },
+    /** Transient errors (network + rate limit + 5xx) */
+    transient: (error) => {
+        return (RetryableErrors.network(error) ||
+            RetryableErrors.rateLimit(error) ||
+            RetryableErrors.serverError(error));
+    },
+    /** All errors are retryable */
+    all: () => true,
+};
+//# sourceMappingURL=retry.js.map

package/packages/@monomind/shared/dist/retry-policy.d.ts

@@ -0,0 +1,14 @@
+/**
+ * RetryPolicy - Configuration for structured output auto-retry behavior
+ * Task 06: Structured Output Auto-Retry
+ */
+export interface RetryPolicy {
+    maxAttempts: number;
+    appendErrorsToReprompt: boolean;
+    logRetries: boolean;
+    gracefulDegradation: boolean;
+}
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+export declare const STRICT_RETRY_POLICY: RetryPolicy;
+export declare const LENIENT_RETRY_POLICY: RetryPolicy;
+//# sourceMappingURL=retry-policy.d.ts.map

package/packages/@monomind/shared/dist/retry-policy.js

@@ -0,0 +1,23 @@
+/**
+ * RetryPolicy - Configuration for structured output auto-retry behavior
+ * Task 06: Structured Output Auto-Retry
+ */
+export const DEFAULT_RETRY_POLICY = {
+    maxAttempts: 3,
+    appendErrorsToReprompt: true,
+    logRetries: true,
+    gracefulDegradation: true,
+};
+export const STRICT_RETRY_POLICY = {
+    maxAttempts: 5,
+    appendErrorsToReprompt: true,
+    logRetries: true,
+    gracefulDegradation: false,
+};
+export const LENIENT_RETRY_POLICY = {
+    maxAttempts: 1,
+    appendErrorsToReprompt: false,
+    logRetries: false,
+    gracefulDegradation: true,
+};
+//# sourceMappingURL=retry-policy.js.map

package/packages/@monomind/shared/dist/retry-runner.d.ts

@@ -0,0 +1,21 @@
+/**
+ * RetryRunner - Core retry loop for structured output auto-retry
+ * Task 06: Structured Output Auto-Retry
+ *
+ * Validates agent output against a Zod or JSON Schema, retrying with
+ * error context appended to the re-prompt when validation fails.
+ */
+import type { ZodSchema } from 'zod';
+import type { ValidationError } from './schema-validator.js';
+import type { AgentErrorResult } from './agent-error-result.js';
+import type { RetryPolicy } from './retry-policy.js';
+export interface RetryRunnerConfig<T> {
+    agentSlug: string;
+    task: string;
+    agentRunner: (task: string) => Promise<unknown>;
+    outputSchema: ZodSchema<T> | string;
+    policy?: RetryPolicy;
+    onRetry?: (attempt: number, errors: ValidationError[], rawOutput: unknown) => void;
+}
+export declare function runAgentWithRetry<T>(config: RetryRunnerConfig<T>): Promise<T | AgentErrorResult>;
+//# sourceMappingURL=retry-runner.d.ts.map

package/packages/@monomind/shared/dist/retry-runner.js

@@ -0,0 +1,57 @@
+/**
+ * RetryRunner - Core retry loop for structured output auto-retry
+ * Task 06: Structured Output Auto-Retry
+ *
+ * Validates agent output against a Zod or JSON Schema, retrying with
+ * error context appended to the re-prompt when validation fails.
+ */
+import { SchemaValidator } from './schema-validator.js';
+import { createAgentErrorResult } from './agent-error-result.js';
+import { DEFAULT_RETRY_POLICY } from './retry-policy.js';
+export async function runAgentWithRetry(config) {
+    const policy = config.policy ?? DEFAULT_RETRY_POLICY;
+    const validator = new SchemaValidator();
+    let currentTask = config.task;
+    let lastValidationErrors = [];
+    let lastRawOutput = undefined;
+    for (let attempt = 0; attempt < policy.maxAttempts; attempt++) {
+        let rawOutput;
+        try {
+            rawOutput = await config.agentRunner(currentTask);
+        }
+        catch (runError) {
+            if (policy.gracefulDegradation) {
+                return createAgentErrorResult(config.agentSlug, [{ path: '', message: `Agent runner threw: ${String(runError)}` }], undefined, attempt + 1);
+            }
+            throw runError;
+        }
+        lastRawOutput = rawOutput;
+        let validationResult;
+        if (typeof config.outputSchema === 'string') {
+            validationResult = validator.validateWithJsonSchemaFile(rawOutput, config.outputSchema);
+        }
+        else {
+            validationResult = validator.validateWithZod(rawOutput, config.outputSchema);
+        }
+        if (validationResult.valid) {
+            return rawOutput;
+        }
+        lastValidationErrors = validationResult.errors;
+        if (policy.logRetries) {
+            console.warn(`[RetryRunner] Attempt ${attempt + 1}/${policy.maxAttempts} failed for "${config.agentSlug}":`, lastValidationErrors.map((e) => `${e.path}: ${e.message}`).join('; '));
+        }
+        if (config.onRetry) {
+            config.onRetry(attempt + 1, lastValidationErrors, rawOutput);
+        }
+        if (policy.appendErrorsToReprompt && attempt < policy.maxAttempts - 1) {
+            const errorContext = validator.formatErrorsForReprompt(lastValidationErrors);
+            currentTask = `${config.task}\n\n${errorContext}`;
+        }
+    }
+    if (policy.gracefulDegradation) {
+        return createAgentErrorResult(config.agentSlug, lastValidationErrors, lastRawOutput, policy.maxAttempts);
+    }
+    throw new Error(`Agent "${config.agentSlug}" failed validation after ${policy.maxAttempts} attempts. ` +
+        `Last errors: ${lastValidationErrors.map((e) => e.message).join('; ')}`);
+}
+//# sourceMappingURL=retry-runner.js.map

package/packages/@monomind/shared/dist/schema-validator.d.ts

@@ -0,0 +1,46 @@
+export interface ValidationError {
+    path: string;
+    message: string;
+    received?: unknown;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+export declare class SchemaValidator {
+    private schemaCache;
+    /**
+     * Validate data against a JSON Schema file loaded from disk.
+     * Caches the schema after the first load.
+     */
+    validateWithJsonSchemaFile(data: unknown, schemaPath: string): ValidationResult;
+    /**
+     * Validate data against a Zod schema.
+     */
+    validateWithZod(data: unknown, zodSchema: {
+        safeParse: (d: unknown) => {
+            success: boolean;
+            error?: {
+                issues: Array<{
+                    path: (string | number)[];
+                    message: string;
+                }>;
+            };
+        };
+    }): ValidationResult;
+    /**
+     * Format validation errors into a human-readable string suitable for re-prompting an agent.
+     */
+    formatErrorsForReprompt(errors: ValidationError[]): string;
+    /**
+     * Clear the schema cache (useful for testing).
+     */
+    clearCache(): void;
+    /**
+     * Check whether a schema path is cached.
+     */
+    isCached(schemaPath: string): boolean;
+    private validateAgainstSchema;
+    private jsonType;
+}
+//# sourceMappingURL=schema-validator.d.ts.map

package/packages/@monomind/shared/dist/schema-validator.js

@@ -0,0 +1,133 @@
+/**
+ * SchemaValidator - JSON Schema and Zod validation for agent I/O contracts
+ * Task 05: Typed Agent I/O Contracts
+ */
+import { readFileSync } from 'fs';
+export class SchemaValidator {
+    schemaCache = new Map();
+    /**
+     * Validate data against a JSON Schema file loaded from disk.
+     * Caches the schema after the first load.
+     */
+    validateWithJsonSchemaFile(data, schemaPath) {
+        let schema = this.schemaCache.get(schemaPath);
+        if (!schema) {
+            const raw = readFileSync(schemaPath, 'utf-8');
+            schema = JSON.parse(raw);
+            this.schemaCache.set(schemaPath, schema);
+        }
+        return this.validateAgainstSchema(data, schema, '');
+    }
+    /**
+     * Validate data against a Zod schema.
+     */
+    validateWithZod(data, zodSchema) {
+        const result = zodSchema.safeParse(data);
+        if (result.success) {
+            return { valid: true, errors: [] };
+        }
+        const errors = (result.error?.issues ?? []).map((issue) => ({
+            path: issue.path.join('.'),
+            message: issue.message,
+        }));
+        return { valid: false, errors };
+    }
+    /**
+     * Format validation errors into a human-readable string suitable for re-prompting an agent.
+     */
+    formatErrorsForReprompt(errors) {
+        if (errors.length === 0)
+            return '';
+        return errors.map((e) => `- ${e.path ? e.path + ': ' : ''}${e.message}`).join('\n');
+    }
+    /**
+     * Clear the schema cache (useful for testing).
+     */
+    clearCache() {
+        this.schemaCache.clear();
+    }
+    /**
+     * Check whether a schema path is cached.
+     */
+    isCached(schemaPath) {
+        return this.schemaCache.has(schemaPath);
+    }
+    // ---------------------------------------------------------------------------
+    // Internal minimal JSON Schema validator
+    // ---------------------------------------------------------------------------
+    validateAgainstSchema(data, schema, path) {
+        const errors = [];
+        // Type check
+        if (schema.type) {
+            const actualType = this.jsonType(data);
+            if (schema.type !== actualType) {
+                errors.push({ path: path || '(root)', message: `Expected type "${schema.type}" but got "${actualType}"`, received: data });
+                return { valid: false, errors };
+            }
+        }
+        // Enum check
+        if (schema.enum && !schema.enum.includes(data)) {
+            errors.push({ path: path || '(root)', message: `Value must be one of: ${schema.enum.join(', ')}`, received: data });
+        }
+        // String constraints
+        if (schema.type === 'string' && typeof data === 'string') {
+            if (schema.minLength !== undefined && data.length < schema.minLength) {
+                errors.push({ path: path || '(root)', message: `String must have at least ${schema.minLength} characters`, received: data });
+            }
+            if (schema.maxLength !== undefined && data.length > schema.maxLength) {
+                errors.push({ path: path || '(root)', message: `String must have at most ${schema.maxLength} characters`, received: data });
+            }
+        }
+        // Number constraints
+        if ((schema.type === 'number' || schema.type === 'integer') && typeof data === 'number') {
+            if (schema.minimum !== undefined && data < schema.minimum) {
+                errors.push({ path: path || '(root)', message: `Value must be >= ${schema.minimum}`, received: data });
+            }
+            if (schema.maximum !== undefined && data > schema.maximum) {
+                errors.push({ path: path || '(root)', message: `Value must be <= ${schema.maximum}`, received: data });
+            }
+        }
+        // Object validation
+        if (schema.type === 'object' && typeof data === 'object' && data !== null && !Array.isArray(data)) {
+            const obj = data;
+            // Required fields
+            if (schema.required) {
+                for (const field of schema.required) {
+                    if (!(field in obj)) {
+                        errors.push({ path: path ? `${path}.${field}` : field, message: `Required field "${field}" is missing` });
+                    }
+                }
+            }
+            // Property validation
+            if (schema.properties) {
+                for (const [key, propSchema] of Object.entries(schema.properties)) {
+                    if (key in obj) {
+                        const propPath = path ? `${path}.${key}` : key;
+                        const result = this.validateAgainstSchema(obj[key], propSchema, propPath);
+                        errors.push(...result.errors);
+                    }
+                }
+            }
+        }
+        // Array validation
+        if (schema.type === 'array' && Array.isArray(data) && schema.items) {
+            for (let i = 0; i < data.length; i++) {
+                const itemPath = `${path}[${i}]`;
+                const result = this.validateAgainstSchema(data[i], schema.items, itemPath);
+                errors.push(...result.errors);
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+    jsonType(value) {
+        if (value === null)
+            return 'null';
+        if (Array.isArray(value))
+            return 'array';
+        if (typeof value === 'number') {
+            return Number.isInteger(value) ? 'integer' : 'number';
+        }
+        return typeof value;
+    }
+}
+//# sourceMappingURL=schema-validator.js.map

package/packages/@monomind/shared/dist/scratchpad.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SharedScratchpad — a shared, append-only log that two or more agents
+ * can use to exchange messages during a collaborate-mode iteration loop.
+ */
+export interface ScratchpadEntry {
+    agentId: string;
+    content: string;
+    timestamp: Date;
+}
+export declare class SharedScratchpad {
+    entries: ScratchpadEntry[];
+    iteration: number;
+    append(agentId: string, content: string): void;
+    /**
+     * Return a human-readable transcript of all entries,
+     * separated by `---` dividers.
+     */
+    read(): string;
+    readEntries(): Readonly<ScratchpadEntry[]>;
+    isConverged(predicate: (entries: ScratchpadEntry[]) => boolean): boolean;
+    reset(): void;
+}
+//# sourceMappingURL=scratchpad.d.ts.map

package/packages/@monomind/shared/dist/scratchpad.js

@@ -0,0 +1,32 @@
+/**
+ * SharedScratchpad — a shared, append-only log that two or more agents
+ * can use to exchange messages during a collaborate-mode iteration loop.
+ */
+export class SharedScratchpad {
+    entries = [];
+    iteration = 0;
+    append(agentId, content) {
+        this.entries.push({ agentId, content, timestamp: new Date() });
+        this.iteration++;
+    }
+    /**
+     * Return a human-readable transcript of all entries,
+     * separated by `---` dividers.
+     */
+    read() {
+        return this.entries
+            .map((e) => `[${e.agentId} @ ${e.timestamp.toISOString()}]\n${e.content}`)
+            .join('\n---\n');
+    }
+    readEntries() {
+        return this.entries;
+    }
+    isConverged(predicate) {
+        return predicate(this.entries);
+    }
+    reset() {
+        this.entries = [];
+        this.iteration = 0;
+    }
+}
+//# sourceMappingURL=scratchpad.js.map

package/packages/@monomind/shared/dist/security/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Security Module
+ *
+ * Shared security utilities for V1 Monomind.
+ *
+ * @module v1/shared/security
+ */
+export { generateSecureId, generateUUID, generateSecureToken, generateShortId, generateSessionId, generateAgentId, generateTaskId, generateMemoryId, generateEventId, generateSwarmId, generatePatternId, generateTrajectoryId, secureRandomInt, secureRandomChoice, secureShuffleArray, } from './secure-random.js';
+export { validateInput, sanitizeString, validatePath, validateCommand, validateTags, isValidIdentifier, escapeForSql, type ValidationResult, type ValidationOptions, } from './input-validation.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/@monomind/shared/dist/security/index.js

@@ -0,0 +1,12 @@
+/**
+ * Security Module
+ *
+ * Shared security utilities for V1 Monomind.
+ *
+ * @module v1/shared/security
+ */
+// Secure random generation
+export { generateSecureId, generateUUID, generateSecureToken, generateShortId, generateSessionId, generateAgentId, generateTaskId, generateMemoryId, generateEventId, generateSwarmId, generatePatternId, generateTrajectoryId, secureRandomInt, secureRandomChoice, secureShuffleArray, } from './secure-random.js';
+// Input validation
+export { validateInput, sanitizeString, validatePath, validateCommand, validateTags, isValidIdentifier, escapeForSql, } from './input-validation.js';
+//# sourceMappingURL=index.js.map

package/packages/@monomind/shared/dist/security/input-validation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Input Validation Utilities
+ *
+ * Secure input validation and sanitization.
+ *
+ * @module v1/shared/security/input-validation
+ */
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    sanitized?: unknown;
+}
+/**
+ * Validation options
+ */
+export interface ValidationOptions {
+    maxLength?: number;
+    minLength?: number;
+    pattern?: RegExp;
+    allowedChars?: RegExp;
+    required?: boolean;
+    trim?: boolean;
+}
+/**
+ * Validate and sanitize string input
+ * @param input Input string
+ * @param options Validation options
+ * @returns Validation result
+ */
+export declare function validateInput(input: unknown, options?: ValidationOptions): ValidationResult;
+/**
+ * Sanitize string by removing dangerous characters
+ * @param input Input string
+ * @returns Sanitized string
+ */
+export declare function sanitizeString(input: string): string;
+/**
+ * Validate file path (prevent path traversal)
+ * @param path File path
+ * @param allowedBase Allowed base directory
+ * @returns Validation result
+ */
+export declare function validatePath(path: string, allowedBase?: string): ValidationResult;
+/**
+ * Validate command (prevent command injection)
+ * @param command Command string
+ * @param allowedCommands Optional whitelist of allowed commands
+ * @returns Validation result
+ */
+export declare function validateCommand(command: string, allowedCommands?: string[]): ValidationResult;
+/**
+ * Validate tags for safe SQL usage
+ * @param tags Array of tag strings
+ * @returns Validation result with sanitized tags
+ */
+export declare function validateTags(tags: unknown): ValidationResult;
+/**
+ * Check if string is a valid identifier
+ * @param id Identifier string
+ * @returns True if valid
+ */
+export declare function isValidIdentifier(id: string): boolean;
+/**
+ * Escape string for safe SQL usage (use parameterized queries instead when possible)
+ * This is a LAST RESORT - always prefer parameterized queries
+ * @param value String to escape
+ * @returns Escaped string
+ */
+export declare function escapeForSql(value: string): string;
+//# sourceMappingURL=input-validation.d.ts.map