principles-disciple 1.126.0 → 1.128.0

package/dist/utils/io.js

@@ -0,0 +1,174 @@
+import * as path from 'path';
+import * as fs from 'fs';
+/**
+ * Atomic file write — write to temp then rename to prevent partial writes on crash.
+ *
+ * On Windows, renameSync can fail with EPERM/EBUSY if the file is temporarily
+ * locked by antivirus software or another process. Retries with exponential
+ * backoff to handle transient locks.
+ */
+const RENAME_MAX_RETRIES = 3;
+const RENAME_BASE_DELAY_MS = 50;
+export function atomicWriteFileSync(filePath, data) {
+    const tmpPath = filePath + '.tmp';
+    fs.writeFileSync(tmpPath, data, 'utf8');
+    let lastError;
+    for (let attempt = 0; attempt < RENAME_MAX_RETRIES; attempt++) {
+        try {
+            fs.renameSync(tmpPath, filePath);
+            return;
+        }
+        catch (err) {
+            lastError = err;
+            const code = err.code;
+            // Only retry on Windows transient lock errors
+            if (code === 'EPERM' || code === 'EBUSY' || code === 'EACCES') {
+                if (attempt < RENAME_MAX_RETRIES - 1) {
+                    const delay = RENAME_BASE_DELAY_MS * Math.pow(2, attempt);
+                    // Bounded spin-wait with CPU yield — materially different from
+                    // tight infinite spin; only 50-200ms total across retries.
+                    const waitUntil = Date.now() + delay;
+                    let yielded = false;
+                    while (Date.now() < waitUntil) {
+                        if (!yielded && Date.now() >= waitUntil - 10) {
+                            // Last few ms: yield to give other sync code a chance to run
+                            try {
+                                require('fs').accessSync?.(tmpPath);
+                            }
+                            catch { /* ignore */ }
+                            yielded = true;
+                        }
+                    }
+                }
+                continue;
+            }
+            // Non-retryable error — throw immediately
+            break;
+        }
+    }
+    // Clean up temp file on failure
+    try {
+        fs.unlinkSync(tmpPath);
+    }
+    catch { /* best effort */ }
+    throw lastError;
+}
+export function normalizePath(filePath, projectDir) {
+    if (!filePath)
+        return '';
+    const projectIsWin = projectDir.includes('\\') || (projectDir.length >= 2 && projectDir[1] === ':');
+    const fileIsWin = filePath.includes('\\') || (filePath.length >= 2 && filePath[1] === ':');
+    let normalizedFilePath = filePath;
+    if (projectIsWin !== fileIsWin) {
+        if (fileIsWin) {
+            // Basic WSL conversion D:\path -> /mnt/d/path
+            normalizedFilePath = `/mnt/${filePath.charAt(0).toLowerCase()}${filePath.slice(2).replace(/\\/g, '/')}`;
+        }
+    }
+    // POSIX absolute paths (e.g., /etc/passwd) are NOT recognized as absolute
+    // by path.isAbsolute() on Windows. When both the project dir and the file
+    // path are POSIX paths, use path.posix for relative computation.
+    const isPosixAbsolute = normalizedFilePath.startsWith('/') && !fileIsWin;
+    const projectIsPosix = !projectIsWin;
+    let rel;
+    if (projectIsWin) {
+        const projectAbs = path.resolve(projectDir);
+        if (isPosixAbsolute) {
+            // POSIX absolute path on Windows project: cannot resolve relative to project,
+            // return as-is (path is outside the project directory).
+            rel = normalizedFilePath;
+        }
+        else {
+            const fileAbs = path.isAbsolute(normalizedFilePath)
+                ? normalizedFilePath
+                : path.join(projectAbs, normalizedFilePath);
+            rel = path.relative(projectAbs, fileAbs);
+        }
+    }
+    else if (projectIsPosix && isPosixAbsolute) {
+        // Both project and file are POSIX → use path.posix
+        const projectPosix = projectDir.replace(/\\/g, '/');
+        rel = path.posix.relative(projectPosix, normalizedFilePath);
+    }
+    else {
+        const projectPosix = projectDir.replace(/\\/g, '/');
+        const filePosix = path.isAbsolute(normalizedFilePath)
+            ? normalizedFilePath
+            : path.posix.join(projectPosix, normalizedFilePath.replace(/\\/g, '/'));
+        rel = path.posix.relative(projectPosix, filePosix);
+    }
+    rel = rel.replace(/\\/g, '/');
+    if (rel.startsWith('../')) {
+        return normalizedFilePath;
+    }
+    return rel;
+}
+export function normalizeRiskPath(p) {
+    let normalized = p.replace(/\\/g, '/');
+    if (normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+export function isRisky(relPath, riskPaths) {
+    if (!relPath || !riskPaths || riskPaths.length === 0)
+        return false;
+    const normalizedRel = normalizeRiskPath(relPath);
+    for (const pattern of riskPaths) {
+        const normalizedPattern = normalizeRiskPath(pattern);
+        if (normalizedRel.startsWith(normalizedPattern)) {
+            // If it starts with the pattern, and either they are exactly equal OR the next char is a slash
+            // (prevents "src/db_backup" matching "src/db")
+            if (normalizedRel === normalizedPattern || normalizedRel.charAt(normalizedPattern.length) === '/') {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+export function parseKvLines(text) {
+    const result = {};
+    const lines = text.split('\n');
+    for (const line of lines) {
+        const idx = line.indexOf(':');
+        if (idx !== -1) {
+            const key = line.slice(0, idx).trim();
+            const value = line.slice(idx + 1).trim();
+            result[key] = value;
+        }
+    }
+    return result;
+}
+export function serializeKvLines(data) {
+    const lines = [];
+    const keys = Object.keys(data).sort();
+    for (const k of keys) {
+        const v = data[k];
+        // Skip empty/undefined values — prevents writing blank lines that cause
+        // agent confusion (SKILL.md lists fields that aren't actually present on disk)
+        if (v === '' || v === undefined || v === null) {
+            continue;
+        }
+        if (Array.isArray(v)) {
+            lines.push(`${k}: ${v.join(',')}`);
+        }
+        else if (typeof v === 'object' && v !== null) {
+            lines.push(`${k}: ${JSON.stringify(v)}`);
+        }
+        else {
+            lines.push(`${k}: ${v}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Normalize command arguments from PluginCommandContext.args.
+ * Handles string | string[] | undefined union by joining arrays with spaces.
+ */
+export function normalizeCommandArgs(args) {
+    if (args === undefined || args === null)
+        return '';
+    if (Array.isArray(args))
+        return args.join(' ');
+    return args;
+}

package/dist/utils/node-vm-polyfill.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Node VM Polyfill — Thin wrapper around node:vm module
+ *
+ * PURPOSE: Provide a single import point for vm compilation functionality
+ * used by the Rule Host. Isolates the node:vm dependency so it can be
+ * easily mocked in tests.
+ */
+import * as vm from 'node:vm';
+export declare const nodeVm: typeof vm;

package/{src/utils/node-vm-polyfill.ts → dist/utils/node-vm-polyfill.js}

@@ -5,7 +5,5 @@
  * used by the Rule Host. Isolates the node:vm dependency so it can be
  * easily mocked in tests.
  */
-
 import * as vm from 'node:vm';
-
 export const nodeVm = vm;

package/dist/utils/retry.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Unified Retry Utilities
+ *
+ * Provides a centralized retry mechanism for all async operations that may fail
+ * due to transient errors (network timeouts, resource locks, rate limits, etc).
+ *
+ * @module utils/retry
+ *
+ * @example
+ * ```typescript
+ * import { retryAsync, isRetryableError } from '../utils/retry.js';
+ *
+ * const result = await retryAsync(
+ *   () => llmClient.generate(prompt),
+ *   { maxRetries: 3, operation: 'llm-generate' }
+ * );
+ * ```
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in ms before first retry (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay in ms between retries (default: 30000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier (default: 2 for exponential) */
+    backoffMultiplier?: number;
+    /** Operation name for logging */
+    operation?: string;
+    /** Logger instance (optional, defaults to console) */
+    logger?: RetryLogger;
+    isRetryable?: (_error: unknown) => boolean;
+}
+export interface RetryLogger {
+    warn?: (_message: string) => void;
+    info?: (_message: string) => void;
+    debug?: (_message: string) => void;
+}
+export interface RetryResult<T> {
+    /** The result value if successful */
+    value: T;
+    /** Number of attempts made (including successful one) */
+    attempts: number;
+    /** Total time spent in ms */
+    totalTimeMs: number;
+}
+/**
+ * Determines if an error is retryable based on common patterns.
+ *
+ * @param error - The error to check
+ * @returns true if the error is likely transient and worth retrying
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Execute an async function with automatic retry on failure.
+ *
+ * Uses exponential backoff with configurable parameters.
+ * Automatically detects retryable errors (timeouts, rate limits, etc).
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry configuration
+ * @returns The result of the function
+ * @throws The last error if all retries fail
+ */
+export declare function retryAsync<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Execute an async function with retry, returning detailed result info.
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry configuration
+ * @returns Detailed result including attempts and timing
+ */
+export declare function retryAsyncWithInfo<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
+/**
+ * Create a retry wrapper for a function.
+ * Useful for wrapping LLM calls or API clients.
+ *
+ * @param fn - The async function to wrap
+ * @param options - Default retry configuration
+ * @returns A wrapped function with retry built-in
+ */
+export declare function withRetry<T, Args extends unknown[]>(fn: (...args: Args) => Promise<T>, options?: RetryOptions): (...args: Args) => Promise<T>;
+/**
+ * Retry an LLM API call with appropriate defaults.
+ * LLM calls often timeout or hit rate limits.
+ */
+export declare function retryLLMCall<T>(fn: () => Promise<T>, operation?: string): Promise<T>;
+/**
+ * Retry a file operation with appropriate defaults.
+ * File operations may fail due to locks or concurrent access.
+ */
+export declare function retryFileOperation<T>(fn: () => Promise<T>, operation?: string): Promise<T>;
+/**
+ * Retry a network request with appropriate defaults.
+ * Network requests may fail due to transient connectivity issues.
+ */
+export declare function retryNetworkRequest<T>(fn: () => Promise<T>, operation?: string): Promise<T>;
+/** Minimum samples needed before trusting learned timeout values */
+export declare const MIN_SAMPLES = 3;
+/** Number of recent completion durations to consider */
+export declare const LOOKBACK_WINDOW = 50;
+/** Safety multiplier applied to P95 */
+export declare const SAFETY_MULTIPLIER = 1.5;
+/** Absolute minimum timeout — never go below this (10s) */
+export declare const MIN_TIMEOUT_MS = 10000;
+/** Absolute maximum timeout cap — never exceed this (5min) */
+export declare const MAX_TIMEOUT_MS = 300000;
+/** Maximum retry attempts for workflow timeout */
+export declare const MAX_TIMEOUT_RETRIES = 2;
+/** Backoff multiplier for retry schedule */
+export declare const RETRY_BACKOFF_MULTIPLIER = 2;
+/**
+ * Interface for a data source that provides historical workflow durations.
+ * Compatible with WorkflowStore's getCompletionDurations API.
+ * This is the primary interface used by WorkflowManager.
+ */
+export interface DurationDataSource {
+    getCompletionDurations(workflowType: string, limit: number): number[];
+}
+/**
+ * Interface for duration history storage (simpler alternative).
+ */
+export interface DurationHistorySource {
+    /** Get recent completion durations in ms */
+    getDurations(limit: number): number[];
+    /** Record a new completion duration */
+    recordDuration(durationMs: number): void;
+}
+/**
+ * Options for adaptive retry with dynamic timeout.
+ */
+export interface AdaptiveRetryOptions extends RetryOptions {
+    /** Source for historical duration data */
+    durationHistory?: DurationHistorySource;
+    /** Minimum samples before using adaptive timeout */
+    minSamples?: number;
+    /** Percentile to use (default: 95) */
+    percentile?: number;
+    /** Safety multiplier for computed timeout (default: 1.5) */
+    safetyMultiplier?: number;
+    /** Minimum allowed timeout in ms (default: 10000) */
+    minTimeoutMs?: number;
+    /** Maximum allowed timeout in ms (default: 300000) */
+    maxTimeoutMs?: number;
+}
+/**
+ * Calculates P95 (or any percentile) from an array of numbers.
+ * Falls back to median for small samples (< 10).
+ *
+ * @param values - Array of duration values
+ * @param p - Percentile to compute (0-100)
+ * @returns The computed percentile value
+ */
+export declare function percentile(values: number[], p: number): number;
+/**
+ * Clamp timeout to safe bounds.
+ */
+export declare function clampTimeout(ms: number): number;
+/**
+ * Computes an adaptive timeout for a workflow type based on historical data.
+ *
+ * Algorithm:
+ * 1. Fetch last LOOKBACK_WINDOW completion durations
+ * 2. If < MIN_SAMPLES: fall back to the provided defaultTimeout
+ * 3. Otherwise: P95(durations) × SAFETY_MULTIPLIER
+ * 4. Clamp to [MIN_TIMEOUT_MS, MAX_TIMEOUT_MS]
+ *
+ * This is the primary function used by WorkflowManager.
+ *
+ * @param dataSource - Source for historical duration data
+ * @param workflowType - e.g. 'empathy-observer', 'deep-reflect'
+ * @param defaultTimeout - Fallback when insufficient data (from spec)
+ * @returns Computed timeout in milliseconds
+ */
+export declare function computeDynamicTimeout(dataSource: DurationDataSource, workflowType: string, defaultTimeout: number): number;
+/**
+ * Computes retry timeout schedule for a workflow.
+ * Returns an array of timeout values for each attempt (including initial).
+ *
+ * Example output: [30000, 60000, 120000] for 3 attempts with base 30s
+ *
+ * @param baseTimeoutMs - Base timeout in milliseconds
+ * @param maxRetries - Maximum retry attempts (default: MAX_TIMEOUT_RETRIES)
+ * @returns Array of timeout values for each attempt
+ */
+export declare function computeRetrySchedule(baseTimeoutMs: number, maxRetries?: number): number[];
+/**
+ * Compute adaptive timeout from historical data (simplified API).
+ * Alternative to computeDynamicTimeout for simpler use cases.
+ */
+export declare function computeAdaptiveTimeout(history: number[], fallbackMs: number, options?: {
+    minSamples?: number;
+    percentile?: number;
+    safetyMultiplier?: number;
+    minTimeoutMs?: number;
+    maxTimeoutMs?: number;
+}): number;
+/**
+ * Execute an async function with adaptive timeout and retry.
+ *
+ * Combines:
+ * 1. Dynamic timeout based on P95 of historical completions
+ * 2. Exponential backoff on retry
+ * 3. Automatic duration recording after success
+ *
+ * @param fn - The async function to execute
+ * @param options - Configuration including history source
+ * @returns The result of the function
+ */
+export declare function retryWithAdaptiveTimeout<T>(fn: () => Promise<T>, options?: AdaptiveRetryOptions): Promise<T>;