groundswell 0.0.2 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Groundswell Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,7 +8,7 @@ Hierarchical workflow orchestration engine with full observability.
 npm install groundswell
 ```
 
-**Requirements:** Node.js 18+, TypeScript 5.2+
+**Requirements:** Node.js 20+, TypeScript 5.2+
 
 ## Quick Start
 
@@ -61,30 +61,41 @@ const result = await workflow.run();
 
 ### Agent with Prompt
 
+> [!IMPORTANT]
+> Groundswell v2.0: `agent.prompt()` now returns `AgentResponse<T>`.
+> See the [Migration Guide](docs/migration-guide-agent-response.md) if upgrading.
+
 ```typescript
 import { createAgent, createPrompt } from 'groundswell';
 import { z } from 'zod';
 
-const agent = createAgent({
-  name: 'AnalysisAgent',
-  enableCache: true,
-});
+const agent = createAgent({ name: 'AnalysisAgent' });
 
 const prompt = createPrompt({
-  user: 'Analyze this code for bugs',
-  data: { code: 'function foo() { return 42; }' },
+  user: 'Analyze this code',
   responseFormat: z.object({
     bugs: z.array(z.string()),
     severity: z.enum(['low', 'medium', 'high']),
   }),
 });
 
-const result = await agent.prompt(prompt);
-// result is typed as { bugs: string[], severity: 'low' | 'medium' | 'high' }
+const response = await agent.prompt(prompt);
+if (response.status === 'error') {
+  throw new Error(response.error.message);
+}
+console.log(response.data.bugs);
 ```
 
+**Why AgentResponse?**
+- Type-safe validated responses with error handling
+- Observable metadata (tokens, timing, cache hits)
+- Consistent API across all agent operations
+
 ## Documentation
 
+- [Migration Guide](docs/migration-guide-agent-response.md) - Upgrading from v1.x ⚠️
+- [Harnesses](docs/harnesses.md) - Pluggable agent runtime (pi default, claude-code optional)
+- [Provider → Harness Migration](docs/migration-provider-to-harness.md) - v1.2 vocabulary migration
 - [Workflows](docs/workflow.md) - Hierarchical task orchestration
 - [Agents](docs/agent.md) - LLM execution with caching and reflection
 - [Prompts](docs/prompt.md) - Type-safe prompt definitions with Zod
@@ -301,6 +312,12 @@ See [examples/](examples/) for source code.
 
 Contributions and issues are welcome.
 
+### Releasing
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please). When `feat:` / `fix:` / `BREAKING CHANGE` commits land on `main`, release-please opens a release PR that bumps the version, updates `CHANGELOG.md`, and tags a release. Merging that PR publishes to npm.
+
+One-time setup: add an **`NPM_TOKEN`** secret to the repository (an npm *automation* access token, or a granular access token with publish permission).
+
 ## Support
 
 If Groundswell helps you build something great, consider fueling future development:

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

@@ -0,0 +1,86 @@
+/**
+ * Cache Key Generation - Deterministic key generation for LLM response caching
+ *
+ * Uses SHA-256 hashing with deterministic JSON serialization to ensure
+ * identical inputs always produce identical cache keys.
+ */
+import type { Tool, MCPServer, Skill } from '../types/index.js';
+import type { HarnessId, ModelProviderId } from '../types/harnesses.js';
+import type { z } from 'zod';
+/**
+ * Inputs used to generate a cache key
+ */
+export interface CacheKeyInputs {
+    /** User message content */
+    user: string;
+    /** Data passed to the prompt */
+    data?: Record<string, unknown>;
+    /** System prompt */
+    system?: string;
+    /** Model identifier */
+    model: string;
+    /**
+     * Agent runtime identifier (PRD §7.2 / §7.14.5 cache isolation).
+     *
+     * Optional during the harness migration window: the Agent cache build-site (P3.M1.T2.S3)
+     * does not yet pass it, so omitting it preserves the pre-task key. Once P3.M1.T2.S3 rewires
+     * `agent.ts` to always pass the resolved harness, this field may be tightened to required.
+     * When provided, it becomes a component of the SHA-256 cache key so `pi` and `claude-code`
+     * runs never share cache entries.
+     */
+    harness?: HarnessId;
+    /**
+     * LLM host / model provider (PRD §7.8 / §7.14.5 cache isolation).
+     *
+     * The LLM-vendor axis (NOT the harness) — e.g. 'anthropic', 'openai', 'google', 'zai', or
+     * any open-set provider string. Optional; resolved from the ModelSpec. When provided, it
+     * becomes a component of the SHA-256 cache key so provider-qualified models with colliding
+     * bare ids get distinct entries.
+     */
+    provider?: ModelProviderId;
+    /** Temperature setting */
+    temperature?: number;
+    /** Maximum tokens */
+    maxTokens?: number;
+    /** Tools available to the agent */
+    tools?: Tool[];
+    /** MCP servers */
+    mcps?: MCPServer[];
+    /** Skills */
+    skills?: Skill[];
+    /** Zod response format schema */
+    responseFormat?: z.ZodType;
+}
+/**
+ * Deterministically stringify a value with sorted object keys
+ *
+ * Unlike JSON.stringify, this function guarantees consistent output
+ * regardless of key insertion order by sorting all object keys.
+ *
+ * @param value - Value to stringify
+ * @returns Deterministic JSON string
+ * @throws TypeError if circular reference detected
+ */
+export declare function deterministicStringify(value: unknown): string;
+/**
+ * Generate a hash from a Zod schema's internal definition
+ *
+ * Zod schemas are functions that cannot be directly serialized.
+ * This extracts the schema's _def property which contains the
+ * schema structure and hashes it.
+ *
+ * @param schema - Zod schema to hash
+ * @returns SHA-256 hex digest of the schema definition
+ */
+export declare function getSchemaHash(schema: z.ZodType | undefined): string;
+/**
+ * Generate a deterministic cache key from prompt execution inputs
+ *
+ * The key is a 64-character SHA-256 hex digest that uniquely identifies
+ * a specific combination of prompt, data, configuration, and tools.
+ *
+ * @param inputs - Cache key inputs
+ * @returns 64-character hex SHA-256 digest
+ */
+export declare function generateCacheKey(inputs: CacheKeyInputs): string;
+//# sourceMappingURL=cache-key.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key.d.ts","sourceRoot":"","sources":["../../src/cache/cache-key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,oBAAoB;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,0BAA0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,kBAAkB;IAClB,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC;IACnB,aAAa;IACb,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,iCAAiC;IACjC,cAAc,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA2D7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,MAAM,CAqBnE;AAoDD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAqD/D"}

package/dist/cache/cache-key.js

@@ -0,0 +1,204 @@
+/**
+ * Cache Key Generation - Deterministic key generation for LLM response caching
+ *
+ * Uses SHA-256 hashing with deterministic JSON serialization to ensure
+ * identical inputs always produce identical cache keys.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Deterministically stringify a value with sorted object keys
+ *
+ * Unlike JSON.stringify, this function guarantees consistent output
+ * regardless of key insertion order by sorting all object keys.
+ *
+ * @param value - Value to stringify
+ * @returns Deterministic JSON string
+ * @throws TypeError if circular reference detected
+ */
+export function deterministicStringify(value) {
+    const seen = new WeakSet();
+    function stringify(val) {
+        if (val === null)
+            return 'null';
+        if (val === undefined)
+            return 'undefined';
+        if (typeof val === 'string')
+            return JSON.stringify(val);
+        if (typeof val === 'number') {
+            if (Number.isNaN(val))
+                return 'NaN';
+            if (!Number.isFinite(val))
+                return val > 0 ? 'Infinity' : '-Infinity';
+            return String(val);
+        }
+        if (typeof val === 'boolean')
+            return String(val);
+        if (typeof val === 'function')
+            return 'function';
+        if (typeof val === 'symbol')
+            return 'symbol';
+        if (typeof val === 'bigint')
+            return `${val}n`;
+        if (typeof val === 'object') {
+            if (seen.has(val)) {
+                throw new TypeError('Converting circular structure to JSON');
+            }
+            seen.add(val);
+            let result;
+            if (Array.isArray(val)) {
+                result = '[' + val.map(stringify).join(',') + ']';
+            }
+            else if (val instanceof Date) {
+                result = JSON.stringify(val.toISOString());
+            }
+            else if (val instanceof Map) {
+                const entries = Array.from(val.entries())
+                    .sort(([a], [b]) => String(a).localeCompare(String(b)))
+                    .map(([k, v]) => `[${stringify(k)},${stringify(v)}]`);
+                result = `Map{${entries.join(',')}}`;
+            }
+            else if (val instanceof Set) {
+                const values = Array.from(val)
+                    .map(stringify)
+                    .sort();
+                result = `Set{${values.join(',')}}`;
+            }
+            else {
+                // Regular object - sort keys
+                const keys = Object.keys(val).sort();
+                const pairs = keys.map((k) => JSON.stringify(k) +
+                    ':' +
+                    stringify(val[k]));
+                result = '{' + pairs.join(',') + '}';
+            }
+            seen.delete(val);
+            return result;
+        }
+        return String(val);
+    }
+    return stringify(value);
+}
+/**
+ * Generate a hash from a Zod schema's internal definition
+ *
+ * Zod schemas are functions that cannot be directly serialized.
+ * This extracts the schema's _def property which contains the
+ * schema structure and hashes it.
+ *
+ * @param schema - Zod schema to hash
+ * @returns SHA-256 hex digest of the schema definition
+ */
+export function getSchemaHash(schema) {
+    if (!schema) {
+        return 'no-schema';
+    }
+    try {
+        // Access Zod's internal _def property
+        const def = schema._def;
+        if (!def) {
+            return 'unknown-schema';
+        }
+        // Create a simplified representation of the schema
+        const schemaRep = extractSchemaStructure(def);
+        const serialized = deterministicStringify(schemaRep);
+        return createHash('sha256').update(serialized, 'utf8').digest('hex');
+    }
+    catch {
+        // Fallback for schemas that can't be introspected
+        return 'fallback-schema';
+    }
+}
+/**
+ * Extract a serializable structure from a Zod schema definition
+ */
+function extractSchemaStructure(def) {
+    if (def === null || def === undefined) {
+        return def;
+    }
+    if (typeof def !== 'object') {
+        return def;
+    }
+    const typedDef = def;
+    const result = {};
+    // Extract key properties that define schema structure
+    if ('typeName' in typedDef) {
+        result.typeName = typedDef.typeName;
+    }
+    if ('shape' in typedDef && typeof typedDef.shape === 'function') {
+        // Object schema - extract shape
+        try {
+            const shape = typedDef.shape();
+            result.shape = Object.fromEntries(Object.entries(shape).map(([key, value]) => [
+                key,
+                extractSchemaStructure(value?._def),
+            ]));
+        }
+        catch {
+            result.shape = 'complex-shape';
+        }
+    }
+    if ('type' in typedDef && typedDef.type && typeof typedDef.type === 'object') {
+        result.type = extractSchemaStructure(typedDef.type._def);
+    }
+    if ('values' in typedDef) {
+        result.values = typedDef.values;
+    }
+    if ('checks' in typedDef && Array.isArray(typedDef.checks)) {
+        result.checks = typedDef.checks.map((check) => check.kind);
+    }
+    return result;
+}
+/**
+ * Generate a deterministic cache key from prompt execution inputs
+ *
+ * The key is a 64-character SHA-256 hex digest that uniquely identifies
+ * a specific combination of prompt, data, configuration, and tools.
+ *
+ * @param inputs - Cache key inputs
+ * @returns 64-character hex SHA-256 digest
+ */
+export function generateCacheKey(inputs) {
+    // Build normalized representation with sorted arrays
+    const normalized = {
+        user: inputs.user,
+        model: inputs.model,
+    };
+    // PRD §7.14.5: incorporate the harness + provider axes for cross-harness/provider isolation.
+    // Conditional append (matches the optional-field pattern below) — omitting them yields the
+    // exact pre-task key, so the Agent build-site stays green until P3.M1.T2.S3 rewires it.
+    if (inputs.harness !== undefined) {
+        normalized.harness = inputs.harness;
+    }
+    if (inputs.provider !== undefined) {
+        normalized.provider = inputs.provider;
+    }
+    // Include optional fields only if defined
+    if (inputs.data !== undefined) {
+        normalized.data = inputs.data;
+    }
+    if (inputs.system !== undefined) {
+        normalized.system = inputs.system;
+    }
+    if (inputs.temperature !== undefined) {
+        normalized.temperature = inputs.temperature;
+    }
+    if (inputs.maxTokens !== undefined) {
+        normalized.maxTokens = inputs.maxTokens;
+    }
+    // Sort tool/mcp/skill names for determinism
+    if (inputs.tools && inputs.tools.length > 0) {
+        normalized.tools = inputs.tools.map((t) => t.name).sort();
+    }
+    if (inputs.mcps && inputs.mcps.length > 0) {
+        normalized.mcps = inputs.mcps.map((m) => m.name).sort();
+    }
+    if (inputs.skills && inputs.skills.length > 0) {
+        normalized.skills = inputs.skills.map((s) => s.name).sort();
+    }
+    // Include schema hash
+    normalized.schemaHash = getSchemaHash(inputs.responseFormat);
+    // Generate SHA-256 hash
+    const serialized = deterministicStringify(normalized);
+    return createHash('sha256').update(serialized, 'utf8').digest('hex');
+}
+//# sourceMappingURL=cache-key.js.map

package/dist/cache/cache-key.js.map

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

package/dist/cache/cache.d.ts

@@ -0,0 +1,104 @@
+/**
+ * LLMCache - LRU cache for LLM responses with size and TTL limits
+ *
+ * Wraps the lru-cache package to provide:
+ * - Item count limits
+ * - Memory size limits
+ * - Time-based expiration (TTL)
+ * - Prefix-based cache busting for related entries
+ */
+/**
+ * Cache configuration options
+ */
+export interface CacheConfig {
+    /** Maximum number of items in cache (default: 1000) */
+    maxItems?: number;
+    /** Maximum cache size in bytes (default: 50MB) */
+    maxSizeBytes?: number;
+    /** Default TTL in milliseconds (default: 1 hour) */
+    defaultTTLMs?: number;
+}
+/**
+ * Cache performance metrics
+ */
+export interface CacheMetrics {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Current number of items in cache */
+    size: number;
+    /** Current cache size in bytes (estimated) */
+    sizeBytes: number;
+    /** Hit rate percentage */
+    hitRate: number;
+}
+/**
+ * LLMCache - High-performance LRU cache for LLM responses
+ */
+export declare class LLMCache<T = unknown> {
+    private readonly cache;
+    private readonly prefixIndex;
+    private readonly config;
+    private hitCount;
+    private missCount;
+    /**
+     * Create a new LLMCache instance
+     * @param config Cache configuration
+     */
+    constructor(config?: CacheConfig);
+    /**
+     * Get a value from the cache
+     * @param key Cache key
+     * @returns Cached value or undefined if not found
+     */
+    get(key: string): Promise<T | undefined>;
+    /**
+     * Set a value in the cache
+     * @param key Cache key
+     * @param value Value to cache
+     * @param options Optional TTL override and prefix for grouping
+     */
+    set(key: string, value: T, options?: {
+        ttl?: number;
+        prefix?: string;
+    }): Promise<void>;
+    /**
+     * Check if a key exists in the cache (without affecting LRU order)
+     * @param key Cache key
+     * @returns True if key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Remove a specific key from the cache
+     * @param key Cache key to remove
+     */
+    bust(key: string): Promise<void>;
+    /**
+     * Remove all keys with a given prefix
+     * @param prefix Prefix to match
+     */
+    bustPrefix(prefix: string): Promise<void>;
+    /**
+     * Clear the entire cache
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache performance metrics
+     * @returns Current cache metrics
+     */
+    metrics(): CacheMetrics;
+    /**
+     * Get the number of items in the cache
+     */
+    get size(): number;
+    /**
+     * Get all keys in the cache
+     */
+    keys(): IterableIterator<string>;
+}
+/**
+ * Default singleton cache instance
+ */
+export declare const defaultCache: LLMCache<unknown>;
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAUD;;GAEG;AACH,qBAAa,QAAQ,CAAC,CAAC,GAAG,OAAO;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAE/C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,SAAS,CAAK;IAEtB;;;OAGG;gBACS,MAAM,GAAE,WAAgB;IAuCpC;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAU9C;;;;;OAKG;IACG,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1C,OAAO,CAAC,IAAI,CAAC;IAwBhB;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;;OAGG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IActC;;;OAGG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;;OAGG;IACH,OAAO,IAAI,YAAY;IAWvB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;CAGjC;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,mBAAiB,CAAC"}

package/dist/cache/cache.js

@@ -0,0 +1,179 @@
+/**
+ * LLMCache - LRU cache for LLM responses with size and TTL limits
+ *
+ * Wraps the lru-cache package to provide:
+ * - Item count limits
+ * - Memory size limits
+ * - Time-based expiration (TTL)
+ * - Prefix-based cache busting for related entries
+ */
+import { LRUCache } from 'lru-cache';
+/**
+ * LLMCache - High-performance LRU cache for LLM responses
+ */
+export class LLMCache {
+    cache;
+    prefixIndex;
+    config;
+    hitCount = 0;
+    missCount = 0;
+    /**
+     * Create a new LLMCache instance
+     * @param config Cache configuration
+     */
+    constructor(config = {}) {
+        this.config = {
+            maxItems: config.maxItems ?? 1000,
+            maxSizeBytes: config.maxSizeBytes ?? 52_428_800, // 50MB
+            defaultTTLMs: config.defaultTTLMs ?? 3_600_000, // 1 hour
+        };
+        this.prefixIndex = new Map();
+        this.cache = new LRUCache({
+            max: this.config.maxItems,
+            maxSize: this.config.maxSizeBytes,
+            sizeCalculation: (entry) => {
+                // Estimate size based on JSON serialization
+                try {
+                    return JSON.stringify(entry.value).length;
+                }
+                catch {
+                    // Fallback for non-serializable values
+                    return 1000;
+                }
+            },
+            ttl: this.config.defaultTTLMs,
+            updateAgeOnGet: true,
+            allowStale: false,
+            dispose: (entry, key) => {
+                // Clean up prefix index on eviction
+                if (entry.prefix) {
+                    const keys = this.prefixIndex.get(entry.prefix);
+                    if (keys) {
+                        keys.delete(key);
+                        if (keys.size === 0) {
+                            this.prefixIndex.delete(entry.prefix);
+                        }
+                    }
+                }
+            },
+        });
+    }
+    /**
+     * Get a value from the cache
+     * @param key Cache key
+     * @returns Cached value or undefined if not found
+     */
+    async get(key) {
+        const entry = this.cache.get(key);
+        if (entry) {
+            this.hitCount++;
+            return entry.value;
+        }
+        this.missCount++;
+        return undefined;
+    }
+    /**
+     * Set a value in the cache
+     * @param key Cache key
+     * @param value Value to cache
+     * @param options Optional TTL override and prefix for grouping
+     */
+    async set(key, value, options) {
+        const entry = {
+            value,
+            prefix: options?.prefix,
+        };
+        const cacheOptions = {};
+        if (options?.ttl !== undefined) {
+            cacheOptions.ttl = options.ttl;
+        }
+        this.cache.set(key, entry, cacheOptions);
+        // Track prefix for bulk invalidation
+        if (options?.prefix) {
+            let keys = this.prefixIndex.get(options.prefix);
+            if (!keys) {
+                keys = new Set();
+                this.prefixIndex.set(options.prefix, keys);
+            }
+            keys.add(key);
+        }
+    }
+    /**
+     * Check if a key exists in the cache (without affecting LRU order)
+     * @param key Cache key
+     * @returns True if key exists
+     */
+    has(key) {
+        return this.cache.has(key);
+    }
+    /**
+     * Remove a specific key from the cache
+     * @param key Cache key to remove
+     */
+    async bust(key) {
+        const entry = this.cache.peek(key);
+        if (entry?.prefix) {
+            const keys = this.prefixIndex.get(entry.prefix);
+            if (keys) {
+                keys.delete(key);
+                if (keys.size === 0) {
+                    this.prefixIndex.delete(entry.prefix);
+                }
+            }
+        }
+        this.cache.delete(key);
+    }
+    /**
+     * Remove all keys with a given prefix
+     * @param prefix Prefix to match
+     */
+    async bustPrefix(prefix) {
+        const keys = this.prefixIndex.get(prefix);
+        if (keys) {
+            for (const key of keys) {
+                this.cache.delete(key);
+            }
+            this.prefixIndex.delete(prefix);
+        }
+    }
+    /**
+     * Clear the entire cache
+     */
+    async clear() {
+        this.cache.clear();
+        this.prefixIndex.clear();
+        this.hitCount = 0;
+        this.missCount = 0;
+    }
+    /**
+     * Get cache performance metrics
+     * @returns Current cache metrics
+     */
+    metrics() {
+        const total = this.hitCount + this.missCount;
+        return {
+            hits: this.hitCount,
+            misses: this.missCount,
+            size: this.cache.size,
+            sizeBytes: this.cache.calculatedSize ?? 0,
+            hitRate: total > 0 ? (this.hitCount / total) * 100 : 0,
+        };
+    }
+    /**
+     * Get the number of items in the cache
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Get all keys in the cache
+     */
+    keys() {
+        return this.cache.keys();
+    }
+}
+/**
+ * Default singleton cache instance
+ */
+export const defaultCache = new LLMCache();
+//# sourceMappingURL=cache.js.map