@trenchwork/coder 1.3.0

package/dist/core/guardrails.js

@@ -0,0 +1,361 @@
+/**
+ * Runtime Guardrails for Revenue Suite
+ * Enforces citations, approvals, and audit logging as per manifest requirements
+ */
+import { reportStatusError } from '../utils/statusReporter.js';
+/**
+ * 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) {
+                reportStatusError(error, 'Failed to send audit log to observability endpoint');
+                // 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/hitl.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Human-in-the-Loop (HITL) System
+ * Pauses AI execution and prompts users for important decision paths
+ * This is the ONLY HITL system in the repository
+ */
+import { EventEmitter } from 'node:events';
+/**
+ * Module-level event bus that fires when a HITL prompt opens or closes. Other
+ * subsystems subscribe to:
+ *   - pause their own run-timeouts so user think-time doesn't abort the agent
+ *     (see AgentController),
+ *   - hand the terminal off cleanly so the prompt and post-prompt I/O don't
+ *     fight (see UnifiedUIRenderer / interactiveShell).
+ *
+ * Always paired: every `prompt-open` is followed by exactly one `prompt-close`,
+ * including on timeout, Ctrl+C, custom-input, and shutdown paths.
+ */
+export declare const hitlEvents: EventEmitter<any>;
+export declare function isHITLPromptActive(): boolean;
+export interface DecisionOption {
+    id: string;
+    label: string;
+    description: string;
+    shortcut?: string;
+}
+export interface DecisionRequest {
+    id: string;
+    title: string;
+    description: string;
+    context: string;
+    options: DecisionOption[];
+    defaultOptionId?: string;
+    requiresExplicitChoice: boolean;
+    metadata?: Record<string, any>;
+}
+export interface DecisionResponse {
+    requestId: string;
+    selectedOptionId: string;
+    userInput?: string;
+    timestamp: Date;
+}
+export interface HITLConfig {
+    /**
+     * Whether to automatically pause execution for decisions
+     * If false, decisions will be logged but execution continues
+     */
+    autoPause: boolean;
+    /**
+     * Timeout in milliseconds before auto-proceeding with default
+     * 0 means no timeout (wait indefinitely)
+     */
+    timeoutMs: number;
+    /**
+     * Default option to choose if timeout occurs
+     */
+    timeoutDefaultOptionId?: string;
+    /**
+     * Log level: 'none' | 'minimal' | 'detailed'
+     */
+    logLevel: 'none' | 'minimal' | 'detailed';
+}
+export declare class HITLSystem {
+    private config;
+    private pendingDecisions;
+    private decisionHistory;
+    private rl?;
+    constructor(config?: Partial<HITLConfig>);
+    /**
+     * Request a human decision
+     * @returns Promise that resolves with the selected option ID
+     */
+    requestDecision(request: DecisionRequest): Promise<string>;
+    /**
+     * Present decision to user and wait for input using interactive arrow-key selection
+     */
+    private promptUserForDecision;
+    private cleanupReadline;
+    private getOptionLabel;
+    private logDecisionRequest;
+    private recordDecision;
+    /**
+     * Get decision history
+     */
+    getHistory(): DecisionResponse[];
+    /**
+     * Clear decision history
+     */
+    clearHistory(): void;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<HITLConfig>): void;
+}
+/**
+ * Get the global HITL instance
+ */
+export declare function getHITL(config?: Partial<HITLConfig>): HITLSystem;
+/**
+ * Helper function for common decision patterns
+ */
+export declare const hitl: {
+    /**
+     * Request a yes/no decision
+     */
+    askYesNo(title: string, description: string, context?: string, defaultYes?: boolean): Promise<boolean>;
+    /**
+     * Request selection from multiple options
+     */
+    selectOption(title: string, description: string, options: Array<{
+        id: string;
+        label: string;
+        description: string;
+    }>, context?: string, defaultOptionId?: string): Promise<string>;
+    /**
+     * Request approval for a risky operation
+     */
+    requestApproval(title: string, riskDescription: string, operationDetails: string): Promise<boolean>;
+};
+//# sourceMappingURL=hitl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.d.ts","sourceRoot":"","sources":["../../src/core/hitl.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,mBAAqB,CAAC;AAK7C,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;CAC3C;AAQD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,gBAAgB,CAA2C;IACnE,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,EAAE,CAAC,CAAqB;gBAEpB,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC;IASxC;;;OAGG;IACG,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAoChE;;OAEG;YACW,qBAAqB;IA6LnC,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,cAAc;IAmBtB;;OAEG;IACH,UAAU,IAAI,gBAAgB,EAAE;IAIhC;;OAEG;IACH,YAAY,IAAI,IAAI;IAIpB;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;CAGhD;AAKD;;GAEG;AACH,wBAAgB,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAUhE;AAED;;GAEG;AACH,eAAO,MAAM,IAAI;IACf;;OAEG;oBACmB,MAAM,eAAe,MAAM,YAAW,MAAM,eAAmB,OAAO,GAAU,OAAO,CAAC,OAAO,CAAC;IA6BtH;;OAEG;wBACuB,MAAM,eAAe,MAAM,WAAW,KAAK,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAAC,YAAW,MAAM,oBAAyB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBzL;;OAEG;2BAC0B,MAAM,mBAAmB,MAAM,oBAAoB,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAQ1G,CAAC"}