@agentxjs/devtools 1.9.1-dev

package/src/mock/MockDriver.ts

@@ -0,0 +1,396 @@
+/**
+ * MockDriver - Mock Driver for Testing
+ *
+ * Plays back recorded fixtures when receiving messages.
+ * Implements the new Driver interface with receive() returning AsyncIterable.
+ *
+ * Usage:
+ * ```typescript
+ * const driver = new MockDriver({
+ *   fixture: "simple-reply",
+ * });
+ *
+ * await driver.initialize();
+ *
+ * for await (const event of driver.receive({ content: "Hello" })) {
+ *   if (event.type === "text_delta") {
+ *     console.log(event.data.text);
+ *   }
+ * }
+ *
+ * await driver.dispose();
+ * ```
+ */
+
+import type {
+  Driver,
+  DriverConfig,
+  DriverState,
+  DriverStreamEvent,
+} from "@agentxjs/core/driver";
+import type { UserMessage } from "@agentxjs/core/agent";
+import type { Fixture, FixtureEvent, MockDriverOptions } from "../types";
+import { BUILTIN_FIXTURES } from "../../fixtures";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("devtools/MockDriver");
+
+/**
+ * MockDriver - Playback driver for testing
+ *
+ * Implements the new Driver interface:
+ * - receive() returns AsyncIterable<DriverStreamEvent>
+ * - Clear input/output boundaries for testing
+ */
+export class MockDriver implements Driver {
+  readonly name = "MockDriver";
+
+  private _sessionId: string | null = null;
+  private _state: DriverState = "idle";
+
+  private readonly config: DriverConfig | null;
+  private readonly options: MockDriverOptions;
+  private readonly fixtures: Map<string, Fixture>;
+  private currentFixture: Fixture;
+
+  // For interrupt handling
+  private isInterrupted = false;
+
+  // Event cursor for multi-turn conversations
+  private eventCursor = 0;
+
+  /**
+   * Create a MockDriver
+   *
+   * @param options - MockDriverOptions or DriverConfig
+   * @param mockOptions - MockDriverOptions if first param is DriverConfig
+   */
+  constructor(
+    optionsOrConfig: MockDriverOptions | DriverConfig,
+    mockOptions?: MockDriverOptions
+  ) {
+    // Detect which constructor form is being used
+    if (mockOptions !== undefined || "apiKey" in optionsOrConfig) {
+      // Factory mode: (DriverConfig, MockDriverOptions)
+      this.config = optionsOrConfig as DriverConfig;
+      const opts = mockOptions || {};
+      this.options = {
+        defaultDelay: 10,
+        speedMultiplier: 0,
+        ...opts,
+      };
+    } else {
+      // Simple mode: (MockDriverOptions)
+      this.config = null;
+      const opts = optionsOrConfig as MockDriverOptions;
+      this.options = {
+        defaultDelay: 10,
+        speedMultiplier: 0,
+        ...opts,
+      };
+    }
+
+    // Initialize fixtures
+    this.fixtures = new Map(BUILTIN_FIXTURES);
+    if (this.options.fixtures) {
+      for (const [name, fixture] of this.options.fixtures) {
+        this.fixtures.set(name, fixture);
+      }
+    }
+
+    // Set initial fixture
+    this.currentFixture = this.resolveFixture(this.options.fixture || "simple-reply");
+
+    logger.debug("MockDriver created", {
+      fixture: this.currentFixture.name,
+      agentId: this.config?.agentId,
+    });
+  }
+
+  // ============================================================================
+  // Driver Interface Properties
+  // ============================================================================
+
+  get sessionId(): string | null {
+    return this._sessionId;
+  }
+
+  get state(): DriverState {
+    return this._state;
+  }
+
+  // ============================================================================
+  // Lifecycle Methods
+  // ============================================================================
+
+  /**
+   * Initialize the Driver
+   */
+  async initialize(): Promise<void> {
+    if (this._state !== "idle") {
+      throw new Error(`Cannot initialize: MockDriver is in "${this._state}" state`);
+    }
+
+    // Generate a mock session ID
+    this._sessionId = `mock-session-${Date.now()}`;
+
+    logger.debug("MockDriver initialized", {
+      sessionId: this._sessionId,
+      fixture: this.currentFixture.name,
+    });
+  }
+
+  /**
+   * Dispose and cleanup resources
+   */
+  async dispose(): Promise<void> {
+    if (this._state === "disposed") {
+      return;
+    }
+
+    this._state = "disposed";
+    this.isInterrupted = true;
+
+    logger.debug("MockDriver disposed");
+  }
+
+  // ============================================================================
+  // Core Methods
+  // ============================================================================
+
+  /**
+   * Receive a user message and return stream of events
+   *
+   * Plays back the current fixture as DriverStreamEvent.
+   *
+   * @param message - User message (ignored for playback)
+   * @returns AsyncIterable of stream events
+   */
+  async *receive(_message: UserMessage): AsyncIterable<DriverStreamEvent> {
+    if (this._state === "disposed") {
+      throw new Error("Cannot receive: MockDriver is disposed");
+    }
+
+    if (this._state === "active") {
+      throw new Error("Cannot receive: MockDriver is already processing a message");
+    }
+
+    this._state = "active";
+    this.isInterrupted = false;
+
+    const { speedMultiplier = 0, defaultDelay = 10 } = this.options;
+    const events = this.currentFixture.events;
+
+    try {
+      // Start from cursor position and play until message_stop
+      while (this.eventCursor < events.length) {
+        const fixtureEvent = events[this.eventCursor];
+        this.eventCursor++;
+
+        // Check for interrupt
+        if (this.isInterrupted) {
+          yield {
+            type: "interrupted",
+            timestamp: Date.now(),
+            data: { reason: "user" },
+          };
+          break;
+        }
+
+        // Apply delay
+        const delay = fixtureEvent.delay || defaultDelay;
+        if (delay > 0 && speedMultiplier > 0) {
+          await this.sleep(delay * speedMultiplier);
+        }
+
+        // Convert and yield event
+        const event = this.convertFixtureEvent(fixtureEvent);
+        if (event) {
+          yield event;
+        }
+
+        // Stop at message_stop (end of one turn)
+        if (fixtureEvent.type === "message_stop") {
+          break;
+        }
+      }
+    } finally {
+      this._state = "idle";
+    }
+  }
+
+  /**
+   * Interrupt current operation
+   */
+  interrupt(): void {
+    if (this._state !== "active") {
+      logger.debug("Interrupt called but no active operation");
+      return;
+    }
+
+    logger.debug("MockDriver interrupted");
+    this.isInterrupted = true;
+  }
+
+  // ============================================================================
+  // Fixture Management
+  // ============================================================================
+
+  /**
+   * Set the fixture to use for next playback
+   */
+  setFixture(fixture: string | Fixture): void {
+    this.currentFixture = this.resolveFixture(fixture);
+    this.eventCursor = 0; // Reset cursor when fixture changes
+    logger.debug("Fixture changed", { fixture: this.currentFixture.name });
+  }
+
+  /**
+   * Add a custom fixture
+   */
+  addFixture(fixture: Fixture): void {
+    this.fixtures.set(fixture.name, fixture);
+  }
+
+  /**
+   * Get the current fixture
+   */
+  getFixture(): Fixture {
+    return this.currentFixture;
+  }
+
+  /**
+   * Get available fixture names
+   */
+  getFixtureNames(): string[] {
+    return Array.from(this.fixtures.keys());
+  }
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  /**
+   * Resolve fixture from name or Fixture object
+   */
+  private resolveFixture(fixture: string | Fixture): Fixture {
+    if (typeof fixture === "string") {
+      const found = this.fixtures.get(fixture);
+      if (!found) {
+        logger.warn(`Fixture "${fixture}" not found, using "simple-reply"`);
+        return this.fixtures.get("simple-reply")!;
+      }
+      return found;
+    }
+    return fixture;
+  }
+
+  /**
+   * Convert FixtureEvent to DriverStreamEvent
+   */
+  private convertFixtureEvent(fixtureEvent: FixtureEvent): DriverStreamEvent | null {
+    const timestamp = Date.now();
+    const data = fixtureEvent.data as Record<string, unknown>;
+
+    switch (fixtureEvent.type) {
+      case "message_start":
+        return {
+          type: "message_start",
+          timestamp,
+          data: {
+            messageId: (data.messageId as string) || `msg_${timestamp}`,
+            model: (data.model as string) || "mock-model",
+          },
+        };
+
+      case "text_delta":
+        return {
+          type: "text_delta",
+          timestamp,
+          data: { text: (data.text as string) || "" },
+        };
+
+      case "tool_use_start":
+        return {
+          type: "tool_use_start",
+          timestamp,
+          data: {
+            toolCallId: (data.toolCallId as string) || `tool_${timestamp}`,
+            toolName: (data.toolName as string) || "",
+          },
+        };
+
+      case "input_json_delta":
+        return {
+          type: "input_json_delta",
+          timestamp,
+          data: { partialJson: (data.partialJson as string) || "" },
+        };
+
+      case "tool_use_stop":
+        return {
+          type: "tool_use_stop",
+          timestamp,
+          data: {
+            toolCallId: (data.toolCallId as string) || "",
+            toolName: (data.toolName as string) || "",
+            input: (data.input as Record<string, unknown>) || {},
+          },
+        };
+
+      case "tool_result":
+        return {
+          type: "tool_result",
+          timestamp,
+          data: {
+            toolCallId: (data.toolCallId as string) || "",
+            result: data.result,
+            isError: data.isError as boolean | undefined,
+          },
+        };
+
+      case "message_stop":
+        return {
+          type: "message_stop",
+          timestamp,
+          data: {
+            stopReason: (data.stopReason as "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | "other") || "end_turn",
+          },
+        };
+
+      case "error":
+        return {
+          type: "error",
+          timestamp,
+          data: {
+            message: (data.message as string) || "Unknown error",
+            errorCode: (data.errorCode as string) || "mock_error",
+          },
+        };
+
+      default:
+        // Pass through unknown events with generic structure
+        logger.debug(`Unknown fixture event type: ${fixtureEvent.type}`);
+        return null;
+    }
+  }
+
+  /**
+   * Sleep for specified milliseconds
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+/**
+ * Create a MockDriver factory function
+ *
+ * Returns a CreateDriver-compatible function.
+ *
+ * @param mockOptions - Options for all created drivers
+ * @returns CreateDriver function
+ */
+export function createMockDriver(mockOptions: MockDriverOptions = {}): (config: DriverConfig) => Driver {
+  return (config: DriverConfig) => new MockDriver(config, mockOptions);
+}

package/src/mock/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Mock Driver Module
+ *
+ * Provides MockDriver for playback testing with fixtures.
+ *
+ * Usage:
+ * ```typescript
+ * import { MockDriver, createMockDriver } from "@agentxjs/devtools/mock";
+ *
+ * // Simple usage
+ * const driver = new MockDriver({ fixture: "simple-reply" });
+ * await driver.initialize();
+ * for await (const event of driver.receive({ content: "Hello" })) {
+ *   console.log(event);
+ * }
+ *
+ * // Factory usage (for Provider)
+ * const createDriver = createMockDriver({ fixture: "simple-reply" });
+ * const driver = createDriver(config);
+ * ```
+ */
+
+export { MockDriver, createMockDriver } from "./MockDriver";

package/src/recorder/RecordingDriver.ts

@@ -0,0 +1,258 @@
+/**
+ * RecordingDriver - Wraps a real driver to record events
+ *
+ * Used to capture real LLM API responses and save them as fixtures.
+ * These fixtures can then be played back by MockDriver for testing.
+ *
+ * Usage:
+ * ```typescript
+ * import { createClaudeDriver } from "@agentxjs/claude-driver";
+ * import { RecordingDriver } from "@agentxjs/devtools/recorder";
+ *
+ * // Create real driver
+ * const realDriver = createClaudeDriver(config);
+ *
+ * // Wrap with recorder
+ * const recorder = new RecordingDriver({
+ *   driver: realDriver,
+ *   name: "my-scenario",
+ *   description: "User asks about weather",
+ * });
+ *
+ * await recorder.initialize();
+ *
+ * // Use like a normal driver - events are recorded
+ * for await (const event of recorder.receive({ content: "Hello" })) {
+ *   console.log(event);
+ * }
+ *
+ * // Save the fixture
+ * await recorder.saveFixture("./fixtures/my-scenario.json");
+ * ```
+ */
+
+import type {
+  Driver,
+  DriverState,
+  DriverStreamEvent,
+} from "@agentxjs/core/driver";
+import type { UserMessage } from "@agentxjs/core/agent";
+import type { Fixture, FixtureEvent } from "../types";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("devtools/RecordingDriver");
+
+/**
+ * Options for RecordingDriver
+ */
+export interface RecordingDriverOptions {
+  /**
+   * The real driver to wrap
+   */
+  driver: Driver;
+
+  /**
+   * Fixture name for the recording
+   */
+  name: string;
+
+  /**
+   * Description for the recording
+   */
+  description?: string;
+}
+
+/**
+ * Recorded event with timing
+ */
+interface RecordedEvent {
+  event: DriverStreamEvent;
+  timestamp: number;
+}
+
+/**
+ * RecordingDriver - Records events from a real driver
+ *
+ * Implements the new Driver interface by wrapping a real driver
+ * and intercepting events from receive().
+ */
+export class RecordingDriver implements Driver {
+  readonly name = "RecordingDriver";
+
+  private readonly realDriver: Driver;
+  private readonly fixtureName: string;
+  private readonly fixtureDescription?: string;
+
+  private recordedEvents: RecordedEvent[] = [];
+  private recordingStartTime: number = 0;
+
+  constructor(options: RecordingDriverOptions) {
+    this.realDriver = options.driver;
+    this.fixtureName = options.name;
+    this.fixtureDescription = options.description;
+
+    logger.info("RecordingDriver created", { name: this.fixtureName });
+  }
+
+  // ============================================================================
+  // Driver Interface Properties (delegate to real driver)
+  // ============================================================================
+
+  get sessionId(): string | null {
+    return this.realDriver.sessionId;
+  }
+
+  get state(): DriverState {
+    return this.realDriver.state;
+  }
+
+  // ============================================================================
+  // Lifecycle Methods (delegate to real driver)
+  // ============================================================================
+
+  async initialize(): Promise<void> {
+    await this.realDriver.initialize();
+    this.recordingStartTime = Date.now();
+    this.recordedEvents = [];
+    logger.info("RecordingDriver initialized, recording started", {
+      name: this.fixtureName,
+    });
+  }
+
+  async dispose(): Promise<void> {
+    await this.realDriver.dispose();
+    logger.info("RecordingDriver disposed", {
+      name: this.fixtureName,
+      eventsRecorded: this.recordedEvents.length,
+    });
+  }
+
+  // ============================================================================
+  // Core Methods
+  // ============================================================================
+
+  /**
+   * Receive a user message and return stream of events
+   *
+   * Wraps the real driver's receive() and records all events.
+   */
+  async *receive(message: UserMessage): AsyncIterable<DriverStreamEvent> {
+    logger.debug("RecordingDriver receiving message", {
+      name: this.fixtureName,
+    });
+
+    // Call the real driver and intercept events
+    for await (const event of this.realDriver.receive(message)) {
+      // Record the event
+      this.recordEvent(event);
+
+      // Pass through to caller
+      yield event;
+    }
+
+    logger.debug("RecordingDriver receive completed", {
+      name: this.fixtureName,
+      eventsRecorded: this.recordedEvents.length,
+    });
+  }
+
+  /**
+   * Interrupt current operation (delegate to real driver)
+   */
+  interrupt(): void {
+    this.realDriver.interrupt();
+  }
+
+  // ============================================================================
+  // Recording Methods
+  // ============================================================================
+
+  /**
+   * Record an event
+   */
+  private recordEvent(event: DriverStreamEvent): void {
+    this.recordedEvents.push({
+      event,
+      timestamp: Date.now(),
+    });
+
+    logger.debug("Event recorded", {
+      type: event.type,
+      totalEvents: this.recordedEvents.length,
+    });
+  }
+
+  /**
+   * Get the recorded fixture
+   */
+  getFixture(): Fixture {
+    const events: FixtureEvent[] = [];
+    let lastTimestamp = this.recordingStartTime;
+
+    for (const recorded of this.recordedEvents) {
+      const delay = recorded.timestamp - lastTimestamp;
+      lastTimestamp = recorded.timestamp;
+
+      events.push({
+        type: recorded.event.type,
+        delay: Math.max(0, delay),
+        data: recorded.event.data,
+      });
+    }
+
+    return {
+      name: this.fixtureName,
+      description: this.fixtureDescription,
+      recordedAt: this.recordingStartTime,
+      events,
+    };
+  }
+
+  /**
+   * Save the recorded fixture to a JSON file
+   */
+  async saveFixture(filePath: string): Promise<void> {
+    const fixture = this.getFixture();
+    const json = JSON.stringify(fixture, null, 2);
+
+    // Use dynamic import for Node.js fs
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(filePath, json, "utf-8");
+
+    logger.info("Fixture saved", {
+      path: filePath,
+      name: fixture.name,
+      eventCount: fixture.events.length,
+    });
+  }
+
+  /**
+   * Get the number of recorded events
+   */
+  get eventCount(): number {
+    return this.recordedEvents.length;
+  }
+
+  /**
+   * Clear recorded events (start fresh recording)
+   */
+  clearRecording(): void {
+    this.recordedEvents = [];
+    this.recordingStartTime = Date.now();
+    logger.debug("Recording cleared");
+  }
+
+  /**
+   * Get raw recorded events (for debugging)
+   */
+  getRawEvents(): RecordedEvent[] {
+    return [...this.recordedEvents];
+  }
+}
+
+/**
+ * Create a RecordingDriver that wraps a real driver
+ */
+export function createRecordingDriver(options: RecordingDriverOptions): RecordingDriver {
+  return new RecordingDriver(options);
+}

package/src/recorder/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Recording Driver Module
+ *
+ * Provides RecordingDriver for capturing LLM events from any driver.
+ * Use these recordings as fixtures for MockDriver to test Runtime.
+ *
+ * Usage:
+ * ```typescript
+ * import { createRecordingDriver } from "@agentxjs/devtools/recorder";
+ *
+ * const recorder = createRecordingDriver({
+ *   driver: realDriver,
+ *   name: "my-scenario",
+ * });
+ *
+ * // After use, save the fixture
+ * await recorder.saveFixture("./fixtures/my-scenario.json");
+ * ```
+ */
+
+export {
+  RecordingDriver,
+  createRecordingDriver,
+  type RecordingDriverOptions,
+} from "./RecordingDriver";