elsabro 2.3.0 → 3.8.0

package/references/event-driven.md

@@ -0,0 +1,1031 @@
+# Event-Driven Architecture (v3.2)
+
+Sistema de eventos para comunicación desacoplada entre componentes, event sourcing y webhooks externos.
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      EVENT-DRIVEN ARCHITECTURE                           │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                      EVENT BUS                                   │    │
+│  │  ┌─────────────────────────────────────────────────────────┐    │    │
+│  │  │                   Publishers                             │    │    │
+│  │  │  ┌──────────┐  ┌──────────┐  ┌──────────┐               │    │    │
+│  │  │  │ Agents   │  │  Flows   │  │ External │               │    │    │
+│  │  │  └────┬─────┘  └────┬─────┘  └────┬─────┘               │    │    │
+│  │  │       │             │             │                      │    │    │
+│  │  │       └─────────────┼─────────────┘                      │    │    │
+│  │  │                     ▼                                    │    │    │
+│  │  │  ┌──────────────────────────────────────────────────┐   │    │    │
+│  │  │  │              Event Router                         │   │    │    │
+│  │  │  │  topic → [subscriber1, subscriber2, ...]          │   │    │    │
+│  │  │  └──────────────────────────────────────────────────┘   │    │    │
+│  │  │                     │                                    │    │    │
+│  │  │       ┌─────────────┼─────────────┐                      │    │    │
+│  │  │       ▼             ▼             ▼                      │    │    │
+│  │  │  ┌──────────┐  ┌──────────┐  ┌──────────┐               │    │    │
+│  │  │  │ Handler1 │  │ Handler2 │  │ Webhook  │               │    │    │
+│  │  │  └──────────┘  └──────────┘  └──────────┘               │    │    │
+│  │  └─────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                      EVENT STORE                                 │    │
+│  │  ┌─────────────────────────────────────────────────────────┐    │    │
+│  │  │ Append-Only Log                                          │    │    │
+│  │  │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐      │    │    │
+│  │  │ │ E001  │→│ E002  │→│ E003  │→│ E004  │→│ E005  │→ ... │    │    │
+│  │  │ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘      │    │    │
+│  │  └─────────────────────────────────────────────────────────┘    │    │
+│  │  ┌─────────────────────────────────────────────────────────┐    │    │
+│  │  │ Projections (Read Models)                                │    │    │
+│  │  │ ┌──────────┐  ┌──────────┐  ┌──────────┐                │    │    │
+│  │  │ │ TaskView │  │ FlowView │  │ AgentView│                │    │    │
+│  │  │ └──────────┘  └──────────┘  └──────────┘                │    │    │
+│  │  └─────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## EventBus
+
+### API Principal
+
+```typescript
+interface Event<T = unknown> {
+  id: string;
+  type: string;
+  topic: string;
+  timestamp: string;
+  source: string;
+  correlationId?: string;
+  causationId?: string;
+  metadata?: Record<string, unknown>;
+  payload: T;
+}
+
+interface Subscription {
+  id: string;
+  topic: string;
+  pattern?: string;
+  handler: EventHandler;
+  filter?: EventFilter;
+  options?: SubscriptionOptions;
+}
+
+interface SubscriptionOptions {
+  queue?: string;          // For competing consumers
+  durable?: boolean;       // Survive restarts
+  ack?: 'auto' | 'manual'; // Acknowledgment mode
+  maxRetries?: number;
+  retryDelay?: number;
+  timeout?: number;
+}
+
+type EventHandler<T = unknown> = (event: Event<T>) => Promise<void>;
+type EventFilter = (event: Event) => boolean;
+
+class EventBus {
+  private subscriptions: Map<string, Set<Subscription>>;
+  private eventStore: EventStore;
+  private webhookManager: WebhookManager;
+  private config: EventBusConfig;
+
+  constructor(config: EventBusConfig) {
+    this.config = config;
+    this.subscriptions = new Map();
+    this.eventStore = new EventStore(config.store);
+    this.webhookManager = new WebhookManager(config.webhooks);
+  }
+
+  // Publish event to topic
+  async publish<T>(topic: string, payload: T, options?: PublishOptions): Promise<Event<T>> {
+    const event: Event<T> = {
+      id: this.generateId(),
+      type: options?.type || this.inferType(topic),
+      topic,
+      timestamp: new Date().toISOString(),
+      source: options?.source || 'elsabro',
+      correlationId: options?.correlationId,
+      causationId: options?.causationId,
+      metadata: options?.metadata,
+      payload
+    };
+
+    // Store event (event sourcing)
+    if (this.config.store.enabled) {
+      await this.eventStore.append(event);
+    }
+
+    // Notify local subscribers
+    await this.notifySubscribers(event);
+
+    // Trigger webhooks
+    if (this.config.webhooks.enabled) {
+      await this.webhookManager.trigger(event);
+    }
+
+    // Emit telemetry
+    TelemetryManager.emit({
+      name: 'event.published',
+      attributes: {
+        event_id: event.id,
+        topic: event.topic,
+        type: event.type
+      }
+    });
+
+    return event;
+  }
+
+  // Publish multiple events atomically
+  async publishBatch<T>(events: Array<{ topic: string; payload: T; options?: PublishOptions }>): Promise<Event<T>[]> {
+    const published: Event<T>[] = [];
+
+    // Store all events atomically
+    const eventRecords = events.map(e => ({
+      id: this.generateId(),
+      type: e.options?.type || this.inferType(e.topic),
+      topic: e.topic,
+      timestamp: new Date().toISOString(),
+      source: e.options?.source || 'elsabro',
+      correlationId: e.options?.correlationId,
+      payload: e.payload
+    }));
+
+    if (this.config.store.enabled) {
+      await this.eventStore.appendBatch(eventRecords);
+    }
+
+    // Notify subscribers for each event
+    for (const event of eventRecords) {
+      await this.notifySubscribers(event);
+      published.push(event);
+    }
+
+    return published;
+  }
+
+  // Subscribe to topic
+  subscribe<T>(
+    topic: string,
+    handler: EventHandler<T>,
+    options?: SubscriptionOptions
+  ): Subscription {
+    const subscription: Subscription = {
+      id: this.generateId(),
+      topic,
+      handler: handler as EventHandler,
+      options
+    };
+
+    if (!this.subscriptions.has(topic)) {
+      this.subscriptions.set(topic, new Set());
+    }
+    this.subscriptions.get(topic)!.add(subscription);
+
+    return subscription;
+  }
+
+  // Subscribe with pattern matching
+  subscribePattern<T>(
+    pattern: string,
+    handler: EventHandler<T>,
+    options?: SubscriptionOptions
+  ): Subscription {
+    const subscription: Subscription = {
+      id: this.generateId(),
+      topic: '*',
+      pattern,
+      handler: handler as EventHandler,
+      options
+    };
+
+    if (!this.subscriptions.has('*')) {
+      this.subscriptions.set('*', new Set());
+    }
+    this.subscriptions.get('*')!.add(subscription);
+
+    return subscription;
+  }
+
+  // Subscribe with filter
+  subscribeFiltered<T>(
+    topic: string,
+    handler: EventHandler<T>,
+    filter: EventFilter,
+    options?: SubscriptionOptions
+  ): Subscription {
+    const subscription: Subscription = {
+      id: this.generateId(),
+      topic,
+      handler: handler as EventHandler,
+      filter,
+      options
+    };
+
+    if (!this.subscriptions.has(topic)) {
+      this.subscriptions.set(topic, new Set());
+    }
+    this.subscriptions.get(topic)!.add(subscription);
+
+    return subscription;
+  }
+
+  // Unsubscribe
+  unsubscribe(subscriptionId: string): boolean {
+    for (const [_, subs] of this.subscriptions) {
+      for (const sub of subs) {
+        if (sub.id === subscriptionId) {
+          subs.delete(sub);
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  // Wait for event (one-time)
+  async once<T>(topic: string, timeout?: number): Promise<Event<T>> {
+    return new Promise((resolve, reject) => {
+      const timeoutId = timeout
+        ? setTimeout(() => {
+            this.unsubscribe(sub.id);
+            reject(new Error('Event timeout'));
+          }, timeout)
+        : null;
+
+      const sub = this.subscribe<T>(topic, async (event) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        this.unsubscribe(sub.id);
+        resolve(event);
+      });
+    });
+  }
+
+  // Replay events from store
+  async replay(
+    topic: string,
+    from: string | Date,
+    to?: string | Date,
+    handler?: EventHandler
+  ): Promise<Event[]> {
+    const events = await this.eventStore.query({
+      topic,
+      from: typeof from === 'string' ? from : from.toISOString(),
+      to: to ? (typeof to === 'string' ? to : to.toISOString()) : undefined
+    });
+
+    if (handler) {
+      for (const event of events) {
+        await handler(event);
+      }
+    }
+
+    return events;
+  }
+
+  // Get event history
+  async history(options: HistoryOptions): Promise<Event[]> {
+    return this.eventStore.query(options);
+  }
+
+  private async notifySubscribers(event: Event): Promise<void> {
+    const directSubs = this.subscriptions.get(event.topic) || new Set();
+    const patternSubs = this.subscriptions.get('*') || new Set();
+
+    const allSubs = [...directSubs, ...patternSubs];
+
+    for (const sub of allSubs) {
+      // Check pattern match
+      if (sub.pattern && !this.matchPattern(event.topic, sub.pattern)) {
+        continue;
+      }
+
+      // Check filter
+      if (sub.filter && !sub.filter(event)) {
+        continue;
+      }
+
+      // Handle with retry logic
+      await this.handleWithRetry(sub, event);
+    }
+  }
+
+  private async handleWithRetry(sub: Subscription, event: Event): Promise<void> {
+    const maxRetries = sub.options?.maxRetries || 3;
+    const retryDelay = sub.options?.retryDelay || 1000;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const timeout = sub.options?.timeout || 30000;
+        await Promise.race([
+          sub.handler(event),
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Handler timeout')), timeout)
+          )
+        ]);
+        return;
+      } catch (error) {
+        if (attempt === maxRetries) {
+          // Move to dead letter queue
+          await this.eventStore.appendDeadLetter(event, error as Error, sub.id);
+          TelemetryManager.emit({
+            name: 'event.handler.failed',
+            attributes: {
+              event_id: event.id,
+              subscription_id: sub.id,
+              error: (error as Error).message
+            }
+          });
+        } else {
+          await this.delay(retryDelay * Math.pow(2, attempt));
+        }
+      }
+    }
+  }
+
+  private matchPattern(topic: string, pattern: string): boolean {
+    const regex = new RegExp(
+      '^' + pattern.replace(/\*/g, '[^.]+').replace(/#/g, '.*') + '$'
+    );
+    return regex.test(topic);
+  }
+
+  private inferType(topic: string): string {
+    // agent.started → AgentStarted
+    return topic
+      .split('.')
+      .map(p => p.charAt(0).toUpperCase() + p.slice(1))
+      .join('');
+  }
+
+  private generateId(): string {
+    return `evt_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+```
+
+---
+
+## EventStore
+
+### Event Sourcing
+
+```typescript
+interface EventStoreConfig {
+  enabled: boolean;
+  backend: 'file' | 'sqlite' | 'postgres' | 'memory';
+  path?: string;
+  connectionString?: string;
+  retention?: {
+    maxEvents?: number;
+    maxAge?: string; // "30d", "1y"
+  };
+  snapshots?: {
+    enabled: boolean;
+    frequency: number; // Every N events
+  };
+}
+
+class EventStore {
+  private backend: EventStoreBackend;
+  private config: EventStoreConfig;
+  private sequence: number = 0;
+
+  constructor(config: EventStoreConfig) {
+    this.config = config;
+    this.backend = this.createBackend(config);
+  }
+
+  // Append single event
+  async append(event: Event): Promise<void> {
+    const record: StoredEvent = {
+      ...event,
+      sequence: ++this.sequence,
+      storedAt: new Date().toISOString()
+    };
+    await this.backend.append(record);
+
+    // Check for snapshot
+    if (this.config.snapshots?.enabled) {
+      if (this.sequence % this.config.snapshots.frequency === 0) {
+        await this.createSnapshot();
+      }
+    }
+  }
+
+  // Append batch atomically
+  async appendBatch(events: Event[]): Promise<void> {
+    const records: StoredEvent[] = events.map(event => ({
+      ...event,
+      sequence: ++this.sequence,
+      storedAt: new Date().toISOString()
+    }));
+    await this.backend.appendBatch(records);
+  }
+
+  // Append to dead letter queue
+  async appendDeadLetter(event: Event, error: Error, subscriberId: string): Promise<void> {
+    const deadLetter: DeadLetterEvent = {
+      originalEvent: event,
+      error: {
+        message: error.message,
+        stack: error.stack
+      },
+      subscriberId,
+      failedAt: new Date().toISOString(),
+      retryCount: 0
+    };
+    await this.backend.appendDeadLetter(deadLetter);
+  }
+
+  // Query events
+  async query(options: QueryOptions): Promise<Event[]> {
+    return this.backend.query(options);
+  }
+
+  // Get events by correlation ID
+  async getByCorrelation(correlationId: string): Promise<Event[]> {
+    return this.backend.query({ correlationId });
+  }
+
+  // Get stream of events for aggregate
+  async getStream(aggregateType: string, aggregateId: string): Promise<Event[]> {
+    return this.backend.query({
+      topic: `${aggregateType}.${aggregateId}.*`
+    });
+  }
+
+  // Create snapshot
+  async createSnapshot(): Promise<void> {
+    const state = await this.computeState();
+    await this.backend.saveSnapshot({
+      sequence: this.sequence,
+      state,
+      createdAt: new Date().toISOString()
+    });
+  }
+
+  // Restore from snapshot
+  async restoreFromSnapshot(): Promise<void> {
+    const snapshot = await this.backend.getLatestSnapshot();
+    if (snapshot) {
+      this.sequence = snapshot.sequence;
+      // Restore state...
+    }
+  }
+
+  // Rebuild projections
+  async rebuildProjection(
+    projectionName: string,
+    handler: (event: Event) => Promise<void>
+  ): Promise<void> {
+    const events = await this.backend.query({ from: '0' });
+    for (const event of events) {
+      await handler(event);
+    }
+  }
+
+  // Cleanup old events
+  async cleanup(): Promise<number> {
+    if (!this.config.retention) return 0;
+
+    const cutoff = this.config.retention.maxAge
+      ? this.calculateCutoff(this.config.retention.maxAge)
+      : undefined;
+
+    return this.backend.deleteOlderThan(cutoff);
+  }
+
+  private createBackend(config: EventStoreConfig): EventStoreBackend {
+    switch (config.backend) {
+      case 'file':
+        return new FileEventStoreBackend(config.path!);
+      case 'sqlite':
+        return new SQLiteEventStoreBackend(config.path!);
+      case 'postgres':
+        return new PostgresEventStoreBackend(config.connectionString!);
+      default:
+        return new MemoryEventStoreBackend();
+    }
+  }
+
+  private calculateCutoff(maxAge: string): Date {
+    const match = maxAge.match(/^(\d+)([dmy])$/);
+    if (!match) throw new Error('Invalid maxAge format');
+
+    const value = parseInt(match[1]);
+    const unit = match[2];
+    const now = new Date();
+
+    switch (unit) {
+      case 'd': return new Date(now.setDate(now.getDate() - value));
+      case 'm': return new Date(now.setMonth(now.getMonth() - value));
+      case 'y': return new Date(now.setFullYear(now.getFullYear() - value));
+      default: return now;
+    }
+  }
+
+  private async computeState(): Promise<unknown> {
+    // Compute current state from events
+    return {};
+  }
+}
+```
+
+---
+
+## WebhookManager
+
+```typescript
+interface WebhookConfig {
+  enabled: boolean;
+  endpoints: WebhookEndpoint[];
+  signing: {
+    enabled: boolean;
+    algorithm: 'sha256' | 'sha512';
+    header: string;
+  };
+  retry: {
+    maxAttempts: number;
+    backoff: 'linear' | 'exponential';
+    initialDelay: number;
+    maxDelay: number;
+  };
+}
+
+interface WebhookEndpoint {
+  id: string;
+  url: string;
+  events: string[];  // Topics to subscribe to
+  secret?: string;
+  headers?: Record<string, string>;
+  enabled: boolean;
+}
+
+interface WebhookDelivery {
+  id: string;
+  endpointId: string;
+  eventId: string;
+  status: 'pending' | 'success' | 'failed';
+  attempts: number;
+  response?: {
+    status: number;
+    body: string;
+  };
+  error?: string;
+  deliveredAt?: string;
+}
+
+class WebhookManager {
+  private config: WebhookConfig;
+  private deliveryLog: Map<string, WebhookDelivery>;
+
+  constructor(config: WebhookConfig) {
+    this.config = config;
+    this.deliveryLog = new Map();
+  }
+
+  // Trigger webhooks for event
+  async trigger(event: Event): Promise<WebhookDelivery[]> {
+    const matchingEndpoints = this.config.endpoints.filter(ep =>
+      ep.enabled && this.matchesTopic(event.topic, ep.events)
+    );
+
+    const deliveries: WebhookDelivery[] = [];
+
+    for (const endpoint of matchingEndpoints) {
+      const delivery = await this.deliver(endpoint, event);
+      deliveries.push(delivery);
+    }
+
+    return deliveries;
+  }
+
+  // Deliver to single endpoint
+  private async deliver(endpoint: WebhookEndpoint, event: Event): Promise<WebhookDelivery> {
+    const deliveryId = this.generateId();
+    const delivery: WebhookDelivery = {
+      id: deliveryId,
+      endpointId: endpoint.id,
+      eventId: event.id,
+      status: 'pending',
+      attempts: 0
+    };
+
+    this.deliveryLog.set(deliveryId, delivery);
+
+    // Prepare payload
+    const payload = JSON.stringify({
+      event: event.type,
+      timestamp: event.timestamp,
+      data: event.payload
+    });
+
+    // Sign payload
+    const signature = this.config.signing.enabled && endpoint.secret
+      ? this.sign(payload, endpoint.secret)
+      : undefined;
+
+    // Deliver with retry
+    for (let attempt = 1; attempt <= this.config.retry.maxAttempts; attempt++) {
+      delivery.attempts = attempt;
+
+      try {
+        const response = await fetch(endpoint.url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...endpoint.headers,
+            ...(signature ? { [this.config.signing.header]: signature } : {})
+          },
+          body: payload,
+          signal: AbortSignal.timeout(30000)
+        });
+
+        delivery.response = {
+          status: response.status,
+          body: await response.text()
+        };
+
+        if (response.ok) {
+          delivery.status = 'success';
+          delivery.deliveredAt = new Date().toISOString();
+          break;
+        }
+      } catch (error) {
+        delivery.error = (error as Error).message;
+      }
+
+      // Retry delay
+      if (attempt < this.config.retry.maxAttempts) {
+        const delay = this.calculateDelay(attempt);
+        await this.delay(delay);
+      }
+    }
+
+    if (delivery.status !== 'success') {
+      delivery.status = 'failed';
+    }
+
+    return delivery;
+  }
+
+  // Register new endpoint
+  async registerEndpoint(endpoint: Omit<WebhookEndpoint, 'id'>): Promise<WebhookEndpoint> {
+    const newEndpoint: WebhookEndpoint = {
+      id: this.generateId(),
+      ...endpoint
+    };
+    this.config.endpoints.push(newEndpoint);
+    return newEndpoint;
+  }
+
+  // Update endpoint
+  async updateEndpoint(id: string, updates: Partial<WebhookEndpoint>): Promise<WebhookEndpoint | null> {
+    const index = this.config.endpoints.findIndex(ep => ep.id === id);
+    if (index === -1) return null;
+
+    this.config.endpoints[index] = {
+      ...this.config.endpoints[index],
+      ...updates
+    };
+    return this.config.endpoints[index];
+  }
+
+  // Delete endpoint
+  async deleteEndpoint(id: string): Promise<boolean> {
+    const index = this.config.endpoints.findIndex(ep => ep.id === id);
+    if (index === -1) return false;
+    this.config.endpoints.splice(index, 1);
+    return true;
+  }
+
+  // Get delivery history
+  getDeliveries(endpointId?: string): WebhookDelivery[] {
+    const deliveries = Array.from(this.deliveryLog.values());
+    return endpointId
+      ? deliveries.filter(d => d.endpointId === endpointId)
+      : deliveries;
+  }
+
+  // Retry failed delivery
+  async retryDelivery(deliveryId: string): Promise<WebhookDelivery | null> {
+    const delivery = this.deliveryLog.get(deliveryId);
+    if (!delivery || delivery.status !== 'failed') return null;
+
+    const endpoint = this.config.endpoints.find(ep => ep.id === delivery.endpointId);
+    if (!endpoint) return null;
+
+    // Get original event from store
+    const eventStore = new EventStore(this.config as any);
+    const events = await eventStore.query({ id: delivery.eventId });
+    if (events.length === 0) return null;
+
+    return this.deliver(endpoint, events[0]);
+  }
+
+  private matchesTopic(topic: string, patterns: string[]): boolean {
+    return patterns.some(pattern => {
+      if (pattern === '*') return true;
+      if (pattern.endsWith('.*')) {
+        return topic.startsWith(pattern.slice(0, -2));
+      }
+      return topic === pattern;
+    });
+  }
+
+  private sign(payload: string, secret: string): string {
+    const crypto = require('crypto');
+    const algorithm = this.config.signing.algorithm === 'sha512' ? 'sha512' : 'sha256';
+    return crypto.createHmac(algorithm, secret).update(payload).digest('hex');
+  }
+
+  private calculateDelay(attempt: number): number {
+    const { backoff, initialDelay, maxDelay } = this.config.retry;
+
+    let delay = initialDelay;
+    if (backoff === 'exponential') {
+      delay = initialDelay * Math.pow(2, attempt - 1);
+    } else {
+      delay = initialDelay * attempt;
+    }
+
+    return Math.min(delay, maxDelay);
+  }
+
+  private generateId(): string {
+    return `wh_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+```
+
+---
+
+## Event Types Predefinidos
+
+```typescript
+// Agent Events
+interface AgentStartedEvent {
+  agentId: string;
+  agentType: string;
+  taskId: string;
+}
+
+interface AgentCompletedEvent {
+  agentId: string;
+  result: unknown;
+  duration_ms: number;
+}
+
+interface AgentFailedEvent {
+  agentId: string;
+  error: string;
+  recoverable: boolean;
+}
+
+// Flow Events
+interface FlowStartedEvent {
+  flowId: string;
+  flowName: string;
+  input: unknown;
+}
+
+interface FlowNodeEnteredEvent {
+  flowId: string;
+  nodeId: string;
+  nodeType: string;
+}
+
+interface FlowCompletedEvent {
+  flowId: string;
+  result: unknown;
+  duration_ms: number;
+}
+
+// Task Events
+interface TaskCreatedEvent {
+  taskId: string;
+  subject: string;
+  description: string;
+}
+
+interface TaskStatusChangedEvent {
+  taskId: string;
+  oldStatus: string;
+  newStatus: string;
+}
+
+// Checkpoint Events
+interface CheckpointCreatedEvent {
+  checkpointId: string;
+  type: 'auto' | 'manual' | 'interrupt';
+  reason: string;
+}
+
+interface CheckpointRestoredEvent {
+  checkpointId: string;
+  previousCheckpointId?: string;
+}
+
+// Memory Events
+interface MemoryStoredEvent {
+  level: 'short-term' | 'long-term' | 'entity' | 'contextual';
+  key: string;
+  size: number;
+}
+
+// Sandbox Events
+interface SandboxExecutionStartedEvent {
+  executionId: string;
+  language: string;
+  provider: string;
+}
+
+interface SandboxExecutionCompletedEvent {
+  executionId: string;
+  exitCode: number;
+  duration_ms: number;
+}
+```
+
+---
+
+## Integración con ELSABRO
+
+### Uso en Flows
+
+```typescript
+// Emit events during flow execution
+class FlowEngine {
+  private eventBus: EventBus;
+
+  async executeFlow(flowId: string, input: unknown): Promise<unknown> {
+    // Emit flow started
+    await this.eventBus.publish('flow.started', {
+      flowId,
+      flowName: this.getFlowName(flowId),
+      input
+    });
+
+    try {
+      const result = await this.runNodes(flowId, input);
+
+      // Emit flow completed
+      await this.eventBus.publish('flow.completed', {
+        flowId,
+        result,
+        duration_ms: this.getDuration()
+      });
+
+      return result;
+    } catch (error) {
+      // Emit flow failed
+      await this.eventBus.publish('flow.failed', {
+        flowId,
+        error: (error as Error).message
+      });
+      throw error;
+    }
+  }
+}
+```
+
+### Uso en Agentes
+
+```typescript
+// Emit events during agent execution
+class AgentRunner {
+  private eventBus: EventBus;
+
+  async runAgent(agent: Agent, task: Task): Promise<AgentResult> {
+    const agentId = this.generateId();
+
+    // Emit agent started
+    await this.eventBus.publish('agent.started', {
+      agentId,
+      agentType: agent.type,
+      taskId: task.id
+    });
+
+    try {
+      const result = await agent.run(task);
+
+      // Emit agent completed
+      await this.eventBus.publish('agent.completed', {
+        agentId,
+        result,
+        duration_ms: this.getDuration()
+      });
+
+      return result;
+    } catch (error) {
+      // Emit agent failed
+      await this.eventBus.publish('agent.failed', {
+        agentId,
+        error: (error as Error).message,
+        recoverable: this.isRecoverable(error)
+      });
+      throw error;
+    }
+  }
+}
+```
+
+### Suscripción a Eventos
+
+```typescript
+// En commands o skills
+const eventBus = new EventBus(config);
+
+// Subscribe to all agent events
+eventBus.subscribePattern('agent.*', async (event) => {
+  console.log(`Agent event: ${event.type}`, event.payload);
+});
+
+// Subscribe to specific event with filter
+eventBus.subscribeFiltered(
+  'task.status.changed',
+  async (event: Event<TaskStatusChangedEvent>) => {
+    // Only handle completed tasks
+    if (event.payload.newStatus === 'completed') {
+      await notifyUser(event);
+    }
+  },
+  (event) => event.payload.newStatus === 'completed'
+);
+
+// Wait for specific event
+const result = await eventBus.once<FlowCompletedEvent>('flow.completed', 60000);
+```
+
+---
+
+## Configuración
+
+```json
+{
+  "events": {
+    "enabled": true,
+    "bus": {
+      "maxListeners": 100,
+      "defaultTimeout": 30000
+    },
+    "store": {
+      "enabled": true,
+      "backend": "file",
+      "path": ".elsabro/events",
+      "retention": {
+        "maxEvents": 10000,
+        "maxAge": "30d"
+      },
+      "snapshots": {
+        "enabled": true,
+        "frequency": 100
+      }
+    },
+    "webhooks": {
+      "enabled": true,
+      "endpoints": [],
+      "signing": {
+        "enabled": true,
+        "algorithm": "sha256",
+        "header": "X-Webhook-Signature"
+      },
+      "retry": {
+        "maxAttempts": 3,
+        "backoff": "exponential",
+        "initialDelay": 1000,
+        "maxDelay": 30000
+      }
+    }
+  }
+}
+```
+
+---
+
+## Changelog
+
+- **v3.2.0**: Initial Event-Driven Architecture
+  - EventBus with pub/sub
+  - EventStore for event sourcing
+  - WebhookManager for external integrations
+  - Predefined event types
+  - Integration with flows and agents