create-principles-disciple 1.104.0 → 1.104.2

package/plugin/dist/utils/retry.js

@@ -1,380 +0,0 @@
-/**
- * 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' }
- * );
- * ```
- */
-// =========================================================================
-// Defaults
-// =========================================================================
-const DEFAULT_MAX_RETRIES = 3;
-const DEFAULT_INITIAL_DELAY_MS = 1000;
-const DEFAULT_MAX_DELAY_MS = 30_000;
-const DEFAULT_BACKOFF_MULTIPLIER = 2;
-/**
- * Sleep for a given number of milliseconds.
- */
-function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
-// =========================================================================
-// Error Classification
-// =========================================================================
-/**
- * Common retryable error patterns.
- * These indicate transient failures that may succeed on retry.
- */
-const RETRYABLE_PATTERNS = [
-    // Network/timeout errors
-    'etimedout',
-    'econnreset',
-    'econnrefused',
-    'enotfound',
-    'eai_again',
-    'socket hang up',
-    'network',
-    'timeout',
-    'timed out',
-    // Rate limiting
-    'rate limit',
-    'ratelimit',
-    '429',
-    'too many requests',
-    // Resource temporarily unavailable
-    'eagain',
-    'ebusy',
-    'resource temporarily unavailable',
-    'lock',
-    'locked',
-    // LLM-specific
-    'overloaded',
-    'capacity',
-    'service unavailable',
-    '503',
-    '502',
-    'gateway timeout',
-    // OpenClaw-specific
-    'gateway request', // Not in gateway context (may succeed later)
-    'missing scope', // Scope not available (may succeed in different context)
-];
-/**
- * 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 function isRetryableError(error) {
-    if (!error)
-        return false;
-    const message = error instanceof Error
-        ? error.message.toLowerCase()
-        : String(error).toLowerCase();
-    // Check against known retryable patterns
-    for (const pattern of RETRYABLE_PATTERNS) {
-        if (message.includes(pattern)) {
-            return true;
-        }
-    }
-    // Check for specific error codes
-    if (error instanceof Error && 'code' in error) {
-        const code = String(error.code).toLowerCase();
-        for (const pattern of RETRYABLE_PATTERNS) {
-            if (code.includes(pattern)) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
-// =========================================================================
-// Core Retry Functions
-// =========================================================================
-/**
- * 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 async function retryAsync(fn, options = {}) {
-    const { maxRetries = DEFAULT_MAX_RETRIES, initialDelayMs = DEFAULT_INITIAL_DELAY_MS, maxDelayMs = DEFAULT_MAX_DELAY_MS, backoffMultiplier = DEFAULT_BACKOFF_MULTIPLIER, operation = 'unknown', logger = console, isRetryable = isRetryableError, } = options;
-    const startTime = Date.now();
-    let lastError = undefined;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        try {
-            const result = await fn();
-            if (attempt > 0) {
-                logger.info?.(`[PD:Retry] ${operation} succeeded on attempt ${attempt + 1} (total time: ${Date.now() - startTime}ms)`);
-            }
-            return result;
-        }
-        catch (error) {
-            lastError = error;
-            const isLastAttempt = attempt === maxRetries;
-            const shouldRetry = !isLastAttempt && isRetryable(error);
-            if (shouldRetry) {
-                const delay = Math.min(initialDelayMs * Math.pow(backoffMultiplier, attempt), maxDelayMs);
-                logger.warn?.(`[PD:Retry] ${operation} failed on attempt ${attempt + 1}, retrying in ${delay}ms: ${String(error)}`);
-                await sleep(delay);
-            }
-            else {
-                logger.warn?.(`[PD:Retry] ${operation} failed after ${attempt + 1} attempts: ${String(error)}`);
-                throw error;
-            }
-        }
-    }
-    // Should never reach here, but TypeScript needs it
-    throw lastError;
-}
-/**
- * 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 async function retryAsyncWithInfo(fn, options = {}) {
-    const startTime = Date.now();
-    let attempts = 0;
-    const value = await retryAsync(async () => {
-        attempts++;
-        return fn();
-    }, { ...options, logger: undefined } // Suppress internal logging
-    );
-    return {
-        value,
-        attempts,
-        totalTimeMs: Date.now() - startTime,
-    };
-}
-/**
- * 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 function withRetry(fn, options = {}) {
-    return (...args) => retryAsync(() => fn(...args), options);
-}
-// =========================================================================
-// Specialized Retry Presets
-// =========================================================================
-/**
- * Retry an LLM API call with appropriate defaults.
- * LLM calls often timeout or hit rate limits.
- */
-export async function retryLLMCall(fn, operation = 'llm-call') {
-    return retryAsync(fn, {
-        maxRetries: 3,
-        initialDelayMs: 2000,
-        maxDelayMs: 60_000,
-        operation,
-    });
-}
-/**
- * Retry a file operation with appropriate defaults.
- * File operations may fail due to locks or concurrent access.
- */
-export async function retryFileOperation(fn, operation = 'file-op') {
-    return retryAsync(fn, {
-        maxRetries: 5,
-        initialDelayMs: 50,
-        maxDelayMs: 5000,
-        operation,
-    });
-}
-/**
- * Retry a network request with appropriate defaults.
- * Network requests may fail due to transient connectivity issues.
- */
-export async function retryNetworkRequest(fn, operation = 'network-request') {
-    return retryAsync(fn, {
-        maxRetries: 3,
-        initialDelayMs: 1000,
-        maxDelayMs: 30_000,
-        operation,
-    });
-}
-// =========================================================================
-// Dynamic Timeout Support
-// =========================================================================
-/** Minimum samples needed before trusting learned timeout values */
-export const MIN_SAMPLES = 3;
-/** Number of recent completion durations to consider */
-export const LOOKBACK_WINDOW = 50;
-/** Safety multiplier applied to P95 */
-export const SAFETY_MULTIPLIER = 1.5;
-/** Absolute minimum timeout — never go below this (10s) */
-export const MIN_TIMEOUT_MS = 10_000;
-/** Absolute maximum timeout cap — never exceed this (5min) */
-export const MAX_TIMEOUT_MS = 300_000;
-/** Maximum retry attempts for workflow timeout */
-export const MAX_TIMEOUT_RETRIES = 2;
-/** Backoff multiplier for retry schedule */
-export const RETRY_BACKOFF_MULTIPLIER = 2;
-/**
- * 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 function percentile(values, p) {
-    if (values.length === 0)
-        return 0;
-    const sorted = [...values].sort((a, b) => a - b);
-    const n = sorted.length;
-    // For small samples, use median to avoid overfitting
-    if (n < 10) {
-        const median = sorted[Math.floor(n / 2)];
-        return median ?? 0;
-    }
-    // Standard percentile calculation (nearest-rank method)
-    const rank = Math.ceil((p / 100) * n);
-    const result = sorted[Math.min(rank, n) - 1];
-    return result ?? 0;
-}
-/**
- * Clamp timeout to safe bounds.
- */
-export function clampTimeout(ms) {
-    return Math.max(MIN_TIMEOUT_MS, Math.min(MAX_TIMEOUT_MS, Math.round(ms)));
-}
-/**
- * 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 function computeDynamicTimeout(dataSource, workflowType, defaultTimeout) {
-    const history = dataSource.getCompletionDurations(workflowType, LOOKBACK_WINDOW);
-    if (history.length < MIN_SAMPLES) {
-        // Not enough data — use the spec's static timeout
-        const fallback = clampTimeout(defaultTimeout);
-        console.info(`[PD:DynamicTimeout] Insufficient samples (${history.length} < ${MIN_SAMPLES}) for '${workflowType}', falling back to static timeout: ${fallback}ms`);
-        return fallback;
-    }
-    const p95 = percentile(history, 95);
-    const adaptive = p95 * SAFETY_MULTIPLIER;
-    const result = clampTimeout(adaptive);
-    console.info(`[PD:DynamicTimeout] Computed adaptive timeout for '${workflowType}': P95=${p95}ms (from ${history.length} samples) × ${SAFETY_MULTIPLIER} = ${result}ms`);
-    return result;
-}
-/**
- * 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 function computeRetrySchedule(baseTimeoutMs, maxRetries = MAX_TIMEOUT_RETRIES) {
-    const schedule = [];
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        const timeout = baseTimeoutMs * Math.pow(RETRY_BACKOFF_MULTIPLIER, attempt);
-        schedule.push(clampTimeout(timeout));
-    }
-    return schedule;
-}
-/**
- * Compute adaptive timeout from historical data (simplified API).
- * Alternative to computeDynamicTimeout for simpler use cases.
- */
-export function computeAdaptiveTimeout(history, fallbackMs, options = {}) {
-    const { minSamples = MIN_SAMPLES, percentile: p = 95, safetyMultiplier = SAFETY_MULTIPLIER, minTimeoutMs = MIN_TIMEOUT_MS, maxTimeoutMs = MAX_TIMEOUT_MS, } = options;
-    if (history.length < minSamples) {
-        return Math.max(minTimeoutMs, Math.min(maxTimeoutMs, fallbackMs));
-    }
-    const sorted = [...history].sort((a, b) => a - b);
-    const rank = Math.ceil((p / 100) * sorted.length);
-    const pValue = sorted[Math.min(rank, sorted.length) - 1];
-    if (pValue === undefined) {
-        return Math.max(minTimeoutMs, Math.min(maxTimeoutMs, fallbackMs));
-    }
-    const adaptive = pValue * safetyMultiplier;
-    return Math.max(minTimeoutMs, Math.min(maxTimeoutMs, Math.round(adaptive)));
-}
-/**
- * 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 async function retryWithAdaptiveTimeout(fn, options = {}) {
-    const { durationHistory, minSamples = 3, percentile: p = 95, safetyMultiplier = 1.5, minTimeoutMs = 10_000, maxTimeoutMs = 300_000, maxRetries = 3, backoffMultiplier = 2, operation = 'adaptive', logger = console, isRetryable = isRetryableError, } = options;
-    // Compute base timeout from history
-    const history = durationHistory?.getDurations(50) ?? [];
-    const baseTimeout = computeAdaptiveTimeout(history, minTimeoutMs * 3, {
-        minSamples,
-        percentile: p,
-        safetyMultiplier,
-        minTimeoutMs,
-        maxTimeoutMs,
-    });
-    const startTime = Date.now();
-    let lastError = undefined;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        const timeoutMs = Math.min(baseTimeout * Math.pow(backoffMultiplier, attempt), maxTimeoutMs);
-        try {
-            logger.debug?.(`[PD:Retry] ${operation} attempt ${attempt + 1}: timeout=${timeoutMs}ms (base=${baseTimeout}ms, samples=${history.length})`);
-            const result = await fn();
-            const duration = Date.now() - startTime;
-            // Record successful completion for future adaptive timeout
-            durationHistory?.recordDuration(duration);
-            if (attempt > 0) {
-                logger.info?.(`[PD:Retry] ${operation} succeeded on attempt ${attempt + 1} (duration=${duration}ms)`);
-            }
-            return result;
-        }
-        catch (error) {
-            lastError = error;
-            const isLastAttempt = attempt === maxRetries;
-            const shouldRetry = !isLastAttempt && isRetryable(error);
-            if (shouldRetry) {
-                logger.warn?.(`[PD:Retry] ${operation} failed on attempt ${attempt + 1}, retrying: ${String(error)}`);
-            }
-            else {
-                logger.warn?.(`[PD:Retry] ${operation} failed after ${attempt + 1} attempts: ${String(error)}`);
-                throw error;
-            }
-        }
-    }
-    throw lastError;
-}

package/plugin/dist/utils/session-key.js

@@ -1,21 +0,0 @@
-/**
- * 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 function extractAgentIdFromSessionKey(sessionKey) {
-    if (!sessionKey)
-        return undefined;
-    const match = /^agent:([^:]+):/.exec(sessionKey);
-    if (!match)
-        return undefined;
-    const raw = match[1];
-    if (!raw)
-        return undefined;
-    const agentId = raw.trim();
-    return agentId || undefined;
-}

package/plugin/dist/utils/workspace-resolver.js

@@ -1,288 +0,0 @@
-/**
- * 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 { validateWorkspaceDir } from '../core/workspace-dir-validation.js';
-import { resolveWorkspaceDirFromApi } from '../core/path-resolver.js';
-import * as path from 'path';
-import * as os from 'os';
-import * as fs from 'fs';
-/**
- * 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 function resolveCommandWorkspaceDir(api, ctx) {
-    // 1. Direct from command context (most reliable — set by OpenClaw for current session)
-    if (ctx.workspaceDir) {
-        const issue = validateWorkspaceDir(ctx.workspaceDir);
-        if (!issue)
-            return ctx.workspaceDir;
-        // Validation failed — fail immediately, do not silently fall back
-        const errorMsg = `[PD:Command] ctx.workspaceDir="${ctx.workspaceDir}" is invalid: ${issue}`;
-        api.logger.error(errorMsg);
-        throw new Error(errorMsg);
-    }
-    // 2. Official OpenClaw API → env vars → config file
-    const resolved = resolveWorkspaceDirFromApi(api);
-    if (resolved)
-        return resolved;
-    // CRITICAL FAILURE: Cannot determine workspace directory
-    const errorMsg = `[PD:Command] CRITICAL: Cannot resolve workspace directory. ` +
-        `ctx.workspaceDir="${ctx.workspaceDir ?? ''}" is invalid, and all fallbacks failed. ` +
-        `Commands will NOT execute to prevent data corruption.`;
-    api.logger.error(errorMsg);
-    throw new Error(errorMsg);
-}
-/**
- * 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 function resolvePluginCommandWorkspaceDir(ctx, source) {
-    // 1. Canonical workspaceDir field (set by OpenClaw command dispatcher)
-    if (ctx.workspaceDir) {
-        const issue = validateWorkspaceDir(ctx.workspaceDir);
-        if (!issue)
-            return ctx.workspaceDir;
-        throw new Error(`[PD:Command:${source}] ctx.workspaceDir="${ctx.workspaceDir}" is invalid: ${issue}`);
-    }
-    // 2. Dispatcher may also put workspaceDir in config (legacy/alternative path)
-    const configWorkspaceDir = ctx.config?.workspaceDir;
-    if (configWorkspaceDir) {
-        const issue = validateWorkspaceDir(configWorkspaceDir);
-        if (!issue)
-            return configWorkspaceDir;
-        throw new Error(`[PD:Command:${source}] ctx.config.workspaceDir="${configWorkspaceDir}" is invalid: ${issue}`);
-    }
-    // CRITICAL FAILURE: No workspace directory available
-    throw new Error(`[PD:Command:${source}] CRITICAL: workspaceDir is not set in ctx.workspaceDir or ctx.config.workspaceDir. ` +
-        `Commands cannot execute without a valid workspace. Set OPENCLAW_WORKSPACE_DIR env var or ensure the workspace is properly initialized.`);
-}
-const PD_CONFIG_FILENAME = 'principles-disciple.json';
-function loadWorkspaceFromPdConfigFile() {
-    const candidates = [
-        path.join(os.homedir(), '.openclaw', PD_CONFIG_FILENAME),
-        path.join(os.homedir(), '.principles', PD_CONFIG_FILENAME),
-        path.join(process.cwd(), PD_CONFIG_FILENAME),
-    ];
-    for (const configPath of candidates) {
-        if (!fs.existsSync(configPath))
-            continue;
-        try {
-            const raw = fs.readFileSync(configPath, 'utf8');
-            const parsed = JSON.parse(raw);
-            if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                if (Object.hasOwn(parsed, 'workspace')) {
-                    const workspaceValue = parsed['workspace'];
-                    if (typeof workspaceValue === 'string' && workspaceValue.trim()) {
-                        return workspaceValue.trim();
-                    }
-                }
-            }
-        }
-        catch {
-            continue;
-        }
-    }
-    return null;
-}
-export function resolveCanonicalWorkspaceDir() {
-    const pdEnv = process.env.PD_WORKSPACE_DIR;
-    if (pdEnv && pdEnv.trim()) {
-        const dir = path.resolve(pdEnv.trim());
-        if (!validateWorkspaceDir(dir)) {
-            return { workspaceDir: dir, source: 'pd_env' };
-        }
-    }
-    const ocEnv = process.env.OPENCLAW_WORKSPACE;
-    if (ocEnv && ocEnv.trim()) {
-        const dir = path.resolve(ocEnv.trim());
-        if (!validateWorkspaceDir(dir)) {
-            return { workspaceDir: dir, source: 'openclaw_env' };
-        }
-    }
-    const configWorkspace = loadWorkspaceFromPdConfigFile();
-    if (configWorkspace) {
-        const dir = path.resolve(configWorkspace);
-        if (!validateWorkspaceDir(dir)) {
-            return { workspaceDir: dir, source: 'pd_config' };
-        }
-    }
-    const defaultDir = path.join(os.homedir(), '.openclaw', 'workspace');
-    if (!validateWorkspaceDir(defaultDir)) {
-        return { workspaceDir: defaultDir, source: 'pd_default' };
-    }
-    return null;
-}
-/**
- * Resolve only PD explicit sources (env vars + config file), excluding pd_default.
- * Used by hook resolution to ensure ctx.workspaceDir takes priority over the
- * hardcoded default fallback.
- */
-function resolveExplicitPdSources() {
-    const pdEnv = process.env.PD_WORKSPACE_DIR;
-    if (pdEnv && pdEnv.trim()) {
-        const dir = path.resolve(pdEnv.trim());
-        if (!validateWorkspaceDir(dir)) {
-            return { workspaceDir: dir, source: 'pd_env' };
-        }
-    }
-    const ocEnv = process.env.OPENCLAW_WORKSPACE;
-    if (ocEnv && ocEnv.trim()) {
-        const dir = path.resolve(ocEnv.trim());
-        if (!validateWorkspaceDir(dir)) {
-            return { workspaceDir: dir, source: 'openclaw_env' };
-        }
-    }
-    const configWorkspace = loadWorkspaceFromPdConfigFile();
-    if (configWorkspace) {
-        const dir = path.resolve(configWorkspace);
-        if (!validateWorkspaceDir(dir)) {
-            return { workspaceDir: dir, source: 'pd_config' };
-        }
-    }
-    return null;
-}
-function tryResolveFromOpenClawApi(api, agentId) {
-    try {
-        const resolved = api.runtime?.agent?.resolveAgentWorkspaceDir?.(api.config, agentId ?? 'main');
-        if (resolved && !validateWorkspaceDir(resolved)) {
-            return resolved;
-        }
-    }
-    catch {
-        // Fall through
-    }
-    return undefined;
-}
-export function resolveHookWorkspaceDir(ctx, api, source, options) {
-    // Priority 1: PD explicit sources (env vars + config file) — these are
-    // owner-declared and intentionally override the live session context.
-    const resolveExplicit = options?.explicitPdResolver ?? resolveExplicitPdSources;
-    const explicit = resolveExplicit();
-    if (explicit) {
-        let consistencyWarning;
-        if (ctx.workspaceDir) {
-            const normalizedCtx = path.resolve(ctx.workspaceDir);
-            const normalizedExplicit = path.resolve(explicit.workspaceDir);
-            if (normalizedCtx !== normalizedExplicit) {
-                consistencyWarning =
-                    `PD explicit workspace (${explicit.source}: ${explicit.workspaceDir}) ` +
-                        `differs from OpenClaw context (${ctx.workspaceDir}). Using PD explicit.`;
-            }
-        }
-        return {
-            ok: true,
-            workspaceDir: explicit.workspaceDir,
-            source: explicit.source,
-            consistencyWarning,
-        };
-    }
-    // Priority 2: OpenClaw live context — the real session workspace.
-    // This MUST take priority over pd_default (the hardcoded fallback).
-    if (ctx.workspaceDir) {
-        const issue = validateWorkspaceDir(ctx.workspaceDir);
-        if (!issue) {
-            return {
-                ok: true,
-                workspaceDir: ctx.workspaceDir,
-                source: 'openclaw_context',
-            };
-        }
-    }
-    // Priority 3: OpenClaw API resolution
-    const apiResolved = tryResolveFromOpenClawApi(api, ctx.agentId);
-    if (apiResolved) {
-        return {
-            ok: true,
-            workspaceDir: apiResolved,
-            source: 'openclaw_api',
-        };
-    }
-    // Priority 4: pd_default (hardcoded fallback) — only when nothing else works
-    const resolveCanonical = options?.canonicalResolver ?? resolveCanonicalWorkspaceDir;
-    const canonical = resolveCanonical();
-    if (canonical && canonical.source === 'pd_default') {
-        return {
-            ok: true,
-            workspaceDir: canonical.workspaceDir,
-            source: 'pd_default',
-            consistencyWarning: 'Using hardcoded default workspace (~/.openclaw/workspace). ' +
-                'Set PD_WORKSPACE_DIR or create ~/.openclaw/principles-disciple.json for stable resolution.',
-        };
-    }
-    return {
-        ok: false,
-        reason: 'workspace_dir_unresolvable',
-        nextAction: 'Set PD_WORKSPACE_DIR environment variable, create ~/.openclaw/principles-disciple.json ' +
-            'with a "workspace" field, or ensure OpenClaw provides workspaceDir in hook context.',
-        message: `[PD:${source}] Cannot resolve workspace directory from any source. ` +
-            `PD explicit config (PD_WORKSPACE_DIR, principles-disciple.json) ` +
-            `and OpenClaw fallback (ctx.workspaceDir, api.resolveAgentWorkspaceDir, ~/.openclaw/workspace) all failed.`,
-    };
-}
-/**
- * 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 function resolveToolHookWorkspaceDirSafe(ctx, api, source, options) {
-    const result = resolveHookWorkspaceDir(ctx, api, source, options);
-    if (!result.ok) {
-        api.logger.warn(result.message);
-        return undefined;
-    }
-    if (result.consistencyWarning) {
-        api.logger.warn(`[PD:${source}] ${result.consistencyWarning}`);
-    }
-    return result.workspaceDir;
-}
-export class WorkspaceResolutionError extends Error {
-    reason;
-    nextAction;
-    constructor(message, reason, nextAction) {
-        super(message);
-        this.name = 'WorkspaceResolutionError';
-        this.reason = reason;
-        this.nextAction = nextAction;
-    }
-    toJSON() {
-        return {
-            ok: false,
-            reason: this.reason,
-            message: this.message,
-            nextAction: this.nextAction,
-        };
-    }
-}
-export function resolveWorkspaceDirForRuntimeV2(ctx, api, source) {
-    const explicit = ctx.workspaceDir;
-    if (!explicit || !explicit.trim()) {
-        throw new WorkspaceResolutionError(`No explicit workspace directory for Runtime V2 entrypoint (${source}). ` +
-            'Provide workspaceDir in context. Runtime V2 does not use legacy discovery fallback.', 'workspace_dir_missing', 'Ensure the OpenClaw hook context includes workspaceDir, or set PD_WORKSPACE_DIR environment variable.');
-    }
-    const normalized = path.resolve(explicit.trim());
-    const validation = validateWorkspaceDir(normalized);
-    if (validation) {
-        throw new WorkspaceResolutionError(`workspaceDir validation failed for ${source}: ${validation}`, 'workspace_dir_invalid', 'Provide a valid workspaceDir that is not the home directory, root, or empty.');
-    }
-    return normalized;
-}