@rigour-labs/core 6.4.3 → 6.5.0

package/dist/gates/hallucinated-imports/js-resolver.js

@@ -13,7 +13,7 @@ import path from 'path';
 import ts from 'typescript';
 import { isNodeBuiltin } from '../hallucinated-imports-stdlib.js';
 import { resolveTsPathTarget } from './ts-path-target.js';
-import { isSvelteKitProvided, resolveSvelteKitLib } from './framework-modules.js';
+import { isNuxtProvided, isSvelteKitProvided, resolveSvelteKitLib } from './framework-modules.js';
 import { loadTsPathConfig } from './tsconfig-paths.js';
 /**
  * Check JavaScript/TypeScript imports in a source file and add hallucinated findings.
@@ -21,6 +21,8 @@ import { loadTsPathConfig } from './tsconfig-paths.js';
 export async function checkJSImports(content, file, ctx) {
     const depsForFile = await resolveJSDepsForFile(file, ctx.cwd, ctx.rootDeps, ctx.depCacheByDir);
     const kitRoot = await ctx.kitRoots.rootFor(file);
+    const nuxtRoot = await ctx.nuxtRoots?.rootFor(file);
+    const typeOnly = typeOnlySpecifiers(content, file);
     for (const spec of collectJSImportSpecs(content, file)) {
         const { line } = spec;
         const importPath = bundlerSpecifier(spec.importPath);
@@ -28,9 +30,11 @@ export async function checkJSImports(content, file, ctx) {
             continue;
         if (kitRoot && isSvelteKitProvided(importPath))
             continue;
+        if (nuxtRoot && isNuxtProvided(importPath, ctx.extractPackageName(importPath)))
+            continue;
         const reason = importPath.startsWith('.')
             ? await checkRelativeImport(file, importPath, ctx)
-            : await checkBareImport(file, importPath, depsForFile, kitRoot, ctx);
+            : await checkBareImport(file, importPath, depsForFile, kitRoot, ctx, typeOnly.has(spec.importPath));
         if (reason) {
             ctx.hallucinated.push({
                 file, line, importPath,
@@ -40,6 +44,21 @@ export async function checkJSImports(content, file, ctx) {
         }
     }
 }
+/** Specifiers imported only for types: `import type`, `export type … from`, or anything in a .d.ts file. */
+export function typeOnlySpecifiers(content, file) {
+    const all = /\.d\.[cm]?ts$/.test(file);
+    const specs = new Set();
+    const pattern = all
+        ? /(?:import|export)[^;]*?from\s*['"]([^'"]+)['"]|import\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+        : /(?:import|export)\s+type\s[^;]*?from\s*['"]([^'"]+)['"]/g;
+    for (const match of content.matchAll(pattern))
+        specs.add(match[1] ?? match[2]);
+    return specs;
+}
+/** `@types/x` for `x`; `@types/scope__x` for `@scope/x`. */
+export function typesPackageFor(pkgName) {
+    return pkgName.startsWith('@') ? `@types/${pkgName.slice(1).replace('/', '__')}` : `@types/${pkgName}`;
+}
 /**
  * Bundler conventions: a query on a relative import (`./logo.svg?raw`, `./worker.ts?worker`)
  * names a transform of that file, so the file is what must exist; a `virtual:` module or a
@@ -82,7 +101,7 @@ async function resolveThroughRootDirs(file, importPath, rootDirs, ctx) {
     return false;
 }
 /** Reason the bare import is hallucinated, or null when it resolves. */
-async function checkBareImport(file, importPath, depsForFile, kitRoot, ctx) {
+async function checkBareImport(file, importPath, depsForFile, kitRoot, ctx, typeOnly = false) {
     const aliasResolution = await resolveTsPathAlias(file, importPath, ctx.cwd, ctx.projectFiles, ctx.tsPathCacheByDir);
     if (aliasResolution === true)
         return null;
@@ -98,6 +117,9 @@ async function checkBareImport(file, importPath, depsForFile, kitRoot, ctx) {
     const pkgName = ctx.extractPackageName(importPath);
     if (isNodeBuiltin(pkgName) || depsForFile.has(pkgName))
         return null;
+    // Types for a package can come from DefinitelyTyped; a type-only import needs nothing at runtime.
+    if (typeOnly && depsForFile.has(typesPackageFor(pkgName)))
+        return null;
     if (ctx.hasNodeModules && await fs.pathExists(path.join(ctx.cwd, 'node_modules', pkgName)))
         return null;
     return `Package '${pkgName}' not in package.json dependencies`;

package/dist/gates/phantom-apis.js

@@ -188,7 +188,7 @@ export class PhantomApisGate extends Gate {
                 continue;
             for (const [alias, moduleName] of moduleAliases) {
                 // Match: alias.methodName( or alias.property.something(
-                const callPattern = new RegExp(`\\b${this.escapeRegex(alias)}\\.(\\w+)\\s*\\(`, 'g');
+                const callPattern = new RegExp(`(?<![\\w$.])${this.escapeRegex(alias)}\\.(\\w+)\\s*\\(`, 'g'); // not `obj.path.split(`
                 let match;
                 while ((match = callPattern.exec(line)) !== null) {
                     const method = match[1];
@@ -243,7 +243,7 @@ export class PhantomApisGate extends Gate {
         for (let i = 0; i < lines.length; i++) {
             const line = this.stripStringLiterals(lines[i]);
             for (const [alias, moduleName] of moduleAliases) {
-                const callPattern = new RegExp(`\\b${this.escapeRegex(alias)}\\.(\\w+)\\s*\\(`, 'g');
+                const callPattern = new RegExp(`(?<![\\w$.])${this.escapeRegex(alias)}\\.(\\w+)\\s*\\(`, 'g'); // not `obj.path.split(`
                 let match;
                 while ((match = callPattern.exec(line)) !== null) {
                     const method = match[1];

package/dist/gates/phantom-apis.test.js

@@ -58,6 +58,16 @@ const exists = path.exists('/tmp');
         expect(failures[0].details).toContain('combine');
         expect(failures[0].details).toContain('exists');
     });
+    it('should NOT flag a property that shares the module name', async () => {
+        mockFindFiles.mockResolvedValue(['src/generate.ts']);
+        mockReadFile.mockResolvedValue(`
+import * as path from 'node:path';
+const tag = proc.path.split('.')[0];
+const dir = path.dirname(file);
+        `);
+        const failures = await gate.run({ cwd: '/project' });
+        expect(failures).toHaveLength(0);
+    });
     it('should NOT flag real path methods', async () => {
         mockFindFiles.mockResolvedValue(['src/paths.ts']);
         mockReadFile.mockResolvedValue(`

package/dist/gates/promise-safety.js

@@ -23,7 +23,7 @@ export class PromiseSafetyGate extends Gate {
         this.config = {
             enabled: config.enabled ?? true,
             check_unhandled_then: config.check_unhandled_then ?? true,
-            check_unsafe_parse: config.check_unsafe_parse ?? true,
+            check_unsafe_parse: config.check_unsafe_parse ?? false,
             check_async_without_await: config.check_async_without_await ?? true,
             check_unsafe_fetch: config.check_unsafe_fetch ?? true,
             ignore_patterns: config.ignore_patterns ?? [],

package/dist/gates/test-quality-matchers.js

@@ -10,6 +10,9 @@ export const JS_ASSERTION_PATTERNS = [
     /expect\s*\(/,
     /assert\s*[.(]/,
     /\.toEqual|\.toBe|\.toContain|\.toMatch|\.toThrow|\.toHaveBeenCalled|\.toHaveLength|\.toBeTruthy|\.toBeFalsy|\.toBeDefined|\.toBeNull|\.toBeUndefined|\.toBeGreaterThan|\.toBeLessThan|\.toHaveProperty|\.toStrictEqual|\.rejects|\.resolves/,
+    // Type-level tests: the compiler is the assertion.
+    /expectTypeOf\s*[<(]|assertType\s*[<(]|@ts-expect-error|\bsatisfies\s+[A-Z]/,
+    /^\s*(?:const|let)\s+[\w$]+\s*:\s*[^=]+=/,
 ];
 /**
  * Regex patterns for detecting mocks in JavaScript/TypeScript tests

package/dist/gates/test-quality.test.js

@@ -47,6 +47,19 @@ describe('API', () => {
         expect(failures).toHaveLength(1);
         expect(failures[0].details).toContain('no-assertion');
     });
+    it('should not flag type-level tests, where the compiler is the assertion', async () => {
+        mockFindFiles.mockResolvedValue(['src/types.test.ts']);
+        mockReadFile.mockResolvedValue(`
+it('our document type accepts the published one', () => {
+    const _published: Document = null as unknown as Published.Document;
+});
+it('infers the output', () => {
+    expectTypeOf(output).toEqualTypeOf<string>();
+});
+        `);
+        const failures = await gate.run({ cwd: '/project' });
+        expect(failures).toHaveLength(0);
+    });
     it('should flag tautological assertions', async () => {
         mockFindFiles.mockResolvedValue(['src/basic.test.ts']);
         mockReadFile.mockResolvedValue(`

package/dist/hooks/checker.test.js

@@ -34,6 +34,15 @@ describe('runHookChecker', () => {
         expect(result.failures).toHaveLength(0);
         expect(result.duration_ms).toBeGreaterThanOrEqual(0);
     });
+    it('lets an agent edit CLAUDE.md by default, and blocks it only when the team opts in', async () => {
+        const filePath = path.join(testDir, 'CLAUDE.md');
+        fs.writeFileSync(filePath, '# Rules\n\n- Use the retry wrapper for partner APIs.\n');
+        const byDefault = await runHookChecker({ cwd: testDir, files: [filePath] });
+        expect(byDefault.failures.filter(f => f.gate === 'governance')).toEqual([]);
+        fs.writeFileSync(path.join(testDir, 'rigour.yml'), yaml.stringify({ version: 1, gates: { governance: { enforce_memory: true } } }));
+        const optedIn = await runHookChecker({ cwd: testDir, files: [filePath] });
+        expect(optedIn.failures.some(f => f.gate === 'governance')).toBe(true);
+    });
     it('should detect file size violations', async () => {
         const filePath = path.join(testDir, 'big.ts');
         const lines = Array.from({ length: 100 }, (_, i) => `export const v${i} = ${i};`);

package/dist/hooks/stop-review.d.ts

@@ -9,6 +9,7 @@
  * an agent back; callers also cap the number of attempts.
  */
 import type { Config, Failure } from '../types/index.js';
+import { type ReviewTaskItem } from '../review/review-task.js';
 export declare const STOP_MAX_ATTEMPTS = 3;
 export interface StopDecision {
     block: boolean;
@@ -20,6 +21,7 @@ export interface StopDecision {
     reviewedFiles: string[];
 }
 export declare function stopReview(cwd: string, config: Config, attempt: number): Promise<StopDecision>;
+export declare function reviewAckMessage(items: ReviewTaskItem[], attempt: number): string;
 /** Critical, or high and either proven by the semantic engine or a security finding. */
 export declare function blocksStop(finding: Failure): boolean;
 export declare function stopMessage(findings: Failure[], attempt: number): string;

package/dist/hooks/stop-review.js

@@ -1,13 +1,29 @@
 import { reviewChange } from '../review/review.js';
+import { buildReviewTask } from '../review/review-task.js';
+import { diffFromGit } from '../review/git-diff.js';
 export const STOP_MAX_ATTEMPTS = 3;
 const MAX_LISTED = 8;
 export async function stopReview(cwd, config, attempt) {
-    const result = await reviewChange({ cwd, config, source: { mode: 'working' } });
+    const diff = diffFromGit(cwd, { mode: 'working' });
+    const result = await reviewChange({ cwd, config, diff });
     const blocking = result.findings.filter(blocksStop);
+    const unreviewed = config.hooks?.require_review_ack ? buildReviewTask(cwd, diff, config.gates.deep?.router).items : [];
     const reviewed = { findings: result.findings, reviewedFiles: Object.keys(result.changedLines) };
-    if (blocking.length === 0)
+    if (blocking.length === 0 && unreviewed.length === 0)
         return { block: false, message: '', blocking: 0, ...reviewed };
-    return { block: true, message: stopMessage(blocking, attempt), blocking: blocking.length, ...reviewed };
+    const message = [
+        ...(blocking.length ? [stopMessage(blocking, attempt)] : []),
+        ...(unreviewed.length ? [reviewAckMessage(unreviewed, attempt)] : []),
+    ].join('\n\n');
+    return { block: true, message, blocking: blocking.length + unreviewed.length, ...reviewed };
+}
+export function reviewAckMessage(items, attempt) {
+    const listed = items.slice(0, MAX_LISTED).map(i => `- ${i.file}:${i.start} \`${i.function}\`: ${i.questions[0]}`);
+    return [
+        `${items.length} risky changed function(s) have not been reviewed (attempt ${attempt} of ${STOP_MAX_ATTEMPTS}).`,
+        'Call rigour_review with mode "agent" for the questions, check each function, then rigour_review_ack it:',
+        ...listed,
+    ].join('\n');
 }
 /** Critical, or high and either proven by the semantic engine or a security finding. */
 export function blocksStop(finding) {

package/dist/hooks/templates.d.ts

@@ -15,6 +15,8 @@
  *
  */
 import type { HookTool } from './types.js';
+/** The `rigour hooks stop` command matching a `rigour hooks check` command, if the checker is the CLI. */
+export declare function stopCommandFor(checkerCommand: string, tool: 'claude' | 'cursor'): string | undefined;
 export interface GeneratedHookFile {
     path: string;
     content: string;

package/dist/hooks/templates.js

@@ -14,6 +14,13 @@
  * Both produce functionally equivalent hook configs for each tool.
  *
  */
+import { STOP_MAX_ATTEMPTS } from './stop-review.js';
+/** Seconds Claude Code waits for the stop review before letting the agent stop. */
+const STOP_HOOK_TIMEOUT_S = 120;
+/** The `rigour hooks stop` command matching a `rigour hooks check` command, if the checker is the CLI. */
+export function stopCommandFor(checkerCommand, tool) {
+    return /\bhooks check$/.test(checkerCommand.trim()) ? `${checkerCommand.trim().replace(/hooks check$/, 'hooks stop')} --tool ${tool}` : undefined;
+}
 /**
  * Generate hook config files for a specific tool.
  */
@@ -44,7 +51,11 @@ function generateClaudeHooks(checkerCommand) {
                         }
                     ]
                 }
-            ]
+            ],
+            // Before the agent finishes: review the uncommitted change, as `rigour hooks init` does.
+            ...(stopCommandFor(checkerCommand, 'claude')
+                ? { Stop: [{ hooks: [{ type: "command", command: stopCommandFor(checkerCommand, 'claude'), timeout: STOP_HOOK_TIMEOUT_S }] }] }
+                : {}),
         }
     };
     return [
@@ -63,7 +74,10 @@ function generateCursorHooks(checkerCommand) {
                 {
                     command: `${checkerCommand} --stdin`,
                 }
-            ]
+            ],
+            ...(stopCommandFor(checkerCommand, 'cursor')
+                ? { stop: [{ command: stopCommandFor(checkerCommand, 'cursor'), loop_limit: STOP_MAX_ATTEMPTS }] }
+                : {}),
         }
     };
     const wrapper = `#!/usr/bin/env node

package/dist/hooks/templates.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/templates.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { generateHookFiles, stopCommandFor } from './templates.js';
+const CHECKER = 'npx @rigour-labs/cli@6.5.0 hooks check';
+describe('hook templates', () => {
+    it('reviews before the agent stops when the checker is the CLI, like `rigour hooks init`', () => {
+        const claude = JSON.parse(generateHookFiles('claude', CHECKER)[0].content);
+        expect(claude.hooks.Stop[0].hooks[0]).toEqual({ type: 'command', command: 'npx @rigour-labs/cli@6.5.0 hooks stop --tool claude', timeout: 120 });
+        const cursor = JSON.parse(generateHookFiles('cursor', CHECKER).find(f => f.path.endsWith('hooks.json')).content);
+        expect(cursor.hooks.stop[0]).toEqual({ command: 'npx @rigour-labs/cli@6.5.0 hooks stop --tool cursor', loop_limit: 3 });
+    });
+    it('adds no stop hook for a checker that is not the CLI', () => {
+        expect(stopCommandFor('node ./my-checker.js', 'claude')).toBeUndefined();
+        const claude = JSON.parse(generateHookFiles('claude', 'node ./my-checker.js')[0].content);
+        expect(claude.hooks.Stop).toBeUndefined();
+    });
+});

package/dist/index.d.ts

@@ -13,6 +13,18 @@ export { normalizeScopePatterns, isScoped } from './utils/scope.js';
 export { deepAnalysisError } from './utils/deep-status.js';
 export { reviewChange, toReviewFinding, type ReviewInput, type ReviewResult, type ReviewFinding } from './review/review.js';
 export { splitByChangedLines, type ChangedLineSplit } from './review/changed-lines.js';
+export { dismissFinding, dismissedKeys, findingKey, isProven, quietSplit, DISMISSED_FILE } from './review/quiet.js';
+export { isGeneratedFile } from './review/generated-files.js';
+export { buildReviewTask, type ReviewTask, type ReviewTaskItem } from './review/review-task.js';
+export { acknowledgeReview, type ReviewAck, type AckResult } from './review/review-ack.js';
+export { exportReviewed, readLedger, reviewedKeys, isReviewed, recordReview, REVIEWED_FILE, type LedgerEntry, type ReviewedKey, type ReviewVerdict } from './review/ledger.js';
+export { rankChangedFunctions, scoreRisk, functionHash, findFunction, type FunctionRisk, type RiskSignals } from './deep/risk.js';
+export { routeFiles, type RouterPolicy, type RouterStats } from './deep/router.js';
+export { appendDeepRun, readDeepRuns, summarizeDeepRuns, type DeepRun, type DeepRunSummary } from './review/deep-runs.js';
+export { learnFromReviews, type LearnFromReviewsOptions, type LearnFromReviewsResult } from './review-learning/learn-from-reviews.js';
+export { readLessons, writeLessons, promoteLesson, matchLessons, lessonText, lessonsPath, type ReviewLesson } from './review-learning/lessons.js';
+export { lessonsForDiff, lessonsSection, type LessonMode } from './review-learning/team-lessons.js';
+export { readRepoRules, rulesForDiff, rulesSection, splitRules, type RepoRule } from './review-learning/repo-rules.js';
 export { diffFromGit, GitDiffError, type DiffSource } from './review/git-diff.js';
 export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount, type ResolvedFix, type FixCapture } from './review/agent-fixes.js';
 export { computeEffectiveness, readAgentEvents, appendAgentEvent, findingKeys, type AgentEvent, type ReviewEffectiveness } from './review/effectiveness.js';
@@ -52,6 +64,7 @@ export * from './context/index-bridge.js';
 export * from './context/automatic-index.js';
 export * from './context/dependency-graph.js';
 export * from './services/context-telemetry-service.js';
+export * from './services/observed-savings.js';
 export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';

package/dist/index.js

@@ -13,6 +13,18 @@ export { normalizeScopePatterns, isScoped } from './utils/scope.js';
 export { deepAnalysisError } from './utils/deep-status.js';
 export { reviewChange, toReviewFinding } from './review/review.js';
 export { splitByChangedLines } from './review/changed-lines.js';
+export { dismissFinding, dismissedKeys, findingKey, isProven, quietSplit, DISMISSED_FILE } from './review/quiet.js';
+export { isGeneratedFile } from './review/generated-files.js';
+export { buildReviewTask } from './review/review-task.js';
+export { acknowledgeReview } from './review/review-ack.js';
+export { exportReviewed, readLedger, reviewedKeys, isReviewed, recordReview, REVIEWED_FILE } from './review/ledger.js';
+export { rankChangedFunctions, scoreRisk, functionHash, findFunction } from './deep/risk.js';
+export { routeFiles } from './deep/router.js';
+export { appendDeepRun, readDeepRuns, summarizeDeepRuns } from './review/deep-runs.js';
+export { learnFromReviews } from './review-learning/learn-from-reviews.js';
+export { readLessons, writeLessons, promoteLesson, matchLessons, lessonText, lessonsPath } from './review-learning/lessons.js';
+export { lessonsForDiff, lessonsSection } from './review-learning/team-lessons.js';
+export { readRepoRules, rulesForDiff, rulesSection, splitRules } from './review-learning/repo-rules.js';
 export { diffFromGit, GitDiffError } from './review/git-diff.js';
 export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount } from './review/agent-fixes.js';
 export { computeEffectiveness, readAgentEvents, appendAgentEvent, findingKeys } from './review/effectiveness.js';
@@ -51,6 +63,7 @@ export * from './context/index-bridge.js';
 export * from './context/automatic-index.js';
 export * from './context/dependency-graph.js';
 export * from './services/context-telemetry-service.js';
+export * from './services/observed-savings.js';
 export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';

package/dist/inference/cloud-provider.d.ts

@@ -12,7 +12,7 @@
  * User provides: api_key + provider name + optional base_url + optional model_name
  * We figure out the rest. Their key, their choice.
  */
-import type { InferenceProvider, InferenceOptions } from './types.js';
+import type { ChatMessage, ChatReply, ChatTool, InferenceProvider, InferenceOptions, InferenceUsage } from './types.js';
 export declare class CloudProvider implements InferenceProvider {
     readonly name: string;
     private client;
@@ -21,6 +21,7 @@ export declare class CloudProvider implements InferenceProvider {
     private baseUrl?;
     private modelName;
     private isClaude;
+    private spent;
     constructor(providerName: string, apiKey: string, options?: {
         baseUrl?: string;
         modelName?: string;
@@ -28,7 +29,17 @@ export declare class CloudProvider implements InferenceProvider {
     isAvailable(): Promise<boolean>;
     setup(onProgress?: (message: string) => void): Promise<void>;
     analyze(prompt: string, options?: InferenceOptions): Promise<string>;
+    /** One turn of a tool-using conversation (Anthropic tool use, or OpenAI-compatible function calling). */
+    chat(messages: ChatMessage[], tools: ChatTool[], options?: InferenceOptions): Promise<ChatReply>;
+    private chatClaude;
+    private chatOpenAICompat;
+    /** Tokens used since setup, and their cost: provider-reported where given, else list price. */
+    usage(): InferenceUsage;
+    private record;
     private analyzeClaude;
     private analyzeOpenAICompat;
+    /** OpenRouter forwards Anthropic's cache_control to Claude models. */
+    private cachesPrompts;
+    private isOpenRouter;
     dispose(): void;
 }

package/dist/inference/cloud-provider.js

@@ -1,3 +1,4 @@
+import { priceTokens } from './pricing.js';
 /** Default models per provider (user can override via model_name) */
 const DEFAULT_MODELS = {
     claude: 'claude-opus-4-6',
@@ -34,6 +35,7 @@ export class CloudProvider {
     baseUrl;
     modelName;
     isClaude;
+    spent = { inputTokens: 0, outputTokens: 0, reportedCost: 0, unreportedIn: 0, unreportedOut: 0 };
     constructor(providerName, apiKey, options) {
         if (!apiKey || apiKey.trim().length === 0) {
             throw new Error(`API key cannot be empty for provider "${providerName}"`);
@@ -89,6 +91,62 @@ export class CloudProvider {
             return this.analyzeOpenAICompat(prompt, options);
         }
     }
+    /** One turn of a tool-using conversation (Anthropic tool use, or OpenAI-compatible function calling). */
+    async chat(messages, tools, options) {
+        if (!this.client)
+            throw new Error('Provider not set up. Call setup() first.');
+        return this.isClaude ? this.chatClaude(messages, tools, options) : this.chatOpenAICompat(messages, tools, options);
+    }
+    async chatClaude(messages, tools, options) {
+        const response = await this.client.messages.create({
+            model: this.modelName,
+            max_tokens: options?.maxTokens || 4096,
+            temperature: options?.temperature ?? 0.1,
+            messages: cacheFirstPrompt(toAnthropicMessages(messages)),
+            ...(tools.length ? { tools: tools.map(t => ({ name: t.name, description: t.description, input_schema: t.parameters })) } : {}),
+            ...(tools.length && options?.toolChoice === 'none' ? { tool_choice: { type: 'none' } } : {}),
+        }, requestOptions(options));
+        this.record(response.usage?.input_tokens, response.usage?.output_tokens);
+        const blocks = response.content ?? [];
+        return {
+            text: blocks.filter(b => b.type === 'text').map(b => b.text).join('\n'),
+            toolCalls: blocks.filter(b => b.type === 'tool_use').map(b => ({ id: b.id, name: b.name, arguments: b.input ?? {} })),
+        };
+    }
+    async chatOpenAICompat(messages, tools, options) {
+        const response = await this.client.chat.completions.create({
+            model: this.modelName,
+            max_tokens: options?.maxTokens || 4096,
+            temperature: options?.temperature ?? 0.1,
+            messages: this.cachesPrompts() ? cacheFirstPrompt(toOpenAIMessages(messages)) : toOpenAIMessages(messages),
+            ...(tools.length ? { tools: tools.map(t => ({ type: 'function', function: { name: t.name, description: t.description, parameters: t.parameters } })) } : {}),
+            ...(tools.length && options?.toolChoice === 'none' ? { tool_choice: 'none' } : {}),
+            ...(this.isOpenRouter() ? { usage: { include: true } } : {}),
+        }, requestOptions(options));
+        this.record(response.usage?.prompt_tokens, response.usage?.completion_tokens, response.usage?.cost);
+        const message = response.choices[0]?.message ?? {};
+        return {
+            text: message.content ?? '',
+            toolCalls: (message.tool_calls ?? []).map((c) => ({ id: c.id, name: c.function?.name, arguments: parseArguments(c.function?.arguments) })),
+        };
+    }
+    /** Tokens used since setup, and their cost: provider-reported where given, else list price. */
+    usage() {
+        const { inputTokens, outputTokens, reportedCost, unreportedIn, unreportedOut } = this.spent;
+        const priced = unreportedIn + unreportedOut === 0 ? 0 : priceTokens(this.modelName, unreportedIn, unreportedOut);
+        return { inputTokens, outputTokens, ...(priced === undefined ? {} : { costUsd: reportedCost + priced }) };
+    }
+    record(inputTokens = 0, outputTokens = 0, reportedCost) {
+        this.spent.inputTokens += inputTokens;
+        this.spent.outputTokens += outputTokens;
+        if (typeof reportedCost === 'number') {
+            this.spent.reportedCost += reportedCost;
+        }
+        else {
+            this.spent.unreportedIn += inputTokens;
+            this.spent.unreportedOut += outputTokens;
+        }
+    }
     async analyzeClaude(prompt, options) {
         const response = await this.client.messages.create({
             model: this.modelName,
@@ -97,7 +155,8 @@ export class CloudProvider {
             messages: [
                 { role: 'user', content: prompt }
             ],
-        });
+        }, requestOptions(options));
+        this.record(response.usage?.input_tokens, response.usage?.output_tokens);
         const textBlock = response.content.find((b) => b.type === 'text');
         if (!textBlock?.text) {
             throw new Error(`Empty response from ${this.providerName} API (model: ${this.modelName}). Response had ${response.content.length} blocks but no text.`);
@@ -113,14 +172,90 @@ export class CloudProvider {
                 { role: 'user', content: prompt }
             ],
             ...(options?.jsonMode ? { response_format: { type: 'json_object' } } : {}),
-        });
+            // OpenRouter reports the call's real cost when asked; other endpoints may reject the field.
+            ...(this.isOpenRouter() ? { usage: { include: true } } : {}),
+        }, requestOptions(options));
+        this.record(response.usage?.prompt_tokens, response.usage?.completion_tokens, response.usage?.cost);
         const content = response.choices[0]?.message?.content;
         if (!content) {
             throw new Error(`Empty response from ${this.providerName} API (model: ${this.modelName}). No content in choices.`);
         }
         return content;
     }
+    /** OpenRouter forwards Anthropic's cache_control to Claude models. */
+    cachesPrompts() {
+        return this.isOpenRouter() && /(^|\/)(anthropic\/|claude)/i.test(this.modelName);
+    }
+    isOpenRouter() {
+        return /(^|\.)openrouter\.ai(\/|$)/.test((this.baseUrl || '').replace(/^https?:\/\//, ''));
+    }
     dispose() {
         this.client = null;
     }
 }
+/** The per-call timeout, honoured by both SDKs (their default is minutes, with retries). */
+function requestOptions(options) {
+    return options?.timeout ? { timeout: options.timeout } : {};
+}
+/**
+ * Mark the first prompt for caching: a tool conversation resends it every
+ * turn, and it is most of the input (the diff and the instructions).
+ */
+function cacheFirstPrompt(messages) {
+    const [first, ...rest] = messages;
+    if (!first || first.role !== 'user' || typeof first.content !== 'string')
+        return messages;
+    return [{ role: 'user', content: [{ type: 'text', text: first.content, cache_control: { type: 'ephemeral' } }] }, ...rest];
+}
+/** Anthropic wants tool results as user turns, consecutive results grouped into one. */
+function toAnthropicMessages(messages) {
+    const out = [];
+    for (const message of messages) {
+        if (message.role === 'tool') {
+            const block = { type: 'tool_result', tool_use_id: message.toolCallId, content: message.content };
+            const last = out[out.length - 1];
+            if (last?.role === 'user' && Array.isArray(last.content) && last.content[0]?.type === 'tool_result')
+                last.content.push(block);
+            else
+                out.push({ role: 'user', content: [block] });
+        }
+        else if (message.role === 'assistant') {
+            const content = message.content ? [{ type: 'text', text: message.content }] : [];
+            for (const call of message.toolCalls ?? [])
+                content.push({ type: 'tool_use', id: call.id, name: call.name, input: call.arguments });
+            out.push({ role: 'assistant', content });
+        }
+        else {
+            out.push({ role: 'user', content: message.content });
+        }
+    }
+    return out;
+}
+function toOpenAIMessages(messages) {
+    return messages.map((message) => {
+        if (message.role === 'tool')
+            return { role: 'tool', tool_call_id: message.toolCallId, content: message.content };
+        if (message.role === 'assistant') {
+            return {
+                role: 'assistant',
+                content: message.content || null,
+                ...(message.toolCalls?.length ? {
+                    tool_calls: message.toolCalls.map(c => ({ id: c.id, type: 'function', function: { name: c.name, arguments: JSON.stringify(c.arguments) } })),
+                } : {}),
+            };
+        }
+        return { role: 'user', content: message.content };
+    });
+}
+/** Function-call arguments arrive as a JSON string; a malformed one becomes no arguments. */
+function parseArguments(raw) {
+    if (typeof raw !== 'string')
+        return {};
+    try {
+        const value = JSON.parse(raw);
+        return value && typeof value === 'object' ? value : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/inference/cloud-provider.test.d.ts

@@ -0,0 +1 @@
+export {};