@od-oneapp/ai-platform 0.1.0

package/src/tools/approval/testing.ts

@@ -0,0 +1,493 @@
+/**
+ * Testing Utilities for HITL Approval System
+ *
+ * Mock implementations and test helpers for testing approval workflows
+ */
+
+import { logError, logInfo } from '@repo/shared/logs';
+
+import type { ApprovalRequest, ApprovalResult, ApprovalHandler, ApprovalRule, Tool } from ".";
+
+/**
+ * Mock approval handler for testing
+ */
+export class MockApprovalHandler implements ApprovalHandler {
+  private approvals: Map<string, ApprovalResult> = new Map();
+  private requestLog: ApprovalRequest[] = [];
+  private notifications: Array<{ request: ApprovalRequest; result: ApprovalResult }> = [];
+
+  /** Default approval decision */
+  defaultApprove: boolean = true;
+
+  /** Delay for simulating review time */
+  delayMs: number = 0;
+
+  /**
+   * Set approval for a specific request ID
+   */
+  setApprovalForId(requestId: string, result: ApprovalResult): void {
+    this.approvals.set(requestId, result);
+  }
+
+  /**
+   * Set approval for tools matching pattern
+   */
+  setApprovalForPattern(pattern: string | RegExp, result: ApprovalResult): void {
+    // Store pattern-based approvals
+    // This would need additional state to track
+    void pattern;
+    void result;
+  }
+
+  async requestApproval(request: ApprovalRequest): Promise<ApprovalResult> {
+    this.requestLog.push(request);
+
+    if (this.delayMs > 0) {
+      await new Promise(resolve => setTimeout(resolve, this.delayMs));
+    }
+
+    // Check for specific ID approval
+    const specific = this.approvals.get(request.id);
+    if (specific) {
+      return specific;
+    }
+
+    // Return default
+    return {
+      approved: this.defaultApprove,
+      approvedBy: 'mock-reviewer',
+      approvedAt: new Date(),
+      reason: this.defaultApprove ? 'Mock approved' : 'Mock rejected',
+    };
+  }
+
+  async notifyApproval(request: ApprovalRequest, result: ApprovalResult): Promise<void> {
+    this.notifications.push({ request, result });
+  }
+
+  /**
+   * Get all approval requests received
+   */
+  getRequestLog(): ApprovalRequest[] {
+    return [...this.requestLog];
+  }
+
+  /**
+   * Get all notifications sent
+   */
+  getNotifications(): Array<{ request: ApprovalRequest; result: ApprovalResult }> {
+    return [...this.notifications];
+  }
+
+  /**
+   * Clear all history
+   */
+  clear(): void {
+    this.approvals.clear();
+    this.requestLog = [];
+    this.notifications = [];
+  }
+
+  /**
+   * Check if a request was received
+   */
+  wasRequested(toolName: string): boolean {
+    return this.requestLog.some(r => r.toolName === toolName);
+  }
+
+  /**
+   * Check if a request was approved
+   */
+  wasApproved(requestId: string): boolean {
+    return this.notifications.some(n => n.request.id === requestId && n.result.approved);
+  }
+}
+
+/**
+ * Mock tool for testing
+ */
+export class MockTool implements Tool {
+  name: string;
+  callCount: number = 0;
+  lastArgs?: Record<string, unknown>;
+  throwError: Error | null = null;
+  returnValue: unknown = { success: true };
+  description?: string;
+
+  constructor(name: string, config?: { throwError?: Error; returnValue?: unknown }) {
+    this.name = name;
+    if (config?.throwError) {
+      this.throwError = config.throwError;
+    }
+    if (config?.returnValue) {
+      this.returnValue = config.returnValue;
+    }
+  }
+
+  async execute(args: Record<string, unknown>): Promise<unknown> {
+    this.callCount += 1;
+    this.lastArgs = args;
+
+    if (this.throwError) {
+      throw this.throwError;
+    }
+
+    return this.returnValue;
+  }
+
+  validate(args: unknown): boolean {
+    void args;
+    return true;
+  }
+
+  /**
+   * Check if tool was called
+   */
+  wasCalled(): boolean {
+    return this.callCount > 0;
+  }
+
+  /**
+   * Get number of calls
+   */
+  getCallCount(): number {
+    return this.callCount;
+  }
+
+  /**
+   * Reset call tracking
+   */
+  reset(): void {
+    this.callCount = 0;
+    this.lastArgs = undefined;
+  }
+}
+
+/**
+ * Test fixtures
+ */
+export const testFixtures = {
+  /**
+   * Common approval rules for testing
+   */
+  rules: {
+    delete: {
+      toolPattern: 'delete*',
+      priority: 'critical' as const,
+      reason: 'Delete operations require approval',
+    } as ApprovalRule,
+
+    export: {
+      toolPattern: 'export*',
+      priority: 'high' as const,
+      reason: 'Export operations require approval',
+    } as ApprovalRule,
+
+    admin: {
+      toolPattern: /^admin_/,
+      priority: 'high' as const,
+      reason: 'Admin operations require approval',
+    } as ApprovalRule,
+  },
+
+  /**
+   * Common approval requests for testing
+   */
+  requests: {
+    deleteUser: (): ApprovalRequest => ({
+      id: `req_${Date.now()}`,
+      toolName: 'deleteUser',
+      args: { userId: 'user123' },
+      reason: 'User deletion',
+      requestedAt: new Date(),
+      status: 'pending',
+      priority: 'high',
+    }),
+
+    transferFunds: (): ApprovalRequest => ({
+      id: `req_${Date.now()}`,
+      toolName: 'transferFunds',
+      args: { amount: 10000, recipient: 'account456' },
+      reason: 'Financial transfer',
+      requestedAt: new Date(),
+      status: 'pending',
+      priority: 'critical',
+    }),
+
+    exportData: (): ApprovalRequest => ({
+      id: `req_${Date.now()}`,
+      toolName: 'exportData',
+      args: { format: 'csv', records: 50000 },
+      reason: 'Data export',
+      requestedAt: new Date(),
+      status: 'pending',
+      priority: 'normal',
+    }),
+  },
+
+  /**
+   * Common tools for testing
+   */
+  tools: {
+    delete: (): Tool => ({
+      name: 'deleteUser',
+      async execute(args) {
+        return { deleted: true, userId: args.userId };
+      },
+    }),
+
+    transfer: (): Tool => ({
+      name: 'transferFunds',
+      async execute(args) {
+        void args;
+        return { success: true, transactionId: 'tx_123' };
+      },
+    }),
+
+    export: (): Tool => ({
+      name: 'exportData',
+      async execute(args) {
+        void args;
+        return { success: true, fileId: 'file_123' };
+      },
+    }),
+  },
+};
+
+/**
+ * Assertion helpers
+ */
+export const assertions = {
+  /**
+   * Assert approval was requested for tool
+   */
+  assertApprovalRequested(handler: MockApprovalHandler, toolName: string): void {
+    if (!handler.wasRequested(toolName)) {
+      throw new Error(`Expected approval to be requested for ${toolName}`);
+    }
+  },
+
+  /**
+   * Assert approval was NOT requested
+   */
+  assertApprovalNotRequested(handler: MockApprovalHandler, toolName: string): void {
+    if (handler.wasRequested(toolName)) {
+      throw new Error(`Expected approval NOT to be requested for ${toolName}`);
+    }
+  },
+
+  /**
+   * Assert tool was called
+   */
+  assertToolCalled(tool: MockTool): void {
+    if (!tool.wasCalled()) {
+      throw new Error(`Expected tool ${tool.name} to be called`);
+    }
+  },
+
+  /**
+   * Assert tool was NOT called
+   */
+  assertToolNotCalled(tool: MockTool): void {
+    if (tool.wasCalled()) {
+      throw new Error(`Expected tool ${tool.name} NOT to be called`);
+    }
+  },
+
+  /**
+   * Assert tool call count
+   */
+  assertToolCallCount(tool: MockTool, expectedCount: number): void {
+    if (tool.getCallCount() !== expectedCount) {
+      throw new Error(
+        `Expected tool ${tool.name} to be called ${expectedCount} times, but was called ${tool.getCallCount()} times`,
+      );
+    }
+  },
+
+  /**
+   * Assert notification was sent
+   */
+  assertNotificationSent(handler: MockApprovalHandler, requestId: string): void {
+    const notifications = handler.getNotifications();
+    if (!notifications.some(n => n.request.id === requestId)) {
+      throw new Error(`Expected notification to be sent for request ${requestId}`);
+    }
+  },
+
+  /**
+   * Assert approval count
+   */
+  assertApprovalCount(handler: MockApprovalHandler, expectedCount: number): void {
+    const requests = handler.getRequestLog();
+    if (requests.length !== expectedCount) {
+      throw new Error(`Expected ${expectedCount} approval requests, but got ${requests.length}`);
+    }
+  },
+};
+
+/**
+ * Test builder for fluent API
+ */
+export class ApprovalTestBuilder {
+  private handler: MockApprovalHandler;
+  private tool: MockTool;
+  private rules: ApprovalRule[] = [];
+
+  constructor(toolName: string) {
+    this.handler = new MockApprovalHandler();
+    this.tool = new MockTool(toolName);
+  }
+
+  /**
+   * Add approval rule
+   */
+  withRule(rule: ApprovalRule): this {
+    this.rules.push(rule);
+    return this;
+  }
+
+  /**
+   * Add multiple rules
+   */
+  withRules(...rules: ApprovalRule[]): this {
+    this.rules.push(...rules);
+    return this;
+  }
+
+  /**
+   * Set handler to auto-approve
+   */
+  approveAll(): this {
+    this.handler.defaultApprove = true;
+    return this;
+  }
+
+  /**
+   * Set handler to auto-reject
+   */
+  rejectAll(): this {
+    this.handler.defaultApprove = false;
+    return this;
+  }
+
+  /**
+   * Set approval delay
+   */
+  withApprovalDelay(delayMs: number): this {
+    this.handler.delayMs = delayMs;
+    return this;
+  }
+
+  /**
+   * Set tool return value
+   */
+  returnsValue(value: unknown): this {
+    this.tool.returnValue = value;
+    return this;
+  }
+
+  /**
+   * Set tool to throw error
+   */
+  throwsError(error: Error): this {
+    this.tool.throwError = error;
+    return this;
+  }
+
+  /**
+   * Get handler
+   */
+  getHandler(): MockApprovalHandler {
+    return this.handler;
+  }
+
+  /**
+   * Get tool
+   */
+  getTool(): MockTool {
+    return this.tool;
+  }
+
+  /**
+   * Get rules
+   */
+  getRules(): ApprovalRule[] {
+    return this.rules;
+  }
+
+  /**
+   * Build and return all components
+   */
+  build(): { handler: MockApprovalHandler; tool: MockTool; rules: ApprovalRule[] } {
+    return {
+      handler: this.handler,
+      tool: this.tool,
+      rules: this.rules,
+    };
+  }
+}
+
+/**
+ * Create a test builder
+ */
+export function createTestBuilder(toolName: string): ApprovalTestBuilder {
+  return new ApprovalTestBuilder(toolName);
+}
+
+/**
+ * Run a test with built-in teardown
+ */
+export async function runApprovalTest(name: string, test: () => Promise<void>): Promise<void> {
+  logInfo(`\n[Test] ${name}`);
+  try {
+    await test();
+    logInfo(`[PASS] ${name}`);
+  } catch (error) {
+    logError(`[FAIL] ${name}`);
+    throw error;
+  }
+}
+
+/**
+ * Example test suite
+ */
+export async function exampleTestSuite(): Promise<void> {
+  logInfo('=== Approval System Test Suite ===\n');
+
+  // Test 1: Basic approval requirement
+  await runApprovalTest('Should request approval for delete operations', async () => {
+    const builder = createTestBuilder('deleteUser')
+      .withRule(testFixtures.rules.delete)
+      .approveAll();
+
+    const { handler, tool, rules } = builder.build();
+    void tool;
+    void rules;
+
+    // In real tests, you would import and use withApproval here
+    assertions.assertApprovalCount(handler, 0); // Haven't called yet
+  });
+
+  // Test 2: Mock handler
+  await runApprovalTest('Mock handler should track requests', async () => {
+    const handler = new MockApprovalHandler();
+    const request = testFixtures.requests.deleteUser();
+
+    const result = await handler.requestApproval(request);
+
+    assertions.assertApprovalCount(handler, 1);
+    if (!result.approved) throw new Error('Expected approval');
+  });
+
+  // Test 3: Mock tool
+  await runApprovalTest('Mock tool should track calls', async () => {
+    const tool = new MockTool('testTool');
+
+    await tool.execute({ test: true });
+
+    if (tool.getCallCount() !== 1) throw new Error('Expected 1 call');
+  });
+
+  logInfo('\n=== All Tests Passed ===\n');
+}

package/src/tools/approval/types.ts

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview Type definitions for the Human-In-The-Loop (HITL) Approval System.
+ * Contains all interfaces used across the approval module including requests,
+ * results, rules, handlers, backends, and queue management.
+ */
+
+/**
+ * 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 type { RedisClientExtended as RedisClient } from '../../integrations/redis';
+
+/**
+ * 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;
+}