@agentxjs/devtools 1.9.5-dev → 2.0.0

package/dist/recorder/index.d.ts

@@ -0,0 +1,120 @@
+import { Driver, DriverState, DriverStreamEvent } from '@agentxjs/core/driver';
+import { UserMessage } from '@agentxjs/core/agent';
+import { F as Fixture } from '../types-C6Lf3vz2.js';
+
+/**
+ * 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");
+ * ```
+ */
+
+/**
+ * Options for RecordingDriver
+ */
+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().
+ */
+declare class RecordingDriver implements Driver {
+    readonly name = "RecordingDriver";
+    private readonly realDriver;
+    private readonly fixtureName;
+    private readonly fixtureDescription?;
+    private recordedEvents;
+    private recordingStartTime;
+    constructor(options: RecordingDriverOptions);
+    get sessionId(): string | null;
+    get state(): DriverState;
+    initialize(): Promise<void>;
+    dispose(): Promise<void>;
+    /**
+     * Receive a user message and return stream of events
+     *
+     * Wraps the real driver's receive() and records all events.
+     */
+    receive(message: UserMessage): AsyncIterable<DriverStreamEvent>;
+    /**
+     * Interrupt current operation (delegate to real driver)
+     */
+    interrupt(): void;
+    /**
+     * Record an event
+     */
+    private recordEvent;
+    /**
+     * Get the recorded fixture
+     */
+    getFixture(): Fixture;
+    /**
+     * Save the recorded fixture to a JSON file
+     */
+    saveFixture(filePath: string): Promise<void>;
+    /**
+     * Get the number of recorded events
+     */
+    get eventCount(): number;
+    /**
+     * Clear recorded events (start fresh recording)
+     */
+    clearRecording(): void;
+    /**
+     * Get raw recorded events (for debugging)
+     */
+    getRawEvents(): RecordedEvent[];
+}
+/**
+ * Create a RecordingDriver that wraps a real driver
+ */
+declare function createRecordingDriver(options: RecordingDriverOptions): RecordingDriver;
+
+export { RecordingDriver, type RecordingDriverOptions, createRecordingDriver };

package/dist/recorder/index.js

@@ -0,0 +1,10 @@
+import {
+  RecordingDriver,
+  createRecordingDriver
+} from "../chunk-DR45HEV4.js";
+import "../chunk-DGUM43GV.js";
+export {
+  RecordingDriver,
+  createRecordingDriver
+};
+//# sourceMappingURL=index.js.map

package/dist/recorder/index.js.map

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

package/dist/types-C6Lf3vz2.d.ts

@@ -0,0 +1,78 @@
+/**
+ * DevTools Types
+ *
+ * Defines the fixture format for recording and playback.
+ */
+/**
+ * A single event in a fixture
+ */
+interface FixtureEvent {
+    /**
+     * Event type (e.g., "message_start", "text_delta", "message_stop")
+     */
+    type: string;
+    /**
+     * Delay in milliseconds since last event (0 for first event)
+     */
+    delay: number;
+    /**
+     * Event data (type-specific)
+     */
+    data: unknown;
+    /**
+     * Optional: index for content blocks
+     */
+    index?: number;
+    /**
+     * Optional: event context (agentId, sessionId, etc.)
+     */
+    context?: unknown;
+}
+/**
+ * A complete fixture (recorded conversation scenario)
+ */
+interface Fixture {
+    /**
+     * Fixture name (e.g., "simple-reply", "tool-call")
+     */
+    name: string;
+    /**
+     * Human-readable description
+     */
+    description?: string;
+    /**
+     * When this fixture was recorded (Unix timestamp)
+     */
+    recordedAt?: number;
+    /**
+     * The user message that triggers this fixture (optional, for documentation)
+     */
+    trigger?: string;
+    /**
+     * Sequence of events to emit
+     */
+    events: FixtureEvent[];
+}
+/**
+ * Options for MockDriver
+ */
+interface MockDriverOptions {
+    /**
+     * Fixture to use for playback
+     */
+    fixture?: Fixture | string;
+    /**
+     * Custom fixtures map (name -> fixture)
+     */
+    fixtures?: Map<string, Fixture>;
+    /**
+     * Default delay between events if not specified (ms)
+     */
+    defaultDelay?: number;
+    /**
+     * Speed multiplier (1.0 = real time, 0 = instant, 2.0 = half speed)
+     */
+    speedMultiplier?: number;
+}
+
+export type { Fixture as F, MockDriverOptions as M, FixtureEvent as a };

package/package.json

@@ -1,23 +1,78 @@
 {
   "name": "@agentxjs/devtools",
-  "version": "1.9.5-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": {
-    ".": "./src/index.ts",
-    "./mock": "./src/mock/index.ts",
-    "./recorder": "./src/recorder/index.ts",
-    "./fixtures": "./fixtures/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./mock": {
+      "types": "./dist/mock/index.d.ts",
+      "import": "./dist/mock/index.js",
+      "default": "./dist/mock/index.js"
+    },
+    "./recorder": {
+      "types": "./dist/recorder/index.d.ts",
+      "import": "./dist/recorder/index.js",
+      "default": "./dist/recorder/index.js"
+    },
+    "./fixtures": {
+      "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": [
+    "dist",
+    "src",
+    "fixtures"
+  ],
   "scripts": {
+    "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "test": "bun test"
+    "test": "echo 'No tests yet'",
+    "bdd": "bdd"
   },
   "dependencies": {
-    "@agentxjs/core": "1.9.5-dev",
-    "commonxjs": "^0.1.0"
+    "@agentxjs/core": "^2.0.0",
+    "commonxjs": "^0.1.1"
   },
   "devDependencies": {
+    "@agentxjs/claude-driver": "^2.0.0",
+    "@agentxjs/mono-driver": "^2.0.0",
     "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "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() };
+  }
+}