outcome-cli 1.0.0

package/src/modules/omnibridge/core/types.ts

@@ -0,0 +1,610 @@
+/**
+ * OmniBridge Core Types
+ *
+ * Type definitions for the Semantic Engine that powers deterministic
+ * web-agency within the WAIESL ecosystem.
+ *
+ * Requirements: 1.1, 2.1, 3.4
+ */
+
+// =============================================================================
+// Intent Document Types (Semantic Normalizer Output)
+// =============================================================================
+
+/**
+ * Semantic identifier for DOM elements.
+ * Replaces CSS selectors with semantic meaning.
+ *
+ * Example: "ACTION_ID:SUBMIT_PURCHASE" instead of "<button class='blue-400'>"
+ */
+export interface IntentId {
+  /** Category of the element's purpose */
+  category: 'ACTION' | 'INPUT' | 'DISPLAY' | 'NAV';
+  /** Specific purpose (e.g., "SUBMIT_PURCHASE", "LOGIN", "SEARCH") */
+  purpose: string;
+  /** Confidence score for the assigned intent (0-1) */
+  confidence: number;
+}
+
+/**
+ * A single element in the Intent Document.
+ * Contains semantic information only - no CSS selectors.
+ */
+export interface IntentElement {
+  /** Semantic identifier (e.g., "ACTION_ID:SUBMIT_PURCHASE") */
+  intentId: string;
+  /** Role of the element in the page */
+  role: 'action' | 'input' | 'display' | 'navigation';
+  /** Human-readable label */
+  label: string;
+  /** ARIA role if present */
+  ariaRole?: string;
+  /** Nearby text for disambiguation */
+  contextHints: string[];
+  /** Original element tag name for reference */
+  tagName: string;
+}
+
+
+/**
+ * Form field information extracted from the DOM.
+ */
+export interface IntentFormField {
+  /** Semantic identifier for the field */
+  intentId: string;
+  /** Field name attribute */
+  name: string;
+  /** Field type (text, email, password, etc.) */
+  type: string;
+  /** Human-readable label */
+  label: string;
+  /** Whether the field is required */
+  required: boolean;
+  /** Validation rules if present */
+  validationRules?: string[];
+  /** Placeholder text */
+  placeholder?: string;
+}
+
+/**
+ * Form structure extracted from the DOM.
+ */
+export interface IntentForm {
+  /** Semantic identifier for the form */
+  intentId: string;
+  /** Form action URL */
+  action?: string;
+  /** HTTP method */
+  method: 'GET' | 'POST';
+  /** Fields in the form */
+  fields: IntentFormField[];
+  /** Submit button intent ID */
+  submitButtonId?: string;
+}
+
+/**
+ * Navigation structure extracted from the DOM.
+ */
+export interface IntentNavigation {
+  /** Primary navigation links */
+  primaryLinks: Array<{
+    intentId: string;
+    label: string;
+    href: string;
+  }>;
+  /** Breadcrumb trail if present */
+  breadcrumbs?: Array<{
+    label: string;
+    href?: string;
+  }>;
+}
+
+/**
+ * The complete Intent Document - output of Semantic Normalizer.
+ * This is what agents see instead of raw HTML.
+ */
+export interface IntentDocument {
+  /** All semantic elements on the page */
+  elements: IntentElement[];
+  /** Forms extracted from the page */
+  forms: IntentForm[];
+  /** Navigation structure */
+  navigation: IntentNavigation;
+  /** Time to build this document in milliseconds (target: <100ms) */
+  buildTimeMs: number;
+  /** Token reduction percentage achieved (target: 90%) */
+  tokenReduction: number;
+  /** Original URL of the page */
+  sourceUrl: string;
+  /** Timestamp when document was created */
+  createdAt: number;
+}
+
+
+// =============================================================================
+// Triangulation Engine Types (Self-Healing Anchors)
+// =============================================================================
+
+/**
+ * Spatial anchor - position-based element identification.
+ */
+export interface SpatialAnchor {
+  /** Region of the page where element is located */
+  region: 'header' | 'main' | 'sidebar' | 'footer';
+  /** Normalized position (0-1 for both x and y) */
+  relativePosition: { x: number; y: number };
+  /** Nearby landmark elements for reference */
+  nearbyLandmarks: string[];
+}
+
+/**
+ * Semantic anchor - meaning-based element identification.
+ */
+export interface SemanticAnchor {
+  /** Semantic identifier */
+  intentId: string;
+  /** Associated labels */
+  labels: string[];
+  /** ARIA roles */
+  ariaRoles: string[];
+  /** Text content of the element */
+  textContent: string;
+}
+
+/**
+ * Functional anchor - behavior-based element identification.
+ */
+export interface FunctionalAnchor {
+  /** Event types the element responds to */
+  eventTypes: string[];
+  /** Form target if element is part of a form */
+  formTarget?: string;
+  /** Navigation target if element is a link */
+  navigationTarget?: string;
+}
+
+/**
+ * Complete anchor set for an element.
+ * Used by Triangulation Engine for self-healing.
+ */
+export interface AnchorSet {
+  /** Position-based anchor */
+  spatial: SpatialAnchor;
+  /** Meaning-based anchor */
+  semantic: SemanticAnchor;
+  /** Behavior-based anchor */
+  functional: FunctionalAnchor;
+}
+
+/**
+ * Result of attempting to locate an element using anchors.
+ */
+export interface LocateResult {
+  /** Whether the element was found */
+  found: boolean;
+  /** The located element if found */
+  element?: IntentElement;
+  /** Number of anchors that matched (0-3) */
+  matchedAnchors: number;
+  /** Confidence score for the match (0-1) */
+  confidence: number;
+  /** Whether this result should be flagged for human review */
+  flaggedForReview?: boolean;
+}
+
+/**
+ * Result of healing (re-locating) an element after UI changes.
+ */
+export interface HealResult {
+  /** Whether healing was successful */
+  healed: boolean;
+  /** Updated anchors if healing succeeded */
+  newAnchors?: AnchorSet;
+  /** Description of what changed */
+  changeLog: string;
+}
+
+
+// =============================================================================
+// Ghost-API Types (Clean JSON Interface)
+// =============================================================================
+
+/**
+ * Definition of a goal for the Ghost-API.
+ */
+export interface GoalDefinition {
+  /** Name of the goal (e.g., "Fetch_Invoice_Data") */
+  name: string;
+  /** Target URL to operate on */
+  targetUrl: string;
+  /** Plain English description of the goal */
+  description: string;
+  /** Optional output schema (will be inferred if not provided) */
+  outputSchema?: Record<string, unknown>;
+}
+
+/**
+ * Mapping from a goal to a Ghost-API endpoint.
+ */
+export interface SchemaMapping {
+  /** Generated endpoint path (e.g., "/omni-bridge/invoice-portal/latest") */
+  endpoint: string;
+  /** JSON schema for the response */
+  schema: Record<string, unknown>;
+  /** Whether authentication is required */
+  requiredAuth: boolean;
+  /** Estimated number of actions to complete the goal */
+  estimatedActions: number;
+}
+
+/**
+ * Response from a Ghost-API call.
+ * This is what agents receive - clean JSON, no HTML.
+ */
+export interface GhostResponse {
+  /** The extracted/processed data */
+  data: Record<string, unknown> | Record<string, unknown>[];
+  /** Metadata about the execution */
+  metadata: {
+    /** Confidence score for the result (0-1) */
+    confidence: number;
+    /** Time taken to execute in milliseconds */
+    executionTimeMs: number;
+    /** Number of DOM actions performed */
+    actionsPerformed: number;
+    /** Number of triangulation heals that occurred */
+    triangulationHeals: number;
+  };
+  /** Cryptographic proof of the action sequence */
+  verificationHash: string;
+}
+
+
+// =============================================================================
+// Session and Auth Types
+// =============================================================================
+
+/**
+ * Device fingerprint for Shadow Sessions.
+ * Used to mimic real user devices and avoid bot detection.
+ */
+export interface DeviceFingerprint {
+  /** Screen resolution */
+  resolution: { width: number; height: number };
+  /** User agent string */
+  userAgent: string;
+  /** Installed fonts */
+  fonts: string[];
+  /** GPU signature */
+  gpuSignature: string;
+  /** Timezone */
+  timezone: string;
+  /** Browser language */
+  language: string;
+}
+
+/**
+ * Configuration for creating a Shadow Session.
+ */
+export interface SessionConfig {
+  /** Target domain for the session */
+  targetDomain: string;
+  /** Device fingerprint to use */
+  fingerprint: DeviceFingerprint;
+  /** Authentication configuration if needed */
+  authConfig?: AuthConfig;
+  /** Isolation level for the session */
+  isolationLevel: 'strict' | 'shared';
+}
+
+/**
+ * Authentication configuration.
+ */
+export interface AuthConfig {
+  /** Type of authentication */
+  type: 'credentials' | 'oauth' | 'api_key';
+  /** Vault reference for credentials (never raw credentials) */
+  vaultRef: string;
+}
+
+/**
+ * A Shadow Session - virtualized browser environment.
+ */
+export interface ShadowSession {
+  /** Unique session identifier */
+  id: string;
+  /** Target domain */
+  domain: string;
+  /** Current session status */
+  status: 'active' | 'expired' | 'mfa_pending';
+  /** Creation timestamp */
+  createdAt: number;
+  /** Last heartbeat timestamp */
+  lastHeartbeat: number;
+  /** Device fingerprint used */
+  fingerprint: DeviceFingerprint;
+}
+
+/**
+ * Encrypted blob for storing sensitive session data.
+ */
+export interface EncryptedBlob {
+  /** Encrypted data (base64) */
+  data: string;
+  /** Initialization vector (base64) */
+  iv: string;
+  /** Encryption algorithm used */
+  algorithm: 'AES-256-GCM';
+}
+
+/**
+ * Serialized session state for vault storage.
+ */
+export interface SerializedSession {
+  /** Encrypted cookies */
+  cookies: EncryptedBlob;
+  /** Encrypted localStorage */
+  localStorage: EncryptedBlob;
+  /** Encrypted sessionStorage */
+  sessionStorage: EncryptedBlob;
+  /** Expiration timestamp */
+  expiresAt: number;
+}
+
+
+// =============================================================================
+// Capability Token Types (Zero-Knowledge Credentials)
+// =============================================================================
+
+/**
+ * Scope of actions allowed by a Capability Token.
+ */
+export interface ActionScope {
+  /** Actions that are allowed (e.g., ["read_invoice", "pay_invoice"]) */
+  allowedActions: string[];
+  /** Actions that are blocked (e.g., ["change_password", "delete_account"]) */
+  blockedActions: string[];
+  /** Maximum number of executions allowed */
+  maxExecutions: number;
+  /** Expiration timestamp */
+  expiresAt: number;
+}
+
+/**
+ * Capability Token - scoped execution token for agents.
+ * Contains ONLY capabilities, never raw credentials.
+ */
+export interface CapabilityToken {
+  /** Unique token identifier */
+  id: string;
+  /** Domain this token is valid for */
+  domain: string;
+  /** Scope of allowed actions */
+  scope: ActionScope;
+  /** Timestamp when token was issued */
+  issuedAt: number;
+  /** Number of times this token has been used */
+  executionCount: number;
+}
+
+// =============================================================================
+// MFA Types (Auth Tunnel)
+// =============================================================================
+
+/**
+ * MFA challenge detected during authentication.
+ */
+export interface MFAChallenge {
+  /** Unique challenge identifier */
+  id: string;
+  /** Associated session ID */
+  sessionId: string;
+  /** Type of MFA challenge */
+  type: 'sms' | 'authenticator' | 'push' | 'email';
+  /** Prompt to show the user */
+  prompt: string;
+  /** Expiration timestamp (5 minute timeout) */
+  expiresAt: number;
+}
+
+/**
+ * Result of an authentication attempt.
+ */
+export interface AuthResult {
+  /** Whether authentication succeeded */
+  success: boolean;
+  /** Serialized session state if successful */
+  sessionState?: SerializedSession;
+  /** Error if authentication failed */
+  error?: AuthError;
+}
+
+/**
+ * Authentication error.
+ */
+export interface AuthError {
+  /** Error code */
+  code: 'invalid_credentials' | 'mfa_failed' | 'timeout' | 'blocked';
+  /** Human-readable message */
+  message: string;
+}
+
+
+// =============================================================================
+// Action Logging Types (Deterministic Verification)
+// =============================================================================
+
+/**
+ * A single logged action in the deterministic log.
+ */
+export interface ActionLogEntry {
+  /** Timestamp of the action */
+  timestamp: number;
+  /** Session ID where action occurred */
+  sessionId: string;
+  /** Type of action performed */
+  action: 'click' | 'type' | 'navigate' | 'wait' | 'extract';
+  /** Intent ID of the target element */
+  intentId: string;
+  /** Value associated with the action (e.g., typed text) */
+  value?: string;
+  /** Result of the action */
+  result: 'success' | 'failure';
+  /** Screenshot at this point (base64, optional) */
+  screenshot?: string;
+}
+
+/**
+ * Cryptographic proof of an action sequence.
+ */
+export interface VerificationProof {
+  /** Session ID this proof is for */
+  sessionId: string;
+  /** Total number of actions */
+  actionCount: number;
+  /** Cryptographic hash of the action sequence */
+  hash: string;
+  /** Screenshots at key decision points */
+  screenshots: string[];
+  /** The result claimed by the agent */
+  claimedResult: unknown;
+  /** Whether the claimed result matches the action log */
+  resultMatchesActions: boolean;
+}
+
+/**
+ * Analysis of differences between two agents' action logs.
+ */
+export interface DiffAnalysis {
+  /** Action index where agents diverged */
+  divergencePoint: number;
+  /** Agent A's action path from divergence */
+  agentAPath: ActionLogEntry[];
+  /** Agent B's action path from divergence */
+  agentBPath: ActionLogEntry[];
+  /** Recommendation based on analysis */
+  recommendation: 'agent_a' | 'agent_b' | 'tie' | 'both_invalid';
+}
+
+
+// =============================================================================
+// Competition Types (Parallel Execution)
+// =============================================================================
+
+/**
+ * A competition between multiple agents.
+ */
+export interface Competition {
+  /** Unique competition identifier */
+  id: string;
+  /** Associated bounty ID */
+  bountyId: string;
+  /** Shadow sessions for each agent */
+  sessions: ShadowSession[];
+  /** Identical starting state for all agents */
+  startState: SerializedSession;
+  /** Timestamp when competition started */
+  startedAt?: number;
+}
+
+/**
+ * Result of a single agent in a competition.
+ */
+export interface CompetitionResult {
+  /** Agent ID */
+  agentId: string;
+  /** Session ID used */
+  sessionId: string;
+  /** Final status */
+  status: 'completed' | 'failed' | 'timeout';
+  /** Result if completed */
+  result?: GhostResponse;
+  /** Complete action log */
+  actionLog: ActionLogEntry[];
+  /** Total execution time in milliseconds */
+  executionTimeMs: number;
+}
+
+/**
+ * Complete bounty execution record.
+ */
+export interface BountyExecution {
+  /** Bounty ID */
+  bountyId: string;
+  /** Goal definition */
+  goal: GoalDefinition;
+  /** Competition details */
+  competition: Competition;
+  /** Results from all agents */
+  results: CompetitionResult[];
+  /** Winner details if determined */
+  winner?: {
+    agentId: string;
+    proof: VerificationProof;
+    confidence: number;
+  };
+  /** Current status */
+  status: 'pending' | 'running' | 'verifying' | 'completed' | 'disputed';
+}
+
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+/**
+ * All possible OmniBridge errors.
+ */
+export type OmniBridgeError =
+  | { type: 'schema_drift'; details: string; confidence: number }
+  | { type: 'mfa_timeout'; challengeId: string }
+  | { type: 'auth_failed'; reason: string }
+  | { type: 'scope_violation'; attemptedAction: string; allowedActions: string[] }
+  | { type: 'session_expired'; domain: string }
+  | { type: 'triangulation_failed'; anchors: AnchorSet }
+  | { type: 'hallucination_detected'; claimedResult: unknown; actualActions: ActionLogEntry[] };
+
+/**
+ * Recoverable errors that OmniBridge handles automatically.
+ */
+export type RecoverableError =
+  | 'session_expired'
+  | 'element_moved'
+  | 'rate_limited'
+  | 'timeout';
+
+/**
+ * Errors requiring user intervention.
+ */
+export type UserInterventionError =
+  | 'mfa_required'
+  | 'captcha_required'
+  | 'low_confidence';
+
+/**
+ * Terminal errors that cause bounty failure.
+ */
+export type TerminalError =
+  | 'schema_drift'
+  | 'auth_failed'
+  | 'scope_violation'
+  | 'hallucination';
+
+/**
+ * Recovery configuration for recoverable errors.
+ */
+export interface RecoveryConfig {
+  action: 'reauthenticate' | 'triangulate' | 'backoff' | 'retry';
+  backoffMs?: number;
+  maxRetries: number;
+}
+
+/**
+ * Default recovery strategies.
+ */
+export const DEFAULT_RECOVERY_CONFIG: Record<RecoverableError, RecoveryConfig> = {
+  session_expired: { action: 'reauthenticate', maxRetries: 2 },
+  element_moved: { action: 'triangulate', maxRetries: 3 },
+  rate_limited: { action: 'backoff', backoffMs: 60000, maxRetries: 5 },
+  timeout: { action: 'retry', backoffMs: 5000, maxRetries: 3 },
+};

package/src/modules/omnibridge/execution/.gitkeep

@@ -0,0 +1 @@
+# Execution module - Shadow Sessions, Parallel Executor, Deterministic Logger