principles-disciple 1.201.0 → 1.202.0

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>;

package/dist/utils/session-key.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Session key parsing utilities.
+ *
+ * Session key format: "agent:{agentId}:{type}:{uuid}" or "agent:{agentId}:{uuid}"
+ */
+/**
+ * Extract agentId from a sessionKey.
+ * Returns `undefined` if sessionKey is missing, malformed, or has whitespace-only agentId.
+ */
+export declare function extractAgentIdFromSessionKey(sessionKey: string | undefined): string | undefined;

package/dist/utils/workspace-resolver.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Workspace Directory Resolution Utilities
+ *
+ * Shared helpers for resolving workspace directories across commands and hooks.
+ *
+ * Hook resolution priority (PRI-259): PD canonical config → OpenClaw fallback.
+ * PD canonical sources: PD_WORKSPACE_DIR env → OPENCLAW_WORKSPACE env →
+ * principles-disciple.json → ~/.openclaw/workspace default.
+ * OpenClaw fallback: ctx.workspaceDir → api.runtime.agent.resolveAgentWorkspaceDir().
+ */
+import type { OpenClawPluginApi, PluginCommandContext } from '../openclaw-sdk.js';
+import { type WorkspaceResolutionContext } from '../core/workspace-dir-validation.js';
+/**
+ * Resolve workspace directory for command execution.
+ *
+ * Chain: ctx.workspaceDir → resolveWorkspaceDirFromApi (official OpenClaw API + env vars)
+ *
+ * CRITICAL: Throws if workspaceDir cannot be resolved. Silent failures are dangerous
+ * because commands might operate on the wrong directory.
+ */
+export declare function resolveCommandWorkspaceDir(api: OpenClawPluginApi, ctx: {
+    workspaceDir?: string;
+}): string;
+/**
+ * Resolve workspace directory for plugin command execution.
+ *
+ * Chain: ctx.workspaceDir (canonical) → ctx.config.workspaceDir (dispatcher fallback)
+ *
+ * CRITICAL: Throws if workspaceDir cannot be resolved. Commands must NEVER silently
+ * fall back to process.cwd() as this masks configuration errors and can corrupt
+ * the wrong workspace.
+ *
+ * @param ctx - Plugin command context (has workspaceDir + config properties)
+ * @param source - Source label for error messages (e.g. 'evolution-status', 'pain')
+ */
+export declare function resolvePluginCommandWorkspaceDir(ctx: PluginCommandContext, source: string): string;
+export type CanonicalWorkspaceSource = 'pd_env' | 'openclaw_env' | 'pd_config' | 'pd_default';
+export interface CanonicalWorkspaceResult {
+    workspaceDir: string;
+    source: CanonicalWorkspaceSource;
+}
+export declare function resolveCanonicalWorkspaceDir(): CanonicalWorkspaceResult | null;
+export type HookWorkspaceSource = CanonicalWorkspaceSource | 'openclaw_context' | 'openclaw_api';
+export interface HookWorkspaceResolutionSuccess {
+    ok: true;
+    workspaceDir: string;
+    source: HookWorkspaceSource;
+    consistencyWarning?: string;
+}
+export interface HookWorkspaceResolutionFailure {
+    ok: false;
+    reason: string;
+    nextAction: string;
+    message: string;
+}
+export type HookWorkspaceResolutionResult = HookWorkspaceResolutionSuccess | HookWorkspaceResolutionFailure;
+export interface HookWorkspaceResolutionOptions {
+    canonicalResolver?: () => CanonicalWorkspaceResult | null;
+    explicitPdResolver?: () => CanonicalWorkspaceResult | null;
+}
+export declare function resolveHookWorkspaceDir(ctx: WorkspaceResolutionContext, api: OpenClawPluginApi, source: string, options?: HookWorkspaceResolutionOptions): HookWorkspaceResolutionResult;
+/**
+ * Resolve workspace directory for tool hook execution (safe version).
+ * Returns undefined instead of throwing if resolution fails.
+ *
+ * PRI-259: Uses PD canonical config as primary source, OpenClaw as fallback.
+ */
+export declare function resolveToolHookWorkspaceDirSafe(ctx: WorkspaceResolutionContext, api: OpenClawPluginApi, source: string, options?: HookWorkspaceResolutionOptions): string | undefined;
+export declare class WorkspaceResolutionError extends Error {
+    readonly reason: string;
+    readonly nextAction: string;
+    constructor(message: string, reason: string, nextAction: string);
+    toJSON(): {
+        ok: false;
+        reason: string;
+        message: string;
+        nextAction: string;
+    };
+}
+export declare function resolveWorkspaceDirForRuntimeV2(ctx: {
+    workspaceDir?: string;
+}, api: OpenClawPluginApi | undefined, source: string): string;

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Turn repeated Agent corrections into Owner-approved, observable, reversible behavior principles. Stop correcting the same AI behavior across sessions.",
-  "version": "1.201.0",
+  "version": "1.202.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.201.0",
+  "version": "1.202.0",
   "description": "Turn repeated Agent corrections into Owner-approved, observable, reversible behavior principles. Stop correcting the same AI behavior across sessions.",
   "type": "module",
   "main": "./dist/index.js",
@@ -57,7 +57,8 @@
     "build": "tsc",
     "build:bundle": "node esbuild.config.js",
     "build:production": "node esbuild.config.js --production && node scripts/verify-build.mjs",
-    "prepack": "npm run build:production",
+    "build:types": "tsc --emitDeclarationOnly",
+    "prepack": "npm run build:production && npm run build:types",
     "test": "vitest run",
     "test:unit": "vitest run --config vitest.unit.config.ts tests/core tests/service tests/hooks tests/commands tests/utils tests/scripts --exclude tests/commands/evolver.test.ts",
     "test:integration": "vitest run tests/integration/",