[FEATURE] Implement Enterprise HITL Features (Documented but Not Implemented)

[murdore]

Problem Statement

Is your feature request related to a problem? Please describe.

The docs/features/enterprise-hitl.md documentation describes comprehensive enterprise HITL (Human-in-the-Loop) features that do not exist in the actual codebase. This creates a significant gap between documented capabilities and actual implementation, potentially misleading users who rely on the documentation.

Current implemented HITLConfig in src/lib/types/hitlTypes.ts:

export type HITLConfig = {
  enabled: boolean;
  dangerousActions: string[];
  timeout?: number;
  confirmationMethod?: "event";
  allowArgumentModification?: boolean;
  autoApproveOnTimeout?: boolean;
  auditLogging?: boolean;
  customRules?: HITLRule[];
};

Documented but NOT implemented features:

• confidenceThreshold - AI confidence threshold for automatic approval
• contentPatterns - RegExp patterns for content-based HITL triggers
• mode - Synchronous vs asynchronous approval workflows
• reviewCallback - Custom callback for review logic
• statusCallback - Callback for checking async review status
• escalationPolicy - Multi-level escalation configuration
• requireApproval - Explicit tool names requiring approval
• Enhanced auditLog with storage backends (file/database/custom)

Proposed Solution

Describe the solution you'd like

Implement the missing enterprise HITL features to match the documentation. The enhanced HITLConfig should support:

1. Confidence Threshold Trigger

confidenceThreshold?: number; // 0-1, trigger review if AI confidence below this

2. Content Pattern Matching

contentPatterns?: RegExp[]; // Patterns that trigger mandatory review

3. Approval Mode

mode?: 'synchronous' | 'asynchronous'; // Blocking vs non-blocking approval

4. Review Callbacks

reviewCallback?: (action: HITLAction, context: HITLContext) => Promise<HITLReviewResult>;
statusCallback?: (reviewId: string) => Promise<HITLReviewStatus>;

5. Escalation Policy

escalationPolicy?: {
  onTimeout: 'approve' | 'reject' | 'escalate';
  escalationLevels?: Array<{
    level: number;
    reviewers: string[];
    timeout: number;
    finalAuthority?: boolean;
  }>;
};

6. Enhanced Audit Logging

auditLog?: {
  enabled: boolean;
  storage: 'file' | 'database' | 'custom';
  path?: string;
  database?: DatabaseConfig;
  customLogger?: (entry: AuditEntry) => Promise<void>;
};

7. Explicit Tool Approval List

requireApproval?: string[]; // Tool names that always require approval

Example Usage

Describe how you would use this feature

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink({
  hitl: {
    enabled: true,
    mode: "synchronous",
    
    // Confidence-based triggers
    confidenceThreshold: 0.85, // Review if AI confidence < 85%
    
    // Content-based triggers
    contentPatterns: [
      /\b\d{3}-\d{2}-\d{4}\b/, // SSN pattern
      /password|secret|token/i, // Sensitive keywords
    ],
    
    // Explicit tool approval
    requireApproval: ["deleteFile", "sendEmail", "executeCode"],
    
    // Review callback
    reviewCallback: async (action, context) => {
      // Custom approval logic (Slack, email, custom UI)
      const approved = await showApprovalDialog(action);
      return {
        approved,
        reason: approved ? "User authorized" : "User denied",
        reviewer: "admin@company.com",
      };
    },
    
    // Escalation for timeouts
    escalationPolicy: {
      onTimeout: "escalate",
      escalationLevels: [
        { level: 1, reviewers: ["team-lead@company.com"], timeout: 300000 },
        { level: 2, reviewers: ["manager@company.com"], timeout: 600000 },
        { level: 3, reviewers: ["cto@company.com"], timeout: 1800000, finalAuthority: true },
      ],
    },
    
    // Enhanced audit logging
    auditLog: {
      enabled: true,
      storage: "database",
      customLogger: async (entry) => {
        await complianceDB.insert("hitl_audit", entry);
      },
    },
    
    // Existing features
    dangerousActions: ["delete", "remove", "drop"],
    timeout: 300000,
    allowArgumentModification: true,
    autoApproveOnTimeout: false,
  },
});

Asynchronous mode example:

const neurolink = new NeuroLink({
  hitl: {
    enabled: true,
    mode: "asynchronous",
    
    reviewCallback: async (action, context) => {
      // Queue for review, return immediately
      const reviewId = await queueForReview(action);
      return {
        pending: true,
        reviewId,
        estimatedTime: 900000, // 15 minutes
      };
    },
    
    statusCallback: async (reviewId) => {
      // Check approval status
      const status = await checkReviewStatus(reviewId);
      return {
        approved: status.decision === "approved",
        pending: status.decision === "pending",
        reason: status.reason,
        reviewer: status.reviewerEmail,
      };
    },
  },
});

Alternatives Considered

Describe alternatives you've considered

• Alternative 1: Keep current simple implementation - This limits enterprise adoption in regulated industries (healthcare, finance, legal)
• Alternative 2: External webhook-only approach - Less type-safe and harder to integrate
• Alternative 3: Separate enterprise package - Fragments the ecosystem and complicates maintenance

The proposed solution provides a unified, type-safe API that supports both simple and complex enterprise workflows.

Use Case

What is your use case?

• Industry: Healthcare, Finance, Legal, Government
• Application type: AI assistants handling sensitive operations
• Scale: Enterprise production deployments with compliance requirements

Specific scenarios:

1. Medical AI requiring physician oversight for diagnosis recommendations
2. Financial systems needing multi-level approval for transactions above thresholds
3. Legal document generation requiring attorney review
4. Code execution safety with security review gates

Impact

Who would benefit from this feature?

• Individual developers
• Small teams
• Enterprise users
• All users (backward compatible)

Additional Context

Documentation vs Implementation Gap:

Feature	Documented	Implemented
enabled	Yes	Yes
dangerousActions	Yes	Yes
timeout	Yes	Yes
allowArgumentModification	Yes	Yes
autoApproveOnTimeout	Yes	Yes
auditLogging	Yes	Yes (basic)
customRules	Yes	Yes
confidenceThreshold	Yes	No
contentPatterns	Yes	No
mode (sync/async)	Yes	No
reviewCallback	Yes	No
statusCallback	Yes	No
escalationPolicy	Yes	No
requireApproval	Yes	No
Enhanced auditLog	Yes	No

Related Files:

• Documentation: docs/features/enterprise-hitl.md
• Current Implementation: src/lib/types/hitlTypes.ts
• HITL Manager: src/lib/hitl/hitlManager.ts

Implementation Considerations

Optional: Technical details

• Affected components: src/lib/hitl/, src/lib/types/hitlTypes.ts, src/lib/neurolink.ts
• Breaking changes: No - new features are additive, existing config remains valid
• Provider compatibility: All providers
• Performance implications:
  • Synchronous mode adds latency during approval
  • Asynchronous mode requires state management
  • Content pattern matching adds minimal overhead

Suggested Implementation Order:

1. requireApproval - Simple array-based tool matching
2. mode with reviewCallback - Core async/sync workflow
3. confidenceThreshold - Requires confidence scoring integration
4. contentPatterns - RegExp matching on content
5. escalationPolicy - Complex state machine
6. statusCallback - Async polling mechanism
7. Enhanced auditLog - Storage backend abstraction

Checklist

• I have searched existing issues and feature requests to ensure this is not a duplicate
• I have clearly described the problem and proposed solution
• I have provided example usage code
• I have considered alternatives and explained why they don't work
• I have described the real-world use case