cachegate 1.0.0

package/test/metrics.test.js

@@ -0,0 +1,282 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function freshMetrics() {
+  const logPath = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'metrics-test-')), 'metrics.jsonl');
+  process.env.METRICS_LOG_PATH = logPath;
+  delete require.cache[require.resolve('../metrics')];
+  return require('../metrics');
+}
+
+async function flush() {
+  await new Promise((resolve) => setTimeout(resolve, 50));
+}
+
+test('readRecent returns [] when no log file exists yet', async () => {
+  const metrics = freshMetrics();
+  const rows = await metrics.readRecent();
+  assert.deepEqual(rows, []);
+});
+
+test('record() writes a line that readRecent() can read back, with a timestamp added', async () => {
+  const metrics = freshMetrics();
+  metrics.record({ provider: 'openai', latency_ms: 120, cost_usd: 0.001 });
+  await flush();
+
+  const rows = await metrics.readRecent();
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].provider, 'openai');
+  assert.ok(rows[0].timestamp, 'expected record() to stamp a timestamp');
+});
+
+test('a malformed line in the log is skipped, not fatal', async () => {
+  const metrics = freshMetrics();
+  metrics.record({ provider: 'openai', latency_ms: 10 });
+  await flush();
+  fs.appendFileSync(metrics.currentLogPath(), 'not valid json\n');
+  metrics.record({ provider: 'anthropic', latency_ms: 20 });
+  await flush();
+
+  const rows = await metrics.readRecent();
+  assert.equal(rows.length, 2);
+});
+
+test('currentLogPath() names a per-UTC-day file, and record() actually writes there', async () => {
+  const metrics = freshMetrics();
+  const today = new Date().toISOString().slice(0, 10);
+  assert.match(metrics.currentLogPath(), new RegExp(`metrics-${today}\\.jsonl$`));
+
+  metrics.record({ provider: 'openai' });
+  await flush();
+  assert.ok(fs.existsSync(metrics.currentLogPath()), "record() should write to today's rotated file");
+});
+
+test('listLogFiles() finds only files matching the rotation naming pattern, sorted ascending by date', async () => {
+  const metrics = freshMetrics();
+  fs.writeFileSync(path.join(metrics.DATA_DIR, 'metrics-2026-08-10.jsonl'), '');
+  fs.writeFileSync(path.join(metrics.DATA_DIR, 'metrics-2026-08-01.jsonl'), '');
+  fs.writeFileSync(path.join(metrics.DATA_DIR, 'not-a-metrics-file.txt'), '');
+
+  const files = await metrics.listLogFiles();
+  assert.deepEqual(files.map((f) => f.date), ['2026-08-01', '2026-08-10']);
+});
+
+test('readRecent() aggregates across multiple real day-files, newest data included first', async () => {
+  const metrics = freshMetrics();
+  fs.writeFileSync(
+    path.join(metrics.DATA_DIR, 'metrics-2026-08-01.jsonl'),
+    JSON.stringify({ timestamp: '2026-08-01T00:00:00.000Z', provider: 'anthropic', tag: 'old' }) + '\n'
+  );
+  fs.writeFileSync(
+    path.join(metrics.DATA_DIR, 'metrics-2026-08-02.jsonl'),
+    JSON.stringify({ timestamp: '2026-08-02T00:00:00.000Z', provider: 'openai', tag: 'newer' }) + '\n'
+  );
+
+  const rows = await metrics.readRecent(10);
+  assert.equal(rows.length, 2);
+  assert.deepEqual(rows.map((r) => r.tag), ['old', 'newer']); // chronological order preserved
+});
+
+test('readRecent(limit) stops opening older files once enough rows are collected', async () => {
+  const metrics = freshMetrics();
+  fs.writeFileSync(
+    path.join(metrics.DATA_DIR, 'metrics-2026-08-01.jsonl'),
+    JSON.stringify({ timestamp: '2026-08-01T00:00:00.000Z', tag: 'should-not-be-needed' }) + '\n'
+  );
+  fs.writeFileSync(
+    path.join(metrics.DATA_DIR, 'metrics-2026-08-02.jsonl'),
+    Array.from({ length: 5 }, (_, i) => JSON.stringify({ timestamp: '2026-08-02T00:00:00.000Z', tag: `row-${i}` })).join('\n') + '\n'
+  );
+
+  const rows = await metrics.readRecent(5);
+  assert.equal(rows.length, 5);
+  assert.ok(rows.every((r) => r.tag.startsWith('row-')), 'the older file should not have been needed to satisfy limit:5');
+});
+
+test('pruneOlderThan() deletes only day-files strictly older than the cutoff, and is never called by anything else in this module', async () => {
+  const metrics = freshMetrics();
+  const oldPath = path.join(metrics.DATA_DIR, 'metrics-2026-01-01.jsonl');
+  const recentPath = metrics.currentLogPath();
+  fs.writeFileSync(oldPath, '{}\n');
+  metrics.record({ provider: 'openai' });
+  await flush();
+
+  const deleted = await metrics.pruneOlderThan(30);
+  assert.deepEqual(deleted, [oldPath]);
+  assert.equal(fs.existsSync(oldPath), false);
+  assert.equal(fs.existsSync(recentPath), true, "pruneOlderThan should never touch today's file");
+});
+
+test('providerStats() computes error rate and average latency per provider', async () => {
+  const metrics = freshMetrics();
+  metrics.record({ provider: 'openai', latency_ms: 100 });
+  metrics.record({ provider: 'openai', latency_ms: 200 });
+  metrics.record({ provider: 'openai', error: 'boom' });
+  await flush();
+
+  const stats = await metrics.providerStats();
+  assert.equal(stats.openai.sampleSize, 3);
+  assert.equal(stats.openai.errorRate, 1 / 3);
+  assert.equal(stats.openai.avgLatencyMs, 150); // average of the two non-error latencies
+});
+
+test('providerStats() only considers the most recent windowSize entries', async () => {
+  const metrics = freshMetrics();
+  for (let i = 0; i < 5; i++) metrics.record({ provider: 'openai', error: 'boom' });
+  for (let i = 0; i < 5; i++) metrics.record({ provider: 'openai', latency_ms: 50 });
+  await flush();
+
+  const stats = await metrics.providerStats(5); // window covers only the second batch
+  assert.equal(stats.openai.errorRate, 0);
+  assert.equal(stats.openai.avgLatencyMs, 50);
+});
+
+test('classifyErrorType() reads Anthropic\'s own {error:{type}} shape (SDK message = "<status> <json>")', () => {
+  const metrics = freshMetrics();
+  const msg = '401 {"type":"error","error":{"type":"authentication_error","message":"API key is invalid."},"request_id":null}';
+  assert.equal(metrics.classifyErrorType(msg), 'authentication_error');
+});
+
+test('classifyErrorType() reads OpenAI\'s own {error:{type,code}} shape', () => {
+  const metrics = freshMetrics();
+  const msg = '429 {"error":{"message":"You exceeded your current quota.","type":"insufficient_quota","param":null,"code":"insufficient_quota"}}';
+  assert.equal(metrics.classifyErrorType(msg), 'insufficient_quota');
+});
+
+test('classifyErrorType() reads an invalid-key error identified only by code, not type', () => {
+  const metrics = freshMetrics();
+  const msg = '401 {"error":{"message":"Incorrect API key provided.","type":"invalid_request_error","param":null,"code":"invalid_api_key"}}';
+  assert.equal(metrics.classifyErrorType(msg), 'authentication_error');
+});
+
+test('classifyErrorType() falls back to keyword matching when the message has no parseable JSON body', () => {
+  const metrics = freshMetrics();
+  assert.equal(metrics.classifyErrorType('connect ECONNREFUSED - the key looks invalid'), 'authentication_error');
+  assert.equal(metrics.classifyErrorType('insufficient funds on this account'), 'insufficient_quota');
+  assert.equal(metrics.classifyErrorType('429 rate limit exceeded, slow down'), 'rate_limit_error');
+  assert.equal(metrics.classifyErrorType('connect ECONNREFUSED 127.0.0.1:4000'), 'unknown');
+});
+
+test('classifyErrorType() never throws on an empty/undefined message', () => {
+  const metrics = freshMetrics();
+  assert.equal(metrics.classifyErrorType(''), 'unknown');
+  assert.equal(metrics.classifyErrorType(undefined), 'unknown');
+});
+
+test('providerStats() reports the MOST RECENT error\'s classified type, not an earlier one still in the window', async () => {
+  const metrics = freshMetrics();
+  metrics.record({
+    provider: 'anthropic',
+    error: '429 {"type":"error","error":{"type":"rate_limit_error"}}',
+    error_type: 'rate_limit_error'
+  });
+  metrics.record({ provider: 'anthropic', latency_ms: 500 }); // recovered in between
+  metrics.record({
+    provider: 'anthropic',
+    error: '401 {"type":"error","error":{"type":"authentication_error"}}',
+    error_type: 'authentication_error'
+  });
+  await flush();
+
+  const stats = await metrics.providerStats();
+  assert.equal(stats.anthropic.lastErrorType, 'authentication_error');
+  assert.ok(stats.anthropic.lastErrorAt, 'expected a timestamp on the last error');
+});
+
+test('providerStats() classifies on the fly for an older record written before error_type existed', async () => {
+  const metrics = freshMetrics();
+  // No error_type field at all - simulates a log line from before this
+  // feature existed, still stored on disk after an upgrade.
+  metrics.record({ provider: 'openai', error: '401 {"error":{"type":"authentication_error"}}' });
+  await flush();
+
+  const stats = await metrics.providerStats();
+  assert.equal(stats.openai.lastErrorType, 'authentication_error');
+});
+
+test('providerStats() reports lastErrorType as null for a provider with no errors at all', async () => {
+  const metrics = freshMetrics();
+  metrics.record({ provider: 'openai', latency_ms: 100 });
+  await flush();
+
+  const stats = await metrics.providerStats();
+  assert.equal(stats.openai.lastErrorType, null);
+  assert.equal(stats.openai.lastErrorAt, null);
+});
+
+function isoDaysAgo(days) {
+  return new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+}
+
+function appendRaw(metrics, entry) {
+  // Deliberately appended to TODAY's physical file regardless of the
+  // entry's own (possibly historical) timestamp - this test is about
+  // rangeSummary()'s PER-ROW timestamp filtering, not file rotation
+  // (that has its own dedicated tests above). Today's file always
+  // passes rangeSummary()'s file-level date filter for any days >= 0,
+  // so the row-level filter is what's actually being exercised here.
+  fs.appendFileSync(metrics.currentLogPath(), JSON.stringify(entry) + '\n');
+}
+
+test('rangeSummary() buckets by calendar day and excludes rows outside the window', async () => {
+  const metrics = freshMetrics();
+  appendRaw(metrics, { timestamp: isoDaysAgo(0), provider: 'openai', cost_usd: 0.01, cache_hit: false });
+  appendRaw(metrics, { timestamp: isoDaysAgo(0), provider: 'openai', cost_usd: 0.02, cache_hit: true, cache_type: 'exact' });
+  appendRaw(metrics, { timestamp: isoDaysAgo(1), provider: 'anthropic', cost_usd: 0.05, cache_hit: true, cache_type: 'semantic' });
+  appendRaw(metrics, { timestamp: isoDaysAgo(30), provider: 'anthropic', cost_usd: 99, cache_hit: false }); // outside a 14-day window
+
+  const summary = await metrics.rangeSummary(14);
+  assert.equal(summary.sample_size, 3);
+  assert.equal(summary.total_cost_usd, 0.08);
+  assert.equal(summary.daily.length, 2); // two distinct calendar days, the 30-day-old row excluded
+  const todayBucket = summary.daily[summary.daily.length - 1];
+  assert.equal(todayBucket.requests, 2);
+  assert.equal(todayBucket.exact_hits, 1);
+  assert.equal(todayBucket.misses, 1);
+});
+
+test('rangeSummary() reports exact/semantic/combined hit rate and error rate separately', async () => {
+  const metrics = freshMetrics();
+  metrics.record({ provider: 'openai', cost_usd: 0.01, cache_hit: false });
+  metrics.record({ provider: 'openai', cost_usd: 0, cache_hit: true, cache_type: 'exact' });
+  metrics.record({ provider: 'openai', cost_usd: 0, cache_hit: true, cache_type: 'semantic' });
+  metrics.record({ provider: 'openai', error: 'boom' });
+  await flush();
+
+  const summary = await metrics.rangeSummary(14);
+  assert.equal(summary.sample_size, 4);
+  assert.equal(summary.cache_hit_rate.exact, 0.25);
+  assert.equal(summary.cache_hit_rate.semantic, 0.25);
+  assert.equal(summary.cache_hit_rate.combined, 0.5);
+  assert.equal(summary.error_rate, 0.25);
+});
+
+test('rangeSummary() computes per-provider cost, requests, error rate and avg latency', async () => {
+  const metrics = freshMetrics();
+  metrics.record({ provider: 'openai', cost_usd: 0.01, latency_ms: 100 });
+  metrics.record({ provider: 'openai', cost_usd: 0.02, latency_ms: 300 });
+  metrics.record({ provider: 'openai', error: 'boom' });
+  metrics.record({ provider: 'anthropic', cost_usd: 0.5, latency_ms: 200 });
+  await flush();
+
+  const summary = await metrics.rangeSummary(14);
+  assert.equal(summary.by_provider.openai.requests, 3);
+  assert.equal(summary.by_provider.openai.cost_usd, 0.03);
+  assert.equal(summary.by_provider.openai.errorRate, 1 / 3);
+  assert.equal(summary.by_provider.openai.avgLatencyMs, 200); // average of the two non-error latencies
+  assert.equal(summary.by_provider.anthropic.requests, 1);
+  assert.equal(summary.by_provider.anthropic.cost_usd, 0.5);
+});
+
+test('rangeSummary() on an empty log returns zeroed rates, not NaN or a crash', async () => {
+  const metrics = freshMetrics();
+  const summary = await metrics.rangeSummary(14);
+  assert.equal(summary.sample_size, 0);
+  assert.equal(summary.cache_hit_rate.combined, 0);
+  assert.equal(summary.error_rate, 0);
+  assert.deepEqual(summary.daily, []);
+  assert.deepEqual(summary.by_provider, {});
+});

package/test/router.test.js

@@ -0,0 +1,195 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// metrics.js and router.js both read env vars once at require time, so
+// each test gets a fresh, isolated metrics log by clearing the require
+// cache and pointing METRICS_LOG_PATH at a throwaway temp file first.
+function freshModules(metricsLogPath) {
+  process.env.METRICS_LOG_PATH = metricsLogPath;
+  delete require.cache[require.resolve('../metrics')];
+  delete require.cache[require.resolve('../router')];
+  const metrics = require('../metrics');
+  const router = require('../router');
+  return { metrics, router };
+}
+
+function tempLogPath() {
+  return path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'router-test-')), 'metrics.jsonl');
+}
+
+test('isVirtualModel only matches the router: prefix', () => {
+  const { router } = freshModules(tempLogPath());
+  assert.equal(router.isVirtualModel('router:fast-cheap'), true);
+  assert.equal(router.isVirtualModel('gpt-4o-mini'), false);
+  assert.equal(router.isVirtualModel('claude-sonnet-4-5-20250929'), false);
+  assert.equal(router.isVirtualModel(undefined), false);
+});
+
+test('pickCandidate returns an error for an unknown tier', async () => {
+  const { router } = freshModules(tempLogPath());
+  const decision = await router.pickCandidate('router:does-not-exist');
+  assert.ok(decision.error);
+});
+
+test('pickCandidate picks the cheaper candidate when both are healthy (no history)', async () => {
+  const { router } = freshModules(tempLogPath());
+  // gpt-4o-mini ($0.15/$0.60 per 1M) is cheaper than claude-haiku-4-5
+  // ($0.80/$4.00 per 1M) at the fixed comparison token counts - see
+  // router.js's COMPARISON_INPUT_TOKENS/OUTPUT_TOKENS.
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.equal(decision.provider, 'openai');
+  assert.equal(decision.model, 'gpt-4o-mini');
+  assert.equal(decision.reason.allUnhealthy, false);
+});
+
+test('pickCandidate exposes the full ranked candidate list, in the same order as the top pick', async () => {
+  const { router } = freshModules(tempLogPath());
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.deepEqual(decision.rankedCandidates, [
+    { provider: 'openai', model: 'gpt-4o-mini' },
+    { provider: 'anthropic', model: 'claude-haiku-4-5-20251001' }
+  ]);
+  // The top pick is always the first entry - server.js's failover loop
+  // relies on this to know which candidate it started with.
+  assert.equal(decision.rankedCandidates[0].provider, decision.provider);
+  assert.equal(decision.rankedCandidates[0].model, decision.model);
+});
+
+test('pickCandidate skips a candidate whose recent error rate is too high, even if cheaper', async () => {
+  const logPath = tempLogPath();
+  const { metrics, router } = freshModules(logPath);
+
+  // Make openai (the cheaper candidate in router:fast-cheap) look
+  // unhealthy: mostly errors in its recent history.
+  for (let i = 0; i < 10; i++) {
+    metrics.record({ provider: 'openai', error: 'simulated failure' });
+  }
+  metrics.record({ provider: 'anthropic', latency_ms: 500 });
+
+  // Metrics writes go through a stream; give it a tick to flush before
+  // reading the file back.
+  await new Promise((resolve) => setTimeout(resolve, 50));
+
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.equal(decision.provider, 'anthropic');
+  assert.equal(decision.model, 'claude-haiku-4-5-20251001');
+  assert.equal(decision.reason.allUnhealthy, false);
+});
+
+test('pickCandidate still returns a candidate when every option is unhealthy', async () => {
+  const logPath = tempLogPath();
+  const { metrics, router } = freshModules(logPath);
+
+  for (let i = 0; i < 10; i++) {
+    metrics.record({ provider: 'openai', error: 'simulated failure' });
+    metrics.record({ provider: 'anthropic', error: 'simulated failure' });
+  }
+  await new Promise((resolve) => setTimeout(resolve, 50));
+
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.ok(decision.provider);
+  assert.equal(decision.reason.allUnhealthy, true);
+});
+
+test('pickCandidate reports which strategy it used', async () => {
+  const { router } = freshModules(tempLogPath());
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.equal(decision.reason.strategy, 'cost'); // default, no ROUTER_STRATEGY set
+});
+
+async function flush() {
+  await new Promise((resolve) => setTimeout(resolve, 50));
+}
+
+test('ROUTER_STRATEGY=latency picks the fastest healthy candidate even when it costs more', async () => {
+  const logPath = tempLogPath();
+  process.env.ROUTER_STRATEGY = 'latency';
+  const { metrics, router } = freshModules(logPath);
+
+  // gpt-4o-mini is the cheaper candidate in router:fast-cheap, but make
+  // it noticeably slower than claude-haiku here.
+  for (let i = 0; i < 5; i++) metrics.record({ provider: 'openai', latency_ms: 2000 });
+  for (let i = 0; i < 5; i++) metrics.record({ provider: 'anthropic', latency_ms: 100 });
+  await flush();
+
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.equal(decision.provider, 'anthropic');
+  assert.equal(decision.model, 'claude-haiku-4-5-20251001');
+  assert.equal(decision.reason.strategy, 'latency');
+
+  delete process.env.ROUTER_STRATEGY;
+});
+
+test('ROUTER_STRATEGY=latency falls back to cost as a tiebreaker when latency is equal (e.g. both unknown)', async () => {
+  process.env.ROUTER_STRATEGY = 'latency';
+  const { router } = freshModules(tempLogPath()); // no recorded latencies at all - both candidates are unknown
+
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.equal(decision.model, 'gpt-4o-mini'); // the cheaper of the two, same as the default cost strategy would pick
+
+  delete process.env.ROUTER_STRATEGY;
+});
+
+test('ROUTER_STRATEGY=latency-guarded-cost excludes a candidate far slower than the fastest known one, even if cheaper', async () => {
+  const logPath = tempLogPath();
+  process.env.ROUTER_STRATEGY = 'latency-guarded-cost';
+  const { metrics, router } = freshModules(logPath);
+
+  // openai/gpt-4o-mini is the cheaper candidate, but 3000ms is far more
+  // than 3x (the default guard multiplier) slower than anthropic's
+  // 100ms - it should get excluded by the guard despite being cheaper.
+  for (let i = 0; i < 5; i++) metrics.record({ provider: 'openai', latency_ms: 3000 });
+  for (let i = 0; i < 5; i++) metrics.record({ provider: 'anthropic', latency_ms: 100 });
+  await flush();
+
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.equal(decision.provider, 'anthropic');
+  assert.equal(decision.reason.strategy, 'latency-guarded-cost');
+  assert.equal(decision.reason.latencyGuardExcludedACandidate, true);
+
+  delete process.env.ROUTER_STRATEGY;
+});
+
+test('ROUTER_STRATEGY=latency-guarded-cost keeps a candidate that is only modestly slower, and still picks by cost', async () => {
+  const logPath = tempLogPath();
+  process.env.ROUTER_STRATEGY = 'latency-guarded-cost';
+  const { metrics, router } = freshModules(logPath);
+
+  // 150ms is only 1.5x anthropic's 100ms - comfortably inside the
+  // default 3x guard multiplier, so openai stays in the pool and wins
+  // on cost as usual.
+  for (let i = 0; i < 5; i++) metrics.record({ provider: 'openai', latency_ms: 150 });
+  for (let i = 0; i < 5; i++) metrics.record({ provider: 'anthropic', latency_ms: 100 });
+  await flush();
+
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.equal(decision.model, 'gpt-4o-mini');
+  assert.equal(decision.reason.latencyGuardExcludedACandidate, false);
+
+  delete process.env.ROUTER_STRATEGY;
+});
+
+test('ROUTER_STRATEGY=latency-guarded-cost degrades to plain cost when there is no latency data yet', async () => {
+  process.env.ROUTER_STRATEGY = 'latency-guarded-cost';
+  const { router } = freshModules(tempLogPath()); // no history at all
+
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.equal(decision.model, 'gpt-4o-mini'); // nothing to guard against yet
+  assert.equal(decision.reason.latencyGuardExcludedACandidate, false);
+
+  delete process.env.ROUTER_STRATEGY;
+});
+
+test('an unrecognized ROUTER_STRATEGY value falls back to "cost" rather than erroring', async () => {
+  process.env.ROUTER_STRATEGY = 'fastest-vibes';
+  const { router } = freshModules(tempLogPath());
+
+  const decision = await router.pickCandidate('router:fast-cheap');
+  assert.equal(decision.reason.strategy, 'cost');
+  assert.equal(decision.model, 'gpt-4o-mini');
+
+  delete process.env.ROUTER_STRATEGY;
+});

package/test/semanticCache.test.js

@@ -0,0 +1,167 @@
+// Exercises the real storage/lookup machinery (list writes, trimming,
+// cosine-similarity scoring) against an actual Redis instance, not a
+// mock - this test file spins up its own throwaway redis-server for
+// the duration of the run so `npm test` stays self-contained. It never
+// calls a real embedding API: a deterministic fake embedder is injected
+// via the `embeddings` option both findMatch() and store() accept, so
+// the similarity math is genuinely exercised without needing
+// OPENAI_API_KEY or network access.
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawn } = require('child_process');
+const net = require('net');
+
+let redisProcess;
+let redisClient;
+let semanticCache;
+let cache;
+
+function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.listen(0, () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+    srv.on('error', reject);
+  });
+}
+
+function waitForRedisReady(proc) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('redis-server did not become ready in time')), 10_000);
+    proc.stdout.on('data', (chunk) => {
+      if (chunk.toString().includes('Ready to accept connections')) {
+        clearTimeout(timeout);
+        resolve();
+      }
+    });
+    proc.on('error', reject);
+  });
+}
+
+// A small fixed-dimension deterministic "embedding": each word maps to
+// a pseudo-random but stable vector slot via a simple hash, so two
+// texts sharing words end up with similar vectors and unrelated texts
+// don't - enough to exercise cosine-similarity thresholding
+// meaningfully without a real embedding model.
+function fakeEmbed(text) {
+  const dims = 32;
+  const vec = new Array(dims).fill(0);
+  for (const word of text.toLowerCase().split(/\W+/).filter(Boolean)) {
+    let h = 0;
+    for (let i = 0; i < word.length; i++) h = (h * 31 + word.charCodeAt(i)) >>> 0;
+    vec[h % dims] += 1;
+  }
+  return Promise.resolve(vec);
+}
+
+const fakeEmbeddings = { isEnabled: () => true, embed: fakeEmbed };
+
+before(async () => {
+  const port = await getFreePort();
+  process.env.REDIS_URL = `redis://127.0.0.1:${port}`;
+  redisProcess = spawn('redis-server', ['--port', String(port), '--save', '', '--appendonly', 'no'], {
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  await waitForRedisReady(redisProcess);
+
+  redisClient = require('../redisClient');
+  await redisClient.ready;
+  semanticCache = require('../semanticCache');
+  cache = require('../cache');
+});
+
+after(async () => {
+  try { await redisClient.client.quit(); } catch { /* already closed */ }
+  if (redisProcess) redisProcess.kill();
+});
+
+test('isEnabled() is true once Redis is connected and embeddings report enabled', () => {
+  assert.equal(semanticCache.isEnabled(fakeEmbeddings), true);
+});
+
+test('isEnabled() is false when embeddings are disabled, even with Redis connected', () => {
+  assert.equal(semanticCache.isEnabled({ isEnabled: () => false }), false);
+});
+
+test('the exact-match cache (cache.js) still works over the same shared connection', async () => {
+  const payload = { model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'shared connection check' }] };
+  assert.equal(await cache.get(payload), null);
+  await cache.set(payload, { provider: 'openai', model: 'gpt-4o-mini', content: 'ok' });
+  const hit = await cache.get(payload);
+  assert.equal(hit.content, 'ok');
+});
+
+test('findMatch() returns null when nothing has been stored yet', async () => {
+  const payload = { model: 'router-test-model-empty', messages: [{ role: 'user', content: 'is anyone there' }] };
+  const result = await semanticCache.findMatch(payload, { embeddings: fakeEmbeddings });
+  assert.equal(result, null);
+});
+
+test('store() then findMatch() with the identical prompt finds a match (similarity ~1)', async () => {
+  const model = 'router-test-model-identical';
+  const payload = { model, messages: [{ role: 'user', content: 'how do I reset my password' }] };
+  const entry = { provider: 'openai', model, content: 'Go to Settings > Security > Reset password.' };
+
+  const stored = await semanticCache.store(payload, entry, { embeddings: fakeEmbeddings });
+  assert.equal(stored, true);
+
+  const match = await semanticCache.findMatch(payload, { embeddings: fakeEmbeddings });
+  assert.ok(match, 'expected a match for the identical prompt');
+  assert.equal(match.entry.content, entry.content);
+  assert.ok(match.similarity > 0.99, `expected near-1 similarity, got ${match.similarity}`);
+});
+
+test('findMatch() does not match an unrelated prompt under the same model', async () => {
+  const model = 'router-test-model-unrelated';
+  const stored = { model, messages: [{ role: 'user', content: 'how do I reset my password' }] };
+  await semanticCache.store(stored, { provider: 'openai', model, content: 'reset password steps' }, { embeddings: fakeEmbeddings });
+
+  const unrelated = { model, messages: [{ role: 'user', content: 'what is the weather in Tokyo tomorrow' }] };
+  const match = await semanticCache.findMatch(unrelated, { embeddings: fakeEmbeddings, threshold: 0.93 });
+  assert.equal(match, null);
+});
+
+test('findMatch()/store() skip tool-calling requests entirely (never cached, never matched)', async () => {
+  const model = 'router-test-model-tools';
+  const payload = {
+    model,
+    messages: [{ role: 'user', content: 'call the tool' }],
+    tools: [{ type: 'function', function: { name: 'do_thing' } }]
+  };
+  const stored = await semanticCache.store(payload, { provider: 'openai', model, content: 'x' }, { embeddings: fakeEmbeddings });
+  assert.equal(stored, false);
+
+  const match = await semanticCache.findMatch(payload, { embeddings: fakeEmbeddings });
+  assert.equal(match, null);
+});
+
+test('per-model list is trimmed to SEMANTIC_CACHE_MAX_CANDIDATES', async () => {
+  const originalMax = process.env.SEMANTIC_CACHE_MAX_CANDIDATES;
+  process.env.SEMANTIC_CACHE_MAX_CANDIDATES = '3';
+  delete require.cache[require.resolve('../semanticCache')];
+  const scopedSemanticCache = require('../semanticCache');
+
+  const model = 'router-test-model-trim';
+  for (let i = 0; i < 5; i++) {
+    await scopedSemanticCache.store(
+      { model, messages: [{ role: 'user', content: `distinct prompt number ${i}` }] },
+      { provider: 'openai', model, content: `answer ${i}` },
+      { embeddings: fakeEmbeddings }
+    );
+  }
+
+  const length = await redisClient.client.lLen(`SEMANTIC_LIST:${model}`);
+  assert.equal(length, 3);
+
+  if (originalMax === undefined) delete process.env.SEMANTIC_CACHE_MAX_CANDIDATES;
+  else process.env.SEMANTIC_CACHE_MAX_CANDIDATES = originalMax;
+});
+
+test('cosineSimilarity() is 1 for identical vectors and 0 for orthogonal ones', () => {
+  assert.equal(semanticCache.cosineSimilarity([1, 0], [1, 0]), 1);
+  assert.equal(semanticCache.cosineSimilarity([1, 0], [0, 1]), 0);
+  assert.equal(semanticCache.cosineSimilarity([1, 0], [0, 0]), 0); // zero vector is defined as no similarity, not NaN
+});