@synergenius/flow-weaver 0.2.0

package/dist/testing/mock-approval.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Mock Approval Provider for deterministic human-approval workflow testing.
+ *
+ * Mirrors the mock LLM provider pattern — pattern matching on prompts,
+ * call recording, and configurable responses.
+ *
+ * Usage in vitest/jest tests:
+ * ```typescript
+ * import { createMockApprovalProvider } from 'flow-weaver/testing';
+ *
+ * const mockApproval = createMockApprovalProvider([
+ *   { match: /expense/, response: { approved: true, reviewer: 'alice' } },
+ *   { match: /delete/, response: { approved: false, response: 'Too risky' } },
+ *   { match: /./, response: { approved: true } },
+ * ]);
+ *
+ * // Inject globally for compiled workflows
+ * (globalThis as unknown as { __fw_approval_provider__?: ApprovalProvider })
+ *   .__fw_approval_provider__ = mockApproval;
+ *
+ * // After test
+ * expect(mockApproval.getCallCount()).toBe(2);
+ * ```
+ */
+export interface ApprovalRequest {
+    id: string;
+    prompt: string;
+    context?: Record<string, unknown>;
+    timeout?: string;
+}
+export interface ApprovalResult {
+    approved: boolean;
+    response?: string;
+    reviewer?: string;
+}
+export interface ApprovalProvider {
+    requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
+}
+export interface MockApprovalResponse {
+    /** Pattern to match against the approval prompt. String = includes check, RegExp = test. */
+    match: string | RegExp;
+    /** The result to return when matched */
+    response: ApprovalResult;
+    /** Maximum number of times this response can be used (default: unlimited) */
+    maxUses?: number;
+}
+export interface MockApprovalCall {
+    /** The approval request that was made */
+    request: ApprovalRequest;
+    /** Which response definition matched (-1 if fallback) */
+    matchedIndex: number;
+    /** The result that was returned */
+    result: ApprovalResult;
+    /** Timestamp of the call */
+    timestamp: number;
+}
+export interface MockApprovalProvider extends ApprovalProvider {
+    /** Get all recorded calls */
+    getCalls(): MockApprovalCall[];
+    /** Get total number of calls */
+    getCallCount(): number;
+    /** Reset call history and usage counters */
+    reset(): void;
+    /** Get calls that matched a specific response index */
+    getCallsForResponse(index: number): MockApprovalCall[];
+}
+/**
+ * Creates a mock approval provider with deterministic response matching.
+ *
+ * Responses are matched in order against the approval request prompt.
+ * First match wins. If no response matches, a fallback result is returned.
+ *
+ * @param responses - Array of match/response pairs, checked in order
+ * @param options - Configuration options
+ * @returns A mock provider with call recording
+ */
+export declare function createMockApprovalProvider(responses?: MockApprovalResponse[], options?: {
+    /** Response to return when no match is found */
+    fallbackResponse?: ApprovalResult;
+}): MockApprovalProvider;
+//# sourceMappingURL=mock-approval.d.ts.map

package/dist/testing/mock-approval.js

@@ -0,0 +1,98 @@
+/**
+ * Mock Approval Provider for deterministic human-approval workflow testing.
+ *
+ * Mirrors the mock LLM provider pattern — pattern matching on prompts,
+ * call recording, and configurable responses.
+ *
+ * Usage in vitest/jest tests:
+ * ```typescript
+ * import { createMockApprovalProvider } from 'flow-weaver/testing';
+ *
+ * const mockApproval = createMockApprovalProvider([
+ *   { match: /expense/, response: { approved: true, reviewer: 'alice' } },
+ *   { match: /delete/, response: { approved: false, response: 'Too risky' } },
+ *   { match: /./, response: { approved: true } },
+ * ]);
+ *
+ * // Inject globally for compiled workflows
+ * (globalThis as unknown as { __fw_approval_provider__?: ApprovalProvider })
+ *   .__fw_approval_provider__ = mockApproval;
+ *
+ * // After test
+ * expect(mockApproval.getCallCount()).toBe(2);
+ * ```
+ */
+const FALLBACK_RESULT = {
+    approved: false,
+    response: '[Mock: no matching approval response configured]',
+};
+/**
+ * Creates a mock approval provider with deterministic response matching.
+ *
+ * Responses are matched in order against the approval request prompt.
+ * First match wins. If no response matches, a fallback result is returned.
+ *
+ * @param responses - Array of match/response pairs, checked in order
+ * @param options - Configuration options
+ * @returns A mock provider with call recording
+ */
+export function createMockApprovalProvider(responses = [], options) {
+    const calls = [];
+    const useCounts = new Map();
+    const fallback = options?.fallbackResponse ?? FALLBACK_RESULT;
+    function findMatch(prompt) {
+        for (let i = 0; i < responses.length; i++) {
+            const def = responses[i];
+            // Check max uses
+            if (def.maxUses !== undefined) {
+                const used = useCounts.get(i) ?? 0;
+                if (used >= def.maxUses)
+                    continue;
+            }
+            const matches = typeof def.match === 'string'
+                ? prompt.includes(def.match)
+                : def.match.test(prompt);
+            if (matches) {
+                return { index: i, response: def };
+            }
+        }
+        return null;
+    }
+    return {
+        async requestApproval(request) {
+            const match = findMatch(request.prompt);
+            let result;
+            let matchedIndex;
+            if (match) {
+                matchedIndex = match.index;
+                useCounts.set(matchedIndex, (useCounts.get(matchedIndex) ?? 0) + 1);
+                result = { ...match.response.response };
+            }
+            else {
+                matchedIndex = -1;
+                result = { ...fallback };
+            }
+            calls.push({
+                request: { ...request },
+                matchedIndex,
+                result,
+                timestamp: Date.now(),
+            });
+            return result;
+        },
+        getCalls() {
+            return [...calls];
+        },
+        getCallCount() {
+            return calls.length;
+        },
+        reset() {
+            calls.length = 0;
+            useCounts.clear();
+        },
+        getCallsForResponse(index) {
+            return calls.filter((c) => c.matchedIndex === index);
+        },
+    };
+}
+//# sourceMappingURL=mock-approval.js.map

package/dist/testing/mock-llm.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Mock LLM Provider for deterministic agent workflow testing.
+ *
+ * Usage in vitest/jest tests:
+ * ```typescript
+ * import { createMockLlmProvider } from 'flow-weaver/testing';
+ *
+ * const mockLlm = createMockLlmProvider([
+ *   { match: /search/, response: { content: null, toolCalls: [{ id: '1', name: 'search', arguments: { q: 'test' } }], finishReason: 'tool_calls' } },
+ *   { match: /./, response: { content: 'Default answer', toolCalls: [], finishReason: 'stop' } },
+ * ]);
+ *
+ * // Inject globally for compiled workflows
+ * (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ = mockLlm;
+ *
+ * // After test
+ * expect(mockLlm.getCallCount()).toBe(2);
+ * expect(mockLlm.getTotalTokens()).toBe(150);
+ * ```
+ */
+export interface LLMMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCallId?: string;
+}
+export interface LLMToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface LLMResponse {
+    content: string | null;
+    toolCalls: LLMToolCall[];
+    finishReason: 'stop' | 'tool_calls' | 'length' | 'error';
+    usage?: LLMTokenUsage;
+}
+export interface LLMTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+export interface LLMTool {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+        }>;
+        required?: string[];
+    };
+}
+export interface LLMProvider {
+    chat(messages: LLMMessage[], options?: {
+        tools?: LLMTool[];
+        systemPrompt?: string;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<LLMResponse>;
+}
+export interface MockLlmResponse {
+    /** Pattern to match against the last user message content. String = includes check, RegExp = test. */
+    match: string | RegExp;
+    /** The response to return when matched */
+    response: {
+        content?: string | null;
+        toolCalls?: LLMToolCall[];
+        finishReason?: LLMResponse['finishReason'];
+    };
+    /** Simulated token usage for this response */
+    usage?: LLMTokenUsage;
+    /** Maximum number of times this response can be used (default: unlimited) */
+    maxUses?: number;
+}
+export interface MockLlmCall {
+    /** Messages sent to the provider */
+    messages: LLMMessage[];
+    /** Options passed to the provider */
+    options?: {
+        tools?: LLMTool[];
+        systemPrompt?: string;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    };
+    /** Which response definition matched (-1 if fallback) */
+    matchedIndex: number;
+    /** The response that was returned */
+    response: LLMResponse;
+    /** Timestamp of the call */
+    timestamp: number;
+}
+export interface MockLlmProvider extends LLMProvider {
+    /** Get all recorded calls */
+    getCalls(): MockLlmCall[];
+    /** Get total number of calls */
+    getCallCount(): number;
+    /** Get total simulated tokens across all calls */
+    getTotalTokens(): number;
+    /** Get token usage breakdown per call */
+    getTokenUsage(): LLMTokenUsage[];
+    /** Reset call history and usage counters */
+    reset(): void;
+    /** Get calls that matched a specific response index */
+    getCallsForResponse(index: number): MockLlmCall[];
+}
+/**
+ * Creates a mock LLM provider with deterministic response matching.
+ *
+ * Responses are matched in order against the last user message content.
+ * First match wins. If no response matches, a fallback response is returned.
+ *
+ * @param responses - Array of match/response pairs, checked in order
+ * @param options - Configuration options
+ * @returns A mock provider with call recording and token tracking
+ */
+export declare function createMockLlmProvider(responses?: MockLlmResponse[], options?: {
+    /** Default token usage when a response doesn't specify usage */
+    defaultUsage?: LLMTokenUsage;
+    /** Response to return when no match is found (default: generic mock message) */
+    fallbackResponse?: Partial<LLMResponse>;
+}): MockLlmProvider;
+//# sourceMappingURL=mock-llm.d.ts.map

package/dist/testing/mock-llm.js

@@ -0,0 +1,119 @@
+/**
+ * Mock LLM Provider for deterministic agent workflow testing.
+ *
+ * Usage in vitest/jest tests:
+ * ```typescript
+ * import { createMockLlmProvider } from 'flow-weaver/testing';
+ *
+ * const mockLlm = createMockLlmProvider([
+ *   { match: /search/, response: { content: null, toolCalls: [{ id: '1', name: 'search', arguments: { q: 'test' } }], finishReason: 'tool_calls' } },
+ *   { match: /./, response: { content: 'Default answer', toolCalls: [], finishReason: 'stop' } },
+ * ]);
+ *
+ * // Inject globally for compiled workflows
+ * (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ = mockLlm;
+ *
+ * // After test
+ * expect(mockLlm.getCallCount()).toBe(2);
+ * expect(mockLlm.getTotalTokens()).toBe(150);
+ * ```
+ */
+const DEFAULT_USAGE = {
+    promptTokens: 50,
+    completionTokens: 25,
+    totalTokens: 75,
+};
+const FALLBACK_RESPONSE = {
+    content: '[Mock: no matching response configured]',
+    toolCalls: [],
+    finishReason: 'stop',
+    usage: DEFAULT_USAGE,
+};
+/**
+ * Creates a mock LLM provider with deterministic response matching.
+ *
+ * Responses are matched in order against the last user message content.
+ * First match wins. If no response matches, a fallback response is returned.
+ *
+ * @param responses - Array of match/response pairs, checked in order
+ * @param options - Configuration options
+ * @returns A mock provider with call recording and token tracking
+ */
+export function createMockLlmProvider(responses = [], options) {
+    const calls = [];
+    const useCounts = new Map();
+    const defaultUsage = options?.defaultUsage ?? DEFAULT_USAGE;
+    const fallback = {
+        ...FALLBACK_RESPONSE,
+        ...(options?.fallbackResponse ?? {}),
+        usage: options?.fallbackResponse?.usage ?? defaultUsage,
+    };
+    function findMatch(lastMessage) {
+        for (let i = 0; i < responses.length; i++) {
+            const def = responses[i];
+            // Check max uses
+            if (def.maxUses !== undefined) {
+                const used = useCounts.get(i) ?? 0;
+                if (used >= def.maxUses)
+                    continue;
+            }
+            const matches = typeof def.match === 'string'
+                ? lastMessage.includes(def.match)
+                : def.match.test(lastMessage);
+            if (matches) {
+                return { index: i, response: def };
+            }
+        }
+        return null;
+    }
+    return {
+        async chat(messages, chatOptions) {
+            const lastUserMessage = [...messages].reverse().find((m) => m.role === 'user')?.content ?? '';
+            const match = findMatch(lastUserMessage);
+            let response;
+            let matchedIndex;
+            if (match) {
+                matchedIndex = match.index;
+                useCounts.set(matchedIndex, (useCounts.get(matchedIndex) ?? 0) + 1);
+                response = {
+                    content: match.response.response.content ?? null,
+                    toolCalls: match.response.response.toolCalls ?? [],
+                    finishReason: match.response.response.finishReason ?? 'stop',
+                    usage: match.response.usage ?? defaultUsage,
+                };
+            }
+            else {
+                matchedIndex = -1;
+                response = { ...fallback };
+            }
+            calls.push({
+                messages: [...messages],
+                options: chatOptions,
+                matchedIndex,
+                response,
+                timestamp: Date.now(),
+            });
+            return response;
+        },
+        getCalls() {
+            return [...calls];
+        },
+        getCallCount() {
+            return calls.length;
+        },
+        getTotalTokens() {
+            return calls.reduce((sum, call) => sum + (call.response.usage?.totalTokens ?? 0), 0);
+        },
+        getTokenUsage() {
+            return calls.map((call) => call.response.usage ?? defaultUsage);
+        },
+        reset() {
+            calls.length = 0;
+            useCounts.clear();
+        },
+        getCallsForResponse(index) {
+            return calls.filter((c) => c.matchedIndex === index);
+        },
+    };
+}
+//# sourceMappingURL=mock-llm.js.map

package/dist/testing/recorder.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Recording LLM Provider — wraps a real provider and records all interactions.
+ *
+ * Usage:
+ * ```typescript
+ * import { createRecordingProvider } from 'flow-weaver/testing';
+ *
+ * const recorder = createRecordingProvider(realLlmProvider);
+ *
+ * // Use recorder.provider as the LLM provider in your workflow
+ * (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ = recorder.provider;
+ *
+ * // Run workflow...
+ *
+ * // Get the recording for later replay
+ * const recording = recorder.getRecording();
+ * const json = JSON.stringify(recording, null, 2);
+ * // Save to disk, fixture file, etc.
+ * ```
+ */
+import type { LLMMessage, LLMProvider, LLMResponse, LLMTool } from './mock-llm.js';
+export interface LlmRecordingStep {
+    /** Sequential index of this call */
+    index: number;
+    /** Input sent to the LLM */
+    input: {
+        messages: LLMMessage[];
+        options?: {
+            tools?: LLMTool[];
+            systemPrompt?: string;
+            model?: string;
+            temperature?: number;
+            maxTokens?: number;
+        };
+    };
+    /** Response from the LLM */
+    output: LLMResponse;
+    /** ISO timestamp when the call started */
+    timestamp: string;
+    /** Wall-clock duration in milliseconds */
+    durationMs: number;
+}
+export interface LlmRecording {
+    /** Recorded LLM interactions in order */
+    steps: LlmRecordingStep[];
+    /** Optional metadata (test name, workflow name, etc.) */
+    metadata: Record<string, unknown>;
+    /** ISO timestamp when recording started */
+    createdAt: string;
+}
+export interface RecordingLlmProvider {
+    /** The wrapped provider — use this as your LLMProvider */
+    provider: LLMProvider;
+    /** Get the current recording */
+    getRecording(): LlmRecording;
+    /** Get the number of recorded calls */
+    getCallCount(): number;
+    /** Clear all recorded data */
+    reset(): void;
+}
+/**
+ * Creates a recording LLM provider that wraps a real provider.
+ *
+ * Every call to `chat()` is passed through to the real provider,
+ * and the input/output/timing is recorded for later replay.
+ *
+ * @param realProvider - The real LLM provider to wrap
+ * @param metadata - Optional metadata to include in the recording
+ * @returns A recording provider with access to the recorded data
+ */
+export declare function createRecordingProvider(realProvider: LLMProvider, metadata?: Record<string, unknown>): RecordingLlmProvider;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/testing/recorder.js

@@ -0,0 +1,70 @@
+/**
+ * Recording LLM Provider — wraps a real provider and records all interactions.
+ *
+ * Usage:
+ * ```typescript
+ * import { createRecordingProvider } from 'flow-weaver/testing';
+ *
+ * const recorder = createRecordingProvider(realLlmProvider);
+ *
+ * // Use recorder.provider as the LLM provider in your workflow
+ * (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ = recorder.provider;
+ *
+ * // Run workflow...
+ *
+ * // Get the recording for later replay
+ * const recording = recorder.getRecording();
+ * const json = JSON.stringify(recording, null, 2);
+ * // Save to disk, fixture file, etc.
+ * ```
+ */
+/**
+ * Creates a recording LLM provider that wraps a real provider.
+ *
+ * Every call to `chat()` is passed through to the real provider,
+ * and the input/output/timing is recorded for later replay.
+ *
+ * @param realProvider - The real LLM provider to wrap
+ * @param metadata - Optional metadata to include in the recording
+ * @returns A recording provider with access to the recorded data
+ */
+export function createRecordingProvider(realProvider, metadata) {
+    const steps = [];
+    const createdAt = new Date().toISOString();
+    const provider = {
+        async chat(messages, options) {
+            const startTime = Date.now();
+            const timestamp = new Date(startTime).toISOString();
+            const response = await realProvider.chat(messages, options);
+            const durationMs = Date.now() - startTime;
+            steps.push({
+                index: steps.length,
+                input: {
+                    messages: [...messages],
+                    ...(options ? { options: { ...options } } : {}),
+                },
+                output: { ...response },
+                timestamp,
+                durationMs,
+            });
+            return response;
+        },
+    };
+    return {
+        provider,
+        getRecording() {
+            return {
+                steps: steps.map((s) => ({ ...s })),
+                metadata: { ...(metadata ?? {}) },
+                createdAt,
+            };
+        },
+        getCallCount() {
+            return steps.length;
+        },
+        reset() {
+            steps.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=recorder.js.map

package/dist/testing/replayer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Replay LLM Provider — creates a mock provider from a recorded session.
+ *
+ * Usage:
+ * ```typescript
+ * import { createReplayProvider, loadRecording } from 'flow-weaver/testing';
+ *
+ * const recording = loadRecording(jsonFixture);
+ * const replay = createReplayProvider(recording);
+ *
+ * // Use as LLM provider — calls are replayed in order
+ * (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ = replay;
+ *
+ * // Run workflow — LLM calls return recorded responses, no network calls
+ *
+ * // All MockLlmProvider methods work: getCalls(), getTotalTokens(), etc.
+ * expect(replay.getCallCount()).toBe(3);
+ * ```
+ */
+import type { LLMTokenUsage, MockLlmProvider } from './mock-llm.js';
+import type { LlmRecording } from './recorder.js';
+export interface ReplayOptions {
+    /**
+     * In strict mode, throws an error if more calls are made than were recorded.
+     * Default: true
+     */
+    strict?: boolean;
+    /**
+     * Default token usage when a recorded step has no usage data.
+     * Default: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+     */
+    defaultUsage?: LLMTokenUsage;
+}
+/**
+ * Creates a MockLlmProvider that replays recorded LLM interactions in order.
+ *
+ * Each `chat()` call returns the next recorded response sequentially.
+ * The returned provider implements the full MockLlmProvider interface,
+ * so all existing assertion helpers and TokenTracker work out of the box.
+ *
+ * @param recording - The recording to replay (from createRecordingProvider or loadRecording)
+ * @param options - Replay configuration
+ * @returns A MockLlmProvider that replays recorded responses
+ */
+export declare function createReplayProvider(recording: LlmRecording, options?: ReplayOptions): MockLlmProvider;
+/**
+ * Parse a recording from JSON data.
+ *
+ * Accepts either a parsed object or a JSON string.
+ * Validates the structure and returns a typed LlmRecording.
+ *
+ * @param data - JSON string or parsed object
+ * @returns A validated LlmRecording
+ */
+export declare function loadRecording(data: string | LlmRecording): LlmRecording;
+//# sourceMappingURL=replayer.d.ts.map