@rudderjs/ai 1.5.0 → 1.6.1

package/dist/computer-use/tool.d.ts

@@ -0,0 +1,154 @@
+/**
+ * `computerUseTool({ page })` — the agent-tool factory for #A7 Phase 2.
+ *
+ * Wraps the phase-1 {@link executeComputerAction} executor as a tool the
+ * agent loop can invoke. The tool is tagged so the Anthropic provider
+ * adapter substitutes the standard function-call schema with Anthropic's
+ * native `computer_20250124` tool block at the API level — Claude is
+ * fine-tuned on that exact tool, so quality is dramatically better than
+ * a generic function-call wrapper.
+ *
+ * # Anthropic-only in v1
+ *
+ * Pass `model` to fail loud at agent-construction time when the agent's
+ * model isn't Anthropic-family — see {@link ComputerUseProviderError}.
+ * Without `model`, validation is deferred (the Anthropic adapter is the
+ * only one that recognizes the provider hint, so non-Anthropic models
+ * silently see a no-arg generic tool — degraded but not catastrophic).
+ *
+ * # Wiring
+ *
+ * ```ts
+ * import { Agent } from '@rudderjs/ai'
+ * import { computerUseTool } from '@rudderjs/ai/computer-use'
+ * import { chromium } from 'playwright'
+ *
+ * const browser = await chromium.launch()
+ * const page    = await browser.newPage()
+ * await page.setViewportSize({ width: 1280, height: 800 })
+ *
+ * class BrowserAgent extends Agent {
+ *   model() { return 'anthropic/claude-opus-4-7' }
+ *
+ *   tools() {
+ *     return [
+ *       computerUseTool({
+ *         page,
+ *         viewport: { width: 1280, height: 800 },
+ *         model:    this.model(),   // upfront provider check
+ *       }),
+ *     ]
+ *   }
+ * }
+ * ```
+ *
+ * # State
+ *
+ * Each `computerUseTool({...})` call captures a fresh
+ * {@link ComputerExecutorState} in its closure. Passing the same tool
+ * instance through multiple agent runs SHARES cursor state across them
+ * — usually fine, but call the factory inside `tools()` (which Agent
+ * runs per request) for clean per-run state.
+ *
+ * The same closure carries the action counter for {@link maxActions}.
+ *
+ * # Image results
+ *
+ * `screenshot` actions return PNG bytes. The tool's execute base64-
+ * encodes them and returns a `ContentPart[]` array with one image
+ * block — the Anthropic adapter's `toAnthropicMessages` handles array
+ * tool-message content directly (a generic enhancement, not
+ * computer-use-specific). Other providers see a JSON-stringified
+ * fallback; in practice they never get here because the tool throws at
+ * construction when bound to a non-Anthropic model.
+ */
+import type { ContentPart, Tool, ToolCallContext, ToolDefinitionOptions, ToolDefinitionSchema } from '../types.js';
+import { ComputerUseLimitError, ComputerUseProviderError, isAnthropicLikeModel } from './errors.js';
+import { type ComputerAction, type ComputerExecutorState, type PageLike } from './actions.js';
+/**
+ * Symbol-tagged marker identifying a computer-use tool. Looked up via
+ * `Symbol.for(...)` so cross-bundle / cross-realm checks succeed even
+ * when `@rudderjs/ai` is loaded twice (rare, but possible in monorepo +
+ * linked setups). Mirrors the `HANDOFF_MARKER` pattern.
+ */
+export declare const COMPUTER_USE_MARKER: unique symbol;
+/**
+ * The fixed tool name. Anthropic's native `computer_20250124` tool
+ * expects calls to land on a tool literally named `computer` — the
+ * model is trained on that name. Apps don't override it.
+ */
+export declare const COMPUTER_USE_TOOL_NAME = "computer";
+/** Options for {@link computerUseTool}. */
+export interface ComputerUseToolOptions {
+    /**
+     * Playwright `Page` (or any object structurally matching {@link PageLike}).
+     * Caller owns the lifecycle — launch, set viewport, navigate, close.
+     */
+    page: PageLike;
+    /**
+     * Display dimensions reported to the model in the native
+     * `computer_20250124` block. Defaults to `1280×800` (Anthropic's
+     * recommended training-distribution size). Must match what
+     * `page.setViewportSize(...)` was called with — Claude grounds clicks
+     * in this coordinate space.
+     */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Optional agent model id. When provided, the factory fails loud at
+     * construction time if the model isn't Anthropic-family — see
+     * {@link ComputerUseProviderError}. Pass `this.model()` from inside
+     * `Agent.tools()` to get the check.
+     */
+    model?: string;
+    /**
+     * Per-action approval gate. `true` (default) routes every action
+     * through the framework's approval middleware before execution.
+     * `false` opts out entirely. Function form decides per-action — useful
+     * for letting cheap actions (`screenshot`, `mouse_move`) run
+     * unattended while gating destructive ones.
+     *
+     * Wired via {@link ToolDefinitionOptions.requireApproval} — same
+     * channel the rest of `@rudderjs/ai`'s approval-resume machinery uses.
+     */
+    needsApproval?: boolean | ((action: ComputerAction) => boolean);
+    /**
+     * Maximum number of actions per agent run before
+     * {@link ComputerUseLimitError} is thrown. Default `50`. Bounds
+     * runaway loops where the model keeps trying the same broken UI step.
+     */
+    maxActions?: number;
+    /**
+     * Override the per-run cursor-tracking state. Rarely needed — the
+     * factory creates a fresh state by default. Provide one if you want
+     * to seed the cursor (e.g. resuming a paused session).
+     */
+    state?: ComputerExecutorState;
+}
+/**
+ * The tool returned by {@link computerUseTool}. Implements the
+ * {@link Tool} interface with `execute` (so the agent loop runs it
+ * directly), and carries the {@link COMPUTER_USE_MARKER} so adapters
+ * and observers can detect it without coupling to a class.
+ */
+export interface ComputerUseTool extends Tool<ComputerAction, ContentPart[] | string> {
+    readonly [COMPUTER_USE_MARKER]: true;
+    readonly definition: ToolDefinitionOptions;
+    execute(input: ComputerAction, ctx?: ToolCallContext): Promise<ContentPart[] | string>;
+    toSchema(): ToolDefinitionSchema;
+}
+/**
+ * Build the agent tool. See module JSDoc for usage.
+ */
+export declare function computerUseTool(opts: ComputerUseToolOptions): ComputerUseTool;
+/**
+ * Structural typeguard. Mirrors {@link isHandoffTool} — handoff /
+ * computer-use tools are plain objects tagged with their respective
+ * `Symbol.for(...)` markers, so the loop and adapters can detect them
+ * without coupling to a class hierarchy.
+ */
+export declare function isComputerUseTool(t: unknown): t is ComputerUseTool;
+export { ComputerUseLimitError, ComputerUseProviderError, isAnthropicLikeModel };
+//# sourceMappingURL=tool.d.ts.map

package/dist/computer-use/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/computer-use/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAElH,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,qBAAqB,EAC1B,KAAK,QAAQ,EACd,MAAM,cAAc,CAAA;AAGrB;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAA+C,CAAA;AAExF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,aAAa,CAAA;AAMhD,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,IAAI,EAAE,QAAQ,CAAA;IACd;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,CAAA;IAC/D;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAA;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,cAAc,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IACnF,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,IAAI,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAA;IAC1C,OAAO,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,MAAM,CAAC,CAAA;IACtF,QAAQ,IAAI,oBAAoB,CAAA;CACjC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,eAAe,CAsE7E;AAiDD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,eAAe,CAIlE;AAID,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,CAAA"}

package/dist/computer-use/tool.js

@@ -0,0 +1,210 @@
+/**
+ * `computerUseTool({ page })` — the agent-tool factory for #A7 Phase 2.
+ *
+ * Wraps the phase-1 {@link executeComputerAction} executor as a tool the
+ * agent loop can invoke. The tool is tagged so the Anthropic provider
+ * adapter substitutes the standard function-call schema with Anthropic's
+ * native `computer_20250124` tool block at the API level — Claude is
+ * fine-tuned on that exact tool, so quality is dramatically better than
+ * a generic function-call wrapper.
+ *
+ * # Anthropic-only in v1
+ *
+ * Pass `model` to fail loud at agent-construction time when the agent's
+ * model isn't Anthropic-family — see {@link ComputerUseProviderError}.
+ * Without `model`, validation is deferred (the Anthropic adapter is the
+ * only one that recognizes the provider hint, so non-Anthropic models
+ * silently see a no-arg generic tool — degraded but not catastrophic).
+ *
+ * # Wiring
+ *
+ * ```ts
+ * import { Agent } from '@rudderjs/ai'
+ * import { computerUseTool } from '@rudderjs/ai/computer-use'
+ * import { chromium } from 'playwright'
+ *
+ * const browser = await chromium.launch()
+ * const page    = await browser.newPage()
+ * await page.setViewportSize({ width: 1280, height: 800 })
+ *
+ * class BrowserAgent extends Agent {
+ *   model() { return 'anthropic/claude-opus-4-7' }
+ *
+ *   tools() {
+ *     return [
+ *       computerUseTool({
+ *         page,
+ *         viewport: { width: 1280, height: 800 },
+ *         model:    this.model(),   // upfront provider check
+ *       }),
+ *     ]
+ *   }
+ * }
+ * ```
+ *
+ * # State
+ *
+ * Each `computerUseTool({...})` call captures a fresh
+ * {@link ComputerExecutorState} in its closure. Passing the same tool
+ * instance through multiple agent runs SHARES cursor state across them
+ * — usually fine, but call the factory inside `tools()` (which Agent
+ * runs per request) for clean per-run state.
+ *
+ * The same closure carries the action counter for {@link maxActions}.
+ *
+ * # Image results
+ *
+ * `screenshot` actions return PNG bytes. The tool's execute base64-
+ * encodes them and returns a `ContentPart[]` array with one image
+ * block — the Anthropic adapter's `toAnthropicMessages` handles array
+ * tool-message content directly (a generic enhancement, not
+ * computer-use-specific). Other providers see a JSON-stringified
+ * fallback; in practice they never get here because the tool throws at
+ * construction when bound to a non-Anthropic model.
+ */
+import { z } from 'zod';
+import { ComputerUseLimitError, ComputerUseProviderError, isAnthropicLikeModel, } from './errors.js';
+import { makeExecutorState, } from './actions.js';
+import { executeComputerAction } from './playwright.js';
+/**
+ * Symbol-tagged marker identifying a computer-use tool. Looked up via
+ * `Symbol.for(...)` so cross-bundle / cross-realm checks succeed even
+ * when `@rudderjs/ai` is loaded twice (rare, but possible in monorepo +
+ * linked setups). Mirrors the `HANDOFF_MARKER` pattern.
+ */
+export const COMPUTER_USE_MARKER = Symbol.for('rudderjs.ai.computer-use');
+/**
+ * The fixed tool name. Anthropic's native `computer_20250124` tool
+ * expects calls to land on a tool literally named `computer` — the
+ * model is trained on that name. Apps don't override it.
+ */
+export const COMPUTER_USE_TOOL_NAME = 'computer';
+const DEFAULT_VIEWPORT = { width: 1280, height: 800 };
+const DEFAULT_MAX_ACTIONS = 50;
+const DEFAULT_NEEDS_APPROVAL = true;
+/**
+ * Build the agent tool. See module JSDoc for usage.
+ */
+export function computerUseTool(opts) {
+    // Upfront provider check — fail loud at agent construction.
+    if (opts.model !== undefined && !isAnthropicLikeModel(opts.model)) {
+        throw new ComputerUseProviderError(opts.model);
+    }
+    const viewport = opts.viewport ?? DEFAULT_VIEWPORT;
+    const maxActions = opts.maxActions ?? DEFAULT_MAX_ACTIONS;
+    const needsApproval = opts.needsApproval ?? DEFAULT_NEEDS_APPROVAL;
+    const state = opts.state ?? makeExecutorState();
+    const page = opts.page;
+    // Per-tool-instance counter. Closure-private so multiple tools (rare)
+    // don't collide.
+    const counter = { value: 0 };
+    // Build the needs-approval shape the framework's tool runner reads.
+    // ToolDefinitionOptions.needsApproval is `boolean | (input) => boolean | Promise<boolean>`.
+    const needsApprovalForDefinition = typeof needsApproval === 'function'
+        ? (input) => needsApproval(input)
+        : needsApproval;
+    const definition = {
+        name: COMPUTER_USE_TOOL_NAME,
+        description: 'Take screenshots, click, type, and otherwise drive a desktop / browser. ' +
+            'Use to interact with on-screen UI you cannot reach via plain HTTP.',
+        // Anthropic's native tool block carries an implicit schema (the model
+        // is trained on it). The standard `parameters` we emit is irrelevant
+        // for Anthropic — the providerHint substitution drops it. `z.any()`
+        // is the conservative default for any non-Anthropic serialization
+        // that still tries to read the schema.
+        inputSchema: z.any(),
+        needsApproval: needsApprovalForDefinition,
+        // Carried through by `toolToSchema` → `toAnthropicTools` recognizes
+        // `providerHint.type === 'computer-use'` and emits the native
+        // `computer_20250124` block instead of a generic function-call shape.
+        providerHint: {
+            type: 'computer-use',
+            tool: 'computer_20250124',
+            display_width_px: viewport.width,
+            display_height_px: viewport.height,
+        },
+    };
+    const tool = {
+        [COMPUTER_USE_MARKER]: true,
+        definition,
+        async execute(input) {
+            counter.value++;
+            if (counter.value > maxActions) {
+                throw new ComputerUseLimitError(maxActions);
+            }
+            const result = await executeComputerAction(page, input, state);
+            return formatActionResult(result);
+        },
+        toSchema() {
+            return {
+                name: COMPUTER_USE_TOOL_NAME,
+                description: definition.description,
+                // Empty object — see comment in `definition.inputSchema` above.
+                parameters: { type: 'object', properties: {}, additionalProperties: true },
+                providerHint: definition.providerHint,
+            };
+        },
+    };
+    return tool;
+}
+/**
+ * Convert a {@link ComputerActionResult} into the message-content shape
+ * the agent loop stores on the tool message and passes to the provider.
+ *
+ * - `image` → `ContentPart[]` with one image block. The Anthropic
+ *   adapter's tool-message handler emits this as Anthropic's `content:
+ *   [{ type: 'image', source: { ... } }]` shape.
+ * - `text` → plain string (current adapter path: `content: <string>`).
+ * - `error` → throw. The agent loop's error path wraps the throw into a
+ *   tool-result with `is_error: true` and the error message — exactly
+ *   the Anthropic semantics we want for "the action failed; let the
+ *   model retry."
+ */
+function formatActionResult(result) {
+    if (result.type === 'image') {
+        const data = bytesToBase64(result.data);
+        return [
+            {
+                type: 'image',
+                mimeType: result.media_type,
+                data,
+            },
+        ];
+    }
+    if (result.type === 'text') {
+        return result.text;
+    }
+    // result.type === 'error' — throw so the agent loop wraps as is_error.
+    throw new Error(result.text);
+}
+/**
+ * Encode raw bytes as a base64 string. Uses `Buffer` when available
+ * (Node) and falls back to a synchronous browser-safe path otherwise.
+ * Computer-use only runs in Node (Playwright requires it), but the
+ * fallback keeps the module importable from runtime-agnostic tests.
+ */
+function bytesToBase64(data) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(data).toString('base64');
+    }
+    // Browser fallback — slow but correct.
+    let binary = '';
+    for (let i = 0; i < data.length; i++)
+        binary += String.fromCharCode(data[i]);
+    return btoa(binary);
+}
+/**
+ * Structural typeguard. Mirrors {@link isHandoffTool} — handoff /
+ * computer-use tools are plain objects tagged with their respective
+ * `Symbol.for(...)` markers, so the loop and adapters can detect them
+ * without coupling to a class hierarchy.
+ */
+export function isComputerUseTool(t) {
+    if (t === null || typeof t !== 'object')
+        return false;
+    const marker = t[COMPUTER_USE_MARKER];
+    return marker === true;
+}
+// ─── Re-export error classes + helper ─────────────────────
+export { ComputerUseLimitError, ComputerUseProviderError, isAnthropicLikeModel };
+//# sourceMappingURL=tool.js.map

package/dist/computer-use/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/computer-use/tool.ts"],"names":[],"mappings":"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"}

package/dist/eval/fixtures.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Fixture I/O for `pnpm rudder ai:eval --record` / `--replay` (#A5
+ * Phase 4). Each case writes one JSON file under
+ * `evals/__fixtures__/<suite>/<case>.json` carrying the assistant
+ * turns from a real provider run, normalized into the
+ * {@link AiFakeStep} shape so `--replay` can re-feed them via
+ * `AiFake.respondWithSequence` for zero-API regression tests.
+ *
+ * The fixture format is versioned. Bumping `version` forces a
+ * re-record on stale fixtures rather than silently mis-replaying.
+ */
+import type { AgentResponse } from '../types.js';
+import type { AiFakeStep } from '../fake.js';
+/** Fixture format. Bump `version` when the shape changes incompatibly. */
+export interface EvalFixture {
+    version: 1;
+    suite: string;
+    case: string;
+    input: string;
+    recordedAt: string;
+    steps: AiFakeStep[];
+}
+/**
+ * Convert an `AgentResponse` into the assistant-turn `AiFakeStep[]`
+ * sequence that `AiFake.respondWithSequence` expects.
+ *
+ * - Drops user/tool turns — those are framework-generated during a
+ *   replayed run, not provider output.
+ * - Multi-modal assistant content collapses to its concatenated text
+ *   parts (the fake's transport is text-only; image/document parts
+ *   wouldn't replay meaningfully).
+ * - `toolCalls` carry through verbatim so multi-step tool loops
+ *   replay deterministically.
+ */
+export declare function stepsFromResponse(response: AgentResponse): AiFakeStep[];
+/**
+ * Default fixtures directory: `<cwd>/evals/__fixtures__`. Override
+ * via the CLI handler's options for tests / non-standard layouts.
+ */
+export declare function defaultFixturesDir(cwd: string): string;
+/**
+ * Filesystem-safe slug for `<suite>/<case>` segments. Letters,
+ * digits, dot, dash, underscore pass through; everything else
+ * collapses to `-`. Multiple consecutive `-` collapse to one.
+ *
+ * Pure function; tested directly so suite/case rename diffs stay
+ * predictable across editors.
+ */
+export declare function slugify(s: string): string;
+export declare function fixturePath(dir: string, suite: string, caseName: string): string;
+/**
+ * Read a fixture file. Returns `null` when the fixture is missing
+ * (replay falls back to running normally with a clear stderr line).
+ *
+ * Throws on parse / version errors — corruption is not a passing
+ * case and silently ignoring it would mask real regressions.
+ */
+export declare function readFixture(dir: string, suite: string, caseName: string): Promise<EvalFixture | null>;
+/**
+ * Write a fixture, creating intermediate directories as needed.
+ * Pretty-printed (2-space) so PR diffs remain readable when the
+ * model output evolves.
+ */
+export declare function writeFixture(dir: string, suite: string, caseName: string, payload: Omit<EvalFixture, 'version' | 'suite' | 'case' | 'recordedAt'>): Promise<string>;
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/eval/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../src/eval/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,aAAa,CAAA;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAK,CAAC,CAAA;IACb,KAAK,EAAO,MAAM,CAAA;IAClB,IAAI,EAAQ,MAAM,CAAA;IAClB,KAAK,EAAO,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAO,UAAU,EAAE,CAAA;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,UAAU,EAAE,CAWvE;AASD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEhF;AAID;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAO,MAAM,EAChB,KAAK,EAAK,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAiB7B;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAO,MAAM,EAChB,KAAK,EAAK,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAG,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC,GACvE,OAAO,CAAC,MAAM,CAAC,CAYjB"}

package/dist/eval/fixtures.js

@@ -0,0 +1,110 @@
+/**
+ * Fixture I/O for `pnpm rudder ai:eval --record` / `--replay` (#A5
+ * Phase 4). Each case writes one JSON file under
+ * `evals/__fixtures__/<suite>/<case>.json` carrying the assistant
+ * turns from a real provider run, normalized into the
+ * {@link AiFakeStep} shape so `--replay` can re-feed them via
+ * `AiFake.respondWithSequence` for zero-API regression tests.
+ *
+ * The fixture format is versioned. Bumping `version` forces a
+ * re-record on stale fixtures rather than silently mis-replaying.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Convert an `AgentResponse` into the assistant-turn `AiFakeStep[]`
+ * sequence that `AiFake.respondWithSequence` expects.
+ *
+ * - Drops user/tool turns — those are framework-generated during a
+ *   replayed run, not provider output.
+ * - Multi-modal assistant content collapses to its concatenated text
+ *   parts (the fake's transport is text-only; image/document parts
+ *   wouldn't replay meaningfully).
+ * - `toolCalls` carry through verbatim so multi-step tool loops
+ *   replay deterministically.
+ */
+export function stepsFromResponse(response) {
+    return response.steps
+        .filter(step => step.message.role === 'assistant')
+        .map(step => {
+        const out = {
+            text: contentToText(step.message.content),
+            finishReason: step.finishReason,
+        };
+        if (step.toolCalls.length > 0)
+            out.toolCalls = step.toolCalls;
+        return out;
+    });
+}
+function contentToText(content) {
+    if (typeof content === 'string')
+        return content;
+    return content.filter(p => p.type === 'text').map(p => p.text).join('');
+}
+// ─── Fixture path conventions ─────────────────────────────
+/**
+ * Default fixtures directory: `<cwd>/evals/__fixtures__`. Override
+ * via the CLI handler's options for tests / non-standard layouts.
+ */
+export function defaultFixturesDir(cwd) {
+    return path.join(cwd, 'evals', '__fixtures__');
+}
+/**
+ * Filesystem-safe slug for `<suite>/<case>` segments. Letters,
+ * digits, dot, dash, underscore pass through; everything else
+ * collapses to `-`. Multiple consecutive `-` collapse to one.
+ *
+ * Pure function; tested directly so suite/case rename diffs stay
+ * predictable across editors.
+ */
+export function slugify(s) {
+    return s.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || '_';
+}
+export function fixturePath(dir, suite, caseName) {
+    return path.join(dir, slugify(suite), `${slugify(caseName)}.json`);
+}
+// ─── Read / write ─────────────────────────────────────────
+/**
+ * Read a fixture file. Returns `null` when the fixture is missing
+ * (replay falls back to running normally with a clear stderr line).
+ *
+ * Throws on parse / version errors — corruption is not a passing
+ * case and silently ignoring it would mask real regressions.
+ */
+export async function readFixture(dir, suite, caseName) {
+    const file = fixturePath(dir, suite, caseName);
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1) {
+        throw new Error(`[RudderJS AI] Fixture ${file} is version ${String(parsed.version)}; expected 1. ` +
+            `Re-record with \`pnpm rudder ai:eval --record\`.`);
+    }
+    return parsed;
+}
+/**
+ * Write a fixture, creating intermediate directories as needed.
+ * Pretty-printed (2-space) so PR diffs remain readable when the
+ * model output evolves.
+ */
+export async function writeFixture(dir, suite, caseName, payload) {
+    const file = fixturePath(dir, suite, caseName);
+    await mkdir(path.dirname(file), { recursive: true });
+    const fixture = {
+        version: 1,
+        suite,
+        case: caseName,
+        recordedAt: new Date().toISOString(),
+        ...payload,
+    };
+    await writeFile(file, `${JSON.stringify(fixture, null, 2)}\n`);
+    return file;
+}
+//# sourceMappingURL=fixtures.js.map

package/dist/eval/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../../src/eval/fixtures.ts"],"names":[],"mappings":"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"}

package/dist/eval/html-reporter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Self-contained HTML reporter for `pnpm rudder ai:eval --html`
+ * (#A5 Phase 5). Renders one or more {@link SuiteReport}s into a
+ * single HTML string with inline styles and minimal vanilla JS for
+ * row expand/collapse — no framework deps, no external assets, safe
+ * to paste into a PR comment or open offline.
+ *
+ * Defensive HTML-escape on every piece of user content (suite name,
+ * case name, input, response, metadata). Long responses get a
+ * `<pre>` block with `white-space: pre-wrap` so output stays
+ * scannable without a horizontal scroll.
+ */
+import type { SuiteReport } from './index.js';
+export interface HtmlReportOptions {
+    /** Document `<title>`. Defaults to `"Eval Report"`. */
+    title?: string;
+    /** ISO timestamp shown in the header. Defaults to `new Date().toISOString()`. */
+    generatedAt?: string;
+}
+/**
+ * Render an array of {@link SuiteReport}s as a single self-contained
+ * HTML document.
+ */
+export declare function reportHtml(reports: SuiteReport[], opts?: HtmlReportOptions): string;
+//# sourceMappingURL=html-reporter.d.ts.map

package/dist/eval/html-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-reporter.d.ts","sourceRoot":"","sources":["../../src/eval/html-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAA;AAE3D,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,KAAK,CAAC,EAAQ,MAAM,CAAA;IACpB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,IAAI,GAAE,iBAAsB,GAAG,MAAM,CA6CvF"}