Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.3 KB
Raw Blame
/**
 * A7 readiness cost contract (test/readiness-http-cost.test.ts, named in the
 * agent operator wave spec).
 *
 * Protects: MCP initialize, whoami and write receipts call the config plane on
 * every request, and doctor / `gbrain://capabilities` call the probed tier. A
 * regression that makes the config plane touch the network or re-read the
 * lock per call, or makes the probed tier call getStats/getHealth (the #5061
 * cost class), skip its cache, double-run concurrent probes, or hang past its
 * bound, fails here.
 */
import { afterEach, describe, expect, test } from 'bun:test';
import {
  __setLockPeekForTests, configReadiness, createReadinessCache, probedReadiness, readinessTail,
  PROBED_TTL_MS, PROBE_TIMEOUT_MS, type ReadinessEntry,
} from '../src/core/readiness.ts';
import { LATEST_VERSION } from '../src/core/migrate.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import type { GBrainConfig } from '../src/core/config.ts';

interface SpyEngine { engine: BrainEngine; calls: string[] }

/** An engine that records every method touched; getStats/getHealth are forbidden. */
function spyEngine(opts: { hang?: boolean; delayMs?: number } = {}): SpyEngine {
  const calls: string[] = [];
  const target: Record<string, unknown> = {
    kind: 'pglite',
    async executeRaw(sql: string) {
      calls.push('executeRaw');
      if (opts.hang) return new Promise(() => {});
      if (opts.delayMs) await new Promise(r => setTimeout(r, opts.delayMs));
      return /count\(\*\)/i.test(sql) ? [{ n: 0 }] : [];
    },
    async getConfig(key: string) {
      calls.push('getConfig');
      return key === 'version' ? String(LATEST_VERSION) : null;
    },
  };
  const engine = new Proxy(target, {
    get(t, prop) {
      if (prop === 'getStats' || prop === 'getHealth') {
        return () => { calls.push(String(prop)); throw new Error(`${String(prop)} must never be called by readiness`); };
      }
      if (typeof prop === 'string' && !(prop in t) && prop !== 'then') calls.push(`missing:${prop}`);
      return t[prop as string];
    },
  }) as unknown as BrainEngine;
  return { engine, calls };
}

afterEach(() => __setLockPeekForTests(null));

describe('config plane cost', () => {
  test('no network, one lock read across transports and repeated calls, memoized per config object', () => {
    const realFetch = globalThis.fetch;
    let fetches = 0;
    globalThis.fetch = (async () => { fetches++; throw new Error('network'); }) as unknown as typeof fetch;
    let peeks = 0;
    __setLockPeekForTests(() => { peeks++; return { held: false }; });
    try {
      const cfg = { engine: 'pglite', database_path: '/brains/cost.pglite', embedding_disabled: true } as GBrainConfig;
      const first = configReadiness(cfg, { transport: 'stdio' });
      for (let i = 0; i < 50; i++) {
        expect(configReadiness(cfg, { transport: 'stdio' })).toBe(first);
        configReadiness(cfg, { transport: 'http' });
      }
      expect(peeks).toBe(1);
      expect(fetches).toBe(0);
      configReadiness({ ...cfg }, { transport: 'stdio' });
      expect(peeks).toBe(2);
    } finally {
      globalThis.fetch = realFetch;
    }
  });

  test('Postgres and thin-client configs never read the PGLite lock', () => {
    let peeks = 0;
    __setLockPeekForTests(() => { peeks++; return { held: false }; });
    configReadiness({ engine: 'postgres', database_url: 'postgres://x/y' } as GBrainConfig, { transport: 'stdio' });
    configReadiness({ engine: 'pglite', remote_mcp: { mcp_url: 'https://h/mcp' } } as unknown as GBrainConfig, { transport: 'http' });
    expect(peeks).toBe(0);
  });
});

describe('probed tier cost', () => {
  test('never calls getStats/getHealth and returns worker, backup, migrations', async () => {
    const { engine, calls } = spyEngine();
    const entries = await probedReadiness(engine, { cache: createReadinessCache() });
    expect(calls).not.toContain('getStats');
    expect(calls).not.toContain('getHealth');
    const caps = new Set(entries.map(e => e.capability));
    for (const c of ['worker', 'migrations', 'sync']) expect(caps.has(c as ReadinessEntry['capability'])).toBe(true);
    expect(entries.find(e => e.capability === 'migrations')).toMatchObject({ state: 'ok', reason: 'current', tier: 'probed' });
    expect(entries.every(e => e.tier === 'probed')).toBe(true);
  });

  test('60 s cache: a second call within the TTL does no engine work', async () => {
    const { engine, calls } = spyEngine();
    const cache = createReadinessCache();
    const a = await probedReadiness(engine, { cache });
    const n = calls.length;
    const b = await probedReadiness(engine, { cache });
    expect(b).toBe(a);
    expect(calls.length).toBe(n);
  });

  test('single-flight: concurrent callers share one probe run', async () => {
    const { engine, calls } = spyEngine({ delayMs: 30 });
    const cache = createReadinessCache();
    const [a, b, c] = await Promise.all([probedReadiness(engine, { cache }), probedReadiness(engine, { cache }), probedReadiness(engine, { cache })]);
    expect(b).toBe(a);
    expect(c).toBe(a);
    const solo = spyEngine();
    await probedReadiness(solo.engine, { cache: createReadinessCache() });
    expect(calls.filter(x => x === 'getConfig').length).toBe(solo.calls.filter(x => x === 'getConfig').length);
  });

  test('stale-while-revalidate: an expired entry is served at once and refreshed in the background', async () => {
    const { engine, calls } = spyEngine();
    const store = new Map<string, { at: number; value: ReadinessEntry[] }>();
    const cache = { get: (k: string) => store.get(k), set: (k: string, v: { at: number; value: ReadinessEntry[] }) => { store.set(k, v); } };
    await probedReadiness(engine, { cache });
    const [key] = [...store.keys()];
    const stale: ReadinessEntry[] = [{ capability: 'worker', state: 'unknown', reason: 'probe_failed', why: 'stale', tier: 'probed', http_visible: false }];
    store.set(key, { at: Date.now() - PROBED_TTL_MS - 1, value: stale });
    const before = calls.length;
    expect(await probedReadiness(engine, { cache })).toBe(stale);
    await new Promise(r => setTimeout(r, 100));
    expect(calls.length).toBeGreaterThan(before);
    expect(store.get(key)?.value).not.toBe(stale);
  });

  test('2 s per-probe bound: a hung probe reports probe_timeout instead of hanging', async () => {
    const { engine } = spyEngine({ hang: true });
    const started = Date.now();
    const entries = await probedReadiness(engine, { cache: createReadinessCache() });
    const elapsed = Date.now() - started;
    expect(elapsed).toBeGreaterThanOrEqual(PROBE_TIMEOUT_MS - 50);
    expect(elapsed).toBeLessThan(PROBE_TIMEOUT_MS + 1500);
    expect(entries.find(e => e.capability === 'worker')?.reason).toMatch(/^probe_(timeout|failed)$/);
    expect(entries.find(e => e.capability === 'migrations')?.reason).toBe('current');
  }, 10_000);

  test('initialize tail: undefined within 250 ms when probes are slow, entries once the cache is warm', async () => {
    const slow = spyEngine({ hang: true });
    const started = Date.now();
    expect(await readinessTail(slow.engine, { cache: createReadinessCache() })).toBeUndefined();
    expect(Date.now() - started).toBeLessThan(1000);
    const fast = spyEngine();
    const cache = createReadinessCache();
    await probedReadiness(fast.engine, { cache });
    expect(Array.isArray(await readinessTail(fast.engine, { cache }))).toBe(true);
  }, 10_000);
});