outcome-cli 1.0.0

package/src/modules/omnibridge/execution/deterministic-logger.ts

@@ -0,0 +1,629 @@
+/**
+ * Deterministic Logger
+ *
+ * Records every DOM interaction for verification and audit purposes.
+ * Provides cryptographic proofs of action sequences and supports
+ * diff analysis between competing agents.
+ *
+ * Requirements: 7.3, 8.1, 8.2, 8.3, 8.4, 8.5, 8.6
+ */
+
+import { createHash } from 'node:crypto';
+import type {
+  ActionLogEntry,
+  VerificationProof,
+  DiffAnalysis,
+} from '../core/types.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Configuration for the Deterministic Logger.
+ */
+export interface DeterministicLoggerConfig {
+  /** Maximum number of screenshots to store per session */
+  maxScreenshotsPerSession: number;
+  /** Whether to capture screenshots at key decision points */
+  captureScreenshots: boolean;
+  /** Hash algorithm to use for verification proofs */
+  hashAlgorithm: 'sha256' | 'sha384' | 'sha512';
+}
+
+/**
+ * Result of logging an action.
+ */
+export interface LogActionResult {
+  /** Whether the action was logged successfully */
+  success: boolean;
+  /** The logged entry */
+  entry?: ActionLogEntry;
+  /** Error message if logging failed */
+  error?: string;
+}
+
+/**
+ * Result of generating a verification proof.
+ */
+export interface GenerateProofResult {
+  /** Whether proof generation succeeded */
+  success: boolean;
+  /** The generated proof */
+  proof?: VerificationProof;
+  /** Error message if generation failed */
+  error?: string;
+}
+
+/**
+ * Result of comparing two agents' action logs.
+ */
+export interface CompareAgentsResult {
+  /** Whether comparison succeeded */
+  success: boolean;
+  /** The diff analysis */
+  analysis?: DiffAnalysis;
+  /** Error message if comparison failed */
+  error?: string;
+}
+
+/**
+ * Key decision point types that trigger screenshot capture.
+ */
+export type KeyDecisionPoint =
+  | 'form_submit'
+  | 'navigation'
+  | 'authentication'
+  | 'data_extraction'
+  | 'error_recovery'
+  | 'mfa_challenge';
+
+/**
+ * Screenshot metadata.
+ */
+export interface ScreenshotMetadata {
+  /** Timestamp when screenshot was taken */
+  timestamp: number;
+  /** Session ID */
+  sessionId: string;
+  /** Action index that triggered the screenshot */
+  actionIndex: number;
+  /** Type of decision point */
+  decisionPoint: KeyDecisionPoint;
+  /** Intent ID of the element involved */
+  intentId: string;
+}
+
+// =============================================================================
+// Default Configuration
+// =============================================================================
+
+const DEFAULT_CONFIG: DeterministicLoggerConfig = {
+  maxScreenshotsPerSession: 50,
+  captureScreenshots: true,
+  hashAlgorithm: 'sha256',
+};
+
+// =============================================================================
+// Deterministic Logger Implementation
+// =============================================================================
+
+/**
+ * Deterministic Logger for recording and verifying agent actions.
+ */
+export class DeterministicLogger {
+  private config: DeterministicLoggerConfig;
+  private logs: Map<string, ActionLogEntry[]>;
+  private screenshots: Map<string, ScreenshotMetadata[]>;
+
+  constructor(config: Partial<DeterministicLoggerConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.logs = new Map();
+    this.screenshots = new Map();
+  }
+
+  // ===========================================================================
+  // Action Logging
+  // ===========================================================================
+
+  /**
+   * Log a DOM interaction action.
+   *
+   * Requirements: 7.3, 8.1, 8.3
+   */
+  logAction(entry: Omit<ActionLogEntry, 'timestamp'>): LogActionResult {
+    try {
+      // Validate required fields
+      if (!entry.sessionId || !entry.intentId || !entry.action) {
+        return {
+          success: false,
+          error: 'Missing required fields: sessionId, intentId, or action',
+        };
+      }
+
+      // Create the complete entry with timestamp
+      const completeEntry: ActionLogEntry = {
+        ...entry,
+        timestamp: Date.now(),
+      };
+
+      // Get or create the log for this session
+      const sessionLog = this.logs.get(entry.sessionId) || [];
+      sessionLog.push(completeEntry);
+      this.logs.set(entry.sessionId, sessionLog);
+
+      // Track screenshot if present
+      if (completeEntry.screenshot && this.config.captureScreenshots) {
+        this.trackScreenshot(completeEntry, sessionLog.length - 1);
+      }
+
+      return {
+        success: true,
+        entry: completeEntry,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  /**
+   * Log an action with a screenshot at a key decision point.
+   *
+   * Requirements: 8.3
+   */
+  logActionWithScreenshot(
+    entry: Omit<ActionLogEntry, 'timestamp'>,
+    screenshot: string,
+    _decisionPoint: KeyDecisionPoint
+  ): LogActionResult {
+    // Check screenshot limit
+    const sessionScreenshots = this.screenshots.get(entry.sessionId) || [];
+    if (sessionScreenshots.length >= this.config.maxScreenshotsPerSession) {
+      // Log without screenshot if limit reached
+      return this.logAction(entry);
+    }
+
+    return this.logAction({
+      ...entry,
+      screenshot,
+    });
+  }
+
+  /**
+   * Track screenshot metadata.
+   */
+  private trackScreenshot(entry: ActionLogEntry, actionIndex: number): void {
+    const metadata: ScreenshotMetadata = {
+      timestamp: entry.timestamp,
+      sessionId: entry.sessionId,
+      actionIndex,
+      decisionPoint: this.inferDecisionPoint(entry),
+      intentId: entry.intentId,
+    };
+
+    const sessionScreenshots = this.screenshots.get(entry.sessionId) || [];
+    sessionScreenshots.push(metadata);
+    this.screenshots.set(entry.sessionId, sessionScreenshots);
+  }
+
+  /**
+   * Infer the decision point type from an action entry.
+   */
+  private inferDecisionPoint(entry: ActionLogEntry): KeyDecisionPoint {
+    const intentLower = entry.intentId.toLowerCase();
+
+    if (intentLower.includes('submit') || intentLower.includes('form')) {
+      return 'form_submit';
+    }
+    if (entry.action === 'navigate' || intentLower.includes('nav')) {
+      return 'navigation';
+    }
+    if (intentLower.includes('login') || intentLower.includes('auth')) {
+      return 'authentication';
+    }
+    if (entry.action === 'extract' || intentLower.includes('data')) {
+      return 'data_extraction';
+    }
+    if (intentLower.includes('mfa') || intentLower.includes('2fa')) {
+      return 'mfa_challenge';
+    }
+    if (entry.result === 'failure') {
+      return 'error_recovery';
+    }
+
+    return 'data_extraction'; // Default
+  }
+
+  /**
+   * Get the action log for a session.
+   *
+   * Requirements: 7.3, 8.1
+   */
+  getLog(sessionId: string): ActionLogEntry[] {
+    return this.logs.get(sessionId) || [];
+  }
+
+  /**
+   * Get all screenshots for a session.
+   */
+  getScreenshots(sessionId: string): string[] {
+    const log = this.getLog(sessionId);
+    return log
+      .filter((entry) => entry.screenshot)
+      .map((entry) => entry.screenshot!);
+  }
+
+  /**
+   * Get screenshot metadata for a session.
+   */
+  getScreenshotMetadata(sessionId: string): ScreenshotMetadata[] {
+    return this.screenshots.get(sessionId) || [];
+  }
+
+  // ===========================================================================
+  // Cryptographic Proof Generation
+  // ===========================================================================
+
+  /**
+   * Generate a cryptographic proof of the action sequence.
+   *
+   * Requirements: 8.2
+   */
+  generateProof(sessionId: string, claimedResult: unknown): GenerateProofResult {
+    try {
+      const log = this.getLog(sessionId);
+
+      if (log.length === 0) {
+        return {
+          success: false,
+          error: `No action log found for session: ${sessionId}`,
+        };
+      }
+
+      // Generate hash of the action sequence
+      const hash = this.hashActionSequence(log);
+
+      // Get screenshots at key decision points
+      const screenshots = this.getScreenshots(sessionId);
+
+      // Check if claimed result matches actions
+      const resultMatchesActions = this.validateResultAgainstActions(
+        claimedResult,
+        log
+      );
+
+      const proof: VerificationProof = {
+        sessionId,
+        actionCount: log.length,
+        hash,
+        screenshots,
+        claimedResult,
+        resultMatchesActions,
+      };
+
+      return {
+        success: true,
+        proof,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  /**
+   * Hash an action sequence to create a cryptographic proof.
+   *
+   * Requirements: 8.2
+   */
+  hashActionSequence(log: ActionLogEntry[]): string {
+    // Create a deterministic string representation of the action sequence
+    const serialized = log
+      .map((entry) => this.serializeActionEntry(entry))
+      .join('|');
+
+    // Generate hash
+    const hash = createHash(this.config.hashAlgorithm);
+    hash.update(serialized);
+    return hash.digest('hex');
+  }
+
+  /**
+   * Serialize an action entry for hashing.
+   * Excludes screenshots and timestamps to keep hash deterministic and focused on actions.
+   */
+  private serializeActionEntry(entry: ActionLogEntry): string {
+    return JSON.stringify({
+      // Note: timestamp excluded for deterministic hashing
+      sessionId: entry.sessionId,
+      action: entry.action,
+      intentId: entry.intentId,
+      value: entry.value,
+      result: entry.result,
+    });
+  }
+
+  /**
+   * Validate that a claimed result can be derived from the action log.
+   *
+   * Requirements: 8.5
+   */
+  validateResultAgainstActions(
+    claimedResult: unknown,
+    log: ActionLogEntry[]
+  ): boolean {
+    // If no result claimed, it's valid (no claim to verify)
+    if (claimedResult === null || claimedResult === undefined) {
+      return true;
+    }
+
+    // If no actions, result cannot be derived
+    if (log.length === 0) {
+      return false;
+    }
+
+    // Check for extract actions that could produce the result
+    const extractActions = log.filter((entry) => entry.action === 'extract');
+
+    // If claiming data but no extract actions, it's a hallucination
+    if (typeof claimedResult === 'object' && extractActions.length === 0) {
+      // Check if result contains data fields
+      const resultObj = claimedResult as Record<string, unknown>;
+      const hasDataFields =
+        'data' in resultObj ||
+        Object.keys(resultObj).some(
+          (key) =>
+            !['metadata', 'verificationHash', 'confidence'].includes(key)
+        );
+
+      if (hasDataFields) {
+        return false;
+      }
+    }
+
+    // Check for failed actions that would prevent result
+    const failedActions = log.filter((entry) => entry.result === 'failure');
+    const successfulActions = log.filter((entry) => entry.result === 'success');
+
+    // If all actions failed, result cannot be valid
+    if (successfulActions.length === 0 && failedActions.length > 0) {
+      return false;
+    }
+
+    // Basic validation passed
+    return true;
+  }
+
+  /**
+   * Verify that a proof hash matches the current action log.
+   *
+   * Requirements: 8.2
+   */
+  verifyProof(proof: VerificationProof): boolean {
+    const log = this.getLog(proof.sessionId);
+
+    if (log.length !== proof.actionCount) {
+      return false;
+    }
+
+    const currentHash = this.hashActionSequence(log);
+    return currentHash === proof.hash;
+  }
+
+  // ===========================================================================
+  // Diff Analysis
+  // ===========================================================================
+
+  /**
+   * Compare action logs of two agents to find divergence.
+   *
+   * Requirements: 8.4
+   */
+  compareAgents(agentASessionId: string, agentBSessionId: string): CompareAgentsResult {
+    try {
+      const logA = this.getLog(agentASessionId);
+      const logB = this.getLog(agentBSessionId);
+
+      if (logA.length === 0 && logB.length === 0) {
+        return {
+          success: false,
+          error: 'Both agents have empty action logs',
+        };
+      }
+
+      // Find divergence point
+      const divergencePoint = this.findDivergencePoint(logA, logB);
+
+      // Get paths from divergence
+      const agentAPath = logA.slice(divergencePoint);
+      const agentBPath = logB.slice(divergencePoint);
+
+      // Determine recommendation
+      const recommendation = this.determineRecommendation(
+        logA,
+        logB,
+        divergencePoint
+      );
+
+      const analysis: DiffAnalysis = {
+        divergencePoint,
+        agentAPath,
+        agentBPath,
+        recommendation,
+      };
+
+      return {
+        success: true,
+        analysis,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  /**
+   * Find the index where two action logs diverge.
+   */
+  private findDivergencePoint(
+    logA: ActionLogEntry[],
+    logB: ActionLogEntry[]
+  ): number {
+    const minLength = Math.min(logA.length, logB.length);
+
+    for (let i = 0; i < minLength; i++) {
+      if (!this.actionsMatch(logA[i], logB[i])) {
+        return i;
+      }
+    }
+
+    // If one log is longer, divergence is at the end of the shorter one
+    if (logA.length !== logB.length) {
+      return minLength;
+    }
+
+    // Logs are identical
+    return logA.length;
+  }
+
+  /**
+   * Check if two action entries match (ignoring timestamps).
+   */
+  private actionsMatch(a: ActionLogEntry, b: ActionLogEntry): boolean {
+    return (
+      a.action === b.action &&
+      a.intentId === b.intentId &&
+      a.value === b.value &&
+      a.result === b.result
+    );
+  }
+
+  /**
+   * Determine recommendation based on action log analysis.
+   */
+  private determineRecommendation(
+    logA: ActionLogEntry[],
+    logB: ActionLogEntry[],
+    divergencePoint: number
+  ): 'agent_a' | 'agent_b' | 'tie' | 'both_invalid' {
+    // Count successful actions after divergence
+    const successA = logA
+      .slice(divergencePoint)
+      .filter((e) => e.result === 'success').length;
+    const successB = logB
+      .slice(divergencePoint)
+      .filter((e) => e.result === 'success').length;
+
+    // Count failures
+    const failuresA = logA.filter((e) => e.result === 'failure').length;
+    const failuresB = logB.filter((e) => e.result === 'failure').length;
+
+    // If both have only failures, both invalid
+    if (
+      logA.every((e) => e.result === 'failure') &&
+      logB.every((e) => e.result === 'failure')
+    ) {
+      return 'both_invalid';
+    }
+
+    // If one has all failures, the other wins
+    if (logA.every((e) => e.result === 'failure')) {
+      return 'agent_b';
+    }
+    if (logB.every((e) => e.result === 'failure')) {
+      return 'agent_a';
+    }
+
+    // Compare success rates
+    if (successA > successB) {
+      return 'agent_a';
+    }
+    if (successB > successA) {
+      return 'agent_b';
+    }
+
+    // If equal successes, prefer fewer failures
+    if (failuresA < failuresB) {
+      return 'agent_a';
+    }
+    if (failuresB < failuresA) {
+      return 'agent_b';
+    }
+
+    // Truly tied
+    return 'tie';
+  }
+
+  // ===========================================================================
+  // Utility Methods
+  // ===========================================================================
+
+  /**
+   * Clear the log for a session.
+   */
+  clearLog(sessionId: string): void {
+    this.logs.delete(sessionId);
+    this.screenshots.delete(sessionId);
+  }
+
+  /**
+   * Clear all logs.
+   */
+  clearAll(): void {
+    this.logs.clear();
+    this.screenshots.clear();
+  }
+
+  /**
+   * Get the total number of actions logged across all sessions.
+   */
+  getTotalActionCount(): number {
+    let total = 0;
+    for (const log of this.logs.values()) {
+      total += log.length;
+    }
+    return total;
+  }
+
+  /**
+   * Get all session IDs with logs.
+   */
+  getSessionIds(): string[] {
+    return Array.from(this.logs.keys());
+  }
+
+  /**
+   * Check if a session has any logged actions.
+   */
+  hasLog(sessionId: string): boolean {
+    const log = this.logs.get(sessionId);
+    return log !== undefined && log.length > 0;
+  }
+
+  /**
+   * Get the configuration.
+   */
+  getConfig(): DeterministicLoggerConfig {
+    return { ...this.config };
+  }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/**
+ * Create a new Deterministic Logger instance.
+ */
+export function createDeterministicLogger(
+  config: Partial<DeterministicLoggerConfig> = {}
+): DeterministicLogger {
+  return new DeterministicLogger(config);
+}