@agentxjs/devtools 1.9.5-dev → 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,240 @@
+import { CreateDriver, Driver } from '@agentxjs/core/driver';
+import { F as Fixture } from './types-C6Lf3vz2.js';
+export { a as FixtureEvent, M as MockDriverOptions } from './types-C6Lf3vz2.js';
+export { MockDriver, createMockDriver } from './mock/index.js';
+export { RecordingDriver, RecordingDriverOptions, createRecordingDriver } from './recorder/index.js';
+export { BUILTIN_FIXTURES, EMPTY_RESPONSE, ERROR_RESPONSE, LONG_REPLY, SIMPLE_REPLY, TOOL_CALL, getFixture, listFixtures } from './fixtures/index.js';
+import '@agentxjs/core/agent';
+
+/**
+ * Devtools SDK - VCR-style fixture management
+ *
+ * Automatically uses existing fixtures or records new ones on-the-fly.
+ *
+ * Usage:
+ * ```typescript
+ * import { createDevtools } from "@agentxjs/devtools";
+ *
+ * import { env } from "@agentxjs/devtools";
+ *
+ * const devtools = createDevtools({
+ *   fixturesDir: "./fixtures",
+ *   apiKey: env.apiKey,
+ * });
+ *
+ * // Has fixture → playback (MockDriver)
+ * // No fixture → call API, record, save, return MockDriver
+ * const driver = await devtools.driver("hello-test", {
+ *   message: "Hello!",
+ * });
+ *
+ * await driver.initialize();
+ * for await (const event of driver.receive({ content: "Hello" })) {
+ *   console.log(event);
+ * }
+ * ```
+ */
+
+/**
+ * Devtools configuration
+ */
+interface DevtoolsConfig {
+    /**
+     * Directory to store/load fixtures
+     */
+    fixturesDir: string;
+    /**
+     * API key for recording (required if recording)
+     */
+    apiKey?: string;
+    /**
+     * API base URL
+     */
+    baseUrl?: string;
+    /**
+     * Default model
+     */
+    model?: string;
+    /**
+     * Default system prompt
+     */
+    systemPrompt?: string;
+    /**
+     * Working directory for tool execution
+     */
+    cwd?: string;
+    /**
+     * Real driver factory for recording
+     * If not provided, will try to use @agentxjs/claude-driver
+     */
+    createDriver?: CreateDriver;
+}
+/**
+ * Options for getting a driver
+ */
+interface DriverOptions {
+    /**
+     * Message to send if recording is needed
+     */
+    message: string;
+    /**
+     * Override system prompt
+     */
+    systemPrompt?: string;
+    /**
+     * Override working directory
+     */
+    cwd?: string;
+    /**
+     * Force re-record even if fixture exists
+     */
+    forceRecord?: boolean;
+}
+/**
+ * Devtools SDK
+ */
+declare class Devtools {
+    private config;
+    private realCreateDriver;
+    constructor(config: DevtoolsConfig);
+    /**
+     * Get a driver for the given fixture name
+     *
+     * - If fixture exists → returns MockDriver with playback
+     * - If fixture doesn't exist → records, saves, returns MockDriver
+     */
+    driver(name: string, options: DriverOptions): Promise<Driver>;
+    /**
+     * Get a CreateDriver function that uses a pre-loaded fixture
+     *
+     * NOTE: This loads the fixture synchronously, so the fixture must exist.
+     * For async loading/recording, use driver() instead.
+     */
+    createDriverForFixture(fixturePath: string): CreateDriver;
+    /**
+     * Record a fixture
+     */
+    record(name: string, options: DriverOptions): Promise<Fixture>;
+    /**
+     * Load a fixture by name
+     */
+    load(name: string): Promise<Fixture>;
+    /**
+     * Check if a fixture exists
+     */
+    exists(name: string): boolean;
+    /**
+     * Delete a fixture
+     */
+    delete(name: string): Promise<void>;
+    private getFixturePath;
+    private loadFixture;
+    private saveFixture;
+    private getRealCreateDriver;
+}
+/**
+ * Create a Devtools instance
+ */
+declare function createDevtools(config: DevtoolsConfig): Devtools;
+/**
+ * Configuration for VCR-aware CreateDriver
+ */
+interface VcrCreateDriverConfig {
+    /**
+     * Directory to store/load fixtures
+     */
+    fixturesDir: string;
+    /**
+     * Get current fixture name. Return null to skip VCR (use real driver).
+     * Called when driver is created.
+     */
+    getFixtureName: () => string | null;
+    /**
+     * API key for recording
+     */
+    apiKey?: string;
+    /**
+     * API base URL
+     */
+    baseUrl?: string;
+    /**
+     * Default model
+     */
+    model?: string;
+    /**
+     * Real driver factory (optional, defaults to @agentxjs/claude-driver)
+     */
+    createRealDriver?: CreateDriver;
+    /**
+     * Called when playback mode is used
+     */
+    onPlayback?: (fixtureName: string) => void;
+    /**
+     * Called when recording mode is used
+     */
+    onRecording?: (fixtureName: string) => void;
+    /**
+     * Called when fixture is saved
+     */
+    onSaved?: (fixtureName: string, eventCount: number) => void;
+}
+/**
+ * Create a VCR-aware CreateDriver function
+ *
+ * VCR logic (hardcoded):
+ * - Fixture exists → Playback (MockDriver)
+ * - Fixture missing → Recording (RecordingDriver) → Auto-save on dispose
+ *
+ * @example
+ * ```typescript
+ * let currentFixture: string | null = null;
+ *
+ * const vcrCreateDriver = createVcrCreateDriver({
+ *   fixturesDir: "./fixtures",
+ *   getFixtureName: () => currentFixture,
+ *   apiKey: process.env.API_KEY,
+ * });
+ *
+ * // Before each test:
+ * currentFixture = "test-scenario-name";
+ *
+ * // Use with server:
+ * const platform = await createNodePlatform({...});
+ * const server = await createServer({
+ *   platform,
+ *   createDriver: vcrCreateDriver,
+ * });
+ * ```
+ */
+declare function createVcrCreateDriver(config: VcrCreateDriverConfig): CreateDriver;
+
+/**
+ * Unified environment configuration for devtools
+ *
+ * Single source of truth for API credentials and model settings.
+ * Automatically loads .env / .env.local from monorepo root on import.
+ *
+ * All devtools modules (VCR, BDD, Devtools SDK) should use this
+ * instead of reading process.env directly.
+ *
+ * @example
+ * ```ts
+ * import { env } from "@agentxjs/devtools";
+ *
+ * const driver = createMonoDriver({
+ *   apiKey: env.apiKey!,
+ *   baseUrl: env.baseUrl,
+ *   model: env.model,
+ * });
+ * ```
+ */
+declare const env: {
+    /** Deepractice API key */
+    readonly apiKey: string | undefined;
+    /** Deepractice API base URL */
+    readonly baseUrl: string | undefined;
+    /** Model identifier */
+    readonly model: string;
+};
+
+export { Devtools, type DevtoolsConfig, type DriverOptions, Fixture, type VcrCreateDriverConfig, createDevtools, createVcrCreateDriver, env };

package/dist/index.js

@@ -0,0 +1,269 @@
+import {
+  MockDriver,
+  createMockDriver
+} from "./chunk-J6L73HM5.js";
+import {
+  RecordingDriver,
+  createRecordingDriver
+} from "./chunk-DR45HEV4.js";
+import {
+  BUILTIN_FIXTURES,
+  EMPTY_RESPONSE,
+  ERROR_RESPONSE,
+  LONG_REPLY,
+  SIMPLE_REPLY,
+  TOOL_CALL,
+  getFixture,
+  listFixtures
+} from "./chunk-6OHXS7LW.js";
+import {
+  env
+} from "./chunk-S7J75AXG.js";
+import "./chunk-DGUM43GV.js";
+
+// src/Devtools.ts
+import { createLogger } from "commonxjs/logger";
+import { existsSync, readFileSync } from "fs";
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join, dirname } from "path";
+var logger = createLogger("devtools/Devtools");
+var Devtools = class {
+  config;
+  realCreateDriver = null;
+  constructor(config) {
+    this.config = config;
+    logger.info("Devtools initialized", { fixturesDir: config.fixturesDir });
+  }
+  /**
+   * Get a driver for the given fixture name
+   *
+   * - If fixture exists → returns MockDriver with playback
+   * - If fixture doesn't exist → records, saves, returns MockDriver
+   */
+  async driver(name, options) {
+    const fixturePath = this.getFixturePath(name);
+    if (!options.forceRecord && existsSync(fixturePath)) {
+      logger.info("Loading existing fixture", { name, path: fixturePath });
+      const fixture2 = await this.loadFixture(fixturePath);
+      return new MockDriver({ fixture: fixture2 });
+    }
+    logger.info("Recording new fixture", { name, message: options.message });
+    const fixture = await this.record(name, options);
+    return new MockDriver({ fixture });
+  }
+  /**
+   * Get a CreateDriver function that uses a pre-loaded fixture
+   *
+   * NOTE: This loads the fixture synchronously, so the fixture must exist.
+   * For async loading/recording, use driver() instead.
+   */
+  createDriverForFixture(fixturePath) {
+    const content = readFileSync(this.getFixturePath(fixturePath), "utf-8");
+    const fixture = JSON.parse(content);
+    return (_config) => {
+      return new MockDriver({ fixture });
+    };
+  }
+  /**
+   * Record a fixture
+   */
+  async record(name, options) {
+    const createDriver = await this.getRealCreateDriver();
+    const agentId = `record-${name}`;
+    const driverConfig = {
+      apiKey: this.config.apiKey,
+      baseUrl: this.config.baseUrl,
+      agentId,
+      model: this.config.model,
+      systemPrompt: options.systemPrompt || this.config.systemPrompt || "You are a helpful assistant.",
+      cwd: options.cwd || this.config.cwd || process.cwd()
+    };
+    const realDriver = createDriver(driverConfig);
+    const recorder = new RecordingDriver({
+      driver: realDriver,
+      name,
+      description: `Recording of: "${options.message}"`
+    });
+    await recorder.initialize();
+    try {
+      const userMessage = {
+        id: `msg_${Date.now()}`,
+        role: "user",
+        subtype: "user",
+        content: options.message,
+        timestamp: Date.now()
+      };
+      for await (const event of recorder.receive(userMessage)) {
+        logger.debug("Recording event", { type: event.type });
+        if (event.type === "message_stop") {
+          break;
+        }
+        if (event.type === "error") {
+          const errorData = event.data;
+          throw new Error(`Recording error: ${errorData.message}`);
+        }
+      }
+      const fixture = recorder.getFixture();
+      await this.saveFixture(name, fixture);
+      return fixture;
+    } finally {
+      await recorder.dispose();
+    }
+  }
+  /**
+   * Load a fixture by name
+   */
+  async load(name) {
+    const fixturePath = this.getFixturePath(name);
+    return this.loadFixture(fixturePath);
+  }
+  /**
+   * Check if a fixture exists
+   */
+  exists(name) {
+    return existsSync(this.getFixturePath(name));
+  }
+  /**
+   * Delete a fixture
+   */
+  async delete(name) {
+    const fixturePath = this.getFixturePath(name);
+    if (existsSync(fixturePath)) {
+      const { unlink } = await import("fs/promises");
+      await unlink(fixturePath);
+      logger.info("Fixture deleted", { name });
+    }
+  }
+  // ==================== Private ====================
+  getFixturePath(name) {
+    if (name.endsWith(".json")) {
+      return name;
+    }
+    return join(this.config.fixturesDir, `${name}.json`);
+  }
+  async loadFixture(path) {
+    const content = await readFile(path, "utf-8");
+    return JSON.parse(content);
+  }
+  async saveFixture(name, fixture) {
+    const path = this.getFixturePath(name);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(fixture, null, 2), "utf-8");
+    logger.info("Fixture saved", { name, path, eventCount: fixture.events.length });
+  }
+  async getRealCreateDriver() {
+    if (this.realCreateDriver) {
+      return this.realCreateDriver;
+    }
+    if (this.config.createDriver) {
+      this.realCreateDriver = this.config.createDriver;
+      return this.realCreateDriver;
+    }
+    if (!this.config.apiKey) {
+      throw new Error(
+        "apiKey is required for recording. Set it in DevtoolsConfig or provide a createDriver."
+      );
+    }
+    try {
+      const { createClaudeDriver } = await import("@agentxjs/claude-driver");
+      this.realCreateDriver = createClaudeDriver;
+      return this.realCreateDriver;
+    } catch {
+      throw new Error("@agentxjs/claude-driver not found. Install it or provide a createDriver.");
+    }
+  }
+};
+function createDevtools(config) {
+  return new Devtools(config);
+}
+function createVcrCreateDriver(config) {
+  const { fixturesDir, getFixtureName, apiKey, baseUrl, model, onPlayback, onRecording, onSaved } = config;
+  const realCreateDriver = config.createRealDriver || null;
+  return (driverConfig) => {
+    const fixtureName = getFixtureName();
+    if (!fixtureName) {
+      if (!apiKey) {
+        throw new Error("No fixture name and no API key. Cannot create driver.");
+      }
+      const createDriver2 = realCreateDriver || config.createRealDriver;
+      if (!createDriver2) {
+        throw new Error("No createRealDriver provided and claude-driver not loaded yet.");
+      }
+      return createDriver2({
+        ...driverConfig,
+        apiKey,
+        baseUrl,
+        model
+      });
+    }
+    const fixturePath = join(fixturesDir, `${fixtureName}.json`);
+    if (existsSync(fixturePath)) {
+      onPlayback?.(fixtureName);
+      logger.info("VCR Playback", { fixtureName });
+      const fixture = JSON.parse(readFileSync(fixturePath, "utf-8"));
+      return new MockDriver({ fixture });
+    }
+    if (!apiKey) {
+      throw new Error(
+        `No fixture found for "${fixtureName}" and no API key for recording. Either create the fixture or provide an API key.`
+      );
+    }
+    onRecording?.(fixtureName);
+    logger.info("VCR Recording", { fixtureName });
+    const createDriver = realCreateDriver || config.createRealDriver;
+    if (!createDriver) {
+      throw new Error(
+        "createRealDriver not available. For async loading, ensure claude-driver is pre-loaded."
+      );
+    }
+    const realDriver = createDriver({
+      ...driverConfig,
+      apiKey,
+      baseUrl,
+      model
+    });
+    const recorder = new RecordingDriver({
+      driver: realDriver,
+      name: fixtureName,
+      description: `VCR recording: ${fixtureName}`
+    });
+    let fixtureSaved = false;
+    const originalDispose = recorder.dispose.bind(recorder);
+    recorder.dispose = async () => {
+      if (!fixtureSaved && recorder.eventCount > 0) {
+        try {
+          const fixture = recorder.getFixture();
+          const { mkdir: mkdir2, writeFile: writeFile2 } = await import("fs/promises");
+          await mkdir2(dirname(fixturePath), { recursive: true });
+          await writeFile2(fixturePath, JSON.stringify(fixture, null, 2), "utf-8");
+          fixtureSaved = true;
+          onSaved?.(fixtureName, recorder.eventCount);
+          logger.info("VCR Saved", { fixtureName, eventCount: recorder.eventCount });
+        } catch (e) {
+          logger.error("VCR Save failed", { fixtureName, error: e });
+        }
+      }
+      return originalDispose();
+    };
+    return recorder;
+  };
+}
+export {
+  BUILTIN_FIXTURES,
+  Devtools,
+  EMPTY_RESPONSE,
+  ERROR_RESPONSE,
+  LONG_REPLY,
+  MockDriver,
+  RecordingDriver,
+  SIMPLE_REPLY,
+  TOOL_CALL,
+  createDevtools,
+  createMockDriver,
+  createRecordingDriver,
+  createVcrCreateDriver,
+  env,
+  getFixture,
+  listFixtures
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/Devtools.ts"],"sourcesContent":["/**\n * Devtools SDK - VCR-style fixture management\n *\n * Automatically uses existing fixtures or records new ones on-the-fly.\n *\n * Usage:\n * ```typescript\n * import { createDevtools } from \"@agentxjs/devtools\";\n *\n * import { env } from \"@agentxjs/devtools\";\n *\n * const devtools = createDevtools({\n *   fixturesDir: \"./fixtures\",\n *   apiKey: env.apiKey,\n * });\n *\n * // Has fixture → playback (MockDriver)\n * // No fixture → call API, record, save, return MockDriver\n * const driver = await devtools.driver(\"hello-test\", {\n *   message: \"Hello!\",\n * });\n *\n * await driver.initialize();\n * for await (const event of driver.receive({ content: \"Hello\" })) {\n *   console.log(event);\n * }\n * ```\n */\n\nimport type { Driver, CreateDriver, DriverConfig } from \"@agentxjs/core/driver\";\nimport type { Fixture } from \"./types\";\nimport { MockDriver } from \"./mock/MockDriver\";\nimport { RecordingDriver } from \"./recorder/RecordingDriver\";\nimport { createLogger } from \"commonxjs/logger\";\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { readFile, writeFile, mkdir } from \"node:fs/promises\";\nimport { join, dirname } from \"node:path\";\n\nconst logger = createLogger(\"devtools/Devtools\");\n\n/**\n * Devtools configuration\n */\nexport interface DevtoolsConfig {\n  /**\n   * Directory to store/load fixtures\n   */\n  fixturesDir: string;\n\n  /**\n   * API key for recording (required if recording)\n   */\n  apiKey?: string;\n\n  /**\n   * API base URL\n   */\n  baseUrl?: string;\n\n  /**\n   * Default model\n   */\n  model?: string;\n\n  /**\n   * Default system prompt\n   */\n  systemPrompt?: string;\n\n  /**\n   * Working directory for tool execution\n   */\n  cwd?: string;\n\n  /**\n   * Real driver factory for recording\n   * If not provided, will try to use @agentxjs/claude-driver\n   */\n  createDriver?: CreateDriver;\n}\n\n/**\n * Options for getting a driver\n */\nexport interface DriverOptions {\n  /**\n   * Message to send if recording is needed\n   */\n  message: string;\n\n  /**\n   * Override system prompt\n   */\n  systemPrompt?: string;\n\n  /**\n   * Override working directory\n   */\n  cwd?: string;\n\n  /**\n   * Force re-record even if fixture exists\n   */\n  forceRecord?: boolean;\n}\n\n/**\n * Devtools SDK\n */\nexport class Devtools {\n  private config: DevtoolsConfig;\n  private realCreateDriver: CreateDriver | null = null;\n\n  constructor(config: DevtoolsConfig) {\n    this.config = config;\n    logger.info(\"Devtools initialized\", { fixturesDir: config.fixturesDir });\n  }\n\n  /**\n   * Get a driver for the given fixture name\n   *\n   * - If fixture exists → returns MockDriver with playback\n   * - If fixture doesn't exist → records, saves, returns MockDriver\n   */\n  async driver(name: string, options: DriverOptions): Promise<Driver> {\n    const fixturePath = this.getFixturePath(name);\n\n    // Check if fixture exists\n    if (!options.forceRecord && existsSync(fixturePath)) {\n      logger.info(\"Loading existing fixture\", { name, path: fixturePath });\n      const fixture = await this.loadFixture(fixturePath);\n      return new MockDriver({ fixture });\n    }\n\n    // Need to record\n    logger.info(\"Recording new fixture\", { name, message: options.message });\n    const fixture = await this.record(name, options);\n    return new MockDriver({ fixture });\n  }\n\n  /**\n   * Get a CreateDriver function that uses a pre-loaded fixture\n   *\n   * NOTE: This loads the fixture synchronously, so the fixture must exist.\n   * For async loading/recording, use driver() instead.\n   */\n  createDriverForFixture(fixturePath: string): CreateDriver {\n    // Load fixture synchronously (requires existing fixture)\n    const content = readFileSync(this.getFixturePath(fixturePath), \"utf-8\");\n    const fixture = JSON.parse(content) as Fixture;\n\n    return (_config: DriverConfig) => {\n      return new MockDriver({ fixture });\n    };\n  }\n\n  /**\n   * Record a fixture\n   */\n  async record(name: string, options: DriverOptions): Promise<Fixture> {\n    const createDriver = await this.getRealCreateDriver();\n\n    const agentId = `record-${name}`;\n\n    // Create driver config\n    const driverConfig: DriverConfig = {\n      apiKey: this.config.apiKey!,\n      baseUrl: this.config.baseUrl,\n      agentId,\n      model: this.config.model,\n      systemPrompt:\n        options.systemPrompt || this.config.systemPrompt || \"You are a helpful assistant.\",\n      cwd: options.cwd || this.config.cwd || process.cwd(),\n    };\n\n    // Create real driver\n    const realDriver = createDriver(driverConfig);\n\n    // Wrap with recorder\n    const recorder = new RecordingDriver({\n      driver: realDriver,\n      name,\n      description: `Recording of: \"${options.message}\"`,\n    });\n\n    // Initialize\n    await recorder.initialize();\n\n    try {\n      // Build user message\n      const userMessage = {\n        id: `msg_${Date.now()}`,\n        role: \"user\" as const,\n        subtype: \"user\" as const,\n        content: options.message,\n        timestamp: Date.now(),\n      };\n\n      // Send message and collect all events\n      for await (const event of recorder.receive(userMessage)) {\n        logger.debug(\"Recording event\", { type: event.type });\n\n        // Check for completion\n        if (event.type === \"message_stop\") {\n          break;\n        }\n\n        // Check for error\n        if (event.type === \"error\") {\n          const errorData = event.data as { message?: string };\n          throw new Error(`Recording error: ${errorData.message}`);\n        }\n      }\n\n      // Get fixture\n      const fixture = recorder.getFixture();\n\n      // Save fixture\n      await this.saveFixture(name, fixture);\n\n      return fixture;\n    } finally {\n      // Cleanup\n      await recorder.dispose();\n    }\n  }\n\n  /**\n   * Load a fixture by name\n   */\n  async load(name: string): Promise<Fixture> {\n    const fixturePath = this.getFixturePath(name);\n    return this.loadFixture(fixturePath);\n  }\n\n  /**\n   * Check if a fixture exists\n   */\n  exists(name: string): boolean {\n    return existsSync(this.getFixturePath(name));\n  }\n\n  /**\n   * Delete a fixture\n   */\n  async delete(name: string): Promise<void> {\n    const fixturePath = this.getFixturePath(name);\n    if (existsSync(fixturePath)) {\n      const { unlink } = await import(\"node:fs/promises\");\n      await unlink(fixturePath);\n      logger.info(\"Fixture deleted\", { name });\n    }\n  }\n\n  // ==================== Private ====================\n\n  private getFixturePath(name: string): string {\n    // If name is already a path, use it directly\n    if (name.endsWith(\".json\")) {\n      return name;\n    }\n    return join(this.config.fixturesDir, `${name}.json`);\n  }\n\n  private async loadFixture(path: string): Promise<Fixture> {\n    const content = await readFile(path, \"utf-8\");\n    return JSON.parse(content) as Fixture;\n  }\n\n  private async saveFixture(name: string, fixture: Fixture): Promise<void> {\n    const path = this.getFixturePath(name);\n    await mkdir(dirname(path), { recursive: true });\n    await writeFile(path, JSON.stringify(fixture, null, 2), \"utf-8\");\n    logger.info(\"Fixture saved\", { name, path, eventCount: fixture.events.length });\n  }\n\n  private async getRealCreateDriver(): Promise<CreateDriver> {\n    if (this.realCreateDriver) {\n      return this.realCreateDriver;\n    }\n\n    if (this.config.createDriver) {\n      this.realCreateDriver = this.config.createDriver;\n      return this.realCreateDriver;\n    }\n\n    // Validate API key\n    if (!this.config.apiKey) {\n      throw new Error(\n        \"apiKey is required for recording. Set it in DevtoolsConfig or provide a createDriver.\"\n      );\n    }\n\n    // Try to import claude-driver\n    try {\n      const { createClaudeDriver } = await import(\"@agentxjs/claude-driver\");\n      this.realCreateDriver = createClaudeDriver;\n      return this.realCreateDriver;\n    } catch {\n      throw new Error(\"@agentxjs/claude-driver not found. Install it or provide a createDriver.\");\n    }\n  }\n}\n\n/**\n * Create a Devtools instance\n */\nexport function createDevtools(config: DevtoolsConfig): Devtools {\n  return new Devtools(config);\n}\n\n// ============================================================================\n// VCR CreateDriver Factory\n// ============================================================================\n\n/**\n * Configuration for VCR-aware CreateDriver\n */\nexport interface VcrCreateDriverConfig {\n  /**\n   * Directory to store/load fixtures\n   */\n  fixturesDir: string;\n\n  /**\n   * Get current fixture name. Return null to skip VCR (use real driver).\n   * Called when driver is created.\n   */\n  getFixtureName: () => string | null;\n\n  /**\n   * API key for recording\n   */\n  apiKey?: string;\n\n  /**\n   * API base URL\n   */\n  baseUrl?: string;\n\n  /**\n   * Default model\n   */\n  model?: string;\n\n  /**\n   * Real driver factory (optional, defaults to @agentxjs/claude-driver)\n   */\n  createRealDriver?: CreateDriver;\n\n  /**\n   * Called when playback mode is used\n   */\n  onPlayback?: (fixtureName: string) => void;\n\n  /**\n   * Called when recording mode is used\n   */\n  onRecording?: (fixtureName: string) => void;\n\n  /**\n   * Called when fixture is saved\n   */\n  onSaved?: (fixtureName: string, eventCount: number) => void;\n}\n\n/**\n * Create a VCR-aware CreateDriver function\n *\n * VCR logic (hardcoded):\n * - Fixture exists → Playback (MockDriver)\n * - Fixture missing → Recording (RecordingDriver) → Auto-save on dispose\n *\n * @example\n * ```typescript\n * let currentFixture: string | null = null;\n *\n * const vcrCreateDriver = createVcrCreateDriver({\n *   fixturesDir: \"./fixtures\",\n *   getFixtureName: () => currentFixture,\n *   apiKey: process.env.API_KEY,\n * });\n *\n * // Before each test:\n * currentFixture = \"test-scenario-name\";\n *\n * // Use with server:\n * const platform = await createNodePlatform({...});\n * const server = await createServer({\n *   platform,\n *   createDriver: vcrCreateDriver,\n * });\n * ```\n */\nexport function createVcrCreateDriver(config: VcrCreateDriverConfig): CreateDriver {\n  const { fixturesDir, getFixtureName, apiKey, baseUrl, model, onPlayback, onRecording, onSaved } =\n    config;\n\n  // Real driver factory (must be provided or pre-loaded)\n  const realCreateDriver: CreateDriver | null = config.createRealDriver || null;\n\n  return (driverConfig: DriverConfig): Driver => {\n    const fixtureName = getFixtureName();\n\n    // No fixture name → use real driver without VCR\n    if (!fixtureName) {\n      if (!apiKey) {\n        throw new Error(\"No fixture name and no API key. Cannot create driver.\");\n      }\n\n      // Sync: we need to return immediately, so we create the driver with merged config\n      // Note: This path is for non-VCR scenarios\n      const createDriver = realCreateDriver || config.createRealDriver;\n      if (!createDriver) {\n        throw new Error(\"No createRealDriver provided and claude-driver not loaded yet.\");\n      }\n\n      return createDriver({\n        ...driverConfig,\n        apiKey,\n        baseUrl,\n        model,\n      });\n    }\n\n    const fixturePath = join(fixturesDir, `${fixtureName}.json`);\n\n    // Fixture exists → Playback (MockDriver)\n    if (existsSync(fixturePath)) {\n      onPlayback?.(fixtureName);\n      logger.info(\"VCR Playback\", { fixtureName });\n\n      const fixture = JSON.parse(readFileSync(fixturePath, \"utf-8\")) as Fixture;\n      return new MockDriver({ fixture });\n    }\n\n    // No fixture → Recording (RecordingDriver)\n    if (!apiKey) {\n      throw new Error(\n        `No fixture found for \"${fixtureName}\" and no API key for recording. ` +\n          `Either create the fixture or provide an API key.`\n      );\n    }\n\n    onRecording?.(fixtureName);\n    logger.info(\"VCR Recording\", { fixtureName });\n\n    // Get real driver factory (sync - must be pre-loaded or provided)\n    const createDriver = realCreateDriver || config.createRealDriver;\n    if (!createDriver) {\n      throw new Error(\n        \"createRealDriver not available. For async loading, ensure claude-driver is pre-loaded.\"\n      );\n    }\n\n    // Create real driver with merged config\n    const realDriver = createDriver({\n      ...driverConfig,\n      apiKey,\n      baseUrl,\n      model,\n    });\n\n    // Wrap with RecordingDriver\n    const recorder = new RecordingDriver({\n      driver: realDriver,\n      name: fixtureName,\n      description: `VCR recording: ${fixtureName}`,\n    });\n\n    // Auto-save fixture on dispose\n    let fixtureSaved = false;\n    const originalDispose = recorder.dispose.bind(recorder);\n\n    recorder.dispose = async () => {\n      if (!fixtureSaved && recorder.eventCount > 0) {\n        try {\n          const fixture = recorder.getFixture();\n\n          // Ensure directory exists\n          const { mkdir, writeFile } = await import(\"node:fs/promises\");\n          await mkdir(dirname(fixturePath), { recursive: true });\n          await writeFile(fixturePath, JSON.stringify(fixture, null, 2), \"utf-8\");\n\n          fixtureSaved = true;\n          onSaved?.(fixtureName, recorder.eventCount);\n          logger.info(\"VCR Saved\", { fixtureName, eventCount: recorder.eventCount });\n        } catch (e) {\n          logger.error(\"VCR Save failed\", { fixtureName, error: e });\n        }\n      }\n\n      return originalDispose();\n    };\n\n    return recorder;\n  };\n}\n"],"mappings":"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","names":["fixture","createDriver","mkdir","writeFile"]}

package/dist/mock/index.d.ts

@@ -0,0 +1,115 @@
+import { Driver, DriverConfig, DriverState, DriverStreamEvent } from '@agentxjs/core/driver';
+import { UserMessage } from '@agentxjs/core/agent';
+import { M as MockDriverOptions, F as Fixture } from '../types-C6Lf3vz2.js';
+
+/**
+ * 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();
+ * ```
+ */
+
+/**
+ * MockDriver - Playback driver for testing
+ *
+ * Implements the new Driver interface:
+ * - receive() returns AsyncIterable<DriverStreamEvent>
+ * - Clear input/output boundaries for testing
+ */
+declare class MockDriver implements Driver {
+    readonly name = "MockDriver";
+    private _sessionId;
+    private _state;
+    private readonly config;
+    private readonly options;
+    private readonly fixtures;
+    private currentFixture;
+    private isInterrupted;
+    private eventCursor;
+    /**
+     * Create a MockDriver
+     *
+     * @param options - MockDriverOptions or DriverConfig
+     * @param mockOptions - MockDriverOptions if first param is DriverConfig
+     */
+    constructor(optionsOrConfig: MockDriverOptions | DriverConfig, mockOptions?: MockDriverOptions);
+    get sessionId(): string | null;
+    get state(): DriverState;
+    /**
+     * Initialize the Driver
+     */
+    initialize(): Promise<void>;
+    /**
+     * Dispose and cleanup resources
+     */
+    dispose(): Promise<void>;
+    /**
+     * 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
+     */
+    receive(_message: UserMessage): AsyncIterable<DriverStreamEvent>;
+    /**
+     * Interrupt current operation
+     */
+    interrupt(): void;
+    /**
+     * Set the fixture to use for next playback
+     */
+    setFixture(fixture: string | Fixture): void;
+    /**
+     * Add a custom fixture
+     */
+    addFixture(fixture: Fixture): void;
+    /**
+     * Get the current fixture
+     */
+    getFixture(): Fixture;
+    /**
+     * Get available fixture names
+     */
+    getFixtureNames(): string[];
+    /**
+     * Resolve fixture from name or Fixture object
+     */
+    private resolveFixture;
+    /**
+     * Convert FixtureEvent to DriverStreamEvent
+     */
+    private convertFixtureEvent;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+}
+/**
+ * Create a MockDriver factory function
+ *
+ * Returns a CreateDriver-compatible function.
+ *
+ * @param mockOptions - Options for all created drivers
+ * @returns CreateDriver function
+ */
+declare function createMockDriver(mockOptions?: MockDriverOptions): (config: DriverConfig) => Driver;
+
+export { MockDriver, createMockDriver };

package/dist/mock/index.js

@@ -0,0 +1,11 @@
+import {
+  MockDriver,
+  createMockDriver
+} from "../chunk-J6L73HM5.js";
+import "../chunk-6OHXS7LW.js";
+import "../chunk-DGUM43GV.js";
+export {
+  MockDriver,
+  createMockDriver
+};
+//# sourceMappingURL=index.js.map

package/dist/mock/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}