@yasserkhanorg/e2e-agents 1.8.5 → 1.10.0

package/dist/esm/adapters/playwright.js

@@ -0,0 +1,49 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Playwright Adapter — FrameworkAdapter implementation for @playwright/test.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export class PlaywrightAdapter {
+    constructor() {
+        this.name = 'playwright';
+        this.specGlob = '**/*.spec.{ts,js}';
+        this.extractTestPattern = /\btest(?:\.describe)?\s*\(/g;
+        this.configFileNames = ['playwright.config.ts', 'playwright.config.js'];
+    }
+    detect(projectRoot) {
+        const pkgPath = path.join(projectRoot, 'package.json');
+        if (!fs.existsSync(pkgPath)) {
+            return false;
+        }
+        try {
+            const raw = fs.readFileSync(pkgPath, 'utf-8');
+            const pkg = JSON.parse(raw);
+            const allDeps = {
+                ...pkg.dependencies,
+                ...pkg.devDependencies,
+            };
+            return '@playwright/test' in allDeps;
+        }
+        catch {
+            return false;
+        }
+    }
+    buildRunCommand(specPath, options) {
+        const args = ['playwright', 'test', specPath];
+        if (options?.headed) {
+            args.push('--headed');
+        }
+        if (options?.browser) {
+            args.push('--browser', options.browser);
+        }
+        if (options?.project) {
+            args.push('--project', options.project);
+        }
+        if (options?.timeout != null) {
+            args.push('--timeout', String(options.timeout));
+        }
+        return { executable: 'npx', args };
+    }
+}

package/dist/esm/adapters/pytest.js

@@ -0,0 +1,59 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Pytest adapter for Python API testing.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export class PytestAdapter {
+    constructor() {
+        this.name = 'pytest';
+        this.specGlob = '**/test_*.py';
+        this.extractTestPattern = /def\s+(test_\w+)/g;
+        this.configFileNames = ['pytest.ini', 'pyproject.toml', 'setup.cfg', 'conftest.py'];
+    }
+    detect(projectRoot) {
+        // Check for common pytest indicator files
+        const indicators = ['pyproject.toml', 'pytest.ini', 'conftest.py', 'setup.cfg'];
+        for (const file of indicators) {
+            const filePath = path.join(projectRoot, file);
+            if (!fs.existsSync(filePath))
+                continue;
+            // For setup.cfg, only match if it contains a [tool:pytest] or [pytest] section
+            if (file === 'setup.cfg') {
+                try {
+                    const content = fs.readFileSync(filePath, 'utf-8');
+                    if (content.includes('[tool:pytest]') || content.includes('[pytest]')) {
+                        return true;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            else if (file === 'pyproject.toml') {
+                try {
+                    const content = fs.readFileSync(filePath, 'utf-8');
+                    if (content.includes('pytest')) {
+                        return true;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            else {
+                // pytest.ini or conftest.py existence is sufficient
+                return true;
+            }
+        }
+        return false;
+    }
+    buildRunCommand(specPath, options) {
+        const args = ['-m', 'pytest', specPath, '-v'];
+        if (options?.timeout) {
+            args.push(`--timeout=${Math.ceil(options.timeout / 1000)}`);
+        }
+        return { executable: 'python', args };
+    }
+}

package/dist/esm/adapters/supertest.js

@@ -0,0 +1,48 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Supertest + Vitest/Jest adapter for Node.js API testing.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export class SupertestAdapter {
+    constructor(runner = 'vitest') {
+        this.name = 'supertest';
+        this.specGlob = '**/*.{test,spec}.{ts,js}';
+        this.extractTestPattern = /(?:it|test)\s*\(\s*(['"`])(.*?)\1/g;
+        this.configFileNames = ['vitest.config.ts', 'vitest.config.js', 'jest.config.ts', 'jest.config.js'];
+        this.runner = runner;
+    }
+    detect(projectRoot) {
+        const pkgPath = path.join(projectRoot, 'package.json');
+        if (!fs.existsSync(pkgPath)) {
+            return false;
+        }
+        try {
+            const raw = fs.readFileSync(pkgPath, 'utf-8');
+            const pkg = JSON.parse(raw);
+            const allDeps = {
+                ...pkg.dependencies,
+                ...pkg.devDependencies,
+            };
+            return 'supertest' in allDeps;
+        }
+        catch {
+            return false;
+        }
+    }
+    buildRunCommand(specPath, options) {
+        if (this.runner === 'jest') {
+            const args = ['jest', specPath];
+            if (options?.timeout) {
+                args.push(`--testTimeout=${options.timeout}`);
+            }
+            return { executable: 'npx', args };
+        }
+        const args = ['vitest', 'run', specPath];
+        if (options?.timeout) {
+            args.push(`--testTimeout=${options.timeout}`);
+        }
+        return { executable: 'npx', args };
+    }
+}

package/dist/esm/agent/git.js

@@ -98,7 +98,7 @@ function isRelevantFile(file) {
     }
     return true;
 }
-function runGitRaw(args, cwd) {
+export function runGitRaw(args, cwd) {
     const result = spawnSync('git', args, {
         cwd,
         encoding: 'utf-8',
@@ -182,8 +182,10 @@ function isCommentOnlyDiff(file, repoRoot, baseRef) {
 export function isTestFile(file) {
     const normalized = file.replace(/\\/g, '/');
     return /\.(spec|test)\.(ts|tsx|js|jsx)$/.test(normalized) ||
+        /\.snap$/.test(normalized) ||
         /_test\.go$/.test(normalized) ||
         normalized.includes('__tests__/') ||
+        normalized.includes('__snapshots__/') ||
         normalized.includes('/tests/') ||
         normalized.includes('/test/');
 }

package/dist/esm/agentic/fix_loop.js

@@ -1,17 +1,18 @@
 // Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
 // See LICENSE.txt for license information.
+import { sanitizeForPrompt } from '../crew/sanitize.js';
 export function buildFixPrompt(ctx) {
     const isCompileError = ctx.failures.some((f) => f.testTitle === '(compile)');
     const failuresBlock = ctx.failures.map((f) => {
-        const lines = [`  Test: ${f.testTitle}`, `  Error: ${f.error}`];
+        const lines = [`  Test: ${sanitizeForPrompt(f.testTitle)}`, `  Error: ${sanitizeForPrompt(f.error)}`];
         if (f.stack)
-            lines.push(`  Stack: ${f.stack}`);
+            lines.push(`  Stack: ${sanitizeForPrompt(f.stack)}`);
         if (f.line)
             lines.push(`  Line: ${f.line}`);
         if (f.expected)
-            lines.push(`  Expected: ${f.expected}`);
+            lines.push(`  Expected: ${sanitizeForPrompt(f.expected)}`);
         if (f.actual)
-            lines.push(`  Actual: ${f.actual}`);
+            lines.push(`  Actual: ${sanitizeForPrompt(f.actual)}`);
         return lines.join('\n');
     }).join('\n\n');
     const errorType = isCompileError ? 'COMPILE ERROR' : 'TEST FAILURE';

package/dist/esm/agentic/runner.js

@@ -6,17 +6,20 @@ import { runPlaywrightSpec } from './playwright_runner.js';
 import { generateFix } from './fix_loop.js';
 import { parseGenerationResponse } from '../prompts/generation.js';
 import { formatApiSurfaceForPrompt } from '../knowledge/api_surface.js';
-function buildGeneratePrompt(scenario, apiSurfaceHint) {
+import { sanitizeForPrompt } from '../crew/sanitize.js';
+function buildGeneratePrompt(scenario, apiSurfaceHint, profile) {
+    const projectName = profile?.projectName || 'Mattermost';
+    const importSource = profile?.importStatement || '@mattermost/playwright-lib';
     const scenariosBlock = scenario.scenarios
-        .map((s, i) => `  ${i + 1}. ${s}`)
+        .map((s, i) => `  ${i + 1}. ${sanitizeForPrompt(s)}`)
         .join('\n');
     return [
-        'Generate a Mattermost Playwright E2E test file.',
+        `Generate a ${projectName} Playwright E2E test file.`,
         '',
-        `FLOW: ${scenario.name}`,
+        `FLOW: ${sanitizeForPrompt(scenario.name)}`,
         `Route Family: ${scenario.routeFamily}`,
         `Priority: ${scenario.priority}`,
-        scenario.evidence ? `Evidence: ${scenario.evidence}` : '',
+        scenario.evidence ? `Evidence: ${sanitizeForPrompt(scenario.evidence)}` : '',
         '',
         'SCENARIOS TO IMPLEMENT:',
         scenariosBlock,
@@ -25,14 +28,14 @@ function buildGeneratePrompt(scenario, apiSurfaceHint) {
         apiSurfaceHint || 'Use page.getByRole() or page.getByTestId() for selectors.',
         '',
         'MANDATORY RULES:',
-        '1. Import ONLY from "@mattermost/playwright-lib" — no other test framework imports.',
+        `1. Import ONLY from "${importSource}" — no other test framework imports.`,
         '2. Every test must call `await pw.initSetup()` first.',
         '3. Use `await pw.testBrowser.login(user)` to log in — never hardcode credentials.',
         '4. Use ONLY page object methods listed above. Do NOT invent methods.',
         '5. If a method is not available, use `page.getByRole()` or `page.getByTestId()`.',
         `6. Tag every test: {tag: '@${scenario.routeFamily}'}`,
         '7. Write one test per scenario with a descriptive name.',
-        '8. Use `expect` from "@mattermost/playwright-lib".',
+        `8. Use \`expect\` from "${importSource}".`,
         '9. Include the copyright header.',
         '10. NEVER fabricate test IDs (MM-TXXXX). Use descriptive names only.',
         '',
@@ -41,7 +44,7 @@ function buildGeneratePrompt(scenario, apiSurfaceHint) {
         '// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.',
         '// See LICENSE.txt for license information.',
         '',
-        "import {expect, test} from '@mattermost/playwright-lib';",
+        `import {expect, test} from '${importSource}';`,
         '',
         'test(',
         "    'user can post a message in channel',",
@@ -80,13 +83,13 @@ function resolveSpecPath(scenario, testsRoot) {
     }
     return specPath;
 }
-async function generateInitialSpec(provider, scenario, specPath, apiSurfaceHint) {
-    const prompt = buildGeneratePrompt(scenario, apiSurfaceHint);
+async function generateInitialSpec(provider, scenario, specPath, apiSurfaceHint, profile) {
+    const prompt = buildGeneratePrompt(scenario, apiSurfaceHint, profile);
     const response = await provider.generateText(prompt, {
         maxTokens: 8000,
         temperature: 0.1,
         timeout: 60000,
-        systemPrompt: 'You are an expert Playwright test writer for Mattermost. Return only TypeScript code.',
+        systemPrompt: `You are an expert Playwright test writer for ${profile?.projectName || 'Mattermost'}. Return only TypeScript code.`,
     });
     // Reuse existing parsing logic from prompts/generation.ts
     const parsed = parseGenerationResponse(response.text, specPath, 'create_spec', scenario.id);
@@ -105,7 +108,7 @@ async function runSingleScenario(scenario, options) {
     // Step 1: Generate initial spec
     let specCode;
     try {
-        specCode = await generateInitialSpec(provider, scenario, specPath, apiHint);
+        specCode = await generateInitialSpec(provider, scenario, specPath, apiHint, options.generationProfile);
     }
     catch (error) {
         const msg = error instanceof Error ? error.message : String(error);

package/dist/esm/agents/cross-impact.js

@@ -30,7 +30,12 @@ export class CrossImpactAgent {
         ctx.crossImpacts.push(...deterministicCrossImpacts);
         // Then: LLM-enriched analysis for semantic cross-impacts
         try {
-            const provider = await getCrewProvider(ctx.providerOverride);
+            const provider = await getCrewProvider(ctx.providerOverride, ctx.budgetUSD, {
+                agentRole: 'cross-impact',
+                modelRoutingProviderType: ctx.modelRoutingProviderType,
+                modelRoutingOverrides: ctx.modelRoutingOverrides,
+                budgetLedger: ctx.budgetLedger,
+            });
             const prompt = buildCrossImpactPrompt({
                 changedFiles: ctx.changedFiles,
                 families: ctx.routeFamilies,

package/dist/esm/agents/executor.js

@@ -35,7 +35,12 @@ export class ExecutorAgent {
             };
         });
         try {
-            const provider = await getCrewProvider(ctx.providerOverride);
+            const provider = await getCrewProvider(ctx.providerOverride, ctx.budgetUSD, {
+                agentRole: 'executor',
+                modelRoutingProviderType: ctx.modelRoutingProviderType,
+                modelRoutingOverrides: ctx.modelRoutingOverrides,
+                budgetLedger: ctx.budgetLedger,
+            });
             const summary = await runAgenticGeneration({
                 scenarios,
                 config: {

package/dist/esm/agents/strategist.js

@@ -28,7 +28,12 @@ export class StrategistAgent {
             regressionRisks: ctx.regressionRisks,
         });
         try {
-            const provider = await getCrewProvider(ctx.providerOverride);
+            const provider = await getCrewProvider(ctx.providerOverride, ctx.budgetUSD, {
+                agentRole: 'strategist',
+                modelRoutingProviderType: ctx.modelRoutingProviderType,
+                modelRoutingOverrides: ctx.modelRoutingOverrides,
+                budgetLedger: ctx.budgetLedger,
+            });
             const response = await provider.generateText(prompt, {
                 maxTokens: 4000,
                 temperature: 0,

package/dist/esm/agents/test-designer.js

@@ -30,7 +30,12 @@ export class TestDesignerAgent {
         }
         let provider;
         try {
-            provider = await getCrewProvider(ctx.providerOverride);
+            provider = await getCrewProvider(ctx.providerOverride, ctx.budgetUSD, {
+                agentRole: 'test-designer',
+                modelRoutingProviderType: ctx.modelRoutingProviderType,
+                modelRoutingOverrides: ctx.modelRoutingOverrides,
+                budgetLedger: ctx.budgetLedger,
+            });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/esm/anthropic_provider.js

@@ -68,6 +68,7 @@ export class AnthropicProvider extends BaseProvider {
         this.model = config.model || 'claude-sonnet-4-5-20250929';
     }
     async generateText(prompt, options) {
+        this.checkBudget();
         const startTime = Date.now();
         try {
             // SECURITY: Validate prompt length to prevent resource exhaustion

package/dist/esm/base_provider.js

@@ -1,14 +1,110 @@
 // Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
 // See LICENSE.txt for license information.
+import { withRetry } from './resilience/retry.js';
+import { CircuitBreaker } from './resilience/circuit_breaker.js';
 /**
  * Abstract base class for all LLM providers
  * Eliminates 240+ lines of duplicate stats management code
  * Provides common functionality for token tracking, cost calculation, and stats management
  */
+export class BudgetExceededError extends Error {
+    constructor(currentCost, budgetUSD) {
+        super(`Budget exceeded: $${currentCost.toFixed(4)} >= $${budgetUSD} limit`);
+        this.currentCost = currentCost;
+        this.budgetUSD = budgetUSD;
+        this.name = 'BudgetExceededError';
+    }
+}
 export class BaseProvider {
     constructor() {
+        /** Tracks the current in-flight budget reservation for this provider instance. */
+        this._activeReservation = 0;
         this.initializeStats();
     }
+    /** Lazily get-or-create a circuit breaker shared across all instances of this provider type. */
+    get circuitBreaker() {
+        let cb = BaseProvider._sharedBreakers.get(this.name);
+        if (!cb) {
+            cb = new CircuitBreaker({
+                shouldCount: (error) => {
+                    if (error instanceof BudgetExceededError)
+                        return false;
+                    if (!(error instanceof Error))
+                        return true;
+                    const msg = error.message.toLowerCase();
+                    return msg.includes('429') || msg.includes('rate limit') ||
+                        msg.includes('500') || msg.includes('502') || msg.includes('503') || msg.includes('504') ||
+                        msg.includes('econnreset') || msg.includes('econnrefused') || msg.includes('etimedout') ||
+                        msg.includes('overloaded') || msg.includes('socket hang up') || msg.includes('network error');
+                },
+            });
+            BaseProvider._sharedBreakers.set(this.name, cb);
+        }
+        return cb;
+    }
+    /**
+     * Set a hard budget limit. Once totalCost reaches this value,
+     * subsequent calls will throw BudgetExceededError.
+     */
+    setBudget(usd) {
+        this._budgetUSD = usd;
+    }
+    get budgetUSD() {
+        return this._budgetUSD;
+    }
+    /**
+     * Attach a shared budget ledger so aggregate cost across all providers
+     * in a crew run is checked before each LLM call.
+     */
+    setBudgetLedger(ledger) {
+        this._ledger = ledger;
+    }
+    /**
+     * Check budget and pre-reserve estimated cost for the upcoming LLM call.
+     *
+     * When a shared ledger exists, reserves an estimate derived from the provider's
+     * output token cost × maxTokens (default 4096). This blocks parallel agents from
+     * spending into the same headroom — like a credit card authorization hold.
+     *
+     * Self-healing: if a prior call failed without reaching updateStats(), the stale
+     * reservation is released here before placing the new one.
+     */
+    checkBudget() {
+        if (this._ledger) {
+            // Release stale reservation from a prior failed call that never hit updateStats
+            if (this._activeReservation > 0) {
+                this._ledger.release(this._activeReservation);
+                this._activeReservation = 0;
+            }
+            // Reserve estimated cost for the upcoming call
+            const estimate = this.estimateCallCost();
+            this._ledger.reserve(estimate);
+            this._activeReservation = estimate;
+            try {
+                this._ledger.check();
+            }
+            catch (err) {
+                // Budget exceeded — release reservation immediately so it doesn't leak
+                this._ledger.release(estimate);
+                this._activeReservation = 0;
+                throw err;
+            }
+            return;
+        }
+        if (this._budgetUSD !== undefined && this.stats.totalCost >= this._budgetUSD) {
+            throw new BudgetExceededError(this.stats.totalCost, this._budgetUSD);
+        }
+    }
+    /**
+     * Conservative cost estimate for the upcoming call.
+     * Uses maxTokens (or 4096 default) × output cost rate.
+     * Overestimating is safe — the reservation is replaced with actual cost in updateStats.
+     */
+    estimateCallCost() {
+        const outputTokenEstimate = 4096;
+        const costRate = this.capabilities?.costPer1MOutputTokens ?? 15; // default to ~Sonnet
+        return (outputTokenEstimate / 1000000) * costRate;
+    }
     /**
      * Initialize stats object with default values
      */
@@ -35,6 +131,14 @@ export class BaseProvider {
         this.stats.totalOutputTokens += usage.outputTokens;
         this.stats.totalTokens += usage.totalTokens;
         this.stats.totalCost += cost;
+        if (this._ledger) {
+            // Settle: release the estimate, record actual
+            if (this._activeReservation > 0) {
+                this._ledger.release(this._activeReservation);
+                this._activeReservation = 0;
+            }
+            this._ledger.record(cost);
+        }
         // Update rolling average response time
         const totalRequests = this.stats.requestCount;
         this.stats.averageResponseTimeMs =
@@ -53,6 +157,17 @@ export class BaseProvider {
     resetUsageStats() {
         this.initializeStats();
     }
+    /**
+     * Wrap an async call with circuit breaker + retry logic.
+     * Circuit breaker protects against cascading failures from a down provider;
+     * retry handles transient failures within a healthy circuit.
+     *
+     * Non-transient errors (budget, auth, validation) are thrown directly and
+     * bypass the circuit breaker so they don't incorrectly trip it.
+     */
+    retryCall(fn) {
+        return this.circuitBreaker.call(() => withRetry(fn, { maxRetries: 2, baseDelayMs: 1000, maxDelayMs: 10000, jitter: true }), () => { throw new Error(`${this.name} provider circuit open — too many consecutive failures`); });
+    }
     /**
      * Calculate cost for token usage, accounting for prompt caching discounts
      * Cached tokens cost 90% less than regular tokens
@@ -75,3 +190,9 @@ export class BaseProvider {
         return inputCost + outputCost;
     }
 }
+/**
+ * Shared circuit breakers keyed by provider name (e.g., "anthropic", "openai").
+ * All instances of the same provider type share one breaker, so if Anthropic is
+ * down, ALL agents discover it after 3 total failures instead of 3 × N.
+ */
+BaseProvider._sharedBreakers = new Map();

package/dist/esm/budget_ledger.js

@@ -0,0 +1,58 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Shared budget ledger — tracks aggregate cost across all provider instances
+ * in a single crew run. Prevents parallel agents from each seeing only 1/N
+ * of actual spend and overshooting the budget by N×limit.
+ *
+ * Usage: create one BudgetLedger per crew run, pass it to getCrewProvider(),
+ * which attaches it to each provider via setBudgetLedger().
+ */
+import { BudgetExceededError } from './base_provider.js';
+export class BudgetLedger {
+    constructor(limitUSD) {
+        this._totalCost = 0;
+        this._reserved = 0;
+        this._limitUSD = limitUSD;
+    }
+    get totalCost() {
+        return this._totalCost;
+    }
+    get limitUSD() {
+        return this._limitUSD;
+    }
+    /**
+     * Record actual cost from a completed LLM call.
+     */
+    record(cost) {
+        if (!Number.isFinite(cost) || cost < 0)
+            return;
+        this._totalCost += cost;
+    }
+    /**
+     * Pre-reserve estimated cost before an LLM call begins.
+     * Blocks parallel agents from spending into the same headroom.
+     * Like a credit card authorization hold.
+     */
+    reserve(estimate) {
+        if (!Number.isFinite(estimate) || estimate <= 0)
+            return;
+        this._reserved += estimate;
+    }
+    /**
+     * Release a prior reservation (after API response or on error).
+     */
+    release(estimate) {
+        this._reserved = Math.max(0, this._reserved - estimate);
+    }
+    /**
+     * Throws BudgetExceededError if committed cost + in-flight reservations
+     * have reached the limit.
+     */
+    check() {
+        const effective = this._totalCost + this._reserved;
+        if (effective >= this._limitUSD) {
+            throw new BudgetExceededError(effective, this._limitUSD);
+        }
+    }
+}

package/dist/esm/cache/cached_provider.js

@@ -0,0 +1,82 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { ResponseCache, TTL } from './response_cache.js';
+/**
+ * Decorator that adds transparent response caching to any LLMProvider.
+ *
+ * - `generateText()` checks the cache first and returns a cached response on hit.
+ *   On a miss it delegates to the inner provider, stores the result, and returns it.
+ * - All other methods (analyzeImage, streamText, capabilities, usage stats)
+ *   delegate directly to the wrapped provider.
+ *
+ * The TTL is selected based on the agent role: agents whose name contains
+ * "generat" use the shorter GENERATION TTL; all others use ANALYSIS.
+ */
+export class CachedProvider {
+    constructor(inner, cache, cacheContext) {
+        this.inner = inner;
+        this.cache = cache;
+        this.ctx = cacheContext;
+        this.name = inner.name;
+        this.capabilities = inner.capabilities;
+        // Pick TTL based on agent role
+        this.ttlMs = cacheContext.agent.toLowerCase().includes('generat')
+            ? TTL.GENERATION
+            : TTL.ANALYSIS;
+        // Wire optional methods only when the inner provider supports them
+        if (inner.analyzeImage) {
+            this.analyzeImage = (images, prompt, options) => inner.analyzeImage(images, prompt, options);
+        }
+        if (inner.streamText) {
+            this.streamText = (prompt, options) => inner.streamText(prompt, options);
+        }
+    }
+    /**
+     * Generate text with cache-through semantics.
+     * On a cache hit the inner provider is never called, saving tokens and latency.
+     */
+    async generateText(prompt, options) {
+        const { agent, family, fileHashes } = this.ctx;
+        const model = this.inner.name;
+        // Check cache
+        const cached = this.cache.get(agent, family, fileHashes, model);
+        if (cached) {
+            return {
+                text: cached.response,
+                usage: {
+                    inputTokens: cached.usage.inputTokens,
+                    outputTokens: cached.usage.outputTokens,
+                    totalTokens: cached.usage.inputTokens + cached.usage.outputTokens,
+                    cachedTokens: cached.usage.inputTokens,
+                },
+                cost: 0, // No cost on cache hit
+            };
+        }
+        // Cache miss - call inner provider
+        const response = await this.inner.generateText(prompt, options);
+        // Store in cache
+        const key = ResponseCache.buildKey({ agent, family, fileHashes, model });
+        const entry = {
+            key,
+            family,
+            response: response.text,
+            usage: {
+                inputTokens: response.usage.inputTokens,
+                outputTokens: response.usage.outputTokens,
+                cost: response.cost,
+            },
+            createdAt: new Date().toISOString(),
+            ttlMs: this.ttlMs,
+        };
+        this.cache.set(entry);
+        return response;
+    }
+    getUsageStats() {
+        return this.inner.getUsageStats();
+    }
+    resetUsageStats() {
+        this.inner.resetUsageStats();
+    }
+}
+// Re-export for convenience
+export { ResponseCache, TTL } from './response_cache.js';