@agentxjs/core 1.9.1-dev

package/src/driver/types.ts

@@ -0,0 +1,363 @@
+/**
+ * Driver Types - LLM Communication Layer
+ *
+ * Driver is the bridge between AgentX and external LLM (Claude, OpenAI, etc.)
+ *
+ * ```
+ *                    AgentX
+ *                      │
+ *         receive()    │    AsyncIterable<StreamEvent>
+ *         ─────────►   │   ◄─────────────────────────
+ *                      │
+ *              ┌───────────────┐
+ *              │    Driver     │
+ *              │               │
+ *              │  UserMessage  │
+ *              │      ↓        │
+ *              │   [SDK call]  │
+ *              │      ↓        │
+ *              │  StreamEvent  │
+ *              └───────────────┘
+ *                      │
+ *                      ▼
+ *               External LLM
+ *               (Claude SDK)
+ * ```
+ *
+ * Key Design:
+ * - Driver = single session communication (like Kimi SDK's Session)
+ * - Clear input/output boundary (for recording/playback)
+ * - Configuration defined by us (capability boundary)
+ */
+
+import type { UserMessage } from "../agent/types/message";
+
+// ============================================================================
+// MCP Server Configuration
+// ============================================================================
+
+/**
+ * MCP Server configuration
+ *
+ * Defines how to launch an MCP server process.
+ */
+export interface McpServerConfig {
+  /**
+   * Command to run the MCP server
+   */
+  command: string;
+
+  /**
+   * Command arguments
+   */
+  args?: string[];
+
+  /**
+   * Environment variables for the process
+   */
+  env?: Record<string, string>;
+}
+
+// ============================================================================
+// Stream Event (Lightweight)
+// ============================================================================
+
+/**
+ * StopReason - Why the LLM stopped generating
+ */
+export type StopReason =
+  | "end_turn"
+  | "max_tokens"
+  | "tool_use"
+  | "stop_sequence"
+  | "content_filter"
+  | "error"
+  | "other";
+
+/**
+ * StreamEvent - Lightweight event from Driver
+ *
+ * Only contains essential fields: type, timestamp, data
+ * No source, category, intent, context (those are added by upper layers)
+ */
+export interface StreamEvent<T extends string = string, D = unknown> {
+  readonly type: T;
+  readonly timestamp: number;
+  readonly data: D;
+}
+
+// Stream Event Types
+export interface MessageStartEvent extends StreamEvent<
+  "message_start",
+  {
+    messageId: string;
+    model: string;
+  }
+> {}
+
+export interface MessageStopEvent extends StreamEvent<
+  "message_stop",
+  {
+    stopReason: StopReason;
+  }
+> {}
+
+export interface TextDeltaEvent extends StreamEvent<
+  "text_delta",
+  {
+    text: string;
+  }
+> {}
+
+export interface ToolUseStartEvent extends StreamEvent<
+  "tool_use_start",
+  {
+    toolCallId: string;
+    toolName: string;
+  }
+> {}
+
+export interface InputJsonDeltaEvent extends StreamEvent<
+  "input_json_delta",
+  {
+    partialJson: string;
+  }
+> {}
+
+export interface ToolUseStopEvent extends StreamEvent<
+  "tool_use_stop",
+  {
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+  }
+> {}
+
+export interface ToolResultEvent extends StreamEvent<
+  "tool_result",
+  {
+    toolCallId: string;
+    result: unknown;
+    isError?: boolean;
+  }
+> {}
+
+export interface ErrorEvent extends StreamEvent<
+  "error",
+  {
+    message: string;
+    errorCode?: string;
+  }
+> {}
+
+export interface InterruptedEvent extends StreamEvent<
+  "interrupted",
+  {
+    reason: "user" | "timeout" | "error";
+  }
+> {}
+
+/**
+ * DriverStreamEvent - Union of all stream events from Driver
+ */
+export type DriverStreamEvent =
+  | MessageStartEvent
+  | MessageStopEvent
+  | TextDeltaEvent
+  | ToolUseStartEvent
+  | InputJsonDeltaEvent
+  | ToolUseStopEvent
+  | ToolResultEvent
+  | ErrorEvent
+  | InterruptedEvent;
+
+/**
+ * DriverStreamEventType - String literal union of event types
+ */
+export type DriverStreamEventType = DriverStreamEvent["type"];
+
+// ============================================================================
+// Driver Configuration
+// ============================================================================
+
+/**
+ * DriverConfig - All configuration for creating a Driver
+ *
+ * This is our capability boundary - we define what we support.
+ * Specific implementations (Claude, OpenAI) must work within this.
+ */
+export interface DriverConfig {
+  // === Provider Configuration ===
+
+  /**
+   * API key for authentication
+   */
+  apiKey: string;
+
+  /**
+   * Base URL for API endpoint (optional, for custom deployments)
+   */
+  baseUrl?: string;
+
+  /**
+   * Model identifier (e.g., "claude-sonnet-4-20250514")
+   */
+  model?: string;
+
+  /**
+   * Request timeout in milliseconds (default: 600000 = 10 minutes)
+   */
+  timeout?: number;
+
+  // === Agent Configuration ===
+
+  /**
+   * Agent ID (for identification and logging)
+   */
+  agentId: string;
+
+  /**
+   * System prompt for the agent
+   */
+  systemPrompt?: string;
+
+  /**
+   * Current working directory for tool execution
+   */
+  cwd?: string;
+
+  /**
+   * MCP servers configuration
+   */
+  mcpServers?: Record<string, McpServerConfig>;
+
+  // === Session Configuration ===
+
+  /**
+   * Session ID to resume (for conversation continuity)
+   *
+   * If provided, Driver will attempt to resume this session.
+   * If not provided, a new session is created.
+   */
+  resumeSessionId?: string;
+
+  /**
+   * Callback when SDK session ID is captured
+   *
+   * Called once when the session ID becomes available.
+   * Save this ID to enable session resume later.
+   */
+  onSessionIdCaptured?: (sessionId: string) => void;
+}
+
+// ============================================================================
+// Driver State
+// ============================================================================
+
+/**
+ * DriverState - Current state of the Driver
+ *
+ * - idle: Ready to receive messages
+ * - active: Currently processing a message
+ * - disposed: Driver has been disposed, cannot be used
+ */
+export type DriverState = "idle" | "active" | "disposed";
+
+// ============================================================================
+// Driver Interface
+// ============================================================================
+
+/**
+ * Driver - LLM Communication Interface
+ *
+ * Responsible for a single session's communication with LLM.
+ * Similar to Kimi SDK's Session concept.
+ *
+ * Lifecycle:
+ * 1. createDriver(config) → Driver instance
+ * 2. driver.initialize() → Start SDK, MCP servers
+ * 3. driver.receive(message) → Send message, get events
+ * 4. driver.dispose() → Cleanup
+ *
+ * @example
+ * ```typescript
+ * const driver = createDriver(config);
+ * await driver.initialize();
+ *
+ * const events = driver.receive(message);
+ * for await (const event of events) {
+ *   if (event.type === "text_delta") {
+ *     console.log(event.data.text);
+ *   }
+ * }
+ *
+ * await driver.dispose();
+ * ```
+ */
+export interface Driver {
+  /**
+   * Driver name (for identification and logging)
+   */
+  readonly name: string;
+
+  /**
+   * SDK Session ID (available after first message)
+   */
+  readonly sessionId: string | null;
+
+  /**
+   * Current state
+   */
+  readonly state: DriverState;
+
+  /**
+   * Receive a user message and return stream of events
+   *
+   * @param message - User message to send
+   * @returns AsyncIterable of stream events
+   */
+  receive(message: UserMessage): AsyncIterable<DriverStreamEvent>;
+
+  /**
+   * Interrupt current operation
+   *
+   * Stops the current receive() operation gracefully.
+   * The AsyncIterable will emit an "interrupted" event and complete.
+   */
+  interrupt(): void;
+
+  /**
+   * Initialize the Driver
+   *
+   * Starts SDK subprocess, MCP servers, etc.
+   * Must be called before receive().
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Dispose and cleanup resources
+   *
+   * Stops SDK subprocess, MCP servers, etc.
+   * Driver cannot be used after dispose().
+   */
+  dispose(): Promise<void>;
+}
+
+// ============================================================================
+// CreateDriver Function Type
+// ============================================================================
+
+/**
+ * CreateDriver - Factory function type for creating Driver instances
+ *
+ * Each implementation package exports a function of this type.
+ *
+ * @example
+ * ```typescript
+ * // @agentxjs/claude-driver
+ * export const createDriver: CreateDriver = (config) => {
+ *   return new ClaudeDriverImpl(config);
+ * };
+ * ```
+ */
+export type CreateDriver = (config: DriverConfig) => Driver;

package/src/event/EventBus.ts

@@ -0,0 +1,260 @@
+/**
+ * EventBus - Central event bus implementation
+ *
+ * Pub/Sub event bus for runtime communication.
+ * Uses RxJS Subject for reactive event distribution.
+ */
+
+import type {
+  EventBus,
+  EventProducer,
+  EventConsumer,
+  Unsubscribe,
+  BusEventHandler,
+  SubscribeOptions,
+  BusEvent,
+  CommandEventMap,
+  CommandRequestType,
+  ResponseEventFor,
+  RequestDataFor,
+  CommandRequestResponseMap,
+} from "./types";
+import { Subject } from "rxjs";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("event/EventBus");
+
+/**
+ * Generate a unique request ID
+ *
+ * Uses crypto.randomUUID when available (modern browsers and Node.js 19+),
+ * falls back to a timestamp-based ID for older environments.
+ */
+function generateRequestId(): string {
+  // Use crypto.randomUUID if available (browsers and modern Node.js)
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return `req_${crypto.randomUUID()}`;
+  }
+  // Fallback for older environments
+  return `req_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+}
+
+/**
+ * Internal subscription record
+ */
+interface Subscription {
+  id: number;
+  type: string | string[] | "*";
+  handler: BusEventHandler;
+  filter?: (event: BusEvent) => boolean;
+  priority: number;
+  once: boolean;
+}
+
+/**
+ * EventBusImpl - EventBus implementation using RxJS Subject
+ */
+export class EventBusImpl implements EventBus {
+  private readonly subject = new Subject<BusEvent>();
+  private subscriptions: Subscription[] = [];
+  private nextId = 0;
+  private isDestroyed = false;
+
+  // Cached restricted views
+  private producerView: EventProducer | null = null;
+  private consumerView: EventConsumer | null = null;
+
+  constructor() {
+    this.subject.subscribe((event) => {
+      this.dispatch(event);
+    });
+  }
+
+  emit(event: BusEvent): void {
+    if (this.isDestroyed) return;
+    this.subject.next(event);
+  }
+
+  emitBatch(events: BusEvent[]): void {
+    for (const event of events) {
+      this.emit(event);
+    }
+  }
+
+  on<T extends string>(
+    typeOrTypes: T | string[],
+    handler: BusEventHandler<BusEvent & { type: T }>,
+    options?: SubscribeOptions<BusEvent & { type: T }>
+  ): Unsubscribe {
+    if (this.isDestroyed) return () => {};
+
+    const subscription: Subscription = {
+      id: this.nextId++,
+      type: typeOrTypes,
+      handler: handler as BusEventHandler,
+      filter: options?.filter as ((event: BusEvent) => boolean) | undefined,
+      priority: options?.priority ?? 0,
+      once: options?.once ?? false,
+    };
+
+    this.subscriptions.push(subscription);
+    this.sortByPriority();
+
+    return () => this.removeSubscription(subscription.id);
+  }
+
+  onAny(handler: BusEventHandler, options?: SubscribeOptions): Unsubscribe {
+    if (this.isDestroyed) return () => {};
+
+    const subscription: Subscription = {
+      id: this.nextId++,
+      type: "*",
+      handler,
+      filter: options?.filter as ((event: BusEvent) => boolean) | undefined,
+      priority: options?.priority ?? 0,
+      once: options?.once ?? false,
+    };
+
+    this.subscriptions.push(subscription);
+    this.sortByPriority();
+
+    return () => this.removeSubscription(subscription.id);
+  }
+
+  once<T extends string>(type: T, handler: BusEventHandler<BusEvent & { type: T }>): Unsubscribe {
+    return this.on(type, handler, { once: true });
+  }
+
+  onCommand<T extends keyof CommandEventMap>(
+    type: T,
+    handler: (event: CommandEventMap[T]) => void
+  ): Unsubscribe {
+    // Reuse the existing on() implementation with type casting
+    return this.on(type as string, handler as BusEventHandler);
+  }
+
+  emitCommand<T extends keyof CommandEventMap>(type: T, data: CommandEventMap[T]["data"]): void {
+    this.emit({
+      type,
+      timestamp: Date.now(),
+      data,
+      source: "command",
+      category: (type as string).endsWith("_response") ? "response" : "request",
+      intent: (type as string).endsWith("_response") ? "result" : "request",
+    } as BusEvent);
+  }
+
+  request<T extends CommandRequestType>(
+    type: T,
+    data: RequestDataFor<T>,
+    timeout: number = 30000
+  ): Promise<ResponseEventFor<T>> {
+    return new Promise((resolve, reject) => {
+      const requestId = generateRequestId();
+
+      // Get response type from request type
+      const responseType = (type as string).replace(
+        "_request",
+        "_response"
+      ) as CommandRequestResponseMap[T];
+
+      // Set up timeout
+      const timer = setTimeout(() => {
+        unsubscribe();
+        reject(new Error(`Request timeout: ${type}`));
+      }, timeout);
+
+      // Listen for response
+      const unsubscribe = this.onCommand(responseType, (event) => {
+        // Match by requestId
+        if ((event.data as { requestId: string }).requestId === requestId) {
+          clearTimeout(timer);
+          unsubscribe();
+          resolve(event as ResponseEventFor<T>);
+        }
+      });
+
+      // Emit request with generated requestId
+      this.emitCommand(type, { ...data, requestId } as CommandEventMap[T]["data"]);
+    });
+  }
+
+  destroy(): void {
+    if (this.isDestroyed) return;
+    this.isDestroyed = true;
+    this.subscriptions = [];
+    this.subject.complete();
+  }
+
+  private dispatch(event: BusEvent): void {
+    const toRemove: number[] = [];
+
+    for (const sub of this.subscriptions) {
+      if (!this.matchesType(sub.type, event.type)) continue;
+      if (sub.filter && !sub.filter(event)) continue;
+
+      try {
+        sub.handler(event);
+      } catch (err) {
+        logger.error("Event handler error", {
+          eventType: event.type,
+          subscriptionType: sub.type,
+          error: err instanceof Error ? err.message : String(err),
+          stack: err instanceof Error ? err.stack : undefined,
+        });
+      }
+
+      if (sub.once) {
+        toRemove.push(sub.id);
+      }
+    }
+
+    for (const id of toRemove) {
+      this.removeSubscription(id);
+    }
+  }
+
+  private matchesType(subscriptionType: string | string[] | "*", eventType: string): boolean {
+    if (subscriptionType === "*") return true;
+    if (Array.isArray(subscriptionType)) return subscriptionType.includes(eventType);
+    return subscriptionType === eventType;
+  }
+
+  private sortByPriority(): void {
+    this.subscriptions.sort((a, b) => b.priority - a.priority);
+  }
+
+  private removeSubscription(id: number): void {
+    this.subscriptions = this.subscriptions.filter((s) => s.id !== id);
+  }
+
+  /**
+   * Get a read-only consumer view (only subscribe methods)
+   */
+  asConsumer(): EventConsumer {
+    if (!this.consumerView) {
+      this.consumerView = {
+        on: this.on.bind(this),
+        onAny: this.onAny.bind(this),
+        once: this.once.bind(this),
+        onCommand: this.onCommand.bind(this),
+        request: this.request.bind(this),
+      };
+    }
+    return this.consumerView;
+  }
+
+  /**
+   * Get a write-only producer view (only emit methods)
+   */
+  asProducer(): EventProducer {
+    if (!this.producerView) {
+      this.producerView = {
+        emit: this.emit.bind(this),
+        emitBatch: this.emitBatch.bind(this),
+        emitCommand: this.emitCommand.bind(this),
+      };
+    }
+    return this.producerView;
+  }
+}