@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/graceful-degradation.js

@@ -1 +1,396 @@
-import{ok,err}from"./_deps/shared/index.js";import{createDetailedError}from"./_deps/ux-helpers/index.js";const DEFAULT_CACHE_CONFIG={defaultTTL:3e5,maxSize:1e3,allowStale:!0,maxStaleMs:36e5},DEFAULT_RETRY_CONFIG={maxAttempts:3,initialDelayMs:1e3,backoffMultiplier:2,maxDelayMs:3e4,jitter:!0};export class GracefulDegradationManager{cacheConfig;retryConfig;cache=new Map;serviceStatus=new Map;constructor(e,t){this.cacheConfig={...DEFAULT_CACHE_CONFIG,...e},this.retryConfig={...DEFAULT_RETRY_CONFIG,...t}}getCached(e,t){const r=this.cache.get(e);if(!r)return;const a=Date.now()-r.cachedAt,i=a<=r.ttl,s=a>r.ttl&&a<=this.cacheConfig.maxStaleMs;return"CRITICAL"===t||"HIGH"===t?i?r.value:void 0:this.cacheConfig.allowStale&&(i||s)?(r.usageCount++,r.value):i?r.value:void 0}setCached(e,t,r){if(this.cache.size>=this.cacheConfig.maxSize){const e=this.cache.keys().next().value;e&&this.cache.delete(e)}this.cache.set(e,{value:t,cachedAt:Date.now(),ttl:r??this.cacheConfig.defaultTTL,usageCount:0})}invalidate(e){this.cache.delete(e)}clearCache(){this.cache.clear()}getCacheStats(){const e=Date.now(),t=Array.from(this.cache.entries()).map(([t,r])=>({key:t,age:e-r.cachedAt,usageCount:r.usageCount}));return{size:this.cache.size,maxSize:this.cacheConfig.maxSize,entries:t}}recordSuccess(e){const t=this.serviceStatus.get(e)||{health:"HEALTHY",lastSuccess:0,failureCount:0};t.health="HEALTHY",t.lastSuccess=Date.now(),t.failureCount=0,t.lastError=void 0,this.serviceStatus.set(e,t)}recordFailure(e,t){const r=this.serviceStatus.get(e)||{health:"HEALTHY",lastSuccess:0,failureCount:0};r.failureCount++,r.lastError=t,r.failureCount>=5?r.health="UNAVAILABLE":r.failureCount>=2&&(r.health="DEGRADED"),this.serviceStatus.set(e,r)}getServiceHealth(e){return this.serviceStatus.get(e)?.health??"HEALTHY"}getServiceStatus(e){return this.serviceStatus.get(e)}resetServiceHealth(e){e?this.serviceStatus.delete(e):this.serviceStatus.clear()}async withRetry(e,t){const r=this.getMaxAttempts(t.qos);let a;for(let t=1;t<=r;t++){const i=await e();if(i.ok)return i;if(a=i.error,t<r){const e=this.calculateBackoff(t);await this.sleep(e)}}return err(a)}getMaxAttempts(e){switch(e){case"CRITICAL":case"LOW":return 1;case"HIGH":return this.retryConfig.maxAttempts;case"NORMAL":return Math.max(1,this.retryConfig.maxAttempts-1)}}calculateBackoff(e){const t=this.retryConfig.initialDelayMs*Math.pow(this.retryConfig.backoffMultiplier,e-1),r=Math.min(t,this.retryConfig.maxDelayMs);if(!this.retryConfig.jitter)return r;const a=new Uint8Array(4);crypto.getRandomValues(a);const i=.75+.5*(new DataView(a.buffer).getUint32(0)/4294967295);return Math.floor(r*i)}sleep(e){return new Promise(t=>setTimeout(t,e))}}export async function registryLookupWithFallback(e,t,r,a){const i=`registry:${t}`;if("LOW"===r.qos){const e=a.getCached(i,r.qos);if(e)return ok(e)}const s=await a.withRetry(()=>e.getEntry(t),r);if(s.ok){a.recordSuccess("registry");const e={publicKey:Buffer.from(s.value.publicKey).toString("base64")};return a.setCached(i,e),ok(e)}if(a.recordFailure("registry",String(s.error)),"HIGH"===r.qos||"NORMAL"===r.qos){const e=a.getCached(i,r.qos);if(e)return ok(e)}return err(createDetailedError("REGISTRY_UNAVAILABLE",`Failed to resolve DID: ${t}`,{hint:"UNAVAILABLE"===a.getServiceHealth("registry")?"Registry service is currently unavailable. Using cached data may help.":"Registry lookup failed after retries. Check network connectivity.",suggested_action:"CRITICAL"===r.qos?"Wait for registry service to recover before retrying critical operations.":"Lower QoS level to NORMAL or LOW to use cached data.",docs:"https://private.me/docs/xbind/registry-fallback",severity:"CRITICAL"===r.qos?"critical":"error"}))}export async function sendWithTransportFallback(e,t,r,a,i){if(0===e.length)return err(createDetailedError("NO_TRANSPORT","No transport adapters configured",{hint:"Configure at least one transport adapter for envelope delivery.",suggested_action:"Add HttpsTransportAdapter or custom transport to agent configuration.",docs:"https://private.me/docs/xbind/transport",severity:"critical"}));const s=[];for(let o=0;o<e.length;o++){const c=e[o];if(!c)continue;const n=await i.withRetry(()=>c.send(t,r),a);if(n.ok)return i.recordSuccess(`transport:${o}`),ok(void 0);s.push({transport:o,error:n.error}),i.recordFailure(`transport:${o}`,n.error)}const o=s[0]?.error??"SEND_FAILED";return err(createDetailedError("TRANSPORT_EXHAUSTED",`All transport adapters failed: ${s.map(e=>e.error).join(", ")}`,{hint:"NETWORK_ERROR"===o?"Network connectivity issue detected. Check internet connection.":"TIMEOUT"===o?"Transport timeout occurred. Recipient may be unreachable or overloaded.":"RECIPIENT_UNREACHABLE"===o?"Recipient DID not found or offline.":"Transport layer failure. Check transport configuration.",suggested_action:"Verify recipient endpoint and network connectivity. Consider increasing timeout or adding fallback transports.",docs:"https://private.me/docs/xbind/transport-fallback",severity:"CRITICAL"===a.qos?"critical":"error"}))}export function enhanceError(e,t,r){const a=r.getServiceHealth(t.type.split(":")[0]??"unknown"),i="DEGRADED"===a?" Service is experiencing degraded performance.":"UNAVAILABLE"===a?" Service is currently unavailable.":"",s="CRITICAL"===t.qos?" Consider retrying when service recovers.":"HIGH"===t.qos?" Cached data may be used if available.":" Using cached data regardless of staleness.";return{...e,hint:(e.hint??"")+i+s}}
+/**
+ * @module graceful-degradation
+ * Enhanced Reliability Capabilities for xBind
+ *
+ * Provides graceful degradation mechanisms to maintain service continuity
+ * when external services (registry, gateway, transport) experience issues.
+ *
+ * Features:
+ * - Quality-of-Service (QoS) tiers for operation prioritization
+ * - Fallback mechanisms with exponential backoff
+ * - Intelligent caching with TTL
+ * - User-friendly error messages with actionable recovery hints
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { createDetailedError } from"./_deps/ux-helpers/index.js";
+const DEFAULT_CACHE_CONFIG = {
+    defaultTTL: 300_000, // 5 minutes
+    maxSize: 1000,
+    allowStale: true,
+    maxStaleMs: 3600_000, // 1 hour
+};
+const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 3,
+    initialDelayMs: 1000,
+    backoffMultiplier: 2,
+    maxDelayMs: 30_000,
+    jitter: true,
+};
+/**
+ * Graceful Degradation Manager
+ *
+ * Coordinates fallback mechanisms, caching, and retry logic across
+ * registry, gateway, and transport layers.
+ */
+export class GracefulDegradationManager {
+    cacheConfig;
+    retryConfig;
+    cache = new Map();
+    serviceStatus = new Map();
+    constructor(cacheConfig, retryConfig) {
+        this.cacheConfig = { ...DEFAULT_CACHE_CONFIG, ...cacheConfig };
+        this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...retryConfig };
+    }
+    /* ── Cache Operations ── */
+    /**
+     * Get cached value if available and valid for the given QoS level.
+     *
+     * @param key Cache key
+     * @param qos Quality of service level
+     * @returns Cached value or undefined
+     */
+    getCached(key, qos) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        const now = Date.now();
+        const age = now - entry.cachedAt;
+        const isFresh = age <= entry.ttl;
+        const isStale = age > entry.ttl && age <= this.cacheConfig.maxStaleMs;
+        // CRITICAL/HIGH: Only use fresh cache
+        if (qos === 'CRITICAL' || qos === 'HIGH') {
+            return isFresh ? entry.value : undefined;
+        }
+        // NORMAL/LOW: Use stale cache if allowed
+        if (this.cacheConfig.allowStale && (isFresh || isStale)) {
+            entry.usageCount++;
+            return entry.value;
+        }
+        return isFresh ? entry.value : undefined;
+    }
+    /**
+     * Store value in cache with TTL.
+     *
+     * @param key Cache key
+     * @param value Value to cache
+     * @param ttl Time-to-live in milliseconds (uses default if omitted)
+     */
+    setCached(key, value, ttl) {
+        // Evict oldest entry if cache is full
+        if (this.cache.size >= this.cacheConfig.maxSize) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey)
+                this.cache.delete(oldestKey);
+        }
+        this.cache.set(key, {
+            value,
+            cachedAt: Date.now(),
+            ttl: ttl ?? this.cacheConfig.defaultTTL,
+            usageCount: 0,
+        });
+    }
+    /**
+     * Invalidate cached entry.
+     *
+     * @param key Cache key
+     */
+    invalidate(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Clear all cached entries.
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Get cache statistics.
+     */
+    getCacheStats() {
+        const now = Date.now();
+        const entries = Array.from(this.cache.entries()).map(([key, entry]) => ({
+            key,
+            age: now - entry.cachedAt,
+            usageCount: entry.usageCount,
+        }));
+        return {
+            size: this.cache.size,
+            maxSize: this.cacheConfig.maxSize,
+            entries,
+        };
+    }
+    /* ── Service Health Tracking ── */
+    /**
+     * Record successful operation for a service.
+     *
+     * @param serviceName Service identifier (e.g., 'registry', 'gateway', 'transport')
+     */
+    recordSuccess(serviceName) {
+        const existing = this.serviceStatus.get(serviceName);
+        const status = existing || {
+            health: 'HEALTHY',
+            lastSuccess: 0,
+            failureCount: 0,
+        };
+        status.health = 'HEALTHY';
+        status.lastSuccess = Date.now();
+        status.failureCount = 0;
+        status.lastError = undefined;
+        this.serviceStatus.set(serviceName, status);
+    }
+    /**
+     * Record failed operation for a service.
+     *
+     * @param serviceName Service identifier
+     * @param error Error message
+     */
+    recordFailure(serviceName, error) {
+        const existing = this.serviceStatus.get(serviceName);
+        const status = existing || {
+            health: 'HEALTHY',
+            lastSuccess: 0,
+            failureCount: 0,
+        };
+        status.failureCount++;
+        status.lastError = error;
+        // Update health based on consecutive failures
+        if (status.failureCount >= 5) {
+            status.health = 'UNAVAILABLE';
+        }
+        else if (status.failureCount >= 2) {
+            status.health = 'DEGRADED';
+        }
+        this.serviceStatus.set(serviceName, status);
+    }
+    /**
+     * Get service health status.
+     *
+     * @param serviceName Service identifier
+     * @returns Service health status
+     */
+    getServiceHealth(serviceName) {
+        return this.serviceStatus.get(serviceName)?.health ?? 'HEALTHY';
+    }
+    /**
+     * Get detailed service status.
+     *
+     * @param serviceName Service identifier
+     * @returns Service status or undefined if not tracked
+     */
+    getServiceStatus(serviceName) {
+        return this.serviceStatus.get(serviceName);
+    }
+    /**
+     * Reset service health tracking.
+     *
+     * @param serviceName Service identifier (all services if omitted)
+     */
+    resetServiceHealth(serviceName) {
+        if (serviceName) {
+            this.serviceStatus.delete(serviceName);
+        }
+        else {
+            this.serviceStatus.clear();
+        }
+    }
+    /* ── Retry Logic ── */
+    /**
+     * Execute operation with retry logic based on QoS level.
+     *
+     * @param operation Async operation to execute
+     * @param context Operation context with QoS level
+     * @returns Result of operation
+     */
+    async withRetry(operation, context) {
+        const maxAttempts = this.getMaxAttempts(context.qos);
+        let lastError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const result = await operation();
+            if (result.ok) {
+                return result;
+            }
+            lastError = result.error;
+            // Don't retry on last attempt
+            if (attempt < maxAttempts) {
+                const delay = this.calculateBackoff(attempt);
+                await this.sleep(delay);
+            }
+        }
+        // All retries exhausted
+        return err(lastError);
+    }
+    /**
+     * Get maximum retry attempts for QoS level.
+     */
+    getMaxAttempts(qos) {
+        switch (qos) {
+            case 'CRITICAL':
+                return 1; // Fail fast
+            case 'HIGH':
+                return this.retryConfig.maxAttempts;
+            case 'NORMAL':
+                return Math.max(1, this.retryConfig.maxAttempts - 1);
+            case 'LOW':
+                return 1; // No retries
+        }
+    }
+    /**
+     * Calculate exponential backoff delay with optional jitter.
+     */
+    calculateBackoff(attempt) {
+        const base = this.retryConfig.initialDelayMs * Math.pow(this.retryConfig.backoffMultiplier, attempt - 1);
+        const capped = Math.min(base, this.retryConfig.maxDelayMs);
+        if (!this.retryConfig.jitter) {
+            return capped;
+        }
+        // Add ±25% jitter using cryptographically secure random
+        const randomBytes = new Uint8Array(4);
+        crypto.getRandomValues(randomBytes);
+        const randomValue = new DataView(randomBytes.buffer).getUint32(0) / 0xffffffff;
+        const jitterFactor = 0.75 + randomValue * 0.5;
+        return Math.floor(capped * jitterFactor);
+    }
+    /**
+     * Sleep for specified milliseconds.
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/* ── Registry Fallback ── */
+/**
+ * Registry lookup with graceful degradation.
+ *
+ * Provides intelligent fallback for DID resolution:
+ * 1. Try primary registry lookup
+ * 2. On failure, check cache based on QoS level
+ * 3. Return user-friendly error if all fallbacks exhausted
+ *
+ * @param registry Trust registry instance
+ * @param did DID to resolve
+ * @param context Operation context
+ * @param manager Degradation manager
+ * @returns Registry lookup result
+ */
+export async function registryLookupWithFallback(registry, did, context, manager) {
+    const cacheKey = `registry:${did}`;
+    // Check cache first for LOW QoS
+    if (context.qos === 'LOW') {
+        const cached = manager.getCached(cacheKey, context.qos);
+        if (cached) {
+            return ok(cached);
+        }
+    }
+    // Attempt registry lookup with retry
+    const lookupResult = await manager.withRetry(() => registry.getEntry(did), context);
+    if (lookupResult.ok) {
+        manager.recordSuccess('registry');
+        // Convert Uint8Array publicKey to base64 string for caching
+        const publicKeyStr = Buffer.from(lookupResult.value.publicKey).toString('base64');
+        const entryValue = { publicKey: publicKeyStr };
+        manager.setCached(cacheKey, entryValue);
+        return ok(entryValue);
+    }
+    // Lookup failed - record failure
+    manager.recordFailure('registry', String(lookupResult.error));
+    // Try cache fallback for HIGH/NORMAL QoS
+    if (context.qos === 'HIGH' || context.qos === 'NORMAL') {
+        const cached = manager.getCached(cacheKey, context.qos);
+        if (cached) {
+            return ok(cached);
+        }
+    }
+    // All fallbacks exhausted - return detailed error
+    return err(createDetailedError('REGISTRY_UNAVAILABLE', `Failed to resolve DID: ${did}`, {
+        hint: manager.getServiceHealth('registry') === 'UNAVAILABLE'
+            ? 'Registry service is currently unavailable. Using cached data may help.'
+            : 'Registry lookup failed after retries. Check network connectivity.',
+        suggested_action: context.qos === 'CRITICAL'
+            ? 'Wait for registry service to recover before retrying critical operations.'
+            : 'Lower QoS level to NORMAL or LOW to use cached data.',
+        docs: 'https://private.me/docs/xbind/registry-fallback',
+        severity: context.qos === 'CRITICAL' ? 'critical' : 'error',
+    }));
+}
+/* ── Transport Fallback ── */
+/**
+ * Send envelope with transport fallback.
+ *
+ * Tries multiple transports in order until one succeeds:
+ * 1. Primary transport with retry
+ * 2. Fallback transports (if configured)
+ * 3. Return detailed error if all transports fail
+ *
+ * @param transports Array of transport adapters
+ * @param envelope Envelope to send
+ * @param recipientDid Recipient DID
+ * @param context Operation context
+ * @param manager Degradation manager
+ * @returns Send result
+ */
+export async function sendWithTransportFallback(transports, envelope, recipientDid, context, manager) {
+    if (transports.length === 0) {
+        return err(createDetailedError('NO_TRANSPORT', 'No transport adapters configured', {
+            hint: 'Configure at least one transport adapter for envelope delivery.',
+            suggested_action: 'Add HttpsTransportAdapter or custom transport to agent configuration.',
+            docs: 'https://private.me/docs/xbind/transport',
+            severity: 'critical',
+        }));
+    }
+    const errors = [];
+    for (let i = 0; i < transports.length; i++) {
+        const transport = transports[i];
+        if (!transport)
+            continue;
+        const sendResult = await manager.withRetry(() => transport.send(envelope, recipientDid), context);
+        if (sendResult.ok) {
+            manager.recordSuccess(`transport:${i}`);
+            return ok(undefined);
+        }
+        // Record failure and try next transport
+        errors.push({ transport: i, error: sendResult.error });
+        manager.recordFailure(`transport:${i}`, sendResult.error);
+    }
+    // All transports failed
+    const primaryError = errors[0]?.error ?? 'SEND_FAILED';
+    return err(createDetailedError('TRANSPORT_EXHAUSTED', `All transport adapters failed: ${errors.map(e => e.error).join(', ')}`, {
+        hint: primaryError === 'NETWORK_ERROR'
+            ? 'Network connectivity issue detected. Check internet connection.'
+            : primaryError === 'TIMEOUT'
+                ? 'Transport timeout occurred. Recipient may be unreachable or overloaded.'
+                : primaryError === 'RECIPIENT_UNREACHABLE'
+                    ? 'Recipient DID not found or offline.'
+                    : 'Transport layer failure. Check transport configuration.',
+        suggested_action: 'Verify recipient endpoint and network connectivity. Consider increasing timeout or adding fallback transports.',
+        docs: 'https://private.me/docs/xbind/transport-fallback',
+        severity: context.qos === 'CRITICAL' ? 'critical' : 'error',
+    }));
+}
+/* ── User-Friendly Error Messages ── */
+/**
+ * Enhance error with QoS-appropriate messaging.
+ *
+ * @param error Original error
+ * @param context Operation context
+ * @param manager Degradation manager
+ * @returns Enhanced error with actionable hints
+ */
+export function enhanceError(error, context, manager) {
+    const serviceHealth = manager.getServiceHealth(context.type.split(':')[0] ?? 'unknown');
+    // Add service health context to hint
+    const healthHint = serviceHealth === 'DEGRADED'
+        ? ' Service is experiencing degraded performance.'
+        : serviceHealth === 'UNAVAILABLE'
+            ? ' Service is currently unavailable.'
+            : '';
+    // Add QoS-specific suggestions
+    const qosHint = context.qos === 'CRITICAL'
+        ? ' Consider retrying when service recovers.'
+        : context.qos === 'HIGH'
+            ? ' Cached data may be used if available.'
+            : ' Using cached data regardless of staleness.';
+    return {
+        ...error,
+        hint: (error.hint ?? '') + healthHint + qosHint,
+    };
+}

package/dist-standalone/guardrails.js

@@ -1 +1,216 @@
-export class PolicyDenied extends Error{rule;allowed;requested;suggestion;details;constructor(e,t,o,i,l){super(`Policy violation: ${e}`),this.rule=e,this.allowed=t,this.requested=o,this.suggestion=i,this.details=l,this.name="PolicyDenied"}toAgentFormat(){return[`POLICY_VIOLATION: ${this.rule}`,`REQUESTED: ${JSON.stringify(this.requested)}`,`ALLOWED: ${JSON.stringify(this.allowed)}`,`SUGGESTION: ${this.suggestion}`].join("\n")}toUserFormat(){return[`❌ Policy Violation: ${this.rule}`,"",`You requested: ${this.formatValue(this.requested)}`,`Policy allows: ${this.formatValue(this.allowed)}`,"",`💡 Suggestion: ${this.suggestion}`].join("\n")}toLogFormat(){return{error:"PolicyDenied",rule:this.rule,allowed:this.allowed,requested:this.requested,suggestion:this.suggestion,details:this.details,timestamp:(new Date).toISOString()}}formatValue(e){return"number"==typeof e?this.rule.includes("amount")||this.rule.includes("Amount")?`$${e.toLocaleString()}`:e.toLocaleString():Array.isArray(e)?e.map(e=>`"${String(e)}"`).join(", "):JSON.stringify(e)}}export class Guardrails{static amountExceeded(e){let t,o;switch(e.type){case"per-transaction":t="maxAmount",o=`Reduce amount to $${e.limit.toLocaleString()} or request policy update from admin`;break;case"daily":t="dailyAmount",o=`Reduce amount to stay within daily limit of $${e.limit.toLocaleString()}, or wait until tomorrow`;break;case"monthly":t="monthlyAmount",o=`Reduce amount to stay within monthly limit of $${e.limit.toLocaleString()}, or wait until next month`}return new PolicyDenied(t,e.limit,e.requested,o)}static rateLimitExceeded(e){const t=e.windowMs/1e3,o=t>=60?`Wait ${Math.ceil(t/60)} minutes before making additional calls`:`Wait ${t} seconds before making additional calls`;return new PolicyDenied("callsPerMinute",e.limit,e.current+1,o)}static toolDenied(e){const[t]=e.tool.split(":"),o=0===e.allowed.length?`No tools are currently allowed. Request approval from admin to enable "${e.tool}"`:`Request approval from admin to add "${e.tool}" or "${t}:*" to allowed tools`;return new PolicyDenied("allowedTools",e.allowed,e.tool,o)}static scopeDenied(e){const t=0===e.allowed.length?`No scopes are currently allowed. Request approval from admin to enable "${e.scope}"`:`Request approval from admin to add "${e.scope}" to allowed scopes`;return new PolicyDenied("allowedScopes",e.allowed,e.scope,t)}static fieldDenied(e){const t=`Field "${e.field}" is restricted. Contact admin to update policy.fieldFilters for "${e.tool}"`;return new PolicyDenied("fieldFilters",e.allowed,e.field,t)}static timeWindowDenied(e){const t=`Actions are only allowed between ${e.allowedStart} and ${e.allowedEnd}. Current time is ${e.current.toTimeString()}`;return new PolicyDenied("timeWindow",`${e.allowedStart} - ${e.allowedEnd}`,e.current.toTimeString(),t)}static custom(e){return new PolicyDenied(e.rule,e.allowed,e.requested,e.suggestion)}}export function extractSuggestion(e){return e.fix??"Contact administrator to update policy"}export function toPolicyDenied(e){let t;switch(e.constraint){case"amountPerTxn":t="maxAmount";break;case"dailyAmount":t="dailyAmount";break;case"callsPerMinute":t="callsPerMinute";break;case"scope":t="allowedScopes";break;case"tool":t="allowedTools";break;default:t=String(e.constraint)}return new PolicyDenied(t,e.allowed,e.requested,e.fix,e)}
+/**
+ * @module guardrails
+ * Enhanced error messages with actionable suggestions for policy violations
+ *
+ * When policies deny requests, guardrails provide specific, actionable
+ * guidance on how to fix the issue or what to request from admins.
+ */
+/**
+ * Policy violation error with actionable suggestions
+ */
+export class PolicyDenied extends Error {
+    rule;
+    allowed;
+    requested;
+    suggestion;
+    details;
+    constructor(
+    /** Which policy rule was violated */
+    rule, 
+    /** What the policy allows */
+    allowed, 
+    /** What was requested */
+    requested, 
+    /** Actionable suggestion for how to fix */
+    suggestion, 
+    /** Full policy violation details */
+    details) {
+        super(`Policy violation: ${rule}`);
+        this.rule = rule;
+        this.allowed = allowed;
+        this.requested = requested;
+        this.suggestion = suggestion;
+        this.details = details;
+        this.name = 'PolicyDenied';
+    }
+    /**
+     * Format error for AI agent consumption
+     *
+     * Structured format optimized for LLM parsing
+     */
+    toAgentFormat() {
+        return [
+            `POLICY_VIOLATION: ${this.rule}`,
+            `REQUESTED: ${JSON.stringify(this.requested)}`,
+            `ALLOWED: ${JSON.stringify(this.allowed)}`,
+            `SUGGESTION: ${this.suggestion}`,
+        ].join('\n');
+    }
+    /**
+     * Format error for human consumption
+     *
+     * User-friendly format with clear next steps
+     */
+    toUserFormat() {
+        return [
+            `❌ Policy Violation: ${this.rule}`,
+            '',
+            `You requested: ${this.formatValue(this.requested)}`,
+            `Policy allows: ${this.formatValue(this.allowed)}`,
+            '',
+            `💡 Suggestion: ${this.suggestion}`,
+        ].join('\n');
+    }
+    /**
+     * Format error for logs (structured JSON)
+     */
+    toLogFormat() {
+        return {
+            error: 'PolicyDenied',
+            rule: this.rule,
+            allowed: this.allowed,
+            requested: this.requested,
+            suggestion: this.suggestion,
+            details: this.details,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    formatValue(value) {
+        if (typeof value === 'number') {
+            // Format currency if it looks like money
+            if (this.rule.includes('amount') || this.rule.includes('Amount')) {
+                return `$${value.toLocaleString()}`;
+            }
+            return value.toLocaleString();
+        }
+        if (Array.isArray(value)) {
+            return value.map((v) => `"${String(v)}"`).join(', ');
+        }
+        return JSON.stringify(value);
+    }
+}
+/**
+ * Guardrail builder - fluent API for creating policy errors with suggestions
+ *
+ * @example
+ * ```typescript
+ * const error = Guardrails.amountExceeded({
+ *   requested: 5000,
+ *   limit: 1000,
+ *   type: 'per-transaction'
+ * });
+ *
+ * throw error;
+ * // ❌ Policy Violation: maxAmount
+ * // You requested: $5,000
+ * // Policy allows: $1,000
+ * // 💡 Suggestion: Reduce amount to $1,000 or request policy update from admin
+ * ```
+ */
+export class Guardrails {
+    /**
+     * Amount exceeded (per-transaction limit)
+     */
+    static amountExceeded(options) {
+        let rule;
+        let suggestion;
+        switch (options.type) {
+            case 'per-transaction':
+                rule = 'maxAmount';
+                suggestion = `Reduce amount to $${options.limit.toLocaleString()} or request policy update from admin`;
+                break;
+            case 'daily':
+                rule = 'dailyAmount';
+                suggestion = `Reduce amount to stay within daily limit of $${options.limit.toLocaleString()}, or wait until tomorrow`;
+                break;
+            case 'monthly':
+                rule = 'monthlyAmount';
+                suggestion = `Reduce amount to stay within monthly limit of $${options.limit.toLocaleString()}, or wait until next month`;
+                break;
+        }
+        return new PolicyDenied(rule, options.limit, options.requested, suggestion);
+    }
+    /**
+     * Rate limit exceeded
+     */
+    static rateLimitExceeded(options) {
+        const windowSec = options.windowMs / 1000;
+        const suggestion = windowSec >= 60
+            ? `Wait ${Math.ceil(windowSec / 60)} minutes before making additional calls`
+            : `Wait ${windowSec} seconds before making additional calls`;
+        return new PolicyDenied('callsPerMinute', options.limit, options.current + 1, suggestion);
+    }
+    /**
+     * Tool not allowed
+     */
+    static toolDenied(options) {
+        const [service] = options.tool.split(':');
+        const suggestion = options.allowed.length === 0
+            ? `No tools are currently allowed. Request approval from admin to enable "${options.tool}"`
+            : `Request approval from admin to add "${options.tool}" or "${service}:*" to allowed tools`;
+        return new PolicyDenied('allowedTools', options.allowed, options.tool, suggestion);
+    }
+    /**
+     * Scope not allowed
+     */
+    static scopeDenied(options) {
+        const suggestion = options.allowed.length === 0
+            ? `No scopes are currently allowed. Request approval from admin to enable "${options.scope}"`
+            : `Request approval from admin to add "${options.scope}" to allowed scopes`;
+        return new PolicyDenied('allowedScopes', options.allowed, options.scope, suggestion);
+    }
+    /**
+     * Field filter denied (data access restriction)
+     */
+    static fieldDenied(options) {
+        const suggestion = `Field "${options.field}" is restricted. Contact admin to update policy.fieldFilters for "${options.tool}"`;
+        return new PolicyDenied('fieldFilters', options.allowed, options.field, suggestion);
+    }
+    /**
+     * Time window restriction
+     */
+    static timeWindowDenied(options) {
+        const suggestion = `Actions are only allowed between ${options.allowedStart} and ${options.allowedEnd}. Current time is ${options.current.toTimeString()}`;
+        return new PolicyDenied('timeWindow', `${options.allowedStart} - ${options.allowedEnd}`, options.current.toTimeString(), suggestion);
+    }
+    /**
+     * Generic policy violation
+     */
+    static custom(options) {
+        return new PolicyDenied(options.rule, options.allowed, options.requested, options.suggestion);
+    }
+}
+/**
+ * Helper: Extract actionable suggestion from AgentError details
+ *
+ * Used by agent.call() to convert PolicyViolationDetails into PolicyDenied
+ */
+export function extractSuggestion(details) {
+    return details.fix ?? 'Contact administrator to update policy';
+}
+/**
+ * Helper: Convert PolicyViolationDetails to PolicyDenied
+ */
+export function toPolicyDenied(details) {
+    let rule;
+    switch (details.constraint) {
+        case 'amountPerTxn':
+            rule = 'maxAmount';
+            break;
+        case 'dailyAmount':
+            rule = 'dailyAmount';
+            break;
+        case 'callsPerMinute':
+            rule = 'callsPerMinute';
+            break;
+        case 'scope':
+            rule = 'allowedScopes';
+            break;
+        case 'tool':
+            rule = 'allowedTools';
+            break;
+        default:
+            rule = String(details.constraint);
+    }
+    return new PolicyDenied(rule, details.allowed, details.requested, details.fix, details);
+}