Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.6 KB
Raw Blame
/**
 * Per-process query-embedding cache in gateway.embedQuery.
 *
 * A counting fake transport stands in for the provider ($0, no keys). Pins:
 *  - a repeat query makes 0 provider calls and returns an equal, independent copy;
 *  - inputs that resolve to the same provider request share an entry
 *    (default model/dims spelled out explicitly);
 *  - a different model, dimensions, query prefix or base URL misses;
 *  - TTL expiry and LRU eviction (512 entries) both force a provider call;
 *  - an aborted or failed embed is never cached;
 *  - a reconfigure while an embed is in flight keeps that vector out of the cache;
 *  - document-side embed() stays uncached.
 */

import { describe, test, expect, beforeEach, afterEach, setSystemTime } from 'bun:test';
import {
  configureGateway,
  resetGateway,
  embed,
  embedQuery,
  __setEmbedTransportForTests,
} from '../../src/core/ai/gateway.ts';
import { withAIInvocationGuard } from '../../src/core/ai/invocation-guard.ts';

const MODEL = 'openai:text-embedding-3-large';
let calls: string[] = [];
let failNext: Error | null = null;
let gate: Promise<void> | null = null;

function dimsOf(providerOptions: unknown): number {
  return (providerOptions as { openai?: { dimensions?: number } })?.openai?.dimensions ?? 1536;
}

function vectorFor(text: string, dims: number): number[] {
  let h = 0;
  for (const ch of text) h = (h * 31 + ch.charCodeAt(0)) >>> 0;
  return Array.from({ length: dims }, (_, i) => ((h + i) % 97) / 97);
}

function configure(extra: Record<string, unknown> = {}): void {
  configureGateway({ embedding_model: MODEL, embedding_dimensions: 1536, env: { OPENAI_API_KEY: 'sk-fake' }, ...extra });
  __setEmbedTransportForTests((async (args: { values: string[]; providerOptions: unknown; abortSignal?: AbortSignal }) => {
    calls.push(...args.values);
    if (gate) await gate;
    if (args.abortSignal?.aborted) throw args.abortSignal.reason ?? new Error('aborted');
    if (failNext) { const e = failNext; failNext = null; throw e; }
    const dims = dimsOf(args.providerOptions);
    return { embeddings: args.values.map(v => vectorFor(v, dims)) };
  }) as never);
}

beforeEach(() => {
  calls = [];
  failNext = null;
  gate = null;
  configure();
});

afterEach(() => {
  setSystemTime();
  __setEmbedTransportForTests(null);
  resetGateway();
});

describe('query-embed cache — hits', () => {
  test('a repeat query makes 0 provider calls and returns an equal copy', async () => {
    const a = await embedQuery('widget roadmap');
    const b = await embedQuery('widget roadmap');
    expect(calls).toEqual(['widget roadmap']);
    expect(Array.from(b)).toEqual(Array.from(a));
    expect(b).not.toBe(a);
    a.fill(0);
    b.fill(0);
    const c = await embedQuery('widget roadmap');
    expect(Array.from(c)).toEqual(Array.from(new Float32Array(vectorFor('widget roadmap', 1536))));
    expect(calls).toHaveLength(1);
  });

  test('the configured model and dims spelled out explicitly share the entry', async () => {
    await embedQuery('widget roadmap');
    await embedQuery('widget roadmap', { embeddingModel: MODEL, dimensions: 1536 });
    await embedQuery('roadmap', { queryPrefix: 'widget ' });
    expect(calls).toEqual(['widget roadmap']);
  });
});

describe('query-embed cache — AI invocation guards', () => {
  test('a guarded caller is admitted by its guard, never served from the cache', async () => {
    await embedQuery('widget roadmap');
    const admitted: string[] = [];
    await withAIInvocationGuard(async call => {
      admitted.push(call.kind);
      return { settle: async () => {} };
    }, () => embedQuery('widget roadmap'));
    expect(admitted).toEqual(['embedding']);
    expect(calls).toEqual(['widget roadmap', 'widget roadmap']);
    const refusal = new Error('spend refused');
    await expect(withAIInvocationGuard(async () => { throw refusal; }, () => embedQuery('widget roadmap'))).rejects.toThrow();
    await embedQuery('widget roadmap');
    expect(calls).toHaveLength(2);
  });
});

describe('query-embed cache — misses', () => {
  test('a different model, dimensions or query prefix misses', async () => {
    await embedQuery('widget roadmap');
    await embedQuery('widget roadmap', { embeddingModel: 'openai:text-embedding-3-small', dimensions: 1536 });
    await embedQuery('widget roadmap', { dimensions: 1024 });
    await embedQuery('widget roadmap', { queryPrefix: 'query: ' });
    expect(calls).toEqual(['widget roadmap', 'widget roadmap', 'widget roadmap', 'query: widget roadmap']);
    const v = await embedQuery('widget roadmap', { dimensions: 1024 });
    expect(v.length).toBe(1024);
    expect(calls).toHaveLength(4);
  });

  test('the exact query string keys the entry: case and whitespace miss', async () => {
    await embedQuery('widget roadmap');
    await embedQuery('Widget roadmap');
    await embedQuery('widget roadmap ');
    expect(calls).toEqual(['widget roadmap', 'Widget roadmap', 'widget roadmap ']);
  });

  test('a different base URL misses (and any reconfigure starts empty)', async () => {
    await embedQuery('widget roadmap');
    configure({ base_urls: { openai: 'http://127.0.0.1:9/v1' } });
    await embedQuery('widget roadmap');
    configure();
    await embedQuery('widget roadmap');
    expect(calls).toHaveLength(3);
  });

  test('an entry expires after 10 minutes', async () => {
    const t0 = Date.now();
    setSystemTime(new Date(t0));
    await embedQuery('widget roadmap');
    setSystemTime(new Date(t0 + 10 * 60_000 - 1));
    await embedQuery('widget roadmap');
    expect(calls).toHaveLength(1);
    setSystemTime(new Date(t0 + 10 * 60_000 + 1));
    await embedQuery('widget roadmap');
    expect(calls).toHaveLength(2);
  });

  test('the least recently used entry is evicted past 512 entries', async () => {
    await embedQuery('q-0');
    await embedQuery('q-1');
    for (let i = 2; i < 512; i++) await embedQuery(`q-${i}`);
    await embedQuery('q-0');
    expect(calls).toHaveLength(512);
    await embedQuery('q-512');
    await embedQuery('q-0');
    expect(calls).toHaveLength(513);
    await embedQuery('q-1');
    expect(calls).toHaveLength(514);
    expect(calls.at(-1)).toBe('q-1');
  });

  test('document-side embed() is never cached', async () => {
    await embed(['widget roadmap']);
    await embed(['widget roadmap']);
    expect(calls).toHaveLength(2);
  });
});

describe('query-embed cache — failures are not cached', () => {
  test('an aborted embed is not cached and does not poison the next caller', async () => {
    const ctl = new AbortController();
    ctl.abort(new Error('caller gave up'));
    await expect(embedQuery('widget roadmap', { abortSignal: ctl.signal })).rejects.toThrow();
    const v = await embedQuery('widget roadmap');
    expect(Array.from(v)).toEqual(Array.from(new Float32Array(vectorFor('widget roadmap', 1536))));
    expect(calls).toHaveLength(2);
    await embedQuery('widget roadmap');
    expect(calls).toHaveLength(2);
  });

  test('a failed embed is not cached', async () => {
    failNext = new Error('provider 500');
    await expect(embedQuery('widget roadmap')).rejects.toThrow();
    await embedQuery('widget roadmap');
    await embedQuery('widget roadmap');
    expect(calls).toHaveLength(2);
  });

  test('a reconfigure during an in-flight embed keeps its vector out of the new cache', async () => {
    let release!: () => void;
    gate = new Promise<void>(r => { release = r; });
    const pending = embedQuery('widget roadmap');
    while (calls.length === 0) await new Promise(r => setTimeout(r, 1));
    configure();
    gate = null;
    release();
    await pending;
    await embedQuery('widget roadmap');
    expect(calls).toHaveLength(2);
  });
});