@oddessentials/odd-ai-reviewers 1.0.0

package/dist/agents/types.js

@@ -0,0 +1,127 @@
+/**
+ * Agent Types Module
+ *
+ * Shared types for the agent system. Extracted from agents/index.ts
+ * to break circular dependencies between agent implementations and the registry.
+ *
+ * AgentResult Discriminated Union (011-agent-result-unions):
+ * - AgentResult is a discriminated union with status: 'success' | 'failure' | 'skipped'
+ * - Use constructor helpers: AgentSuccess(), AgentFailure(), AgentSkipped()
+ * - Handle all variants with switch + assertNever in default
+ */
+import { z } from 'zod';
+// ============================================================================
+// Constructor Helpers (FR-002, FR-012)
+// Use these instead of object literals to ensure valid field combinations
+// ============================================================================
+/**
+ * Create a successful agent result.
+ */
+export function AgentSuccess(params) {
+    return { status: 'success', ...params };
+}
+/**
+ * Create a failed agent result.
+ */
+export function AgentFailure(params) {
+    return {
+        status: 'failure',
+        agentId: params.agentId,
+        error: params.error,
+        failureStage: params.failureStage,
+        partialFindings: params.partialFindings ?? [],
+        metrics: params.metrics,
+    };
+}
+/**
+ * Create a skipped agent result.
+ */
+export function AgentSkipped(params) {
+    return { status: 'skipped', ...params };
+}
+// ============================================================================
+// Type Guards (FR-001)
+// ============================================================================
+/**
+ * Type guard for success results.
+ */
+export function isSuccess(result) {
+    return result.status === 'success';
+}
+/**
+ * Type guard for failure results.
+ */
+export function isFailure(result) {
+    return result.status === 'failure';
+}
+/**
+ * Type guard for skipped results.
+ */
+export function isSkipped(result) {
+    return result.status === 'skipped';
+}
+// ============================================================================
+// Zod Serialization Schema (FR-025)
+// Required for cache round-trip safety in cache/store.ts
+// ============================================================================
+/** Zod schema for AgentMetrics */
+export const AgentMetricsSchema = z.object({
+    durationMs: z.number(),
+    filesProcessed: z.number(),
+    tokensUsed: z.number().optional(),
+    estimatedCostUsd: z.number().optional(),
+});
+/** Zod schema for Finding */
+export const FindingSchema = z.object({
+    severity: z.enum(['error', 'warning', 'info']),
+    file: z.string(),
+    line: z.number().optional(),
+    endLine: z.number().optional(),
+    message: z.string(),
+    suggestion: z.string().optional(),
+    ruleId: z.string().optional(),
+    sourceAgent: z.string(),
+    fingerprint: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    provenance: z.enum(['complete', 'partial']).optional(),
+});
+/** Zod schema for AgentResultSuccess */
+export const AgentResultSuccessSchema = z.object({
+    status: z.literal('success'),
+    agentId: z.string(),
+    findings: z.array(FindingSchema),
+    metrics: AgentMetricsSchema,
+});
+/** Zod schema for AgentResultFailure */
+export const AgentResultFailureSchema = z.object({
+    status: z.literal('failure'),
+    agentId: z.string(),
+    error: z.string(),
+    failureStage: z.enum(['preflight', 'exec', 'postprocess']),
+    partialFindings: z.array(FindingSchema),
+    metrics: AgentMetricsSchema,
+});
+/** Zod schema for AgentResultSkipped */
+export const AgentResultSkippedSchema = z.object({
+    status: z.literal('skipped'),
+    agentId: z.string(),
+    reason: z.string(),
+    metrics: AgentMetricsSchema,
+});
+/** Discriminated union schema - validates exact shape */
+export const AgentResultSchema = z.discriminatedUnion('status', [
+    AgentResultSuccessSchema,
+    AgentResultFailureSchema,
+    AgentResultSkippedSchema,
+]);
+/**
+ * Cache schema version - bump when AgentResultSchema changes shape.
+ * Included in cache keys to invalidate legacy entries.
+ * (012-fix-agent-result-regressions, FR-005)
+ *
+ * History:
+ * - v1: Original format (success: boolean, no status field) - DEPRECATED
+ * - v2: Discriminated union (status: 'success'|'failure'|'skipped')
+ */
+export const CACHE_SCHEMA_VERSION = 2;
+//# sourceMappingURL=types.js.map

package/dist/agents/types.js.map

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

package/dist/budget.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Budget Module
+ * Enforces per-PR and monthly cost limits
+ */
+import type { Limits } from './config.js';
+export interface BudgetContext {
+    /** Number of files changed in the PR */
+    fileCount: number;
+    /** Total lines changed (additions + deletions) */
+    diffLines: number;
+    /** Estimated tokens for LLM input */
+    estimatedTokens: number;
+}
+export interface BudgetCheck {
+    allowed: boolean;
+    reason?: string;
+    /** Suggested reduced scope if over budget */
+    reducedScope?: {
+        maxFiles?: number;
+        maxLines?: number;
+    };
+}
+export interface CostEstimate {
+    /** Estimated USD cost for LLM calls */
+    estimatedUsd: number;
+    /** Breakdown by agent */
+    breakdown: Record<string, number>;
+}
+/**
+ * Pricing constants for GPT-4o-mini model
+ * These MUST stay in sync with the hardcoded values in agents (pr_agent.ts, ai_semantic_review.ts)
+ * See test: "should use consistent pricing with budget module" in budget.test.ts
+ */
+export declare const COST_PER_1K_TOKENS_INPUT = 0.00015;
+export declare const COST_PER_1K_TOKENS_OUTPUT = 0.0006;
+export declare const ESTIMATED_OUTPUT_RATIO = 0.2;
+/**
+ * Check if the PR is within budget limits
+ */
+export declare function checkBudget(context: BudgetContext, limits: Limits): BudgetCheck;
+/**
+ * Estimate cost based on token count
+ */
+export declare function estimateCost(tokens: number): CostEstimate;
+/**
+ * Estimate token count from diff content
+ * Rough approximation: 1 token ≈ 4 characters
+ */
+export declare function estimateTokens(diffContent: string): number;
+/**
+ * Track monthly spending (stub - would use persistent storage in production)
+ */
+export interface MonthlyUsage {
+    month: string;
+    totalUsd: number;
+    prCount: number;
+}
+export declare function checkMonthlyBudget(currentUsage: MonthlyUsage, estimatedCost: number, monthlyLimit: number): BudgetCheck;
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,YAAY,CAAC,EAAE;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAChD,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAChD,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAqC/E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAYzD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,YAAY,EAC1B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,WAAW,CAWb"}

package/dist/budget.js

@@ -0,0 +1,82 @@
+/**
+ * Budget Module
+ * Enforces per-PR and monthly cost limits
+ */
+/**
+ * Pricing constants for GPT-4o-mini model
+ * These MUST stay in sync with the hardcoded values in agents (pr_agent.ts, ai_semantic_review.ts)
+ * See test: "should use consistent pricing with budget module" in budget.test.ts
+ */
+export const COST_PER_1K_TOKENS_INPUT = 0.00015;
+export const COST_PER_1K_TOKENS_OUTPUT = 0.0006;
+export const ESTIMATED_OUTPUT_RATIO = 0.2; // Output is typically 20% of input
+/**
+ * Check if the PR is within budget limits
+ */
+export function checkBudget(context, limits) {
+    // Check file count limit
+    if (context.fileCount > limits.max_files) {
+        return {
+            allowed: false,
+            reason: `PR has ${context.fileCount} files, exceeds limit of ${limits.max_files}`,
+            reducedScope: { maxFiles: limits.max_files },
+        };
+    }
+    // Check diff lines limit
+    if (context.diffLines > limits.max_diff_lines) {
+        return {
+            allowed: false,
+            reason: `PR has ${context.diffLines} changed lines, exceeds limit of ${limits.max_diff_lines}`,
+            reducedScope: { maxLines: limits.max_diff_lines },
+        };
+    }
+    // Check token limit
+    if (context.estimatedTokens > limits.max_tokens_per_pr) {
+        return {
+            allowed: false,
+            reason: `Estimated ${context.estimatedTokens} tokens, exceeds limit of ${limits.max_tokens_per_pr}`,
+        };
+    }
+    // Check estimated cost
+    const estimate = estimateCost(context.estimatedTokens);
+    if (estimate.estimatedUsd > limits.max_usd_per_pr) {
+        return {
+            allowed: false,
+            reason: `Estimated cost $${estimate.estimatedUsd.toFixed(2)} exceeds limit of $${limits.max_usd_per_pr.toFixed(2)}`,
+        };
+    }
+    return { allowed: true };
+}
+/**
+ * Estimate cost based on token count
+ */
+export function estimateCost(tokens) {
+    const inputCost = (tokens / 1000) * COST_PER_1K_TOKENS_INPUT;
+    const outputTokens = tokens * ESTIMATED_OUTPUT_RATIO;
+    const outputCost = (outputTokens / 1000) * COST_PER_1K_TOKENS_OUTPUT;
+    return {
+        estimatedUsd: inputCost + outputCost,
+        breakdown: {
+            input: inputCost,
+            output: outputCost,
+        },
+    };
+}
+/**
+ * Estimate token count from diff content
+ * Rough approximation: 1 token ≈ 4 characters
+ */
+export function estimateTokens(diffContent) {
+    return Math.ceil(diffContent.length / 4);
+}
+export function checkMonthlyBudget(currentUsage, estimatedCost, monthlyLimit) {
+    const projectedTotal = currentUsage.totalUsd + estimatedCost;
+    if (projectedTotal > monthlyLimit) {
+        return {
+            allowed: false,
+            reason: `Monthly budget exhausted. Current: $${currentUsage.totalUsd.toFixed(2)}, Limit: $${monthlyLimit.toFixed(2)}`,
+        };
+    }
+    return { allowed: true };
+}
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

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

package/dist/cache/key.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Cache Key Module
+ * Generates deterministic cache keys for review results
+ *
+ * (012-fix-agent-result-regressions) - Cache keys now include CACHE_SCHEMA_VERSION
+ * to automatically invalidate legacy cache entries when schema changes.
+ */
+/** Cache key prefix for namespacing (includes version for automatic invalidation) */
+export declare const CACHE_KEY_PREFIX = "ai-review-v2";
+/** Default cache directory path */
+export declare const AI_REVIEW_CACHE_PATH = ".ai-review-cache";
+export interface CacheKeyInputs {
+    prNumber: number;
+    headSha: string;
+    configHash: string;
+    agentId: string;
+}
+/**
+ * Generate a cache key for a review run
+ * Format: ai-review-{prNumber}-{headSha}-{configHash}-{agentId}
+ */
+export declare function generateCacheKey(inputs: CacheKeyInputs): string;
+/**
+ * Generate a restore key prefix for partial cache matches
+ * This allows fallback to older cached results for the same PR
+ */
+export declare function generateRestoreKeyPrefix(prNumber: number): string;
+/**
+ * Generate a hash of the configuration
+ * Used for cache invalidation when config changes
+ */
+export declare function hashConfig(config: unknown): string;
+/**
+ * Generate a hash of file contents for cache invalidation
+ */
+export declare function hashContent(content: string): string;
+/**
+ * Parse a cache key to extract components
+ *
+ * (012-fix-agent-result-regressions) - Updated to handle versioned key format
+ * Supports both legacy format (ai-review-{prNumber}-{hash}) and new format
+ * (ai-review-v{version}-{prNumber}-{hash}) for backwards compatibility in parsing.
+ */
+export declare function parseCacheKey(key: string): {
+    prNumber: number;
+    hash: string;
+    version?: number;
+} | null;
+//# sourceMappingURL=key.d.ts.map

package/dist/cache/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../src/cache/key.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,qFAAqF;AACrF,eAAO,MAAM,gBAAgB,iBAAuC,CAAC;AAErE,mCAAmC;AACnC,eAAO,MAAM,oBAAoB,qBAAqB,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAI/D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAGlD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,GACV;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAqB7D"}

package/dist/cache/key.js

@@ -0,0 +1,71 @@
+/**
+ * Cache Key Module
+ * Generates deterministic cache keys for review results
+ *
+ * (012-fix-agent-result-regressions) - Cache keys now include CACHE_SCHEMA_VERSION
+ * to automatically invalidate legacy cache entries when schema changes.
+ */
+import { createHash } from 'crypto';
+import { CACHE_SCHEMA_VERSION } from '../agents/types.js';
+/** Cache key prefix for namespacing (includes version for automatic invalidation) */
+export const CACHE_KEY_PREFIX = `ai-review-v${CACHE_SCHEMA_VERSION}`;
+/** Default cache directory path */
+export const AI_REVIEW_CACHE_PATH = '.ai-review-cache';
+/**
+ * Generate a cache key for a review run
+ * Format: ai-review-{prNumber}-{headSha}-{configHash}-{agentId}
+ */
+export function generateCacheKey(inputs) {
+    const data = `${inputs.prNumber}:${inputs.headSha}:${inputs.configHash}:${inputs.agentId}`;
+    const hash = createHash('sha256').update(data).digest('hex').slice(0, 16);
+    return `${CACHE_KEY_PREFIX}-${inputs.prNumber}-${hash}`;
+}
+/**
+ * Generate a restore key prefix for partial cache matches
+ * This allows fallback to older cached results for the same PR
+ */
+export function generateRestoreKeyPrefix(prNumber) {
+    return `${CACHE_KEY_PREFIX}-${prNumber}-`;
+}
+/**
+ * Generate a hash of the configuration
+ * Used for cache invalidation when config changes
+ */
+export function hashConfig(config) {
+    const json = JSON.stringify(config, Object.keys(config).sort());
+    return createHash('sha256').update(json).digest('hex').slice(0, 16);
+}
+/**
+ * Generate a hash of file contents for cache invalidation
+ */
+export function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+/**
+ * Parse a cache key to extract components
+ *
+ * (012-fix-agent-result-regressions) - Updated to handle versioned key format
+ * Supports both legacy format (ai-review-{prNumber}-{hash}) and new format
+ * (ai-review-v{version}-{prNumber}-{hash}) for backwards compatibility in parsing.
+ */
+export function parseCacheKey(key) {
+    // Try new versioned format first
+    const versionedMatch = key.match(/^ai-review-v(\d+)-(\d+)-([a-f0-9]+)$/);
+    if (versionedMatch && versionedMatch[1] && versionedMatch[2] && versionedMatch[3]) {
+        return {
+            version: parseInt(versionedMatch[1], 10),
+            prNumber: parseInt(versionedMatch[2], 10),
+            hash: versionedMatch[3],
+        };
+    }
+    // Fall back to legacy format (for parsing only - new keys always use versioned format)
+    const legacyMatch = key.match(/^ai-review-(\d+)-([a-f0-9]+)$/);
+    if (legacyMatch && legacyMatch[1] && legacyMatch[2]) {
+        return {
+            prNumber: parseInt(legacyMatch[1], 10),
+            hash: legacyMatch[2],
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=key.js.map

package/dist/cache/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../../src/cache/key.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,qFAAqF;AACrF,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,oBAAoB,EAAE,CAAC;AAErE,mCAAmC;AACnC,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AASvD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAsB;IACrD,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;IAC3F,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1E,OAAO,GAAG,gBAAgB,IAAI,MAAM,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAgB;IACvD,OAAO,GAAG,gBAAgB,IAAI,QAAQ,GAAG,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAgB,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAW;IAEX,iCAAiC;IACjC,MAAM,cAAc,GAAG,GAAG,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACzE,IAAI,cAAc,IAAI,cAAc,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,OAAO;YACL,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACxC,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACzC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;SACxB,CAAC;IACJ,CAAC;IAED,uFAAuF;IACvF,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IAC/D,IAAI,WAAW,IAAI,WAAW,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,OAAO;YACL,QAAQ,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;SACrB,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cache/store.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Cache Store Module
+ * Stores and retrieves cached review results
+ * Uses GitHub Actions cache in CI, file-based cache locally
+ */
+import type { AgentResult } from '../agents/index.js';
+export interface CacheEntry {
+    key: string;
+    result: AgentResult;
+    createdAt: string;
+    expiresAt: string;
+}
+/**
+ * Get a cached result
+ */
+export declare function getCached(key: string): Promise<AgentResult | null>;
+/**
+ * Store a result in the cache
+ */
+export declare function setCache(key: string, result: AgentResult, ttlSeconds?: number): Promise<void>;
+/**
+ * Clear the cache
+ */
+export declare function clearCache(): Promise<void>;
+/**
+ * Clean up expired cache entries
+ */
+export declare function cleanupExpired(): Promise<number>;
+/**
+ * Find cached result for a PR (even with different SHA)
+ * Used for fallback when exact cache miss
+ *
+ * (012-fix-agent-result-regressions) - Now validates results through validateCachedResult()
+ * to ensure legacy/malformed entries are treated as cache misses.
+ */
+export declare function findCachedForPR(prNumber: number): Promise<AgentResult | null>;
+/**
+ * Save cache for GitHub Actions
+ * Call this at the end of a CI run to persist cache
+ */
+export declare function saveGitHubActionsCache(key: string): Promise<boolean>;
+/**
+ * Restore cache from GitHub Actions
+ * Call this at the start of a CI run
+ */
+export declare function restoreGitHubActionsCache(primaryKey: string, restoreKeys: string[]): Promise<string | undefined>;
+//# sourceMappingURL=store.d.ts.map

package/dist/cache/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/cache/store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKtD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AA8GD;;GAEG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAkDxE;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,EACnB,UAAU,SAAsB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED;;GAEG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAiBhD;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAoCtD;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAqCnF;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAiB1E;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAkB7B"}