deepseek-coder-agent-cli 1.0.0

package/dist/core/guardrails.js

@@ -0,0 +1,360 @@
+/**
+ * Runtime Guardrails for Revenue Suite
+ * Enforces citations, approvals, and audit logging as per manifest requirements
+ */
+/**
+ * Citation Validator
+ * Ensures every claim has proper source attribution
+ */
+export class CitationValidator {
+    /**
+     * Validates that a response includes proper citations
+     */
+    validateCitations(response, citations) {
+        if (citations.length === 0) {
+            return {
+                valid: false,
+                coverage: 0,
+                missing: ['No citations provided']
+            };
+        }
+        // Check for citation markers in response (e.g., [1], [Source: ...])
+        const citationMarkers = response.match(/\[(\d+|Source:.*?)\]/g) || [];
+        // Check for factual claims without citations
+        const claimPatterns = [
+            /\b(according to|as stated in|referenced in|cited in)\b/gi,
+            /\b(our policy|our documentation|our guide)\b/gi
+        ];
+        const hasClaimMarkers = claimPatterns.some(pattern => pattern.test(response));
+        const hasCitations = citations.length > 0;
+        if (hasClaimMarkers && !hasCitations) {
+            return {
+                valid: false,
+                coverage: 0,
+                missing: ['Claims detected but no citations provided']
+            };
+        }
+        // Basic validation: ensure citations have required fields
+        const invalidCitations = citations.filter(c => !c.sourceDoc);
+        if (invalidCitations.length > 0) {
+            return {
+                valid: false,
+                coverage: (citations.length - invalidCitations.length) / citations.length * 100,
+                missing: invalidCitations.map((_, i) => `Citation ${i + 1} missing sourceDoc`)
+            };
+        }
+        // All validations passed
+        return {
+            valid: true,
+            coverage: 100,
+            missing: []
+        };
+    }
+    /**
+     * Extracts citations from structured response
+     */
+    extractCitations(response) {
+        if (typeof response === 'string') {
+            // Parse citations from markdown-style references
+            const citations = [];
+            const citationRegex = /\[Source:\s*([^\]]+)\]/g;
+            let match;
+            while ((match = citationRegex.exec(response)) !== null) {
+                const parts = match[1].split(',').map(p => p.trim());
+                citations.push({
+                    sourceDoc: parts[0],
+                    section: parts[1],
+                    version: parts[2]
+                });
+            }
+            return citations;
+        }
+        // Handle structured response with citations array
+        if (response && Array.isArray(response.citations)) {
+            return response.citations;
+        }
+        return [];
+    }
+}
+/**
+ * Approval Manager
+ * Handles human-in-the-loop approval workflows
+ */
+export class ApprovalManager {
+    pendingApprovals = new Map();
+    approvalHistory = new Map();
+    /**
+     * Request approval for a high-risk action
+     */
+    async requestApproval(actionType, actionDescription, riskLevel, requiredApprover, context) {
+        const request = {
+            id: `APPROVAL-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+            actionType,
+            actionDescription,
+            riskLevel,
+            requiredApprover,
+            context,
+            requestedAt: new Date()
+        };
+        this.pendingApprovals.set(request.id, request);
+        // Send notification to approver (email, Slack, webhook, etc.)
+        console.log(`⚠️  Approval required: ${actionDescription}`);
+        console.log(`   Approver: ${requiredApprover}`);
+        console.log(`   Risk Level: ${riskLevel}`);
+        console.log(`   Approval ID: ${request.id}`);
+        // TODO: Implement actual notification system (email, Slack, webhook)
+        return request;
+    }
+    /**
+     * Record an approval response
+     */
+    async recordApproval(response) {
+        this.approvalHistory.set(response.requestId, response);
+        this.pendingApprovals.delete(response.requestId);
+    }
+    /**
+     * Check if an action requires approval based on policy
+     */
+    requiresApproval(actionType, actionContext) {
+        // Define approval policies
+        const policies = [
+            {
+                condition: (type, ctx) => type === 'refund' && ctx.amount > 50000,
+                approver: 'finance_director',
+                riskLevel: 'high'
+            },
+            {
+                condition: (type, ctx) => type === 'contract_edit',
+                approver: 'legal_counsel',
+                riskLevel: 'critical'
+            },
+            {
+                condition: (type, ctx) => type === 'crm_update' && ctx.dealValue > 100000,
+                approver: 'sales_director',
+                riskLevel: 'medium'
+            },
+            {
+                condition: (type, ctx) => type === 'data_export' && ctx.pii === true,
+                approver: 'compliance_officer',
+                riskLevel: 'high'
+            }
+        ];
+        const matchedPolicy = policies.find(p => p.condition(actionType, actionContext));
+        if (matchedPolicy) {
+            return {
+                required: true,
+                approver: matchedPolicy.approver,
+                riskLevel: matchedPolicy.riskLevel
+            };
+        }
+        return { required: false };
+    }
+    /**
+     * Get pending approval by ID
+     */
+    getPendingApproval(id) {
+        return this.pendingApprovals.get(id);
+    }
+    /**
+     * Get approval status
+     */
+    getApprovalStatus(id) {
+        return this.approvalHistory.get(id);
+    }
+}
+/**
+ * Audit Logger
+ * Logs all actions with inputs, outputs, and correlation IDs
+ */
+export class AuditLogger {
+    logs = [];
+    observabilityEndpoint;
+    constructor(observabilityEndpoint) {
+        this.observabilityEndpoint = observabilityEndpoint || process.env.OBSERVABILITY_ENDPOINT;
+    }
+    /**
+     * Log an action with full context
+     */
+    async logAction(entry) {
+        const fullEntry = {
+            ...entry,
+            id: `AUDIT-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+            timestamp: new Date()
+        };
+        // Redact PII from logs
+        const redactedEntry = this.redactPII(fullEntry);
+        // Store locally
+        this.logs.push(redactedEntry);
+        // Send to observability endpoint if configured
+        if (this.observabilityEndpoint) {
+            try {
+                await this.sendToObservability(redactedEntry);
+            }
+            catch (error) {
+                console.error('Failed to send audit log to observability endpoint:', error);
+                // Continue - don't fail the action if logging fails
+            }
+        }
+        // Also log to console for development
+        console.log(`[AUDIT] ${redactedEntry.actionType}: ${redactedEntry.status}`);
+        return fullEntry.id;
+    }
+    /**
+     * Redact PII from audit logs
+     */
+    redactPII(entry) {
+        const piiPatterns = [
+            { regex: /\b\d{3}-\d{2}-\d{4}\b/g, replacement: 'SSN-REDACTED' }, // SSN
+            { regex: /\b\d{16}\b/g, replacement: 'CC-REDACTED' }, // Credit card
+            { regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g, replacement: 'EMAIL-REDACTED' } // Email (optional)
+        ];
+        const redactedEntry = { ...entry };
+        // Redact inputs
+        if (entry.inputs) {
+            const inputsStr = JSON.stringify(entry.inputs);
+            let redactedStr = inputsStr;
+            for (const pattern of piiPatterns) {
+                redactedStr = redactedStr.replace(pattern.regex, pattern.replacement);
+            }
+            redactedEntry.inputs = JSON.parse(redactedStr);
+        }
+        // Redact outputs
+        if (entry.outputs) {
+            const outputsStr = JSON.stringify(entry.outputs);
+            let redactedStr = outputsStr;
+            for (const pattern of piiPatterns) {
+                redactedStr = redactedStr.replace(pattern.regex, pattern.replacement);
+            }
+            redactedEntry.outputs = JSON.parse(redactedStr);
+        }
+        return redactedEntry;
+    }
+    /**
+     * Send audit log to external observability system
+     */
+    async sendToObservability(entry) {
+        if (!this.observabilityEndpoint) {
+            return;
+        }
+        // TODO: Implement actual HTTP POST to observability endpoint
+        // Use fetch or axios
+        console.log(`Sending audit log to ${this.observabilityEndpoint}:`, entry.id);
+        // Example implementation:
+        // await fetch(this.observabilityEndpoint, {
+        //   method: 'POST',
+        //   headers: { 'Content-Type': 'application/json' },
+        //   body: JSON.stringify(entry)
+        // });
+    }
+    /**
+     * Query audit logs by correlation ID
+     */
+    getLogsByCorrelationId(correlationId) {
+        return this.logs.filter(log => log.correlationId === correlationId);
+    }
+    /**
+     * Query audit logs by user ID
+     */
+    getLogsByUserId(userId) {
+        return this.logs.filter(log => log.userId === userId);
+    }
+    /**
+     * Get all logs (for testing/debugging)
+     */
+    getAllLogs() {
+        return [...this.logs];
+    }
+}
+/**
+ * Guardrails Orchestrator
+ * Coordinates citation validation, approval flows, and audit logging
+ */
+export class GuardrailsOrchestrator {
+    citationValidator;
+    approvalManager;
+    auditLogger;
+    constructor(observabilityEndpoint) {
+        this.citationValidator = new CitationValidator();
+        this.approvalManager = new ApprovalManager();
+        this.auditLogger = new AuditLogger(observabilityEndpoint);
+    }
+    getCitationValidator() {
+        return this.citationValidator;
+    }
+    getApprovalManager() {
+        return this.approvalManager;
+    }
+    getAuditLogger() {
+        return this.auditLogger;
+    }
+    /**
+     * Execute an action with full guardrail enforcement
+     */
+    async executeWithGuardrails(userId, correlationId, actionType, actionDescription, actionFn, inputs, options = {}) {
+        // 1. Check if approval is required
+        const approvalCheck = this.approvalManager.requiresApproval(actionType, inputs);
+        if (approvalCheck.required) {
+            const approvalRequest = await this.approvalManager.requestApproval(actionType, actionDescription, approvalCheck.riskLevel, approvalCheck.approver, inputs);
+            // TODO: Wait for approval (implement polling or webhook callback)
+            throw new Error(`Action requires approval from ${approvalCheck.approver}. ` +
+                `Approval ID: ${approvalRequest.id}`);
+        }
+        // 2. Validate citations if required
+        if (options.requireCitations) {
+            const citationValidation = this.citationValidator.validateCitations(actionDescription, options.citations || []);
+            if (!citationValidation.valid) {
+                await this.auditLogger.logAction({
+                    correlationId,
+                    userId,
+                    actionType,
+                    actionDescription,
+                    inputs,
+                    status: 'failed',
+                    errorMessage: `Citation validation failed: ${citationValidation.missing.join(', ')}`,
+                    citations: options.citations
+                });
+                throw new Error(`Citation requirement not met: ${citationValidation.missing.join(', ')}`);
+            }
+        }
+        // 3. Execute action with audit logging
+        try {
+            const result = await actionFn();
+            await this.auditLogger.logAction({
+                correlationId,
+                userId,
+                actionType,
+                actionDescription,
+                inputs,
+                outputs: result,
+                citations: options.citations,
+                status: 'success'
+            });
+            return result;
+        }
+        catch (error) {
+            await this.auditLogger.logAction({
+                correlationId,
+                userId,
+                actionType,
+                actionDescription,
+                inputs,
+                status: 'failed',
+                errorMessage: error instanceof Error ? error.message : String(error),
+                citations: options.citations
+            });
+            throw error;
+        }
+    }
+}
+// Singleton instance
+let guardrailsInstance = null;
+/**
+ * Get or create the guardrails orchestrator instance
+ */
+export function getGuardrails(observabilityEndpoint) {
+    if (!guardrailsInstance) {
+        guardrailsInstance = new GuardrailsOrchestrator(observabilityEndpoint);
+    }
+    return guardrailsInstance;
+}
+//# sourceMappingURL=guardrails.js.map

package/dist/core/guardrails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.js","sourceRoot":"","sources":["../../src/core/guardrails.ts"],"names":[],"mappings":"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"}

package/dist/core/hallucinationGuard.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Hallucination Guard - Advanced validation to minimize AI hallucinations
+ *
+ * Features:
+ * 1. Content validation before edits
+ * 2. Fact verification for web search results
+ * 3. Confidence scoring for AI outputs
+ * 4. Cross-referencing with existing knowledge
+ */
+export interface HallucinationCheck {
+    type: 'content_guess' | 'fact_claim' | 'code_pattern' | 'file_existence';
+    confidence: 'high' | 'medium' | 'low';
+    riskLevel: 'critical' | 'warning' | 'info';
+    message: string;
+    suggestion: string;
+}
+export interface HallucinationReport {
+    checks: HallucinationCheck[];
+    overallRisk: 'critical' | 'warning' | 'safe';
+    confidenceScore: number;
+}
+/**
+ * Validate AI content for hallucinations before execution
+ */
+export declare class HallucinationGuard {
+    private readonly workingDir;
+    private readonly knownFacts;
+    constructor(options?: {
+        workingDir?: string;
+    });
+    /**
+     * Validate file operations for hallucinations
+     */
+    validateFileOperation(toolName: string, args: Record<string, unknown>, existingContent?: string): HallucinationReport;
+    /**
+     * Validate AI-generated code for common hallucination patterns
+     */
+    validateGeneratedCode(code: string, _context?: string): HallucinationReport;
+    /**
+     * Register known facts from previous operations to cross-reference
+     */
+    registerFact(fact: string, source: string, confidence: number): void;
+    /**
+     * Check if a claim contradicts known facts
+     */
+    checkFactContradiction(claim: string): HallucinationCheck | null;
+    private calculateContentSimilarity;
+    private isOverlyBroadPattern;
+    private containsFactClaim;
+    private areContradictory;
+    private generateReport;
+}
+/**
+ * Enhanced validation that integrates with existing tool runtime
+ */
+export declare function enhanceWithHallucinationGuard(toolName: string, args: Record<string, unknown>, existingContent?: string): HallucinationReport;
+//# sourceMappingURL=hallucinationGuard.d.ts.map

package/dist/core/hallucinationGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hallucinationGuard.d.ts","sourceRoot":"","sources":["../../src/core/hallucinationGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,eAAe,GAAG,YAAY,GAAG,cAAc,GAAG,gBAAgB,CAAC;IACzE,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,SAAS,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,WAAW,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IAC7C,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;gBAEjD,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;IAIjD;;OAEG;IACH,qBAAqB,CACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,eAAe,CAAC,EAAE,MAAM,GACvB,mBAAmB;IAkEtB;;OAEG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,mBAAmB;IA6C3E;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAKpE;;OAEG;IACH,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAsBhE,OAAO,CAAC,0BAA0B;IAWlC,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,cAAc;CA4CvB;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,eAAe,CAAC,EAAE,MAAM,GACvB,mBAAmB,CAGrB"}

package/dist/core/hallucinationGuard.js

@@ -0,0 +1,237 @@
+/**
+ * Hallucination Guard - Advanced validation to minimize AI hallucinations
+ *
+ * Features:
+ * 1. Content validation before edits
+ * 2. Fact verification for web search results
+ * 3. Confidence scoring for AI outputs
+ * 4. Cross-referencing with existing knowledge
+ */
+import { existsSync } from 'node:fs';
+/**
+ * Validate AI content for hallucinations before execution
+ */
+export class HallucinationGuard {
+    workingDir;
+    knownFacts = new Map();
+    constructor(options = {}) {
+        this.workingDir = options.workingDir ?? process.cwd();
+    }
+    /**
+     * Validate file operations for hallucinations
+     */
+    validateFileOperation(toolName, args, existingContent) {
+        const checks = [];
+        const toolLower = toolName.toLowerCase();
+        // === Edit Tool Validation ===
+        if (toolLower === 'edit') {
+            const oldString = args['old_string'];
+            const filePath = args['file_path'];
+            // Check 1: Edit without existing content reference
+            if (oldString && existingContent) {
+                const similarity = this.calculateContentSimilarity(oldString, existingContent);
+                if (similarity < 0.5) {
+                    checks.push({
+                        type: 'content_guess',
+                        confidence: 'high',
+                        riskLevel: 'critical',
+                        message: `Low content similarity (${Math.round(similarity * 100)}%) - AI may be guessing file content`,
+                        suggestion: 'Verify exact file content matches old_string. Use Read tool to confirm.',
+                    });
+                }
+            }
+            // Check 2: File existence validation
+            if (filePath && !existsSync(filePath) && oldString) {
+                checks.push({
+                    type: 'file_existence',
+                    confidence: 'high',
+                    riskLevel: 'warning',
+                    message: `Editing non-existent file: ${filePath}`,
+                    suggestion: 'Check if file exists before editing. Use empty old_string for new file creation.',
+                });
+            }
+        }
+        // === Search Operations ===
+        if (toolLower.includes('search') || toolLower.includes('grep')) {
+            const pattern = args['pattern'];
+            if (pattern && this.isOverlyBroadPattern(pattern)) {
+                checks.push({
+                    type: 'code_pattern',
+                    confidence: 'medium',
+                    riskLevel: 'warning',
+                    message: `Search pattern '${pattern}' is very broad and may produce overwhelming results`,
+                    suggestion: 'Use more specific patterns or add file type filters.',
+                });
+            }
+        }
+        // === Web Operations ===
+        if (toolLower.includes('web') || toolLower.includes('search')) {
+            const query = args['query'];
+            if (query && this.containsFactClaim(query)) {
+                checks.push({
+                    type: 'fact_claim',
+                    confidence: 'low',
+                    riskLevel: 'info',
+                    message: 'Query contains factual claims that should be verified',
+                    suggestion: 'Cross-reference results with authoritative sources.',
+                });
+            }
+        }
+        return this.generateReport(checks);
+    }
+    /**
+     * Validate AI-generated code for common hallucination patterns
+     */
+    validateGeneratedCode(code, _context) {
+        const checks = [];
+        // Check for placeholder patterns
+        const placeholderPatterns = [
+            /\{\{.*?\}\}/g, // {{variable}}
+            /\[\[.*?\]\]/g, // [[placeholder]]
+            /<TODO>/gi, // <TODO>
+            /FIXME/gi, // FIXME (in generated code)
+        ];
+        for (const pattern of placeholderPatterns) {
+            const matches = code.match(pattern);
+            if (matches) {
+                checks.push({
+                    type: 'content_guess',
+                    confidence: 'high',
+                    riskLevel: 'critical',
+                    message: `Placeholder patterns found in generated code: ${matches.slice(0, 3).join(', ')}`,
+                    suggestion: 'Replace placeholders with actual implementation based on context.',
+                });
+            }
+        }
+        // Check for unrealistic imports
+        const importPatterns = [
+            /import\s+.*\s+from\s+['"][@\w\-/]+['"]/g,
+        ];
+        const imports = code.match(importPatterns[0]) || [];
+        for (const imp of imports) {
+            if (imp.includes('undefined-package') || imp.includes('example-library')) {
+                checks.push({
+                    type: 'code_pattern',
+                    confidence: 'medium',
+                    riskLevel: 'warning',
+                    message: `Suspicious import pattern: ${imp}`,
+                    suggestion: 'Verify package names and availability in the project.',
+                });
+            }
+        }
+        return this.generateReport(checks);
+    }
+    /**
+     * Register known facts from previous operations to cross-reference
+     */
+    registerFact(fact, source, confidence) {
+        const key = `${source}:${fact}`;
+        this.knownFacts.set(key, confidence);
+    }
+    /**
+     * Check if a claim contradicts known facts
+     */
+    checkFactContradiction(claim) {
+        const claimLower = claim.toLowerCase();
+        for (const [key, confidence] of this.knownFacts.entries()) {
+            const [, fact] = key.split(':');
+            const factLower = fact.toLowerCase();
+            // Simple contradiction detection
+            if (this.areContradictory(claimLower, factLower)) {
+                return {
+                    type: 'fact_claim',
+                    confidence: confidence > 0.7 ? 'high' : 'medium',
+                    riskLevel: 'warning',
+                    message: `Claim contradicts previously established fact: ${fact}`,
+                    suggestion: 'Verify information consistency across operations.',
+                };
+            }
+        }
+        return null;
+    }
+    calculateContentSimilarity(a, b) {
+        // Simple similarity calculation for validation
+        const wordsA = new Set(a.toLowerCase().split(/\s+/));
+        const wordsB = new Set(b.toLowerCase().split(/\s+/));
+        const intersection = new Set([...wordsA].filter(x => wordsB.has(x)));
+        const union = new Set([...wordsA, ...wordsB]);
+        return union.size > 0 ? intersection.size / union.size : 0;
+    }
+    isOverlyBroadPattern(pattern) {
+        // Patterns that match everything
+        const broadPatterns = [
+            /^.*$/,
+            /^\.*$/,
+            /^\w*$/,
+            /^[a-zA-Z]*$/,
+        ];
+        return broadPatterns.some(p => p.test(pattern));
+    }
+    containsFactClaim(text) {
+        const factIndicators = [
+            'is', 'are', 'was', 'were', 'will be',
+            'has', 'have', 'had',
+            'can', 'cannot', 'could', 'would',
+            'always', 'never', 'every', 'all',
+            'true', 'false', 'correct', 'incorrect',
+        ];
+        const words = text.toLowerCase().split(/\s+/);
+        return words.some(word => factIndicators.includes(word));
+    }
+    areContradictory(claim, fact) {
+        // Simple contradiction detection
+        const contradictions = [
+            ['is', 'is not'],
+            ['has', 'has no'],
+            ['can', 'cannot'],
+            ['true', 'false'],
+            ['always', 'never'],
+        ];
+        return contradictions.some(([a, b]) => (claim.includes(a) && fact.includes(b)) ||
+            (claim.includes(b) && fact.includes(a)));
+    }
+    generateReport(checks) {
+        if (checks.length === 0) {
+            return {
+                checks: [],
+                overallRisk: 'safe',
+                confidenceScore: 100,
+            };
+        }
+        const riskScores = {
+            'critical': 3,
+            'warning': 2,
+            'info': 1,
+        };
+        const confidenceScores = {
+            'high': 1.0,
+            'medium': 0.7,
+            'low': 0.3,
+        };
+        let totalRisk = 0;
+        let maxRisk = 0;
+        for (const check of checks) {
+            const riskScore = riskScores[check.riskLevel];
+            const confidence = confidenceScores[check.confidence];
+            totalRisk += riskScore * confidence;
+            maxRisk = Math.max(maxRisk, riskScore * confidence);
+        }
+        const averageRisk = totalRisk / checks.length;
+        const overallRisk = averageRisk >= 2.5 ? 'critical' : averageRisk >= 1.5 ? 'warning' : 'safe';
+        // Confidence score: 100 - (risk * 20)
+        const confidenceScore = Math.max(0, Math.min(100, 100 - (averageRisk * 20)));
+        return {
+            checks,
+            overallRisk,
+            confidenceScore,
+        };
+    }
+}
+/**
+ * Enhanced validation that integrates with existing tool runtime
+ */
+export function enhanceWithHallucinationGuard(toolName, args, existingContent) {
+    const guard = new HallucinationGuard();
+    return guard.validateFileOperation(toolName, args, existingContent);
+}
+//# sourceMappingURL=hallucinationGuard.js.map