@darkiceinteractive/mcp-conductor 2.0.0-alpha.1 → 3.0.0-beta.2

package/dist/cache/cache.js

@@ -0,0 +1,209 @@
+/**
+ * CacheLayer — three-tier cache composition (memory LRU + disk CBOR + delta).
+ *
+ * Call flow:
+ *   get(server, tool, args)
+ *     → memory LRU hit?  → return CacheHit (source: 'memory')
+ *     → disk hit?        → promote to memory, return CacheHit (source: 'disk')
+ *     → miss             → return null (caller must fetch from backend)
+ *
+ * Stale-while-revalidate (SWR):
+ *   All staleness decisions are made here, not in DiskCache, so that
+ *   vi.useFakeTimers() in tests correctly affects TTL checks at all tiers.
+ *
+ * Bridge wiring order (per spec):
+ *   cache check → cache miss → reliability gateway (Agent C) → backend
+ *
+ * @module cache/cache
+ */
+import { MemoryLru } from './lru.js';
+import { DiskCache } from './disk.js';
+import { buildCacheKey, cacheKeyToString } from './key.js';
+import { resolveTtl, isCacheable } from './policy.js';
+import { computeDelta } from './delta.js';
+import { logger } from '../utils/index.js';
+export class CacheLayer {
+    lru;
+    disk;
+    registry;
+    options;
+    unsubscribe = null;
+    diskMisses = 0;
+    ttlMap = new Map();
+    /** Keys currently being background-revalidated; prevents SWR thundering herd. */
+    revalidating = new Set();
+    constructor(options) {
+        this.options = {
+            diskDir: `${process.env['HOME'] ?? '/tmp'}/.mcp-conductor/cache`,
+            maxMemoryBytes: 100 * 1024 * 1024,
+            maxDiskBytes: 2 * 1024 * 1024 * 1024,
+            staleWhileRevalidate: true,
+            policies: {},
+            ...options,
+        };
+        this.registry = options.registry;
+        this.lru = new MemoryLru({ maxMemoryBytes: this.options.maxMemoryBytes });
+        this.disk = new DiskCache({
+            diskDir: this.options.diskDir,
+            maxDiskBytes: this.options.maxDiskBytes,
+        });
+        const sub = this.registry.watch((event) => {
+            if (event.type === 'tool-updated') {
+                const prefix = `${event.server}:${event.tool}:`;
+                this.lru.invalidateByPrefix(prefix);
+                this.disk.invalidateByPrefix(prefix).catch((err) => logger.warn('CacheLayer: disk invalidation error', { error: String(err) }));
+                logger.debug('CacheLayer: invalidated on tool-updated', {
+                    server: event.server,
+                    tool: event.tool,
+                });
+            }
+        });
+        this.unsubscribe = sub.unsubscribe;
+    }
+    async get(server, tool, args) {
+        const cacheKey = buildCacheKey(server, tool, args);
+        const keyStr = cacheKeyToString(cacheKey);
+        const now = Date.now();
+        // 1. Memory LRU — MemoryLru.get() enforces TTL via manual storedAt check
+        const memHit = this.lru.get(keyStr);
+        if (memHit) {
+            const ttlMs = this.ttlMap.get(keyStr) ?? 0;
+            const isStale = ttlMs > 0 && now - memHit.storedAt > ttlMs;
+            if (!isStale) {
+                return { ...memHit, staleness: now - memHit.storedAt };
+            }
+            if (this.options.staleWhileRevalidate) {
+                // Suppress duplicate SWR triggers: if already revalidating, return stale without the flag
+                const needsRevalidation = !this.revalidating.has(keyStr);
+                return { ...memHit, staleness: now - memHit.storedAt, needsRevalidation };
+            }
+            this.lru.delete(keyStr);
+            // fall through to disk
+        }
+        // 2. Disk — DiskCache.get() does NOT enforce TTL; we decide staleness here
+        const diskHit = await this.disk.get(cacheKey.argsHash);
+        if (diskHit) {
+            const entryTtl = diskHit.ttlMs > 0 ? diskHit.ttlMs : (this.ttlMap.get(keyStr) ?? 0);
+            const staleness = now - diskHit.storedAt;
+            const isStale = entryTtl > 0 && staleness > entryTtl;
+            if (!isStale) {
+                const remaining = entryTtl > 0 ? Math.max(1, entryTtl - staleness) : 0;
+                this.lru.set(keyStr, diskHit.value, remaining);
+                this.ttlMap.set(keyStr, entryTtl);
+                return { value: diskHit.value, storedAt: diskHit.storedAt, source: 'disk', staleness };
+            }
+            if (this.options.staleWhileRevalidate) {
+                const remaining = Math.max(1, entryTtl);
+                this.lru.set(keyStr, diskHit.value, remaining);
+                this.ttlMap.set(keyStr, entryTtl);
+                // Suppress duplicate SWR triggers: if already revalidating, return stale without the flag
+                const needsRevalidation = !this.revalidating.has(keyStr);
+                return {
+                    value: diskHit.value,
+                    storedAt: diskHit.storedAt,
+                    source: 'disk',
+                    staleness,
+                    needsRevalidation,
+                };
+            }
+            await this.disk.delete(cacheKey.argsHash);
+        }
+        this.diskMisses++;
+        return null;
+    }
+    async set(server, tool, args, result, options) {
+        const toolDef = this.registry.getTool(server, tool);
+        const ttlMs = options?.ttl ?? resolveTtl(toolDef, this.options.policies);
+        if (ttlMs === 0)
+            return;
+        const cacheKey = buildCacheKey(server, tool, args);
+        const keyStr = cacheKeyToString(cacheKey);
+        this.lru.set(keyStr, result, ttlMs);
+        this.ttlMap.set(keyStr, ttlMs);
+        await this.disk.set(cacheKey.argsHash, {
+            value: result,
+            storedAt: Date.now(),
+            ttlMs,
+            server,
+            tool,
+        });
+    }
+    async invalidate(server, pattern) {
+        const prefix = pattern ? `${server}:${pattern}` : `${server}:`;
+        const memCount = this.lru.invalidateByPrefix(prefix);
+        const diskCount = await this.disk.invalidateByPrefix(prefix);
+        return memCount + diskCount;
+    }
+    async delta(server, tool, args, current) {
+        const hit = await this.get(server, tool, args);
+        if (!hit)
+            return { unchanged: false, full: current };
+        return computeDelta(hit.value, current);
+    }
+    stats() {
+        const lruCounters = this.lru.getCounters();
+        const diskCounters = this.disk.getCounters();
+        return {
+            memoryHits: lruCounters.hits,
+            diskHits: diskCounters.hits,
+            misses: this.diskMisses,
+            evictions: lruCounters.evictions,
+            bytesInMemory: this.lru.bytesUsed,
+            bytesOnDisk: this.disk.approximateBytesOnDisk,
+        };
+    }
+    async clear() {
+        this.lru.clear();
+        this.lru.resetCounters();
+        this.ttlMap.clear();
+        this.diskMisses = 0;
+        await this.disk.clear();
+    }
+    wouldCache(server, tool) {
+        const toolDef = this.registry.getTool(server, tool);
+        return isCacheable(toolDef, this.options.policies);
+    }
+    /**
+     * Deduplicated background revalidation helper for stale-while-revalidate.
+     *
+     * Marks the cache key as being revalidated so subsequent concurrent `get()`
+     * calls that would also see `needsRevalidation: true` get `false` instead,
+     * preventing a thundering herd of parallel refreshes.
+     *
+     * The key is removed from the revalidating set on completion (success or
+     * failure), allowing a future `get()` to schedule a fresh revalidation if
+     * the entry is still stale at that point.
+     *
+     * @param server   MCP server name.
+     * @param tool     Tool name.
+     * @param args     Original call arguments (used to build the cache key).
+     * @param fetchFn  Async function that calls the backend and returns the fresh result.
+     * @returns        A promise that resolves when the background refresh completes.
+     *                 Callers should `.catch()` the returned promise to handle errors.
+     */
+    refreshInBackground(server, tool, args, fetchFn) {
+        const cacheKey = buildCacheKey(server, tool, args);
+        const keyStr = cacheKeyToString(cacheKey);
+        // Already in-flight — skip
+        if (this.revalidating.has(keyStr)) {
+            return Promise.resolve();
+        }
+        this.revalidating.add(keyStr);
+        return (async () => {
+            try {
+                const freshResult = await fetchFn();
+                await this.set(server, tool, args, freshResult);
+            }
+            finally {
+                this.revalidating.delete(keyStr);
+            }
+        })();
+    }
+    destroy() {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = null;
+        }
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache/cache.js.map

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

package/dist/cache/delta.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Delta encoding for repeated tool-call results.
+ *
+ * When a caller wants to know "what changed since the last call", we compute
+ * a structural diff and return only the delta. This is significantly smaller
+ * than the full result for incremental work (e.g. polling a list of issues).
+ *
+ * Strategy:
+ * - Arrays: compare items by identity (JSON equality). Report added/removed.
+ *   Items that appear in both but at different positions count as unchanged
+ *   (we do not track moves for simplicity).
+ * - Objects at the top level: compare property values; modified = { before, after }.
+ * - Scalars or mixed types: return full result (no useful delta possible).
+ * - When the delta payload is larger than the full result, return full result.
+ *
+ * @module cache/delta
+ */
+import type { DeltaResult } from './index.js';
+/**
+ * Compute the delta between a previous result and the current result.
+ *
+ * Always returns a DeltaResult. When results are identical, returns
+ * `{ unchanged: true }`. When results differ but the full payload is
+ * smaller than the delta, `full` is set and the delta fields are absent.
+ */
+export declare function computeDelta(previous: unknown, current: unknown): DeltaResult;
+/**
+ * Deep equality via JSON serialisation. Fast enough for typical MCP result
+ * sizes; avoids pulling in a heavy comparison library.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=delta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.ts","sourceRoot":"","sources":["../../src/cache/delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,WAAW,CAqB7E;AAiFD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAOzD"}

package/dist/cache/delta.js

@@ -0,0 +1,131 @@
+/**
+ * Delta encoding for repeated tool-call results.
+ *
+ * When a caller wants to know "what changed since the last call", we compute
+ * a structural diff and return only the delta. This is significantly smaller
+ * than the full result for incremental work (e.g. polling a list of issues).
+ *
+ * Strategy:
+ * - Arrays: compare items by identity (JSON equality). Report added/removed.
+ *   Items that appear in both but at different positions count as unchanged
+ *   (we do not track moves for simplicity).
+ * - Objects at the top level: compare property values; modified = { before, after }.
+ * - Scalars or mixed types: return full result (no useful delta possible).
+ * - When the delta payload is larger than the full result, return full result.
+ *
+ * @module cache/delta
+ */
+/**
+ * Compute the delta between a previous result and the current result.
+ *
+ * Always returns a DeltaResult. When results are identical, returns
+ * `{ unchanged: true }`. When results differ but the full payload is
+ * smaller than the delta, `full` is set and the delta fields are absent.
+ */
+export function computeDelta(previous, current) {
+    // Identical check (fast path)
+    if (deepEqual(previous, current)) {
+        return { unchanged: true };
+    }
+    // Array diff
+    if (Array.isArray(previous) && Array.isArray(current)) {
+        return arrayDelta(previous, current);
+    }
+    // Object diff
+    if (isPlainObject(previous) && isPlainObject(current)) {
+        return objectDelta(previous, current);
+    }
+    // Scalar or mixed-type change — return full
+    return { unchanged: false, full: current };
+}
+// ── Array diff ────────────────────────────────────────────────────────────────
+function arrayDelta(prev, curr) {
+    const added = [];
+    const removed = [];
+    // Items in curr but not in prev
+    for (const item of curr) {
+        if (!prev.some((p) => deepEqual(p, item))) {
+            added.push(item);
+        }
+    }
+    // Items in prev but not in curr
+    for (const item of prev) {
+        if (!curr.some((c) => deepEqual(c, item))) {
+            removed.push(item);
+        }
+    }
+    const delta = {
+        unchanged: false,
+        added: added.length > 0 ? added : undefined,
+        removed: removed.length > 0 ? removed : undefined,
+    };
+    // Only prefer full when the delta is genuinely larger than the full result
+    if (shouldReturnFull(delta, curr)) {
+        return { unchanged: false, full: curr };
+    }
+    return delta;
+}
+// ── Object diff ───────────────────────────────────────────────────────────────
+function objectDelta(prev, curr) {
+    const added = [];
+    const removed = [];
+    const modified = [];
+    const allKeys = new Set([...Object.keys(prev), ...Object.keys(curr)]);
+    for (const key of allKeys) {
+        const inPrev = key in prev;
+        const inCurr = key in curr;
+        if (!inPrev && inCurr) {
+            added.push({ [key]: curr[key] });
+        }
+        else if (inPrev && !inCurr) {
+            removed.push({ [key]: prev[key] });
+        }
+        else if (!deepEqual(prev[key], curr[key])) {
+            modified.push({ before: { [key]: prev[key] }, after: { [key]: curr[key] } });
+        }
+    }
+    const delta = {
+        unchanged: false,
+        added: added.length > 0 ? added : undefined,
+        removed: removed.length > 0 ? removed : undefined,
+        modified: modified.length > 0 ? modified : undefined,
+    };
+    if (shouldReturnFull(delta, curr)) {
+        return { unchanged: false, full: curr };
+    }
+    return delta;
+}
+// ── Utilities ─────────────────────────────────────────────────────────────────
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Deep equality via JSON serialisation. Fast enough for typical MCP result
+ * sizes; avoids pulling in a heavy comparison library.
+ */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns true when the full current value is strictly smaller (in serialised
+ * bytes) than the delta payload. We use a strict greater-than comparison so
+ * that delta is preferred when sizes are equal.
+ */
+function shouldReturnFull(delta, current) {
+    try {
+        const deltaSize = Buffer.byteLength(JSON.stringify(delta), 'utf8');
+        const fullSize = Buffer.byteLength(JSON.stringify(current), 'utf8');
+        return deltaSize > fullSize;
+    }
+    catch {
+        return true; // If we can't measure, default to full
+    }
+}
+//# sourceMappingURL=delta.js.map

package/dist/cache/delta.js.map

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

package/dist/cache/disk.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Persistent disk cache tier using CBOR encoding (cbor-x).
+ *
+ * Layout on disk:
+ *   <diskDir>/<sha256-prefix-2>/<full-argsHash>.cbor
+ *
+ * TTL enforcement is the responsibility of the caller (CacheLayer). DiskCache
+ * returns entries regardless of TTL so that stale-while-revalidate can be
+ * handled at the CacheLayer level.
+ *
+ * Parallel writes are safe: each key maps to a unique path; writes are
+ * atomic via a temp-file rename pattern.
+ *
+ * @module cache/disk
+ */
+import type { CacheHit } from './index.js';
+export interface DiskEntry {
+    value: unknown;
+    storedAt: number;
+    ttlMs: number;
+    server: string;
+    tool: string;
+}
+/** Extended CacheHit that includes the stored TTL so CacheLayer can apply its own expiry policy. */
+export interface DiskCacheHit extends CacheHit {
+    ttlMs: number;
+}
+export interface DiskCacheOptions {
+    diskDir: string;
+    maxDiskBytes?: number;
+}
+export declare class DiskCache {
+    private diskDir;
+    private maxDiskBytes;
+    private hits;
+    private misses;
+    private bytesOnDisk;
+    private ready;
+    constructor(options: DiskCacheOptions);
+    private ensureReady;
+    private entryPath;
+    /**
+     * Read an entry from disk.
+     * Returns null only on genuine miss or read errors — TTL is NOT enforced here.
+     * CacheLayer is responsible for staleness decisions (enabling SWR to work).
+     */
+    get(argsHash: string): Promise<DiskCacheHit | null>;
+    /**
+     * Write an entry to disk atomically (write to .tmp then rename).
+     * Triggers rotation when over maxDiskBytes.
+     */
+    set(argsHash: string, entry: DiskEntry): Promise<void>;
+    delete(argsHash: string): Promise<boolean>;
+    invalidateByPrefix(serverToolPrefix: string): Promise<number>;
+    invalidateServer(server: string): Promise<number>;
+    clear(): Promise<void>;
+    get approximateBytesOnDisk(): number;
+    getCounters(): {
+        hits: number;
+        misses: number;
+    };
+    private scanAndDelete;
+    private rotate;
+}
+//# sourceMappingURL=disk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disk.d.ts","sourceRoot":"","sources":["../../src/cache/disk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,oGAAoG;AACpG,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,KAAK,CAAgB;gBAEjB,OAAO,EAAE,gBAAgB;YAMvB,WAAW;IAIzB,OAAO,CAAC,SAAS;IAKjB;;;;OAIG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAuBzD;;;OAGG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBtD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa1C,kBAAkB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsB7D,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,IAAI,sBAAsB,IAAI,MAAM,CAA6B;IACjE,WAAW,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;YAEjC,aAAa;YA2Bb,MAAM;CAqCrB"}