@agentxjs/devtools 1.9.6-dev → 2.0.0

package/dist/index.d.ts

@@ -15,9 +15,11 @@ import '@agentxjs/core/agent';
  * ```typescript
  * import { createDevtools } from "@agentxjs/devtools";
  *
+ * import { env } from "@agentxjs/devtools";
+ *
  * const devtools = createDevtools({
  *   fixturesDir: "./fixtures",
- *   apiKey: process.env.DEEPRACTICE_API_KEY,
+ *   apiKey: env.apiKey,
  * });
  *
  * // Has fixture → playback (MockDriver)
@@ -196,12 +198,43 @@ interface VcrCreateDriverConfig {
  * // Before each test:
  * currentFixture = "test-scenario-name";
  *
- * // Use with server/provider:
- * const provider = await createNodeProvider({
+ * // Use with server:
+ * const platform = await createNodePlatform({...});
+ * const server = await createServer({
+ *   platform,
  *   createDriver: vcrCreateDriver,
  * });
  * ```
  */
 declare function createVcrCreateDriver(config: VcrCreateDriverConfig): CreateDriver;
 
-export { Devtools, type DevtoolsConfig, type DriverOptions, Fixture, type VcrCreateDriverConfig, createDevtools, createVcrCreateDriver };
+/**
+ * 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

@@ -1,11 +1,11 @@
 import {
   MockDriver,
   createMockDriver
-} from "./chunk-SQDCFUA3.js";
+} from "./chunk-J6L73HM5.js";
 import {
   RecordingDriver,
   createRecordingDriver
-} from "./chunk-YRTTCKHM.js";
+} from "./chunk-DR45HEV4.js";
 import {
   BUILTIN_FIXTURES,
   EMPTY_RESPONSE,
@@ -16,6 +16,10 @@ import {
   getFixture,
   listFixtures
 } from "./chunk-6OHXS7LW.js";
+import {
+  env
+} from "./chunk-S7J75AXG.js";
+import "./chunk-DGUM43GV.js";
 
 // src/Devtools.ts
 import { createLogger } from "commonxjs/logger";
@@ -173,16 +177,7 @@ function createDevtools(config) {
   return new Devtools(config);
 }
 function createVcrCreateDriver(config) {
-  const {
-    fixturesDir,
-    getFixtureName,
-    apiKey,
-    baseUrl,
-    model,
-    onPlayback,
-    onRecording,
-    onSaved
-  } = config;
+  const { fixturesDir, getFixtureName, apiKey, baseUrl, model, onPlayback, onRecording, onSaved } = config;
   const realCreateDriver = config.createRealDriver || null;
   return (driverConfig) => {
     const fixtureName = getFixtureName();
@@ -267,6 +262,7 @@ export {
   createMockDriver,
   createRecordingDriver,
   createVcrCreateDriver,
+  env,
   getFixture,
   listFixtures
 };

package/dist/index.js.map

@@ -1 +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 * const devtools = createDevtools({\n *   fixturesDir: \"./fixtures\",\n *   apiKey: process.env.DEEPRACTICE_API_KEY,\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: 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/provider:\n * const provider = await createNodeProvider({\n *   createDriver: vcrCreateDriver,\n * });\n * ```\n */\nexport function createVcrCreateDriver(config: VcrCreateDriverConfig): CreateDriver {\n  const {\n    fixturesDir,\n    getFixtureName,\n    apiKey,\n    baseUrl,\n    model,\n    onPlayback,\n    onRecording,\n    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"]}
+{"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":";;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAS,oBAAoB;AAC7B,SAAS,YAAY,oBAAoB;AACzC,SAAS,UAAU,WAAW,aAAa;AAC3C,SAAS,MAAM,eAAe;AAE9B,IAAM,SAAS,aAAa,mBAAmB;AAuExC,IAAM,WAAN,MAAe;AAAA,EACZ;AAAA,EACA,mBAAwC;AAAA,EAEhD,YAAY,QAAwB;AAClC,SAAK,SAAS;AACd,WAAO,KAAK,wBAAwB,EAAE,aAAa,OAAO,YAAY,CAAC;AAAA,EACzE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,OAAO,MAAc,SAAyC;AAClE,UAAM,cAAc,KAAK,eAAe,IAAI;AAG5C,QAAI,CAAC,QAAQ,eAAe,WAAW,WAAW,GAAG;AACnD,aAAO,KAAK,4BAA4B,EAAE,MAAM,MAAM,YAAY,CAAC;AACnE,YAAMA,WAAU,MAAM,KAAK,YAAY,WAAW;AAClD,aAAO,IAAI,WAAW,EAAE,SAAAA,SAAQ,CAAC;AAAA,IACnC;AAGA,WAAO,KAAK,yBAAyB,EAAE,MAAM,SAAS,QAAQ,QAAQ,CAAC;AACvE,UAAM,UAAU,MAAM,KAAK,OAAO,MAAM,OAAO;AAC/C,WAAO,IAAI,WAAW,EAAE,QAAQ,CAAC;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,uBAAuB,aAAmC;AAExD,UAAM,UAAU,aAAa,KAAK,eAAe,WAAW,GAAG,OAAO;AACtE,UAAM,UAAU,KAAK,MAAM,OAAO;AAElC,WAAO,CAAC,YAA0B;AAChC,aAAO,IAAI,WAAW,EAAE,QAAQ,CAAC;AAAA,IACnC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAO,MAAc,SAA0C;AACnE,UAAM,eAAe,MAAM,KAAK,oBAAoB;AAEpD,UAAM,UAAU,UAAU,IAAI;AAG9B,UAAM,eAA6B;AAAA,MACjC,QAAQ,KAAK,OAAO;AAAA,MACpB,SAAS,KAAK,OAAO;AAAA,MACrB;AAAA,MACA,OAAO,KAAK,OAAO;AAAA,MACnB,cACE,QAAQ,gBAAgB,KAAK,OAAO,gBAAgB;AAAA,MACtD,KAAK,QAAQ,OAAO,KAAK,OAAO,OAAO,QAAQ,IAAI;AAAA,IACrD;AAGA,UAAM,aAAa,aAAa,YAAY;AAG5C,UAAM,WAAW,IAAI,gBAAgB;AAAA,MACnC,QAAQ;AAAA,MACR;AAAA,MACA,aAAa,kBAAkB,QAAQ,OAAO;AAAA,IAChD,CAAC;AAGD,UAAM,SAAS,WAAW;AAE1B,QAAI;AAEF,YAAM,cAAc;AAAA,QAClB,IAAI,OAAO,KAAK,IAAI,CAAC;AAAA,QACrB,MAAM;AAAA,QACN,SAAS;AAAA,QACT,SAAS,QAAQ;AAAA,QACjB,WAAW,KAAK,IAAI;AAAA,MACtB;AAGA,uBAAiB,SAAS,SAAS,QAAQ,WAAW,GAAG;AACvD,eAAO,MAAM,mBAAmB,EAAE,MAAM,MAAM,KAAK,CAAC;AAGpD,YAAI,MAAM,SAAS,gBAAgB;AACjC;AAAA,QACF;AAGA,YAAI,MAAM,SAAS,SAAS;AAC1B,gBAAM,YAAY,MAAM;AACxB,gBAAM,IAAI,MAAM,oBAAoB,UAAU,OAAO,EAAE;AAAA,QACzD;AAAA,MACF;AAGA,YAAM,UAAU,SAAS,WAAW;AAGpC,YAAM,KAAK,YAAY,MAAM,OAAO;AAEpC,aAAO;AAAA,IACT,UAAE;AAEA,YAAM,SAAS,QAAQ;AAAA,IACzB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,KAAK,MAAgC;AACzC,UAAM,cAAc,KAAK,eAAe,IAAI;AAC5C,WAAO,KAAK,YAAY,WAAW;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,MAAuB;AAC5B,WAAO,WAAW,KAAK,eAAe,IAAI,CAAC;AAAA,EAC7C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAO,MAA6B;AACxC,UAAM,cAAc,KAAK,eAAe,IAAI;AAC5C,QAAI,WAAW,WAAW,GAAG;AAC3B,YAAM,EAAE,OAAO,IAAI,MAAM,OAAO,aAAkB;AAClD,YAAM,OAAO,WAAW;AACxB,aAAO,KAAK,mBAAmB,EAAE,KAAK,CAAC;AAAA,IACzC;AAAA,EACF;AAAA;AAAA,EAIQ,eAAe,MAAsB;AAE3C,QAAI,KAAK,SAAS,OAAO,GAAG;AAC1B,aAAO;AAAA,IACT;AACA,WAAO,KAAK,KAAK,OAAO,aAAa,GAAG,IAAI,OAAO;AAAA,EACrD;AAAA,EAEA,MAAc,YAAY,MAAgC;AACxD,UAAM,UAAU,MAAM,SAAS,MAAM,OAAO;AAC5C,WAAO,KAAK,MAAM,OAAO;AAAA,EAC3B;AAAA,EAEA,MAAc,YAAY,MAAc,SAAiC;AACvE,UAAM,OAAO,KAAK,eAAe,IAAI;AACrC,UAAM,MAAM,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;AAC9C,UAAM,UAAU,MAAM,KAAK,UAAU,SAAS,MAAM,CAAC,GAAG,OAAO;AAC/D,WAAO,KAAK,iBAAiB,EAAE,MAAM,MAAM,YAAY,QAAQ,OAAO,OAAO,CAAC;AAAA,EAChF;AAAA,EAEA,MAAc,sBAA6C;AACzD,QAAI,KAAK,kBAAkB;AACzB,aAAO,KAAK;AAAA,IACd;AAEA,QAAI,KAAK,OAAO,cAAc;AAC5B,WAAK,mBAAmB,KAAK,OAAO;AACpC,aAAO,KAAK;AAAA,IACd;AAGA,QAAI,CAAC,KAAK,OAAO,QAAQ;AACvB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAGA,QAAI;AACF,YAAM,EAAE,mBAAmB,IAAI,MAAM,OAAO,yBAAyB;AACrE,WAAK,mBAAmB;AACxB,aAAO,KAAK;AAAA,IACd,QAAQ;AACN,YAAM,IAAI,MAAM,0EAA0E;AAAA,IAC5F;AAAA,EACF;AACF;AAKO,SAAS,eAAe,QAAkC;AAC/D,SAAO,IAAI,SAAS,MAAM;AAC5B;AAqFO,SAAS,sBAAsB,QAA6C;AACjF,QAAM,EAAE,aAAa,gBAAgB,QAAQ,SAAS,OAAO,YAAY,aAAa,QAAQ,IAC5F;AAGF,QAAM,mBAAwC,OAAO,oBAAoB;AAEzE,SAAO,CAAC,iBAAuC;AAC7C,UAAM,cAAc,eAAe;AAGnC,QAAI,CAAC,aAAa;AAChB,UAAI,CAAC,QAAQ;AACX,cAAM,IAAI,MAAM,uDAAuD;AAAA,MACzE;AAIA,YAAMC,gBAAe,oBAAoB,OAAO;AAChD,UAAI,CAACA,eAAc;AACjB,cAAM,IAAI,MAAM,gEAAgE;AAAA,MAClF;AAEA,aAAOA,cAAa;AAAA,QAClB,GAAG;AAAA,QACH;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAEA,UAAM,cAAc,KAAK,aAAa,GAAG,WAAW,OAAO;AAG3D,QAAI,WAAW,WAAW,GAAG;AAC3B,mBAAa,WAAW;AACxB,aAAO,KAAK,gBAAgB,EAAE,YAAY,CAAC;AAE3C,YAAM,UAAU,KAAK,MAAM,aAAa,aAAa,OAAO,CAAC;AAC7D,aAAO,IAAI,WAAW,EAAE,QAAQ,CAAC;AAAA,IACnC;AAGA,QAAI,CAAC,QAAQ;AACX,YAAM,IAAI;AAAA,QACR,yBAAyB,WAAW;AAAA,MAEtC;AAAA,IACF;AAEA,kBAAc,WAAW;AACzB,WAAO,KAAK,iBAAiB,EAAE,YAAY,CAAC;AAG5C,UAAM,eAAe,oBAAoB,OAAO;AAChD,QAAI,CAAC,cAAc;AACjB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAGA,UAAM,aAAa,aAAa;AAAA,MAC9B,GAAG;AAAA,MACH;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAGD,UAAM,WAAW,IAAI,gBAAgB;AAAA,MACnC,QAAQ;AAAA,MACR,MAAM;AAAA,MACN,aAAa,kBAAkB,WAAW;AAAA,IAC5C,CAAC;AAGD,QAAI,eAAe;AACnB,UAAM,kBAAkB,SAAS,QAAQ,KAAK,QAAQ;AAEtD,aAAS,UAAU,YAAY;AAC7B,UAAI,CAAC,gBAAgB,SAAS,aAAa,GAAG;AAC5C,YAAI;AACF,gBAAM,UAAU,SAAS,WAAW;AAGpC,gBAAM,EAAE,OAAAC,QAAO,WAAAC,WAAU,IAAI,MAAM,OAAO,aAAkB;AAC5D,gBAAMD,OAAM,QAAQ,WAAW,GAAG,EAAE,WAAW,KAAK,CAAC;AACrD,gBAAMC,WAAU,aAAa,KAAK,UAAU,SAAS,MAAM,CAAC,GAAG,OAAO;AAEtE,yBAAe;AACf,oBAAU,aAAa,SAAS,UAAU;AAC1C,iBAAO,KAAK,aAAa,EAAE,aAAa,YAAY,SAAS,WAAW,CAAC;AAAA,QAC3E,SAAS,GAAG;AACV,iBAAO,MAAM,mBAAmB,EAAE,aAAa,OAAO,EAAE,CAAC;AAAA,QAC3D;AAAA,MACF;AAEA,aAAO,gBAAgB;AAAA,IACzB;AAEA,WAAO;AAAA,EACT;AACF;","names":["fixture","createDriver","mkdir","writeFile"]}

package/dist/mock/index.js

@@ -1,8 +1,9 @@
 import {
   MockDriver,
   createMockDriver
-} from "../chunk-SQDCFUA3.js";
+} from "../chunk-J6L73HM5.js";
 import "../chunk-6OHXS7LW.js";
+import "../chunk-DGUM43GV.js";
 export {
   MockDriver,
   createMockDriver

package/dist/recorder/index.js

@@ -1,7 +1,8 @@
 import {
   RecordingDriver,
   createRecordingDriver
-} from "../chunk-YRTTCKHM.js";
+} from "../chunk-DR45HEV4.js";
+import "../chunk-DGUM43GV.js";
 export {
   RecordingDriver,
   createRecordingDriver

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@agentxjs/devtools",
-  "version": "1.9.6-dev",
+  "version": "2.0.0",
   "description": "Development tools for AgentX - MockDriver, RecordingDriver, Fixtures",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "bdd": "./dist/bdd/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -25,6 +28,11 @@
       "types": "./dist/fixtures/index.d.ts",
       "import": "./dist/fixtures/index.js",
       "default": "./dist/fixtures/index.js"
+    },
+    "./bdd": {
+      "types": "./dist/bdd/index.d.ts",
+      "import": "./dist/bdd/index.js",
+      "default": "./dist/bdd/index.js"
     }
   },
   "files": [
@@ -35,22 +43,36 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "test": "bun test"
+    "test": "echo 'No tests yet'",
+    "bdd": "bdd"
   },
   "dependencies": {
-    "@agentxjs/core": "1.9.6-dev",
+    "@agentxjs/core": "^2.0.0",
     "commonxjs": "^0.1.1"
   },
   "devDependencies": {
-    "@agentxjs/claude-driver": "1.9.6-dev",
+    "@agentxjs/claude-driver": "^2.0.0",
+    "@agentxjs/mono-driver": "^2.0.0",
     "typescript": "^5.3.3"
   },
   "peerDependencies": {
-    "@agentxjs/claude-driver": "1.9.6-dev"
+    "agentxjs": "^2.0.0",
+    "@agentxjs/claude-driver": "^2.0.0",
+    "@playwright/test": "^1.50.0",
+    "@cucumber/cucumber": "^11.0.0"
   },
   "peerDependenciesMeta": {
+    "agentxjs": {
+      "optional": true
+    },
     "@agentxjs/claude-driver": {
       "optional": true
+    },
+    "@playwright/test": {
+      "optional": true
+    },
+    "@cucumber/cucumber": {
+      "optional": true
     }
   }
 }

package/src/Devtools.ts

@@ -7,9 +7,11 @@
  * ```typescript
  * import { createDevtools } from "@agentxjs/devtools";
  *
+ * import { env } from "@agentxjs/devtools";
+ *
  * const devtools = createDevtools({
  *   fixturesDir: "./fixtures",
- *   apiKey: process.env.DEEPRACTICE_API_KEY,
+ *   apiKey: env.apiKey,
  * });
  *
  * // Has fixture → playback (MockDriver)
@@ -166,7 +168,8 @@ export class Devtools {
       baseUrl: this.config.baseUrl,
       agentId,
       model: this.config.model,
-      systemPrompt: options.systemPrompt || this.config.systemPrompt || "You are a helpful assistant.",
+      systemPrompt:
+        options.systemPrompt || this.config.systemPrompt || "You are a helpful assistant.",
       cwd: options.cwd || this.config.cwd || process.cwd(),
     };
 
@@ -381,23 +384,17 @@ export interface VcrCreateDriverConfig {
  * // Before each test:
  * currentFixture = "test-scenario-name";
  *
- * // Use with server/provider:
- * const provider = await createNodeProvider({
+ * // Use with server:
+ * const platform = await createNodePlatform({...});
+ * const server = await createServer({
+ *   platform,
  *   createDriver: vcrCreateDriver,
  * });
  * ```
  */
 export function createVcrCreateDriver(config: VcrCreateDriverConfig): CreateDriver {
-  const {
-    fixturesDir,
-    getFixtureName,
-    apiKey,
-    baseUrl,
-    model,
-    onPlayback,
-    onRecording,
-    onSaved,
-  } = config;
+  const { fixturesDir, getFixtureName, apiKey, baseUrl, model, onPlayback, onRecording, onSaved } =
+    config;
 
   // Real driver factory (must be provided or pre-loaded)
   const realCreateDriver: CreateDriver | null = config.createRealDriver || null;

package/src/bdd/agent-doc-tester.ts

@@ -0,0 +1,130 @@
+import { readFileSync, existsSync } from "node:fs";
+import { env } from "../env";
+
+const SYSTEM_PROMPT = `You are a documentation reviewer evaluating documents from the reader's experience.
+
+EVALUATION DIMENSIONS:
+1. Completeness — All required information is present. Nothing critical is missing.
+2. Logic — Structure flows naturally. Concepts build on each other without jumps.
+3. Readability — A newcomer can follow without confusion. No unexplained jargon.
+
+RULES:
+- Read the provided document carefully
+- Evaluate each requirement listed in the prompt against ALL three dimensions
+- Be strict but fair — the document should genuinely help the reader achieve the stated goal
+- Output your result as a single line: PASS or FAIL followed by a brief reason
+- If FAIL, list which specific requirements are not met and which dimension they violate`;
+
+export interface DocTestResult {
+  passed: boolean;
+  output: string;
+}
+
+export interface DocTesterOptions {
+  /** LLM provider (default: "anthropic") */
+  provider?: string;
+  /** Model name */
+  model?: string;
+  /** API key (reads from env if not provided) */
+  apiKey?: string;
+  /** Base URL (reads from env if not provided) */
+  baseUrl?: string;
+  /** Timeout in ms */
+  timeout?: number;
+}
+
+/**
+ * Evaluate a document against requirements using AgentX.
+ *
+ * Uses agentxjs local mode — no subprocess, no CLI, no auth issues.
+ * Requires `agentxjs` as a peer dependency.
+ */
+export async function agentDocTester(
+  options: {
+    files: string[];
+    requirements: string;
+  },
+  testerOptions: DocTesterOptions = {}
+): Promise<DocTestResult> {
+  const {
+    provider = process.env.AGENTX_PROVIDER || "anthropic",
+    model = env.model,
+    apiKey = env.apiKey || "",
+    baseUrl = env.baseUrl,
+    timeout = 120_000,
+  } = testerOptions;
+
+  const docContents = options.files
+    .map((filePath) => {
+      if (!existsSync(filePath)) {
+        return `--- ${filePath} ---\n[FILE NOT FOUND]`;
+      }
+      return `--- ${filePath} ---\n${readFileSync(filePath, "utf-8")}`;
+    })
+    .join("\n\n");
+
+  const userPrompt = [
+    "Evaluate the following document(s) against the requirements below.",
+    "",
+    "DOCUMENTS:",
+    docContents,
+    "",
+    "REQUIREMENTS:",
+    options.requirements,
+    "",
+    "Evaluate each requirement. Output PASS if all are met, FAIL if any are not.",
+  ].join("\n");
+
+  // Dynamic import to avoid circular dependency (devtools ↔ agentxjs)
+  // Use variable to prevent TypeScript DTS from resolving the module
+  const moduleName = "agentxjs";
+  const agentxjs: any = await import(/* @vite-ignore */ moduleName);
+  const createAgentX: (...args: any[]) => Promise<any> = agentxjs.createAgentX;
+
+  let agentx: any = null;
+
+  try {
+    agentx = await createAgentX({
+      apiKey,
+      provider,
+      model,
+      baseUrl,
+      logLevel: "silent",
+    });
+
+    await agentx.containers.create("doc-tester");
+
+    const { record: image } = await agentx.images.create({
+      containerId: "doc-tester",
+      systemPrompt: SYSTEM_PROMPT,
+    });
+
+    const { agentId } = await agentx.agents.create({ imageId: image.imageId });
+
+    // Collect response text
+    let output = "";
+    agentx.on("text_delta", (e: any) => {
+      output += e.data.text;
+    });
+
+    // Send prompt and wait for completion
+    await Promise.race([
+      agentx.sessions.send(agentId, userPrompt),
+      new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), timeout)),
+    ]);
+
+    output = output.trim();
+    const passed = /\*{0,2}PASS\*{0,2}\b/m.test(output);
+    return { passed, output };
+  } catch (error: any) {
+    return { passed: false, output: error.message || "Unknown error" };
+  } finally {
+    if (agentx) {
+      try {
+        await agentx.shutdown();
+      } catch {
+        // ignore shutdown errors
+      }
+    }
+  }
+}

package/src/bdd/agent-ui-tester.ts

@@ -0,0 +1,88 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const SKILL_PATH = resolve(__dirname, "../../../../.claude/skills/agent-browser/SKILL.md");
+
+function loadSystemPrompt(headed = false): string {
+  let skillContent = "";
+  try {
+    skillContent = readFileSync(SKILL_PATH, "utf-8");
+  } catch {
+    // Skill file not found, continue without it
+  }
+
+  return `You are a UI tester. You test web application scenarios using the agent-browser CLI.
+
+RULES:
+- ONLY use agent-browser commands via Bash tool
+- Use ${headed ? "--headed " : ""}--executable-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" for all commands
+- After each navigation or click, run: agent-browser snapshot -i
+- Refs (@e1, @e2) are invalidated after page changes — always re-snapshot
+- At the end, close the browser with: agent-browser close
+- Output your result as a single line: PASS or FAIL followed by a brief reason
+
+${skillContent ? `AGENT-BROWSER REFERENCE:\n${skillContent}` : ""}`;
+}
+
+export interface UiTestResult {
+  passed: boolean;
+  output: string;
+}
+
+export interface UiTesterOptions {
+  model?: string;
+  baseUrl?: string;
+  timeout?: number;
+  /** Show browser window (default: false) */
+  headed?: boolean;
+}
+
+/**
+ * Run a UI test scenario using Claude Code CLI + agent-browser.
+ *
+ * BDD scripts must run under Node.js (not Bun) to avoid claude CLI auth bug.
+ */
+export function agentUiTester(prompt: string, options: UiTesterOptions = {}): UiTestResult {
+  const { model = "haiku", baseUrl, timeout = 300_000, headed = false } = options;
+
+  const fullPrompt = baseUrl ? `Base URL: ${baseUrl}\n\n${prompt}` : prompt;
+
+  const systemPrompt = loadSystemPrompt(headed);
+
+  // Filter out CLAUDE* env vars to avoid auth conflicts when spawned from Claude Code
+  const cleanEnv = Object.fromEntries(
+    Object.entries(process.env).filter(([k]) => !k.startsWith("CLAUDE"))
+  );
+
+  try {
+    const output = execFileSync(
+      "claude",
+      [
+        "-p",
+        fullPrompt,
+        "--model",
+        model,
+        "--append-system-prompt",
+        systemPrompt,
+        "--allowedTools",
+        "Bash(agent-browser:*)",
+      ],
+      {
+        encoding: "utf-8",
+        timeout,
+        env: cleanEnv,
+        maxBuffer: 10 * 1024 * 1024,
+      }
+    ).trim();
+
+    const passed = /\*{0,2}PASS\*{0,2}\b/m.test(output);
+    return { passed, output };
+  } catch (error: any) {
+    const output = error.stdout || error.stderr || error.message || "Unknown error";
+    return { passed: false, output: output.trim() };
+  }
+}