@od-oneapp/ai-platform 0.1.0

package/src/tools/approval/index.ts

@@ -0,0 +1,737 @@
+/**
+ * Human-In-The-Loop (HITL) Approval System
+ * Main approval orchestration module for tool workflows requiring human validation
+ *
+ * FEATURES:
+ * - Tool-level approval workflows
+ * - Flexible approval rules and conditions
+ * - Approval queue management (in-memory and Redis)
+ * - Middleware integration for automatic interception
+ * - Approval tracking and audit trails
+ * - Modification support during approval
+ */
+
+import { logInfo } from '@repo/shared/logs';
+
+/**
+ * Approval request that needs human review
+ */
+export interface ApprovalRequest {
+  /** Unique identifier for this approval request */
+  id: string;
+
+  /** Name of the tool requiring approval */
+  toolName: string;
+
+  /** Arguments passed to the tool */
+  args: Record<string, unknown>;
+
+  /** Reason why approval is needed */
+  reason: string;
+
+  /** Additional context for approval decision */
+  context?: Record<string, unknown>;
+
+  /** When the request was created */
+  requestedAt: Date;
+
+  /** When the request expires (null = no expiration) */
+  expiresAt?: Date;
+
+  /** Priority level for approval queue */
+  priority?: 'low' | 'normal' | 'high' | 'critical';
+
+  /** Requester information */
+  requestedBy?: string;
+
+  /** Callback URL for approval notification (webhook) */
+  notificationUrl?: string;
+
+  /** Request status */
+  status: 'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled';
+}
+
+/**
+ * Result of an approval decision
+ */
+export interface ApprovalResult {
+  /** Whether the tool was approved */
+  approved: boolean;
+
+  /** User ID of the approver */
+  approvedBy?: string;
+
+  /** When the approval was decided */
+  approvedAt?: Date;
+
+  /** Modifications to the original args by approver */
+  modifications?: Record<string, unknown>;
+
+  /** Reason for approval/rejection decision */
+  reason?: string;
+
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Approval rule to determine if a tool needs approval
+ */
+export interface ApprovalRule {
+  /** Tool name pattern (supports wildcards) */
+  toolPattern: string | RegExp;
+
+  /** Condition function to determine approval requirement */
+  condition?: (args: unknown, context?: Record<string, unknown>) => boolean;
+
+  /** Priority for approval */
+  priority?: 'low' | 'normal' | 'high' | 'critical';
+
+  /** Expiration time in milliseconds */
+  expirationMs?: number;
+
+  /** Custom reason message */
+  reason?: string | ((args: unknown) => string);
+}
+
+/**
+ * Configuration options for approval system
+ */
+export interface ApprovalOptions {
+  /** Array of rules determining approval requirements */
+  rules?: ApprovalRule[];
+
+  /** Global expiration time in milliseconds */
+  defaultExpirationMs?: number;
+
+  /** Default priority for approvals */
+  defaultPriority?: 'low' | 'normal' | 'high' | 'critical';
+
+  /** Enable logging for debugging */
+  enableLogging?: boolean;
+
+  /** Approval backend to use */
+  backend?: ApprovalBackend;
+
+  /** Custom approval handler */
+  handler?: ApprovalHandler;
+
+  /** Timeout for approval decision in milliseconds */
+  approvalTimeoutMs?: number;
+}
+
+/**
+ * Handler for approval decisions
+ */
+export interface ApprovalHandler {
+  /** Request approval from user */
+  requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
+
+  /** Notify approval decision */
+  notifyApproval(request: ApprovalRequest, result: ApprovalResult): Promise<void>;
+}
+
+export interface RedisClient {
+  get: (key: string) => Promise<string | null> | string | null;
+  set: (
+    key: string,
+    value: string,
+    mode?: string,
+    durationSeconds?: number,
+  ) => Promise<unknown> | unknown;
+  keys: (pattern: string) => Promise<string[]> | string[];
+  del: (key: string) => Promise<number> | number;
+}
+
+/**
+ * Tool interface for approval wrapping
+ */
+export interface Tool<T = unknown> {
+  /** Tool name */
+  name: string;
+
+  /** Tool description */
+  description?: string;
+
+  /** Execute the tool */
+  execute(args: Record<string, unknown>): Promise<T>;
+
+  /** Validate tool arguments */
+  validate?(args: unknown): boolean;
+}
+
+/**
+ * Backend interface for approval storage and retrieval
+ */
+export interface ApprovalBackend {
+  /** Store approval request */
+  store(request: ApprovalRequest): Promise<void>;
+
+  /** Retrieve approval request by ID */
+  get(requestId: string): Promise<ApprovalRequest | null>;
+
+  /** List pending approvals */
+  listPending(): Promise<ApprovalRequest[]>;
+
+  /** Update approval request status */
+  updateStatus(requestId: string, status: ApprovalRequest['status']): Promise<void>;
+
+  /** Delete approval request */
+  delete(requestId: string): Promise<void>;
+
+  /** Clear expired requests */
+  clearExpired(): Promise<number>;
+}
+
+/**
+ * Approval queue interface
+ */
+export interface ApprovalQueue {
+  /** Add request to queue */
+  enqueue(request: ApprovalRequest): Promise<void>;
+
+  /** Get next request from queue */
+  dequeue(): Promise<ApprovalRequest | null>;
+
+  /** Get request by ID */
+  get(requestId: string): Promise<ApprovalRequest | null>;
+
+  /** List all pending requests */
+  listPending(limit?: number, offset?: number): Promise<ApprovalRequest[]>;
+
+  /** Update request status */
+  updateStatus(
+    requestId: string,
+    status: ApprovalRequest['status'],
+    result?: ApprovalResult,
+  ): Promise<void>;
+
+  /** Remove request from queue */
+  remove(requestId: string): Promise<void>;
+
+  /** Get queue statistics */
+  getStats(): Promise<QueueStats>;
+
+  /** Clear expired requests */
+  clearExpired(): Promise<number>;
+}
+
+/**
+ * Statistics about the approval queue
+ */
+export interface QueueStats {
+  /** Total pending requests */
+  totalPending: number;
+
+  /** Requests by priority */
+  byPriority: Record<string, number>;
+
+  /** Oldest pending request age in milliseconds */
+  oldestRequestAgeMs?: number;
+
+  /** Average time in queue (milliseconds) */
+  averageTimeInQueueMs?: number;
+
+  /** Total requests processed */
+  totalProcessed: number;
+
+  /** Approval rate (0-1) */
+  approvalRate: number;
+}
+
+/**
+ * Tool wrapper that requires approval
+ *
+ * @param tool - Tool to wrap
+ * @param options - Approval options
+ * @returns Wrapped tool that requires approval
+ *
+ * @example
+ * ```typescript
+ * const deleteTool = {
+ *   name: 'deleteDatabase',
+ *   execute: async (args) => { ... }
+ * };
+ *
+ * const approvedDeleteTool = withApproval(deleteTool, {
+ *   rules: [{
+ *     toolPattern: 'delete*',
+ *     priority: 'critical',
+ *     reason: 'Database operations require approval'
+ *   }],
+ *   handler: myApprovalHandler
+ * });
+ * ```
+ */
+export function withApproval<T = unknown>(tool: Tool<T>, options?: ApprovalOptions): Tool<T> {
+  const logger = options?.enableLogging ? logInfo : () => {};
+  let approvalQueue: ApprovalQueue | null = null;
+
+  return {
+    name: tool.name,
+    description: tool.description,
+
+    async execute(args: Record<string, unknown>): Promise<T> {
+      // Check if approval is needed
+      const needsApprovalResult = needsApproval(tool.name, args, options?.rules);
+
+      if (!needsApprovalResult.required) {
+        logger(`[Approval] Tool '${tool.name}' does not require approval`);
+        return tool.execute(args);
+      }
+
+      logger(`[Approval] Tool '${tool.name}' requires approval`);
+
+      // Create approval request
+      const requestId = generateRequestId();
+      const request: ApprovalRequest = {
+        id: requestId,
+        toolName: tool.name,
+        args,
+        reason: needsApprovalResult.reason,
+        context: needsApprovalResult.context,
+        requestedAt: new Date(),
+        expiresAt: options?.defaultExpirationMs
+          ? new Date(Date.now() + options.defaultExpirationMs)
+          : undefined,
+        priority: needsApprovalResult.priority || options?.defaultPriority || 'normal',
+        status: 'pending',
+      };
+
+      // Store in queue
+      approvalQueue =
+        approvalQueue || (options?.backend ? createQueueFromBackend(options.backend) : null);
+      if (approvalQueue) {
+        await approvalQueue.enqueue(request);
+        logger(`[Approval] Request ${requestId} enqueued`);
+      }
+
+      // Request approval from handler
+      const handler = options?.handler;
+      if (!handler) {
+        throw new Error(`No approval handler configured for tool '${tool.name}'`);
+      }
+
+      const result = await handler.requestApproval(request);
+
+      if (!result.approved) {
+        logger(`[Approval] Request ${requestId} rejected: ${result.reason}`);
+        throw new Error(`Approval denied for tool '${tool.name}': ${result.reason}`);
+      }
+
+      logger(`[Approval] Request ${requestId} approved`);
+
+      // Apply modifications if any
+      const finalArgs = result.modifications ? { ...args, ...result.modifications } : args;
+
+      // Notify approval
+      try {
+        await handler.notifyApproval(request, result);
+      } catch (error) {
+        logger(`[Approval] Notification failed: ${error}`);
+      }
+
+      // Update queue status
+      if (approvalQueue) {
+        await approvalQueue.updateStatus(requestId, 'approved', result);
+      }
+
+      // Execute tool with approved args
+      return tool.execute(finalArgs);
+    },
+
+    validate: tool.validate,
+  };
+}
+
+/**
+ * Check if a tool needs approval based on rules
+ *
+ * @param toolName - Name of the tool
+ * @param args - Tool arguments
+ * @param rules - Approval rules
+ * @returns Object indicating if approval is needed and metadata
+ *
+ * @example
+ * ```typescript
+ * const result = needsApproval('deleteUser', { userId: '123' }, [
+ *   {
+ *     toolPattern: 'delete*',
+ *     priority: 'critical',
+ *     reason: 'Delete operations require approval'
+ *   }
+ * ]);
+ *
+ * if (result.required) {
+ *   logInfo(`Approval needed: ${result.reason}`);
+ * }
+ * ```
+ */
+export function needsApproval(
+  toolName: string,
+  args: unknown,
+  rules?: ApprovalRule[],
+): {
+  required: boolean;
+  reason: string;
+  priority?: ApprovalRequest['priority'];
+  context?: Record<string, unknown>;
+} {
+  if (!rules || rules.length === 0) {
+    return { required: false, reason: 'No approval rules defined' };
+  }
+
+  for (const rule of rules) {
+    const matches = matchPattern(toolName, rule.toolPattern);
+    if (!matches) continue;
+
+    // Check condition if provided
+    if (rule.condition && !rule.condition(args)) {
+      continue;
+    }
+
+    // Tool matches this rule
+    const reason =
+      typeof rule.reason === 'function'
+        ? rule.reason(args)
+        : rule.reason || `Tool '${toolName}' requires approval`;
+
+    return {
+      required: true,
+      reason,
+      priority: rule.priority,
+      context: { toolName, argsPreview: JSON.stringify(args).substring(0, 200) },
+    };
+  }
+
+  return { required: false, reason: 'No matching approval rules' };
+}
+
+/**
+ * Create an approval queue with in-memory backend
+ *
+ * @param options - Queue options
+ * @returns ApprovalQueue instance
+ *
+ * @example
+ * ```typescript
+ * const queue = createApprovalQueue();
+ *
+ * // Add request
+ * await queue.enqueue(request);
+ *
+ * // Process requests
+ * const pending = await queue.listPending();
+ * ```
+ */
+export function createApprovalQueue(options?: { enableLogging?: boolean }): ApprovalQueue {
+  const backend = createInMemoryBackend();
+  return createQueueFromBackend(backend, options);
+}
+
+/**
+ * Create approval queue with Redis backend
+ *
+ * @param redisClient - Redis client instance
+ * @param options - Queue options
+ * @returns ApprovalQueue instance
+ *
+ * @example
+ * ```typescript
+ * const redis = new Redis();
+ * const queue = createApprovalQueueWithRedis(redis);
+ * ```
+ */
+export async function createApprovalQueueWithRedis(
+  redisClient: RedisClient,
+  options?: {
+    keyPrefix?: string;
+    enableLogging?: boolean;
+  },
+): Promise<ApprovalQueue> {
+  const backend = createRedisBackend(redisClient, options?.keyPrefix || 'approval:');
+  return createQueueFromBackend(backend, options);
+}
+
+/**
+ * Create a basic approval handler (stub for user implementation)
+ *
+ * @param implementation - Custom implementation
+ * @returns ApprovalHandler
+ *
+ * @example
+ * ```typescript
+ * const handler = createApprovalHandler({
+ *   requestApproval: async (request) => {
+ *     // Notify user via email/Slack/etc
+ *     await notifyUser(request);
+ *     // Wait for approval...
+ *     return { approved: true, approvedBy: 'user@example.com' };
+ *   }
+ * });
+ * ```
+ */
+export function createApprovalHandler(implementation: Partial<ApprovalHandler>): ApprovalHandler {
+  return {
+    requestApproval: implementation.requestApproval || (async () => ({ approved: false })),
+    notifyApproval: implementation.notifyApproval || (async () => {}),
+  };
+}
+
+/**
+ * Create approval middleware for intercepting tool calls
+ *
+ * @param options - Middleware options
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * const middleware = createApprovalMiddleware({
+ *   rules: approvalRules,
+ *   handler: approvalHandler,
+ *   enableLogging: true
+ * });
+ *
+ * // Use in your tool execution pipeline
+ * tools = tools.map(tool => middleware(tool));
+ * ```
+ */
+export function createApprovalMiddleware(options: ApprovalOptions) {
+  return function approvalMiddleware<T>(tool: Tool<T>): Tool<T> {
+    return withApproval(tool, options);
+  };
+}
+
+// ============================================================================
+// INTERNAL HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Generate a unique approval request ID
+ */
+function generateRequestId(): string {
+  return `apr_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+
+/**
+ * Match tool name against pattern (supports wildcards)
+ */
+function matchPattern(toolName: string, pattern: string | RegExp): boolean {
+  if (pattern instanceof RegExp) {
+    return pattern.test(toolName);
+  }
+
+  // Convert wildcard pattern to regex
+  const regexPattern = pattern.replace(/\./g, '\\.').replace(/\*/g, '.*').replace(/\?/g, '.');
+
+  return new RegExp(`^${regexPattern}$`).test(toolName);
+}
+
+/**
+ * Create in-memory backend for approval queue
+ */
+function createInMemoryBackend(): ApprovalBackend {
+  const requests = new Map<string, ApprovalRequest>();
+  const results = new Map<string, ApprovalResult>();
+
+  return {
+    async store(request: ApprovalRequest): Promise<void> {
+      requests.set(request.id, { ...request });
+    },
+
+    async get(requestId: string): Promise<ApprovalRequest | null> {
+      return requests.get(requestId) || null;
+    },
+
+    async listPending(): Promise<ApprovalRequest[]> {
+      return Array.from(requests.values()).filter(r => r.status === 'pending');
+    },
+
+    async updateStatus(requestId: string, status: ApprovalRequest['status']): Promise<void> {
+      const request = requests.get(requestId);
+      if (request) {
+        request.status = status;
+      }
+    },
+
+    async delete(requestId: string): Promise<void> {
+      requests.delete(requestId);
+      results.delete(requestId);
+    },
+
+    async clearExpired(): Promise<number> {
+      const now = new Date();
+      let count = 0;
+
+      for (const [id, request] of requests.entries()) {
+        if (request.expiresAt && request.expiresAt < now) {
+          requests.delete(id);
+          count += 1;
+        }
+      }
+
+      return count;
+    },
+  };
+}
+
+/**
+ * Create Redis backend for approval queue
+ */
+function createRedisBackend(redisClient: RedisClient, keyPrefix: string): ApprovalBackend {
+  return {
+    async store(request: ApprovalRequest): Promise<void> {
+      const key = `${keyPrefix}${request.id}`;
+      await redisClient.set(key, JSON.stringify(request), 'EX', 86400); // 24h TTL
+    },
+
+    async get(requestId: string): Promise<ApprovalRequest | null> {
+      const key = `${keyPrefix}${requestId}`;
+      const data = await redisClient.get(key);
+      return data ? JSON.parse(data) : null;
+    },
+
+    async listPending(): Promise<ApprovalRequest[]> {
+      const pattern = `${keyPrefix}*`;
+      const keys = await redisClient.keys(pattern);
+      const requests: ApprovalRequest[] = [];
+
+      for (const key of keys) {
+        const data = await redisClient.get(key);
+        if (data) {
+          const request = JSON.parse(data);
+          if (request.status === 'pending') {
+            requests.push(request);
+          }
+        }
+      }
+
+      return requests;
+    },
+
+    async updateStatus(requestId: string, status: ApprovalRequest['status']): Promise<void> {
+      const key = `${keyPrefix}${requestId}`;
+      const data = await redisClient.get(key);
+      if (data) {
+        const request = JSON.parse(data);
+        request.status = status;
+        await redisClient.set(key, JSON.stringify(request), 'EX', 86400);
+      }
+    },
+
+    async delete(requestId: string): Promise<void> {
+      const key = `${keyPrefix}${requestId}`;
+      await redisClient.del(key);
+    },
+
+    async clearExpired(): Promise<number> {
+      // Redis TTL handles expiration, return 0
+      return 0;
+    },
+  };
+}
+
+/**
+ * Create queue from backend
+ */
+function createQueueFromBackend(
+  backend: ApprovalBackend,
+  options?: { enableLogging?: boolean },
+): ApprovalQueue {
+  const logger = options?.enableLogging ? logInfo : () => {};
+  const processedRequests = new Map<string, ApprovalResult>();
+
+  return {
+    async enqueue(request: ApprovalRequest): Promise<void> {
+      logger(`[Queue] Enqueuing request ${request.id}`);
+      await backend.store(request);
+    },
+
+    async dequeue(): Promise<ApprovalRequest | null> {
+      const pending = await backend.listPending();
+      if (pending.length === 0) return null;
+
+      // Sort by priority (critical > high > normal > low) and requestedAt
+      pending.sort((a, b) => {
+        const priorityOrder: Record<string, number> = {
+          critical: 0,
+          high: 1,
+          normal: 2,
+          low: 3,
+        };
+        const defaultPriority = priorityOrder.normal ?? 2;
+        const aPriority = priorityOrder[a.priority ?? 'normal'];
+        const bPriority = priorityOrder[b.priority ?? 'normal'];
+        const aValue = typeof aPriority === 'number' ? aPriority : defaultPriority;
+        const bValue = typeof bPriority === 'number' ? bPriority : defaultPriority;
+
+        if (aValue !== bValue) return aValue - bValue;
+        return a.requestedAt.getTime() - b.requestedAt.getTime();
+      });
+
+      return pending[0] ?? null;
+    },
+
+    async get(requestId: string): Promise<ApprovalRequest | null> {
+      return backend.get(requestId);
+    },
+
+    async listPending(limit = 100, offset = 0): Promise<ApprovalRequest[]> {
+      const pending = await backend.listPending();
+      return pending.slice(offset, offset + limit);
+    },
+
+    async updateStatus(
+      requestId: string,
+      status: ApprovalRequest['status'],
+      result?: ApprovalResult,
+    ): Promise<void> {
+      await backend.updateStatus(requestId, status);
+      if (result) {
+        processedRequests.set(requestId, result);
+      }
+    },
+
+    async remove(requestId: string): Promise<void> {
+      await backend.delete(requestId);
+      processedRequests.delete(requestId);
+    },
+
+    async getStats(): Promise<QueueStats> {
+      const pending = await backend.listPending();
+      const byPriority: Record<string, number> = {
+        critical: 0,
+        high: 0,
+        normal: 0,
+        low: 0,
+      };
+
+      let oldestTime = Date.now();
+      for (const req of pending) {
+        const priority = req.priority ?? 'normal';
+        const key = priority in byPriority ? priority : 'normal';
+        byPriority[key] = (byPriority[key] ?? 0) + 1;
+        oldestTime = Math.min(oldestTime, req.requestedAt.getTime());
+      }
+
+      const oldestRequestAgeMs = pending.length > 0 ? Date.now() - oldestTime : undefined;
+      const totalProcessed = processedRequests.size;
+      const approvalRate =
+        totalProcessed > 0
+          ? Array.from(processedRequests.values()).filter(r => r.approved).length / totalProcessed
+          : 0;
+
+      return {
+        totalPending: pending.length,
+        byPriority,
+        oldestRequestAgeMs,
+        totalProcessed,
+        approvalRate,
+      };
+    },
+
+    async clearExpired(): Promise<number> {
+      return backend.clearExpired();
+    },
+  };
+}