@game_ryo/lsji 0.1.1 → 0.3.0

package/src/execution/hitl/approval-gate.js

@@ -0,0 +1,210 @@
+/**
+ * HITL Approval Gate
+ * 
+ * Human-in-the-Loop approval workflow for sensitive operations.
+ * Integrates with storage, notifier, and provides timeout/escalation.
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { ApprovalStore, createApprovalStore } from './store.js';
+import { Notifier } from './notifier.js';
+
+/**
+ * Approval request options
+ * @typedef {Object} ApprovalRequest
+ * @property {string} action - Action identifier (e.g., 'send_email', 'charge_payment')
+ * @property {Object} context - Context data for human review
+ * @property {string} requester - Who is requesting approval
+ * @property {number} [timeout] - Timeout in ms (default: 5 min)
+ * @property {Array<string>} [channels] - Notification channels
+ * @property {Object} [metadata] - Additional metadata
+ */
+
+/**
+ * Approval result
+ * @typedef {Object} ApprovalResult
+ * @property {string} id - Approval ID
+ * @property {string} status - 'approved' | 'rejected' | 'expired'
+ * @property {string} [decider] - Who decided
+ * @property {string} [reason] - Reason for decision
+ * @property {Date} decidedAt - When decision was made
+ */
+
+/**
+ * Approval Gate - Manages human approval workflows
+ */
+export class ApprovalGate {
+  constructor({ store, notifier, defaultTimeout = 300000 } = {}) {
+    this.store = store;
+    this.notifier = notifier;
+    this.defaultTimeout = defaultTimeout;
+    this.pendingApprovals = new Map(); // id -> { resolve, reject, timeout }
+  }
+
+  /**
+   * Request approval for an action
+   * Returns a promise that resolves when approved, rejects when rejected/expired
+   */
+  async requestApproval(request) {
+    const id = uuidv4();
+    const createdAt = new Date();
+    const expiresAt = new Date(createdAt.getTime() + (request.timeout || this.defaultTimeout));
+    
+    const approval = {
+      id,
+      action: request.action,
+      context: request.context,
+      requester: request.requester,
+      status: 'pending',
+      createdAt: createdAt.toISOString(),
+      expiresAt: expiresAt.toISOString(),
+      metadata: request.metadata,
+    };
+    
+    // Store in database
+    await this.store.createApproval(approval);
+    
+    // Notify via configured channels
+    await this.notifier.notify(approval, request.channels);
+    
+    // Return promise that resolves when decision is made
+    return new Promise((resolve, reject) => {
+      const timeoutHandle = setTimeout(async () => {
+        // Check if still pending (not decided yet)
+        const current = await this.store.getApproval(id);
+        if (current && current.status === 'pending') {
+          await this.store.updateStatus(id, 'expired', null, 'Timeout');
+          this.pendingApprovals.delete(id);
+          reject(new Error(`Approval timeout: ${id}`));
+        }
+      }, request.timeout || this.defaultTimeout);
+      
+      this.pendingApprovals.set(id, { resolve, reject, timeout: timeoutHandle });
+    });
+  }
+
+  /**
+   * Approve a pending request
+   */
+  async approve(id, { decider, reason } = {}) {
+    const result = await this.store.approve(id, { decider, reason });
+    
+    // Resolve pending promise
+    const pending = this.pendingApprovals.get(id);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      pending.resolve(result);
+      this.pendingApprovals.delete(id);
+    }
+    
+    // Notify
+    await this.notifier.notify({ ...result, status: 'approved' });
+    
+    return result;
+  }
+
+  /**
+   * Reject a pending request
+   */
+  async reject(id, { decider, reason } = {}) {
+    const result = await this.store.reject(id, { decider, reason });
+    
+    // Reject pending promise
+    const pending = this.pendingApprovals.get(id);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error(`Approval rejected: ${reason || 'No reason provided'}`));
+      this.pendingApprovals.delete(id);
+    }
+    
+    // Notify
+    await this.notifier.notify({ ...result, status: 'rejected' });
+    
+    return result;
+  }
+
+  /**
+   * Get approval status
+   */
+  async getApproval(id) {
+    return this.store.getApproval(id);
+  }
+
+  /**
+   * Get all pending approvals
+   */
+  async getPendingApprovals(limit = 100) {
+    return this.store.getPendingApprovals(limit);
+  }
+
+  /**
+   * Get approvals by requester
+   */
+  async getApprovalsByRequester(requester, limit = 100) {
+    return this.store.getApprovalsByRequester(requester, limit);
+  }
+
+  /**
+   * Clean up expired approvals
+   */
+  async cleanup() {
+    await this.store.cleanupExpired();
+  }
+
+  /**
+   * Check if action requires approval
+   * Override this to define custom approval rules
+   */
+  requiresApproval(action, context = {}) {
+    // Default: require approval for sensitive actions
+    const sensitiveActions = [
+      'send_email',
+      'charge_payment',
+      'delete_data',
+      'modify_user',
+      'deploy_code',
+      'run_sql',
+      'api_call',
+      'file_write',
+      'ssh_command',
+    ];
+    
+    return sensitiveActions.includes(action);
+  }
+
+  /**
+   * Execute action with automatic approval if needed
+   */
+  async executeWithApproval(action, context, executor, requester = 'agent') {
+    if (!this.requiresApproval(action, context)) {
+      return executor();
+    }
+    
+    // Request approval
+    const approval = await this.requestApproval({
+      action,
+      context,
+      requester,
+    });
+    
+    if (approval.status === 'approved') {
+      return executor();
+    } else {
+      throw new Error(`Action ${action} was ${approval.status}`);
+    }
+  }
+}
+
+/**
+ * Create approval gate from config
+ */
+export async function createApprovalGate(config = {}) {
+  const store = await createApprovalStore(config.store || {});
+  const notifier = new Notifier(config.notifier || {});
+  
+  return new ApprovalGate({
+    store,
+    notifier,
+    defaultTimeout: config.defaultTimeout,
+  });
+}

package/src/execution/hitl/index.js

@@ -0,0 +1,12 @@
+/**
+ * HITL (Human-in-the-Loop) System
+ * 
+ * Exports all HITL components:
+ * - ApprovalStore: Persistent storage for approvals
+ * - Notifier: Multi-channel notifications
+ * - ApprovalGate: Approval workflow management
+ */
+
+export { ApprovalStore, createApprovalStore } from './store.js';
+export { Notifier, NotificationChannel, createNotifier } from './notifier.js';
+export { ApprovalGate, createApprovalGate } from './approval-gate.js';

package/src/execution/hitl/notifier.js

@@ -0,0 +1,151 @@
+/**
+ * HITL Notifier
+ * 
+ * Multi-channel notification system for approval requests.
+ * Supports console, webhook, email, and custom handlers.
+ */
+
+/**
+ * Notification channels
+ */
+export const NotificationChannel = {
+  CONSOLE: 'console',
+  WEBHOOK: 'webhook',
+  EMAIL: 'email',
+  CUSTOM: 'custom',
+};
+
+/**
+ * Notifier - Sends approval notifications via multiple channels
+ */
+export class Notifier {
+  constructor(config = {}) {
+    this.channels = new Map();
+    this.defaultChannels = config.defaultChannels || [NotificationChannel.CONSOLE];
+    
+    // Register built-in channels
+    this.registerChannel(NotificationChannel.CONSOLE, this.notifyConsole.bind(this));
+    
+    if (config.webhookUrl) {
+      this.registerChannel(NotificationChannel.WEBHOOK, this.notifyWebhook.bind(this, config.webhookUrl));
+    }
+    
+    if (config.emailConfig) {
+      this.registerChannel(NotificationChannel.EMAIL, this.notifyEmail.bind(this, config.emailConfig));
+    }
+    
+    // Register custom channels
+    if (config.customChannels) {
+      for (const [name, handler] of Object.entries(config.customChannels)) {
+        this.registerChannel(name, handler);
+      }
+    }
+  }
+
+  /**
+   * Register a notification channel
+   */
+  registerChannel(name, handler) {
+    this.channels.set(name, handler);
+  }
+
+  /**
+   * Unregister a channel
+   */
+  unregisterChannel(name) {
+    this.channels.delete(name);
+  }
+
+  /**
+   * Send notification to all configured channels
+   */
+  async notify(approval, channels = this.defaultChannels) {
+    const results = [];
+    
+    for (const channel of channels) {
+      const handler = this.channels.get(channel);
+      if (handler) {
+        try {
+          await handler(approval);
+          results.push({ channel, success: true });
+        } catch (error) {
+          results.push({ channel, success: false, error: error.message });
+        }
+      } else {
+        results.push({ channel, success: false, error: 'Channel not registered' });
+      }
+    }
+    
+    return results;
+  }
+
+  /**
+   * Console notification (built-in)
+   */
+  async notifyConsole(approval) {
+    const status = approval.status === 'pending' ? '⏳ PENDING' : 
+                   approval.status === 'approved' ? '✅ APPROVED' : 
+                   approval.status === 'rejected' ? '❌ REJECTED' : '⏰ EXPIRED';
+    
+    console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║  HITL Approval ${status.padEnd(50)}║
+╠══════════════════════════════════════════════════════════════╣
+║  ID:        ${approval.id.padEnd(50)}║
+║  Action:    ${approval.action.padEnd(50)}║
+║  Requester: ${approval.requester.padEnd(50)}║
+║  Status:    ${status.padEnd(50)}║
+║  Created:   ${new Date(approval.createdAt).toLocaleString().padEnd(50)}║
+${approval.expiresAt ? `║  Expires:   ${new Date(approval.expiresAt).toLocaleString().padEnd(50)}║` : ''}
+${approval.context ? `║  Context:   ${JSON.stringify(approval.context).substring(0, 48).padEnd(50)}║` : ''}
+╚══════════════════════════════════════════════════════════════╝
+    `);
+  }
+
+  /**
+   * Webhook notification (built-in)
+   */
+  async notifyWebhook(webhookUrl, approval) {
+    const payload = {
+      type: 'hitl_approval',
+      approval: {
+        id: approval.id,
+        action: approval.action,
+        context: approval.context,
+        requester: approval.requester,
+        status: approval.status,
+        createdAt: approval.createdAt,
+        expiresAt: approval.expiresAt,
+      },
+      timestamp: new Date().toISOString(),
+    };
+    
+    const response = await fetch(webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    
+    if (!response.ok) {
+      throw new Error(`Webhook failed: ${response.status} ${response.statusText}`);
+    }
+  }
+
+  /**
+   * Email notification (built-in - requires email service)
+   */
+  async notifyEmail(emailConfig, approval) {
+    // This is a placeholder - integrate with actual email service
+    // Example: SendGrid, Mailgun, AWS SES, etc.
+    console.log(`[EMAIL] Would send approval notification to ${emailConfig.to}`);
+    console.log(`Subject: [LSJI] Approval ${approval.status}: ${approval.action}`);
+    console.log(`Body: Approval ${approval.id} requires your attention`);
+  }
+}
+
+/**
+ * Create notifier from config
+ */
+export function createNotifier(config = {}) {
+  return new Notifier(config);
+}

package/src/execution/hitl/store.js

@@ -0,0 +1,311 @@
+/**
+ * Approval Store
+ * 
+ * Persistent storage for approval requests and decisions.
+ * Uses the existing storage abstraction.
+ */
+
+import { createStorage } from '../../index.js';
+
+/**
+ * Approval request record
+ * @typedef {Object} ApprovalRecord
+ * @property {string} id - Unique approval ID
+ * @property {string} action - Action requiring approval
+ * @property {Object} context - Context data for the action
+ * @property {string} requester - Who requested the approval
+ * @property {string} status - 'pending' | 'approved' | 'rejected' | 'expired'
+ * @property {Date} createdAt - When request was created
+ * @property {Date} [expiresAt] - When request expires
+ * @property {Date} [decidedAt] - When decision was made
+ * @property {string} [decider] - Who made the decision
+ * @property {string} [reason] - Reason for approval/rejection
+ * @property {Object} [metadata] - Additional metadata
+ */
+
+/**
+ * Approval Store - Manages approval requests in storage
+ */
+export class ApprovalStore {
+  constructor(storage) {
+    this.storage = storage;
+    this.initialized = false;
+  }
+
+  /**
+   * Check if storage is SQL-based (has db with all method)
+   */
+  isSqlStorage() {
+    return this.storage.db && typeof this.storage.db.all === 'function';
+  }
+
+  /**
+   * Initialize the approval table
+   */
+  async initialize() {
+    if (this.initialized) return;
+    
+    // Create approvals table if using SQL storage
+    if (this.isSqlStorage()) {
+      await this.storage.db.exec(`
+        CREATE TABLE IF NOT EXISTS approvals (
+          id TEXT PRIMARY KEY,
+          action TEXT NOT NULL,
+          context TEXT NOT NULL,
+          requester TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'pending',
+          created_at TEXT NOT NULL,
+          expires_at TEXT,
+          decided_at TEXT,
+          decider TEXT,
+          reason TEXT,
+          metadata TEXT
+        )
+      `);
+      
+      // Create index for pending approvals
+      await this.storage.db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_approvals_status ON approvals(status)
+      `);
+      
+      await this.storage.db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_approvals_created ON approvals(created_at)
+      `);
+    }
+    
+    this.initialized = true;
+  }
+
+  /**
+   * Create a new approval request
+   */
+  async createApproval(approval) {
+    await this.initialize();
+    
+    const record = {
+      id: approval.id,
+      action: approval.action,
+      context: JSON.stringify(approval.context),
+      requester: approval.requester,
+      status: 'pending',
+      createdAt: approval.createdAt || new Date().toISOString(),
+      expiresAt: approval.expiresAt?.toISOString() || null,
+      decidedAt: null,
+      decider: null,
+      reason: null,
+      metadata: approval.metadata ? JSON.stringify(approval.metadata) : null,
+    };
+    
+    if (this.isSqlStorage()) {
+      await this.storage.db.run(
+        `INSERT INTO approvals (id, action, context, requester, status, created_at, expires_at, decided_at, decider, reason, metadata)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [record.id, record.action, record.context, record.requester, record.status,
+         record.createdAt, record.expiresAt, record.decidedAt, record.decider, record.reason, record.metadata]
+      );
+    } else {
+      // Fallback for memory storage
+      if (!this.memoryApprovals) this.memoryApprovals = new Map();
+      this.memoryApprovals.set(record.id, record);
+    }
+    
+    return record;
+  }
+
+  /**
+   * Get approval by ID
+   */
+  async getApproval(id) {
+    await this.initialize();
+    
+    if (this.isSqlStorage()) {
+      const row = await this.storage.db.get('SELECT * FROM approvals WHERE id = ?', [id]);
+      if (!row) return null;
+      return this.rowToRecord(row);
+    } else {
+      return this.memoryApprovals?.get(id) || null;
+    }
+  }
+
+  /**
+   * Get pending approvals
+   */
+  async getPendingApprovals(limit = 100) {
+    await this.initialize();
+    
+    if (this.isSqlStorage()) {
+      const rows = await this.storage.db.all(
+        'SELECT * FROM approvals WHERE status = ? ORDER BY created_at DESC LIMIT ?',
+        ['pending', limit]
+      );
+      return rows.map(r => this.rowToRecord(r));
+    } else {
+      const approvals = [];
+      for (const record of this.memoryApprovals?.values() || []) {
+        if (record.status === 'pending') {
+          approvals.push(record);
+        }
+      }
+      return approvals.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt)).slice(0, limit);
+    }
+  }
+
+  /**
+   * Get approvals by requester
+   */
+  async getApprovalsByRequester(requester, limit = 100) {
+    await this.initialize();
+    
+    if (this.isSqlStorage()) {
+      const rows = await this.storage.db.all(
+        'SELECT * FROM approvals WHERE requester = ? ORDER BY created_at DESC LIMIT ?',
+        [requester, limit]
+      );
+      return rows.map(r => this.rowToRecord(r));
+    } else {
+      const approvals = [];
+      for (const record of this.memoryApprovals?.values() || []) {
+        if (record.requester === requester) {
+          approvals.push(record);
+        }
+      }
+      return approvals.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt)).slice(0, limit);
+    }
+  }
+
+  /**
+   * Update approval status (approve/reject)
+   */
+  async decideApproval(id, { status, decider, reason }) {
+    await this.initialize();
+    
+    const validStatuses = ['approved', 'rejected'];
+    if (!validStatuses.includes(status)) {
+      throw new Error(`Invalid status: ${status}. Must be 'approved' or 'rejected'`);
+    }
+    
+    const record = await this.getApproval(id);
+    if (!record) {
+      throw new Error(`Approval not found: ${id}`);
+    }
+    
+    if (record.status !== 'pending') {
+      throw new Error(`Approval already decided: ${record.status}`);
+    }
+    
+    // Check expiration
+    if (record.expiresAt && new Date(record.expiresAt) < new Date()) {
+      await this.updateStatus(id, 'expired', null, 'Expired');
+      throw new Error('Approval request has expired');
+    }
+    
+    const decidedAt = new Date().toISOString();
+    
+    if (this.isSqlStorage()) {
+      await this.storage.db.run(
+        `UPDATE approvals SET status = ?, decided_at = ?, decider = ?, reason = ? WHERE id = ?`,
+        [status, decidedAt, decider, reason, id]
+      );
+    } else {
+      record.status = status;
+      record.decidedAt = decidedAt;
+      record.decider = decider;
+      record.reason = reason;
+      this.memoryApprovals.set(id, record);
+    }
+    
+    return { ...record, status, decidedAt, decider, reason };
+  }
+
+  /**
+   * Approve a request
+   */
+  async approve(id, { decider, reason } = {}) {
+    return this.decideApproval(id, { status: 'approved', decider, reason });
+  }
+
+  /**
+   * Reject a request
+   */
+  async reject(id, { decider, reason } = {}) {
+    return this.decideApproval(id, { status: 'rejected', decider, reason });
+  }
+
+  /**
+   * Update status (internal)
+   */
+  async updateStatus(id, status, decider = null, reason = null) {
+    await this.initialize();
+    
+    if (this.isSqlStorage()) {
+      await this.storage.db.run(
+        `UPDATE approvals SET status = ?, decided_at = ?, decider = ?, reason = ? WHERE id = ?`,
+        [status, new Date().toISOString(), decider, reason, id]
+      );
+    } else {
+      const record = this.memoryApprovals?.get(id);
+      if (record) {
+        record.status = status;
+        record.decidedAt = new Date().toISOString();
+        record.decider = decider;
+        record.reason = reason;
+        this.memoryApprovals.set(id, record);
+      }
+    }
+  }
+
+  /**
+   * Clean up expired approvals
+   */
+  async cleanupExpired() {
+    await this.initialize();
+    
+    const now = new Date().toISOString();
+    
+    if (this.isSqlStorage()) {
+      await this.storage.db.run(
+        `UPDATE approvals SET status = 'expired' WHERE status = 'pending' AND expires_at < ?`,
+        [now]
+      );
+    } else {
+      for (const record of this.memoryApprovals?.values() || []) {
+        if (record.status === 'pending' && record.expiresAt && new Date(record.expiresAt) < new Date()) {
+          record.status = 'expired';
+          this.memoryApprovals.set(record.id, record);
+        }
+      }
+    }
+  }
+
+  /**
+   * Convert database row to record
+   */
+  rowToRecord(row) {
+    return {
+      id: row.id,
+      action: row.action,
+      context: JSON.parse(row.context),
+      requester: row.requester,
+      status: row.status,
+      createdAt: row.created_at,
+      expiresAt: row.expires_at,
+      decidedAt: row.decided_at,
+      decider: row.decider,
+      reason: row.reason,
+      metadata: row.metadata ? JSON.parse(row.metadata) : null,
+    };
+  }
+}
+
+/**
+ * Create approval store from storage config
+ */
+export async function createApprovalStore(storageConfig = {}) {
+  const storage = await createStorage(
+    storageConfig.type || 'sqlite',
+    storageConfig.options || {}
+  );
+  const store = new ApprovalStore(storage);
+  await store.initialize();
+  return store;
+}