@runcore-sh/runcore 0.1.2

package/dist/browser/sessions.js

@@ -0,0 +1,121 @@
+/**
+ * Browser session manager — persist and reuse Playwright storageState per domain.
+ *
+ * Sessions are stored as AES-256-GCM encrypted JSON in brain/browser/sessions/.
+ * Each session is keyed by domain with a 7-day expiry.
+ */
+import { readFile, writeFile, readdir, unlink, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { createLogger } from "../utils/logger.js";
+import { getEncryptionKey } from "../lib/key-store.js";
+const log = createLogger("browser-sessions");
+const SESSIONS_DIR = join(process.cwd(), "brain", "browser", "sessions");
+const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+// ── Crypto helpers ───────────────────────────────────────────────────────────
+function deriveSessionKey() {
+    const masterKey = getEncryptionKey();
+    if (!masterKey)
+        throw new Error("No encryption key available — not authenticated");
+    // Use first 32 bytes of the master key (AES-256)
+    return masterKey.subarray(0, 32);
+}
+function encrypt(plaintext) {
+    const key = deriveSessionKey();
+    const iv = randomBytes(16);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, "utf-8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return { iv: iv.toString("hex"), tag: tag.toString("hex"), data: encrypted.toString("hex") };
+}
+function decrypt(iv, tag, data) {
+    const key = deriveSessionKey();
+    const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(iv, "hex"));
+    decipher.setAuthTag(Buffer.from(tag, "hex"));
+    return decipher.update(data, "hex", "utf-8") + decipher.final("utf-8");
+}
+// ── File helpers ─────────────────────────────────────────────────────────────
+function sessionPath(domain) {
+    // Sanitize domain for filesystem: replace dots/colons with underscores
+    const safe = domain.replace(/[^a-zA-Z0-9-]/g, "_");
+    return join(SESSIONS_DIR, `${safe}.session.json`);
+}
+async function ensureDir() {
+    await mkdir(SESSIONS_DIR, { recursive: true });
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Save a Playwright storageState (cookies, localStorage, etc.) for a domain.
+ */
+export async function saveSession(domain, storageState) {
+    await ensureDir();
+    const plaintext = JSON.stringify(storageState);
+    const { iv, tag, data } = encrypt(plaintext);
+    const now = new Date();
+    const envelope = {
+        domain,
+        createdAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + SESSION_TTL_MS).toISOString(),
+        iv,
+        tag,
+        data,
+    };
+    await writeFile(sessionPath(domain), JSON.stringify(envelope, null, 2), "utf-8");
+    log.info(`Saved browser session for ${domain}`);
+}
+/**
+ * Load a stored session for a domain, or null if missing/expired/corrupted.
+ */
+export async function loadSession(domain) {
+    try {
+        const raw = await readFile(sessionPath(domain), "utf-8");
+        const envelope = JSON.parse(raw);
+        // Check expiry
+        if (new Date(envelope.expiresAt).getTime() < Date.now()) {
+            log.info(`Session expired for ${domain} — removing`);
+            await unlink(sessionPath(domain)).catch(() => { });
+            return null;
+        }
+        const plaintext = decrypt(envelope.iv, envelope.tag, envelope.data);
+        return JSON.parse(plaintext);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete a stored session for a domain.
+ */
+export async function deleteSession(domain) {
+    await unlink(sessionPath(domain)).catch(() => { });
+    log.info(`Deleted browser session for ${domain}`);
+}
+/**
+ * Purge all expired sessions from disk.
+ */
+export async function purgeExpiredSessions() {
+    await ensureDir();
+    let purged = 0;
+    const files = await readdir(SESSIONS_DIR);
+    for (const file of files) {
+        if (!file.endsWith(".session.json"))
+            continue;
+        try {
+            const raw = await readFile(join(SESSIONS_DIR, file), "utf-8");
+            const envelope = JSON.parse(raw);
+            if (new Date(envelope.expiresAt).getTime() < Date.now()) {
+                await unlink(join(SESSIONS_DIR, file));
+                purged++;
+            }
+        }
+        catch {
+            // Corrupted file — remove it
+            await unlink(join(SESSIONS_DIR, file)).catch(() => { });
+            purged++;
+        }
+    }
+    if (purged > 0)
+        log.info(`Purged ${purged} expired browser session(s)`);
+    return purged;
+}
+//# sourceMappingURL=sessions.js.map

package/dist/browser/sessions.js.map

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

package/dist/cache/file.d.ts

@@ -0,0 +1,56 @@
+/**
+ * File-backed cache for persistent LLM response caching across restarts.
+ * Stores entries in a single JSON file with debounced writes.
+ * No external dependencies.
+ */
+export interface FileCacheConfig {
+    /** Absolute path to the cache file. */
+    filePath: string;
+    /** Default TTL in milliseconds. Default: 30 minutes. */
+    defaultTTLMs?: number;
+    /** Maximum entries before pruning. Default: 1024. */
+    maxSize?: number;
+    /** Debounce interval for writes in milliseconds. Default: 2000. */
+    writeDebounceMs?: number;
+}
+/**
+ * File-backed cache.
+ *
+ * - Loads all entries from disk on `init()`.
+ * - Writes are debounced to avoid excessive disk I/O.
+ * - Expired entries are pruned on load and when capacity is reached.
+ * - Call `dispose()` to flush pending writes before shutdown.
+ */
+export declare class FileCache {
+    private entries;
+    private dirty;
+    private writeTimer;
+    private readonly filePath;
+    private readonly defaultTTLMs;
+    private readonly maxSize;
+    private readonly writeDebounceMs;
+    constructor(config: FileCacheConfig);
+    /** Load cache from disk. Call once before use. Expired entries are pruned. */
+    init(): Promise<void>;
+    /** Retrieve a value by key. Returns undefined on miss or expiry. */
+    get(key: string): string | undefined;
+    /** Store a value. Prunes when at capacity. */
+    set(key: string, value: string, ttlMs?: number): void;
+    /** Remove a specific key. Returns true if it existed. */
+    delete(key: string): boolean;
+    /** Check if a non-expired entry exists. */
+    has(key: string): boolean;
+    /** Remove all entries. */
+    clear(): void;
+    /** Current number of stored entries. */
+    get size(): number;
+    /** Force an immediate write to disk. */
+    flush(): Promise<void>;
+    /** Flush pending writes and release timers. Call before shutdown. */
+    dispose(): Promise<void>;
+    private scheduleSave;
+    private saveToDisk;
+    /** Remove expired entries, then oldest entries if still over capacity. */
+    private prune;
+}
+//# sourceMappingURL=file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/cache/file.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAiBD;;;;;;;GAOG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,MAAM,EAAE,eAAe;IAOnC,8EAA8E;IACxE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B,oEAAoE;IACpE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAWpC,8CAA8C;IAC9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAYrD,yDAAyD;IACzD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAM5B,2CAA2C;IAC3C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAWzB,0BAA0B;IAC1B,KAAK,IAAI,IAAI;IAKb,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,wCAAwC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,qEAAqE;IAC/D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAY9B,OAAO,CAAC,YAAY;YAWN,UAAU;IAexB,0EAA0E;IAC1E,OAAO,CAAC,KAAK;CAoBd"}

package/dist/cache/file.js

@@ -0,0 +1,176 @@
+/**
+ * File-backed cache for persistent LLM response caching across restarts.
+ * Stores entries in a single JSON file with debounced writes.
+ * No external dependencies.
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("cache.file");
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const DEFAULT_MAX_SIZE = 1024;
+const DEFAULT_DEBOUNCE_MS = 2000;
+/**
+ * File-backed cache.
+ *
+ * - Loads all entries from disk on `init()`.
+ * - Writes are debounced to avoid excessive disk I/O.
+ * - Expired entries are pruned on load and when capacity is reached.
+ * - Call `dispose()` to flush pending writes before shutdown.
+ */
+export class FileCache {
+    entries = new Map();
+    dirty = false;
+    writeTimer = null;
+    filePath;
+    defaultTTLMs;
+    maxSize;
+    writeDebounceMs;
+    constructor(config) {
+        this.filePath = config.filePath;
+        this.defaultTTLMs = config.defaultTTLMs ?? DEFAULT_TTL_MS;
+        this.maxSize = config.maxSize ?? DEFAULT_MAX_SIZE;
+        this.writeDebounceMs = config.writeDebounceMs ?? DEFAULT_DEBOUNCE_MS;
+    }
+    /** Load cache from disk. Call once before use. Expired entries are pruned. */
+    async init() {
+        try {
+            const raw = await readFile(this.filePath, "utf-8");
+            const data = JSON.parse(raw);
+            if (data.version !== 1)
+                return;
+            const now = Date.now();
+            for (const [key, entry] of Object.entries(data.entries)) {
+                if (entry.expiresAt > now) {
+                    this.entries.set(key, entry);
+                }
+            }
+            log.debug("loaded from disk", { entries: this.entries.size });
+        }
+        catch {
+            // File doesn't exist or is corrupt — start fresh
+            log.debug("no cache file, starting fresh");
+        }
+    }
+    /** Retrieve a value by key. Returns undefined on miss or expiry. */
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            this.scheduleSave();
+            return undefined;
+        }
+        return entry.value;
+    }
+    /** Store a value. Prunes when at capacity. */
+    set(key, value, ttlMs) {
+        if (this.entries.size >= this.maxSize && !this.entries.has(key)) {
+            this.prune();
+        }
+        this.entries.set(key, {
+            value,
+            expiresAt: Date.now() + (ttlMs ?? this.defaultTTLMs),
+            createdAt: Date.now(),
+        });
+        this.scheduleSave();
+    }
+    /** Remove a specific key. Returns true if it existed. */
+    delete(key) {
+        const result = this.entries.delete(key);
+        if (result)
+            this.scheduleSave();
+        return result;
+    }
+    /** Check if a non-expired entry exists. */
+    has(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return false;
+        if (Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            this.scheduleSave();
+            return false;
+        }
+        return true;
+    }
+    /** Remove all entries. */
+    clear() {
+        this.entries.clear();
+        this.scheduleSave();
+    }
+    /** Current number of stored entries. */
+    get size() {
+        return this.entries.size;
+    }
+    /** Force an immediate write to disk. */
+    async flush() {
+        if (this.writeTimer) {
+            clearTimeout(this.writeTimer);
+            this.writeTimer = null;
+        }
+        await this.saveToDisk();
+    }
+    /** Flush pending writes and release timers. Call before shutdown. */
+    async dispose() {
+        if (this.writeTimer) {
+            clearTimeout(this.writeTimer);
+            this.writeTimer = null;
+        }
+        if (this.dirty) {
+            await this.saveToDisk();
+        }
+    }
+    // ── Internal ────────────────────────────────────────────────────────────────
+    scheduleSave() {
+        this.dirty = true;
+        if (this.writeTimer)
+            return;
+        this.writeTimer = setTimeout(() => {
+            this.writeTimer = null;
+            this.saveToDisk().catch((err) => {
+                log.error("failed to save cache", { error: String(err) });
+            });
+        }, this.writeDebounceMs);
+    }
+    async saveToDisk() {
+        const data = {
+            version: 1,
+            entries: Object.fromEntries(this.entries),
+        };
+        try {
+            await mkdir(dirname(this.filePath), { recursive: true });
+            await writeFile(this.filePath, JSON.stringify(data), "utf-8");
+            this.dirty = false;
+            log.debug("saved to disk", { entries: this.entries.size });
+        }
+        catch (err) {
+            log.error("disk write failed", { error: String(err) });
+        }
+    }
+    /** Remove expired entries, then oldest entries if still over capacity. */
+    prune() {
+        const now = Date.now();
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt <= now) {
+                this.entries.delete(key);
+            }
+        }
+        while (this.entries.size >= this.maxSize) {
+            let oldestKey;
+            let oldestTime = Infinity;
+            for (const [k, v] of this.entries) {
+                if (v.createdAt < oldestTime) {
+                    oldestTime = v.createdAt;
+                    oldestKey = k;
+                }
+            }
+            if (oldestKey)
+                this.entries.delete(oldestKey);
+            else
+                break;
+        }
+    }
+}
+//# sourceMappingURL=file.js.map

package/dist/cache/file.js.map

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

package/dist/cache/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * LLM response cache — interface, two-tier implementation, and factory.
+ *
+ * Architecture:
+ *   L1 = in-memory TTL cache (fast, bounded)
+ *   L2 = optional file-backed cache (persistent across restarts)
+ *
+ * On `get`: check L1 → on miss, check L2 → promote hit to L1.
+ * On `set`: write to both L1 and L2.
+ */
+import type { MemoryCacheConfig, CacheStats } from "./memory.js";
+import type { FileCacheConfig } from "./file.js";
+/** Minimal cache store contract. */
+export interface CacheStore {
+    get(key: string): string | undefined;
+    set(key: string, value: string, ttlMs?: number): void;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+}
+export interface LLMCacheConfig {
+    /** Master switch. Default: true. */
+    enabled?: boolean;
+    /** In-memory (L1) settings. */
+    memory?: MemoryCacheConfig;
+    /** File persistence (L2) settings. Omit to use memory-only. */
+    file?: FileCacheConfig;
+}
+/**
+ * Two-tier cache: memory (L1) + optional file persistence (L2).
+ *
+ * When file persistence is configured, call `init()` once to load from disk,
+ * and `dispose()` before shutdown to flush pending writes.
+ */
+export declare class TieredCache implements CacheStore {
+    private readonly memory;
+    private readonly file;
+    private readonly _enabled;
+    constructor(config?: LLMCacheConfig);
+    /** Load file-backed cache from disk. No-op when file persistence is disabled. */
+    init(): Promise<void>;
+    get(key: string): string | undefined;
+    set(key: string, value: string, ttlMs?: number): void;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    /** Whether the cache is enabled. */
+    get enabled(): boolean;
+    /** Return L1 (memory) cache statistics. */
+    stats(): CacheStats;
+    /** Force an immediate flush of the file-backed cache. */
+    flush(): Promise<void>;
+    /** Flush pending writes and release timers. Call before shutdown. */
+    dispose(): Promise<void>;
+}
+/** Create a cache with sensible defaults. */
+export declare function createCache(config?: LLMCacheConfig): TieredCache;
+export { MemoryCache } from "./memory.js";
+export type { MemoryCacheConfig, CacheStats } from "./memory.js";
+export { FileCache } from "./file.js";
+export type { FileCacheConfig } from "./file.js";
+export { generateCacheKey, hashString } from "./keys.js";
+export type { CacheKeyInput } from "./keys.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAMjD,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;CACf;AAID,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAID;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;gBAEvB,MAAM,GAAE,cAAmB;IAMvC,iFAAiF;IAC3E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAmBpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAMrD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAM5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKzB,KAAK,IAAI,IAAI;IAKb,oCAAoC;IACpC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,2CAA2C;IAC3C,KAAK,IAAI,UAAU;IAInB,yDAAyD;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,qEAAqE;IAC/D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAID,6CAA6C;AAC7C,wBAAgB,WAAW,CAAC,MAAM,GAAE,cAAmB,GAAG,WAAW,CAMpE;AAID,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,108 @@
+/**
+ * LLM response cache — interface, two-tier implementation, and factory.
+ *
+ * Architecture:
+ *   L1 = in-memory TTL cache (fast, bounded)
+ *   L2 = optional file-backed cache (persistent across restarts)
+ *
+ * On `get`: check L1 → on miss, check L2 → promote hit to L1.
+ * On `set`: write to both L1 and L2.
+ */
+import { createLogger } from "../utils/logger.js";
+import { MemoryCache } from "./memory.js";
+import { FileCache } from "./file.js";
+const log = createLogger("cache");
+// ── Two-tier cache ────────────────────────────────────────────────────────────
+/**
+ * Two-tier cache: memory (L1) + optional file persistence (L2).
+ *
+ * When file persistence is configured, call `init()` once to load from disk,
+ * and `dispose()` before shutdown to flush pending writes.
+ */
+export class TieredCache {
+    memory;
+    file;
+    _enabled;
+    constructor(config = {}) {
+        this._enabled = config.enabled ?? true;
+        this.memory = new MemoryCache(config.memory);
+        this.file = config.file ? new FileCache(config.file) : null;
+    }
+    /** Load file-backed cache from disk. No-op when file persistence is disabled. */
+    async init() {
+        if (this.file)
+            await this.file.init();
+    }
+    get(key) {
+        if (!this._enabled)
+            return undefined;
+        // L1
+        const memResult = this.memory.get(key);
+        if (memResult !== undefined)
+            return memResult;
+        // L2
+        if (this.file) {
+            const fileResult = this.file.get(key);
+            if (fileResult !== undefined) {
+                // Promote to L1
+                this.memory.set(key, fileResult);
+                return fileResult;
+            }
+        }
+        return undefined;
+    }
+    set(key, value, ttlMs) {
+        if (!this._enabled)
+            return;
+        this.memory.set(key, value, ttlMs);
+        if (this.file)
+            this.file.set(key, value, ttlMs);
+    }
+    delete(key) {
+        const memDel = this.memory.delete(key);
+        const fileDel = this.file ? this.file.delete(key) : false;
+        return memDel || fileDel;
+    }
+    has(key) {
+        if (!this._enabled)
+            return false;
+        return this.memory.has(key) || (this.file?.has(key) ?? false);
+    }
+    clear() {
+        this.memory.clear();
+        if (this.file)
+            this.file.clear();
+    }
+    /** Whether the cache is enabled. */
+    get enabled() {
+        return this._enabled;
+    }
+    /** Return L1 (memory) cache statistics. */
+    stats() {
+        return this.memory.stats();
+    }
+    /** Force an immediate flush of the file-backed cache. */
+    async flush() {
+        if (this.file)
+            await this.file.flush();
+    }
+    /** Flush pending writes and release timers. Call before shutdown. */
+    async dispose() {
+        if (this.file)
+            await this.file.dispose();
+    }
+}
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a cache with sensible defaults. */
+export function createCache(config = {}) {
+    log.debug("creating cache", {
+        enabled: config.enabled ?? true,
+        hasFile: !!config.file,
+    });
+    return new TieredCache(config);
+}
+// ── Re-exports ────────────────────────────────────────────────────────────────
+export { MemoryCache } from "./memory.js";
+export { FileCache } from "./file.js";
+export { generateCacheKey, hashString } from "./keys.js";
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

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

package/dist/cache/keys.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Cache key generation for LLM responses.
+ * Produces deterministic SHA-256 keys from model, messages, and parameters.
+ * No external dependencies.
+ */
+export interface CacheKeyInput {
+    /** LLM provider (e.g. "openrouter", "ollama"). */
+    provider?: string;
+    /** Model identifier. */
+    model?: string;
+    /** Chat messages — normalised for stable hashing. */
+    messages?: ReadonlyArray<{
+        role: string;
+        content: string | unknown[];
+    }>;
+    /** Additional parameters that affect the response (temperature, etc.). */
+    params?: Record<string, unknown>;
+}
+/**
+ * Generate a deterministic SHA-256 cache key from structured input.
+ * Normalises messages and sorts parameter keys for stability.
+ */
+export declare function generateCacheKey(input: CacheKeyInput): string;
+/**
+ * Generate a SHA-256 cache key from a raw string.
+ * Useful when you already have a pre-formatted key source.
+ */
+export declare function hashString(input: string): string;
+//# sourceMappingURL=keys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/cache/keys.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;IACxE,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAY7D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/cache/keys.js

@@ -0,0 +1,52 @@
+/**
+ * Cache key generation for LLM responses.
+ * Produces deterministic SHA-256 keys from model, messages, and parameters.
+ * No external dependencies.
+ */
+import { createHash } from "node:crypto";
+/**
+ * Generate a deterministic SHA-256 cache key from structured input.
+ * Normalises messages and sorts parameter keys for stability.
+ */
+export function generateCacheKey(input) {
+    const normalized = {};
+    if (input.provider != null)
+        normalized.provider = input.provider;
+    if (input.model != null)
+        normalized.model = input.model;
+    if (input.messages) {
+        normalized.messages = input.messages.map(normalizeMessage);
+    }
+    if (input.params)
+        normalized.params = sortKeys(input.params);
+    return createHash("sha256")
+        .update(JSON.stringify(normalized))
+        .digest("hex");
+}
+/**
+ * Generate a SHA-256 cache key from a raw string.
+ * Useful when you already have a pre-formatted key source.
+ */
+export function hashString(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+/** Flatten multimodal content blocks into a stable string form. */
+function normalizeMessage(m) {
+    const content = typeof m.content === "string"
+        ? m.content
+        : m.content
+            .map((b) => "text" in b
+            ? b.text
+            : b.image_url.url)
+            .join("|");
+    return { role: m.role, content };
+}
+/** Sort object keys for deterministic serialisation. */
+function sortKeys(obj) {
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        sorted[key] = obj[key];
+    }
+    return sorted;
+}
+//# sourceMappingURL=keys.js.map

package/dist/cache/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/cache/keys.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAazC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAoB;IACnD,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,IAAI,KAAK,CAAC,QAAQ,IAAI,IAAI;QAAE,UAAU,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IACjE,IAAI,KAAK,CAAC,KAAK,IAAI,IAAI;QAAE,UAAU,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACxD,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,UAAU,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,KAAK,CAAC,MAAM;QAAE,UAAU,CAAC,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAE7D,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;SAClC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,mEAAmE;AACnE,SAAS,gBAAgB,CAAC,CAAgD;IAIxE,MAAM,OAAO,GACX,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAC3B,CAAC,CAAC,CAAC,CAAC,OAAO;QACX,CAAC,CAAE,CAAC,CAAC,OAA0C;aAC1C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACT,MAAM,IAAI,CAAC;YACT,CAAC,CAAE,CAAsB,CAAC,IAAI;YAC9B,CAAC,CAAE,CAAoC,CAAC,SAAS,CAAC,GAAG,CACxD;aACA,IAAI,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;AACnC,CAAC;AAED,wDAAwD;AACxD,SAAS,QAAQ,CACf,GAA4B;IAE5B,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1C,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}