@agentxjs/core 1.9.1-dev

package/src/event/types/base.ts

@@ -0,0 +1,241 @@
+/**
+ * Base Event Types - SystemEvent, EventSource, EventIntent, EventCategory, EventContext
+ *
+ * Foundation types for the event system.
+ */
+
+// ============================================================================
+// SECTION 1: Legacy BusEvent Types (for backward compatibility)
+// ============================================================================
+
+/**
+ * BusEvent - Base event type for EventBus
+ *
+ * All events flowing through the EventBus must conform to this structure.
+ * This is a minimal event type that can be extended for specific use cases.
+ *
+ * @deprecated Use SystemEvent instead for full event system support
+ */
+export interface BusEvent<T extends string = string, D = unknown> {
+  /**
+   * Event type identifier (e.g., "text_delta", "assistant_message")
+   */
+  readonly type: T;
+
+  /**
+   * Event timestamp (Unix milliseconds)
+   */
+  readonly timestamp: number;
+
+  /**
+   * Event payload data
+   */
+  readonly data: D;
+
+  /**
+   * Event source (optional, for routing/filtering)
+   */
+  readonly source?: string;
+
+  /**
+   * Event category (optional, for classification)
+   */
+  readonly category?: string;
+
+  /**
+   * Event intent (optional, for command pattern)
+   */
+  readonly intent?: string;
+}
+
+// ============================================================================
+// SECTION 2: Base Types (SystemEvent, EventSource, EventIntent, EventCategory)
+// ============================================================================
+
+/**
+ * Event source - where the event originated
+ */
+export type EventSource =
+  | "driver" // LLM Driver (Claude API, etc.)
+  | "agent" // Agent internal
+  | "session" // Session operations
+  | "container" // Container operations
+  | "sandbox" // Sandbox resources (Workspace, MCP)
+  | "command"; // Command request/response (API operations)
+
+/**
+ * Event intent - what the event represents
+ */
+export type EventIntent =
+  | "request" // Request to perform action (may be forwarded or executed)
+  | "result" // Result of completed action
+  | "notification"; // State change notification (no action needed)
+
+/**
+ * Event category - fine-grained classification within source
+ */
+export type EventCategory =
+  // Environment categories
+  | "stream" // Streaming output from LLM
+  | "connection" // Network connection status
+  // Agent categories
+  | "state" // State transitions
+  | "message" // Complete messages
+  | "turn" // Conversation turns
+  | "error" // Errors
+  // Session categories
+  | "lifecycle" // Creation/destruction
+  | "persist" // Persistence operations
+  | "action" // User actions (resume, fork)
+  // Sandbox categories
+  | "workdir" // File operations
+  | "mcp" // MCP tool operations
+  // Command categories (API request/response)
+  | "request" // Request to perform action
+  | "response"; // Response with result
+
+/**
+ * EventContext - Scope information attached to events
+ */
+export interface EventContext {
+  /**
+   * Container ID (isolation boundary)
+   */
+  containerId?: string;
+
+  /**
+   * Image ID (persistent conversation identity)
+   */
+  imageId?: string;
+
+  /**
+   * Agent ID (if event is agent-scoped)
+   */
+  agentId?: string;
+
+  /**
+   * Session ID (if event is session-scoped)
+   */
+  sessionId?: string;
+
+  /**
+   * Turn ID (for correlating events within a single turn)
+   * A turn = one user message + assistant response cycle
+   */
+  turnId?: string;
+
+  /**
+   * Correlation ID (for request-response tracking)
+   */
+  correlationId?: string;
+}
+
+/**
+ * SystemEvent - Base interface for ALL events in the system
+ *
+ * Every event has:
+ * - type: What happened (e.g., "text_delta", "session_saved")
+ * - timestamp: When it happened
+ * - data: Event payload
+ * - source: Where it came from
+ * - category: What kind of event
+ * - intent: What it means (notification/request/result)
+ * - context: Optional scope information
+ * - broadcastable: Whether to broadcast to external clients (default: true)
+ */
+export interface SystemEvent<
+  T extends string = string,
+  D = unknown,
+  S extends EventSource = EventSource,
+  C extends EventCategory = EventCategory,
+  I extends EventIntent = EventIntent,
+> {
+  /**
+   * Event type identifier (e.g., "text_delta", "session_saved")
+   */
+  readonly type: T;
+
+  /**
+   * Event timestamp (Unix milliseconds)
+   */
+  readonly timestamp: number;
+
+  /**
+   * Event payload data
+   */
+  readonly data: D;
+
+  /**
+   * Event source - where the event originated
+   */
+  readonly source: S;
+
+  /**
+   * Event category - fine-grained classification
+   */
+  readonly category: C;
+
+  /**
+   * Event intent - what the event represents
+   */
+  readonly intent: I;
+
+  /**
+   * Event context - scope information (optional)
+   */
+  readonly context?: EventContext;
+
+  /**
+   * Whether to broadcast this event to external clients (SSE/WebSocket)
+   *
+   * - true or undefined: Broadcast to all external clients
+   * - false: Only consumed internally, not broadcast
+   *
+   * Used for internal events like DriveableEvent that should be
+   * processed by the engine but not sent directly to clients.
+   * @default true
+   */
+  readonly broadcastable?: boolean;
+}
+
+// Type Guards for SystemEvent
+/**
+ * Check if event is from a specific source
+ */
+export function isFromSource<S extends EventSource>(
+  event: SystemEvent,
+  source: S
+): event is SystemEvent<string, unknown, S> {
+  return event.source === source;
+}
+
+/**
+ * Check if event has a specific intent
+ */
+export function hasIntent<I extends EventIntent>(
+  event: SystemEvent,
+  intent: I
+): event is SystemEvent<string, unknown, EventSource, EventCategory, I> {
+  return event.intent === intent;
+}
+
+/**
+ * Check if event is a request
+ */
+export function isRequest(event: SystemEvent): boolean {
+  return event.intent === "request";
+}
+
+/**
+ * Check if event is a result
+ */
+export function isResult(event: SystemEvent): boolean {
+  return event.intent === "result";
+}
+
+/**
+ * Check if event is a notification
+ */
+export function isNotification(event: SystemEvent): boolean {
+  return event.intent === "notification";
+}

package/src/event/types/bus.ts

@@ -0,0 +1,429 @@
+/**
+ * EventBus Interfaces - EventBus, EventProducer, EventConsumer
+ *
+ * Central event bus interfaces for ecosystem communication.
+ */
+
+import type { BusEvent } from "./base";
+import type {
+  CommandEventMap,
+  CommandRequestType,
+  ResponseEventFor,
+  RequestDataFor,
+} from "./command";
+
+// ============================================================================
+// Types for Event Subscription
+// ============================================================================
+
+/**
+ * Unsubscribe function type
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * Event handler function type
+ */
+export type BusEventHandler<E extends BusEvent = BusEvent> = (event: E) => void;
+
+/**
+ * Subscription options for advanced event handling
+ */
+export interface SubscribeOptions<E extends BusEvent = BusEvent> {
+  /**
+   * Event filter - only events returning true will trigger the handler
+   * Useful for filtering by agentId, sessionId, etc.
+   */
+  filter?: (event: E) => boolean;
+
+  /**
+   * Priority - higher numbers execute first (default: 0)
+   * Useful for ensuring certain handlers run before others
+   */
+  priority?: number;
+
+  /**
+   * Whether to trigger only once then auto-unsubscribe
+   */
+  once?: boolean;
+}
+
+// ============================================================================
+// EventProducer Interface (Write-only view)
+// ============================================================================
+
+/**
+ * EventProducer interface - Write-only view
+ *
+ * Used by components that produce events:
+ * - Effector (emits DriveableEvents from Claude API)
+ * - Receptor (emits stream events)
+ * - Agent (emits state/message events)
+ *
+ * Producer can only emit events, cannot subscribe.
+ * This prevents accidental event loops and clarifies data flow.
+ *
+ * @example
+ * ```typescript
+ * class Effector {
+ *   constructor(private producer: EventProducer) {}
+ *
+ *   async sendMessage(message: UserMessage) {
+ *     // Can only emit, cannot subscribe
+ *     this.producer.emit({
+ *       type: "message_start",
+ *       timestamp: Date.now(),
+ *       data: { messageId: "msg-1", model: "claude" },
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export interface EventProducer {
+  /**
+   * Emit a single event to the bus
+   *
+   * @param event - The event to emit
+   */
+  emit(event: BusEvent): void;
+
+  /**
+   * Emit multiple events (batch operation)
+   *
+   * @param events - Array of events to emit
+   */
+  emitBatch(events: BusEvent[]): void;
+
+  /**
+   * Emit a typed command event
+   *
+   * @param type - The command event type
+   * @param data - Event data (type-checked)
+   */
+  emitCommand<T extends keyof CommandEventMap>(type: T, data: CommandEventMap[T]["data"]): void;
+}
+
+// ============================================================================
+// EventConsumer Interface (Read-only view)
+// ============================================================================
+
+/**
+ * EventConsumer interface - Read-only view
+ *
+ * Used by components that consume events:
+ * - BusDriver (subscribes to DriveableEvents)
+ * - UI components (subscribes to display events)
+ * - Presenters (subscribes to forward events)
+ *
+ * Consumer can only subscribe to events, cannot emit.
+ * This prevents accidental event emission and clarifies data flow.
+ *
+ * @example
+ * ```typescript
+ * class BusDriver {
+ *   constructor(private consumer: EventConsumer) {}
+ *
+ *   async *receive(message: UserMessage) {
+ *     // Can only subscribe, cannot emit
+ *     this.consumer.on('message_start', (event) => {
+ *       console.log('Received:', event.type);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export interface EventConsumer {
+  /**
+   * Subscribe to a specific event type
+   *
+   * @param type - The event type to listen for
+   * @param handler - Callback invoked when event is received
+   * @param options - Subscription options (filter, priority, once)
+   * @returns Unsubscribe function
+   */
+  on<T extends string>(
+    type: T,
+    handler: BusEventHandler<BusEvent & { type: T }>,
+    options?: SubscribeOptions<BusEvent & { type: T }>
+  ): Unsubscribe;
+
+  /**
+   * Subscribe to multiple event types
+   *
+   * @param types - Array of event types to listen for
+   * @param handler - Callback invoked when any matching event is received
+   * @param options - Subscription options
+   * @returns Unsubscribe function
+   */
+  on(types: string[], handler: BusEventHandler, options?: SubscribeOptions): Unsubscribe;
+
+  /**
+   * Subscribe to all events
+   *
+   * @param handler - Callback invoked for every event
+   * @param options - Subscription options
+   * @returns Unsubscribe function
+   */
+  onAny(handler: BusEventHandler, options?: SubscribeOptions): Unsubscribe;
+
+  /**
+   * Subscribe to an event type once (auto-unsubscribes after first trigger)
+   *
+   * @param type - Event type to subscribe to
+   * @param handler - Callback function
+   * @returns Unsubscribe function
+   */
+  once<T extends string>(type: T, handler: BusEventHandler<BusEvent & { type: T }>): Unsubscribe;
+
+  /**
+   * Subscribe to a CommandEvent with full type safety
+   *
+   * @example
+   * ```typescript
+   * consumer.onCommand("container_create_request", (event) => {
+   *   event.data.requestId;    // string
+   *   event.data.containerId;  // string
+   * });
+   * ```
+   *
+   * @param type - The command event type
+   * @param handler - Callback with fully typed event
+   * @returns Unsubscribe function
+   */
+  onCommand<T extends keyof CommandEventMap>(
+    type: T,
+    handler: (event: CommandEventMap[T]) => void
+  ): Unsubscribe;
+
+  /**
+   * Send a command request and wait for response
+   *
+   * Automatically generates requestId, emits request, waits for matching response.
+   *
+   * @example
+   * ```typescript
+   * const response = await consumer.request("container_create_request", {
+   *   containerId: "my-container"
+   * });
+   * // response is ContainerCreateResponse
+   * console.log(response.data.containerId);
+   * ```
+   *
+   * @param type - The request event type
+   * @param data - Request data (without requestId)
+   * @param timeout - Timeout in milliseconds (default: 30000)
+   * @returns Promise of response event
+   */
+  request<T extends CommandRequestType>(
+    type: T,
+    data: RequestDataFor<T>,
+    timeout?: number
+  ): Promise<ResponseEventFor<T>>;
+}
+
+// ============================================================================
+// EventBus Interface (Full access)
+// ============================================================================
+
+/**
+ * EventBus interface - Central event bus for ecosystem communication.
+ *
+ * Extends both Producer and Consumer interfaces for internal use.
+ * External components should use restricted views via asProducer/asConsumer.
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus();
+ *
+ * // Subscribe to specific event type
+ * bus.on('text_chunk', (e) => {
+ *   console.log('Received text:', e.data.text);
+ * });
+ *
+ * // Subscribe with options
+ * bus.on('text_delta', handler, {
+ *   filter: (e) => e.agentId === 'agent-1',
+ *   priority: 10,
+ *   once: true
+ * });
+ *
+ * // Subscribe to all events
+ * bus.onAny((e) => {
+ *   console.log('Event:', e.type);
+ * });
+ *
+ * // Emit event
+ * bus.emit({ type: 'text_chunk', data: { text: 'Hello' } });
+ * ```
+ */
+export interface EventBus {
+  /**
+   * Emit an event to the bus.
+   *
+   * All subscribed handlers will receive this event.
+   *
+   * @param event - The event to emit
+   */
+  emit(event: BusEvent): void;
+
+  /**
+   * Emit multiple events (batch operation).
+   *
+   * @param events - Array of events to emit
+   */
+  emitBatch(events: BusEvent[]): void;
+
+  /**
+   * Subscribe to a specific event type.
+   *
+   * @param type - The event type to listen for
+   * @param handler - Callback invoked when event is received
+   * @param options - Subscription options (filter, priority, once)
+   * @returns Unsubscribe function
+   */
+  on<T extends string>(
+    type: T,
+    handler: BusEventHandler<BusEvent & { type: T }>,
+    options?: SubscribeOptions<BusEvent & { type: T }>
+  ): Unsubscribe;
+
+  /**
+   * Subscribe to multiple event types.
+   *
+   * @param types - Array of event types to listen for
+   * @param handler - Callback invoked when any matching event is received
+   * @param options - Subscription options
+   * @returns Unsubscribe function
+   */
+  on(types: string[], handler: BusEventHandler, options?: SubscribeOptions): Unsubscribe;
+
+  /**
+   * Subscribe to all events.
+   *
+   * @param handler - Callback invoked for every event
+   * @param options - Subscription options
+   * @returns Unsubscribe function
+   */
+  onAny(handler: BusEventHandler, options?: SubscribeOptions): Unsubscribe;
+
+  /**
+   * Subscribe to an event type once (auto-unsubscribes after first trigger).
+   *
+   * @param type - Event type to subscribe to
+   * @param handler - Callback function
+   * @returns Unsubscribe function
+   */
+  once<T extends string>(type: T, handler: BusEventHandler<BusEvent & { type: T }>): Unsubscribe;
+
+  /**
+   * Subscribe to a CommandEvent with full type safety.
+   *
+   * @example
+   * ```typescript
+   * bus.onCommand("container_create_request", (event) => {
+   *   event.data.requestId;    // string
+   *   event.data.containerId;  // string
+   * });
+   * ```
+   *
+   * @param type - The command event type
+   * @param handler - Callback with fully typed event
+   * @returns Unsubscribe function
+   */
+  onCommand<T extends keyof CommandEventMap>(
+    type: T,
+    handler: (event: CommandEventMap[T]) => void
+  ): Unsubscribe;
+
+  /**
+   * Emit a CommandEvent with full type safety.
+   *
+   * @example
+   * ```typescript
+   * bus.emitCommand("container_create_request", {
+   *   requestId: "req_123",
+   *   containerId: "my-container"
+   * });
+   * ```
+   *
+   * @param type - The command event type
+   * @param data - Event data (type-checked)
+   */
+  emitCommand<T extends keyof CommandEventMap>(type: T, data: CommandEventMap[T]["data"]): void;
+
+  /**
+   * Send a command request and wait for response.
+   *
+   * Automatically generates requestId, emits request, waits for matching response.
+   *
+   * @example
+   * ```typescript
+   * const response = await bus.request("container_create_request", {
+   *   containerId: "my-container"
+   * });
+   * // response is ContainerCreateResponse
+   * console.log(response.data.containerId);
+   * ```
+   *
+   * @param type - The request event type
+   * @param data - Request data (without requestId)
+   * @param timeout - Timeout in milliseconds (default: 30000)
+   * @returns Promise of response event
+   */
+  request<T extends CommandRequestType>(
+    type: T,
+    data: RequestDataFor<T>,
+    timeout?: number
+  ): Promise<ResponseEventFor<T>>;
+
+  /**
+   * Get a read-only consumer view of the bus.
+   *
+   * Use this to safely expose event subscription to external code
+   * without allowing them to emit events.
+   *
+   * @example
+   * ```typescript
+   * class BusDriver {
+   *   constructor(consumer: EventConsumer) {
+   *     // Can only subscribe, cannot emit
+   *     consumer.on('text_delta', ...);
+   *   }
+   * }
+   * ```
+   *
+   * @returns EventConsumer - Read-only view
+   */
+  asConsumer(): EventConsumer;
+
+  /**
+   * Get a write-only producer view of the bus.
+   *
+   * Use this to give components the ability to emit events
+   * without exposing subscription capabilities.
+   *
+   * @example
+   * ```typescript
+   * class ClaudeReceptor {
+   *   constructor(producer: EventProducer) {
+   *     // Can only emit, cannot subscribe
+   *     producer.emit({ type: 'text_delta', ... });
+   *   }
+   * }
+   * ```
+   *
+   * @returns EventProducer - Write-only view
+   */
+  asProducer(): EventProducer;
+
+  /**
+   * Destroy the bus and clean up resources.
+   *
+   * All subscriptions will be terminated.
+   * After calling destroy():
+   * - All subscriptions are removed
+   * - New emissions are ignored
+   * - New subscriptions are no-ops
+   */
+  destroy(): void;
+}