@od-oneapp/ai-platform 0.1.0

package/src/tools/approval/README.md

@@ -0,0 +1,514 @@
+# Human-In-The-Loop (HITL) Approval System
+
+A comprehensive TypeScript implementation of Human-In-The-Loop approval workflows for tool execution. This system
+provides a flexible framework for intercepting tool calls, requesting human approval, managing approval queues, and
+executing tools based on approval decisions.
+
+## Features
+
+### Core Functionality
+
+- **Tool Wrapping**: Wrap any tool with approval logic using `withApproval()`
+- **Approval Rules**: Define rules with pattern matching and conditional logic
+- **Rule Engine**: Pattern-based matching (wildcards, regex) and condition evaluation
+- **Flexible Approval**: Approve, reject, or modify tool arguments during approval
+- **Priority Handling**: Critical, high, normal, and low priority levels
+
+### Queue Management
+
+- **In-Memory Queue**: Fast local queue with full feature support
+- **Redis Queue**: Distributed queue for multi-process environments
+- **Priority Sorting**: Automatic ordering by priority and age
+- **Expiration**: Automatic cleanup of expired requests
+- **Dead Letter Queue**: Capture rejected requests for analysis
+- **Metrics**: Comprehensive statistics and performance tracking
+
+### Middleware System
+
+- **Middleware Chain**: Extensible request/response interception
+- **Approval Middleware**: Core approval decision logic
+- **Validation Middleware**: Pre-execution argument validation
+- **Audit Logging**: Complete execution trail
+- **Rate Limiting**: Per-user and global request limits
+- **Retry Logic**: Exponential backoff with configurable strategy
+- **Context Enrichment**: Dynamic metadata injection
+
+### Monitoring & Analytics
+
+- **Queue Statistics**: Total pending, by priority, approval rates
+- **Audit Trails**: Complete request/approval/execution logs
+- **Performance Metrics**: Response times, approval duration
+- **Dead Letter Queue**: Failed request analysis
+
+## Installation & Setup
+
+### Basic Setup
+
+```typescript
+import { withApproval, createApprovalQueue, createApprovalHandler, type ApprovalRule, type Tool } from "./approval";
+
+// Define approval rules
+const rules: ApprovalRule[] = [
+  {
+    toolPattern: "delete*",
+    priority: "critical",
+    reason: "Delete operations require approval"
+  }
+];
+
+// Create approval handler
+const handler = createApprovalHandler({
+  requestApproval: async (request) => {
+    // Request user approval (email, Slack, webhook, etc.)
+    console.log(`Please approve: ${request.toolName}`);
+    return { approved: true, approvedBy: "admin@example.com" };
+  }
+});
+
+// Wrap tool with approval
+const tool: Tool = {
+  name: "deleteUser",
+  async execute(args) {
+    // Tool implementation
+    return { success: true };
+  }
+};
+
+const protectedTool = withApproval(tool, {
+  rules,
+  handler,
+  enableLogging: true
+});
+
+// Execute with approval
+const result = await protectedTool.execute({ userId: "123" });
+```
+
+## Architecture
+
+### Component Overview
+
+#### 1. **index.ts** - Main Approval Orchestration
+
+- Core types and interfaces
+- `withApproval()` - Tool wrapper function
+- `needsApproval()` - Rule evaluation engine
+- `createApprovalQueue()` - Queue factory
+- `createApprovalHandler()` - Handler factory
+
+#### 2. **queue.ts** - Queue Implementations
+
+- `InMemoryApprovalQueue` - Local in-memory queue
+- `RedisApprovalQueue` - Redis-backed distributed queue
+- `AdvancedQueueConfig` - Configuration options
+- `QueueMetrics` - Performance statistics
+- Batch processing support
+- Dead letter queue management
+
+#### 3. **middleware.ts** - Request Interception
+
+- `MiddlewareChain` - Composable middleware system
+- Approval middleware
+- Validation middleware
+- Audit logging middleware
+- Rate limiting middleware
+- Retry middleware with exponential backoff
+- Context enrichment middleware
+
+## Usage Examples
+
+### Example 1: Basic Approval
+
+```typescript
+const deleteToolWithApproval = withApproval(deleteDatabase, {
+  rules: [
+    {
+      toolPattern: "delete*",
+      priority: "critical"
+    }
+  ],
+  handler: approvalHandler,
+  enableLogging: true
+});
+
+// This will trigger approval request
+await deleteToolWithApproval.execute({ database: "production" });
+```
+
+### Example 2: Queue Management
+
+```typescript
+const queue = createApprovalQueue();
+
+// Add requests
+const request: ApprovalRequest = {
+  id: "req_001",
+  toolName: "deleteUser",
+  args: { userId: "123" },
+  reason: "User requested deletion",
+  requestedAt: new Date(),
+  priority: "high",
+  status: "pending"
+};
+
+await queue.enqueue(request);
+
+// Process queue
+const nextRequest = await queue.dequeue();
+if (nextRequest) {
+  // Handle approval decision
+  await queue.updateStatus(nextRequest.id, "approved");
+}
+
+// Get statistics
+const stats = await queue.getStats();
+console.log(`Pending: ${stats.totalPending}, Approval Rate: ${stats.approvalRate}`);
+```
+
+### Example 3: Complex Approval Rules
+
+```typescript
+const rules: ApprovalRule[] = [
+  // Wildcard patterns
+  {
+    toolPattern: "delete*",
+    priority: "critical"
+  },
+
+  // Conditional rules
+  {
+    toolPattern: "exportData",
+    condition: (args) => args.recordCount > 10000,
+    priority: "high",
+    reason: (args) => `Export ${args.recordCount} records requires approval`
+  },
+
+  // Regex patterns
+  {
+    toolPattern: /^(create|update|delete)User$/,
+    priority: "high"
+  }
+];
+
+const result = needsApproval("deleteUser", { userId: "123" }, rules);
+if (result.required) {
+  console.log(`Approval needed: ${result.reason}`);
+}
+```
+
+### Example 4: Middleware Chain
+
+```typescript
+import { buildApprovalChain, createContext } from "./middleware";
+
+const chain = buildApprovalChain({
+  rules: approvalRules,
+  handler: approvalHandler,
+  validators: {
+    transferFunds: (args) => {
+      if (args.amount < 0) return "Amount must be positive";
+      return true;
+    }
+  },
+  auditLog: async (entry) => {
+    console.log(`[${entry.toolName}] ${entry.status}`);
+  },
+  rateLimit: {
+    maxPerMinute: 10,
+    maxPerHour: 100
+  },
+  enableLogging: true
+});
+
+// Execute through middleware
+const context = createContext("transferFunds", { amount: 1000 });
+const result = await chain.execute(context, () => tool.execute(args));
+```
+
+### Example 5: Redis Queue
+
+```typescript
+import Redis from "redis";
+import { createApprovalQueueWithRedis } from "./approval";
+
+const redis = new Redis();
+const queue = await createApprovalQueueWithRedis(redis, {
+  keyPrefix: "approval:",
+  enableLogging: true
+});
+
+await queue.enqueue(request);
+const stats = await queue.getStats();
+```
+
+## API Reference
+
+### Core Functions
+
+#### `withApproval<T>(tool, options?): Tool<T>`
+
+Wraps a tool with approval logic.
+
+**Parameters:**
+
+- `tool` - Tool to wrap
+- `options.rules` - Approval rules array
+- `options.handler` - Approval handler implementation
+- `options.defaultPriority` - Default priority level
+- `options.enableLogging` - Enable debug logging
+
+**Returns:** Wrapped tool that requires approval
+
+#### `needsApproval(toolName, args, rules?): ApprovalCheckResult`
+
+Checks if a tool needs approval based on rules.
+
+**Parameters:**
+
+- `toolName` - Name of the tool
+- `args` - Tool arguments
+- `rules` - Array of approval rules
+
+**Returns:** Object with `required` boolean and metadata
+
+#### `createApprovalQueue(options?): ApprovalQueue`
+
+Creates an in-memory approval queue.
+
+**Parameters:**
+
+- `options.enableLogging` - Enable logging
+- `options.enableMetrics` - Track metrics
+- `options.enableDLQ` - Enable dead letter queue
+
+**Returns:** ApprovalQueue instance
+
+#### `createApprovalQueueWithRedis(client, options?): Promise<ApprovalQueue>`
+
+Creates a Redis-backed approval queue.
+
+**Parameters:**
+
+- `client` - Redis client instance
+- `options.keyPrefix` - Redis key prefix
+- `options.enableLogging` - Enable logging
+
+**Returns:** Promise resolving to ApprovalQueue
+
+### Middleware Functions
+
+#### `buildApprovalChain(config): MiddlewareChain`
+
+Builds a complete middleware chain with all features.
+
+**Parameters:**
+
+- `config.rules` - Approval rules
+- `config.handler` - Approval handler
+- `config.validators` - Validation functions
+- `config.auditLog` - Audit logger
+- `config.rateLimit` - Rate limit config
+- `config.retry` - Retry config
+- `config.enableLogging` - Enable logging
+
+**Returns:** MiddlewareChain instance
+
+#### `createApprovalMiddleware(rules, handler, options?): MiddlewareFunction`
+
+Creates approval middleware for chain.
+
+#### `createValidationMiddleware(validators, options?): MiddlewareFunction`
+
+Creates validation middleware.
+
+#### `createAuditMiddleware(auditLog, options?): MiddlewareFunction`
+
+Creates audit logging middleware.
+
+#### `createRateLimitMiddleware(options): MiddlewareFunction`
+
+Creates rate limiting middleware.
+
+#### `createRetryMiddleware(options): MiddlewareFunction`
+
+Creates retry middleware with exponential backoff.
+
+## Types
+
+### ApprovalRequest
+
+```typescript
+interface ApprovalRequest {
+  id: string;
+  toolName: string;
+  args: Record<string, unknown>;
+  reason: string;
+  context?: Record<string, unknown>;
+  requestedAt: Date;
+  expiresAt?: Date;
+  priority?: "low" | "normal" | "high" | "critical";
+  requestedBy?: string;
+  notificationUrl?: string;
+  status: "pending" | "approved" | "rejected" | "expired" | "cancelled";
+}
+```
+
+### ApprovalResult
+
+```typescript
+interface ApprovalResult {
+  approved: boolean;
+  approvedBy?: string;
+  approvedAt?: Date;
+  modifications?: Record<string, unknown>;
+  reason?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+### ApprovalRule
+
+```typescript
+interface ApprovalRule {
+  toolPattern: string | RegExp;
+  condition?: (args: unknown, context?: Record<string, unknown>) => boolean;
+  priority?: "low" | "normal" | "high" | "critical";
+  expirationMs?: number;
+  reason?: string | ((args: unknown) => string);
+}
+```
+
+### ApprovalQueue
+
+```typescript
+interface ApprovalQueue {
+  enqueue(request: ApprovalRequest): Promise<void>;
+  dequeue(): Promise<ApprovalRequest | null>;
+  get(requestId: string): Promise<ApprovalRequest | null>;
+  listPending(limit?: number, offset?: number): Promise<ApprovalRequest[]>;
+  updateStatus(requestId: string, status: string, result?: ApprovalResult): Promise<void>;
+  remove(requestId: string): Promise<void>;
+  getStats(): Promise<QueueStats>;
+  clearExpired(): Promise<number>;
+}
+```
+
+## Configuration
+
+### Approval Options
+
+```typescript
+interface ApprovalOptions {
+  rules?: ApprovalRule[];
+  defaultExpirationMs?: number;
+  defaultPriority?: "low" | "normal" | "high" | "critical";
+  enableLogging?: boolean;
+  backend?: ApprovalBackend;
+  handler?: ApprovalHandler;
+  approvalTimeoutMs?: number;
+}
+```
+
+### Queue Config
+
+```typescript
+interface AdvancedQueueConfig {
+  enableLogging?: boolean;
+  maxQueueSize?: number;
+  enableDLQ?: boolean;
+  enableMetrics?: boolean;
+  retentionMs?: number;
+  batchSize?: number;
+  cleanupIntervalMs?: number;
+}
+```
+
+## Patterns
+
+### Pattern Matching
+
+Rules support multiple pattern types:
+
+```typescript
+// Wildcard pattern
+{
+  toolPattern: "delete*";
+} // Matches: deleteUser, deleteDatabase, etc.
+
+// Specific wildcard
+{
+  toolPattern: "*Database";
+} // Matches: createDatabase, dropDatabase, etc.
+
+// Regex pattern
+{
+  toolPattern: /^(create|update|delete)User$/;
+}
+
+// Exact match
+{
+  toolPattern: "specificTool";
+}
+```
+
+### Conditional Rules
+
+```typescript
+{
+  toolPattern: 'exportData',
+  condition: (args) => {
+    // Only require approval for large exports
+    return args.recordCount > 10000;
+  },
+  priority: 'high',
+}
+```
+
+## Best Practices
+
+1. **Rule Organization**: Group related rules and document their purpose
+2. **Priority Assignment**: Use critical only for sensitive operations
+3. **Expiration Handling**: Set appropriate expiration times for requests
+4. **Error Handling**: Wrap tool execution in try-catch blocks
+5. **Logging**: Enable logging during development, disable in production
+6. **Queue Monitoring**: Regularly check queue stats and DLQ
+7. **Audit Trails**: Implement proper audit logging for compliance
+8. **Rate Limiting**: Configure based on expected load
+9. **Retry Strategy**: Balance between reliability and latency
+10. **Handler Implementation**: Ensure approval handler is robust and fast
+
+## Performance Considerations
+
+### In-Memory Queue
+
+- Fast for single-process scenarios
+- Limited by available memory
+- Good for testing and development
+
+### Redis Queue
+
+- Suitable for distributed systems
+- Persistent across restarts
+- Better for production deployments
+- Additional latency from network calls
+
+### Middleware Chain
+
+- Minimal overhead for basic operations
+- Accumulates latency with multiple middlewares
+- Profile in production environments
+
+## Testing
+
+See `usage-example.ts` for comprehensive examples including:
+
+- Basic approval wrapping
+- Queue management
+- Rule evaluation
+- Complete middleware workflows
+- Rate limiting and retry logic
+- Dead letter queue handling
+
+## License
+
+Part of the AI Platform package. See main LICENSE file for details.

package/src/tools/approval/advanced-approval-queue.ts

@@ -0,0 +1,7 @@
+/**
+ * Advanced Approval Queue Implementations
+ * Re-exports from in-memory-queue and redis-queue modules
+ */
+export { InMemoryApprovalQueue, createInMemoryQueue } from './in-memory-queue';
+export type { AdvancedQueueConfig, QueueMetrics } from './in-memory-queue';
+export { RedisApprovalQueue, createRedisQueue } from './redis-queue';