Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.5 KB
Raw Blame
/**
 * C5 (cost wave): search skips the saved-facts scan and the declared-name
 * scan cheaply when there is nothing to find, and changes nothing when there
 * is. The golden below was captured on the build before C5 (the cost wave's
 * C3+C4 commit) with GBRAIN_TEST_UPDATE_GOLDENS=1; it holds the full MCP
 * result (content[0], every notice block and _meta.retrieval) for searches
 * and queries on a brain with active saved facts and declared other names,
 * including one that fans out to the other name, plus the same searches on a
 * brain with neither. Regenerate only on a build whose search output is meant
 * to change, and say why in the commit. The query facts arm
 * (`search.query_facts_arm`, default on) and the query facts block
 * (`search.query_facts_block`, default on) change query output on purpose, so
 * these brains pin both off; test/search-facts-arm.test.ts and
 * test/search-8k-conversion.test.ts cover them.
 *
 * Also: a fact saved with `remember` is found by the next search in the same
 * process, and by a search after another process saved it (no per-process
 * cache can hide a fresh fact).
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { serializeMarkdown } from '../src/core/markdown.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { aliasDeclarations } from '../src/core/ops/search.ts';
import { withEnv } from './helpers/with-env.ts';
import { asOwner } from './helpers/owner-tier.ts';

const GOLDEN = join(import.meta.dir, 'fixtures/goldens/search-c5/notices.json');
/** The remote write path the fresh-fact probes save through. */
const WRITER = { remote: true, transport: 'http' as const, sourceId: 'default' };
/** A full-surface HTTP client with a read grant: `fetch` is callable, so lean rows keep `id`. */
const REMOTE = { ...WRITER, auth: { token: 't', clientId: 'c5-client', clientName: 'c5', scopes: ['read'], expiresAt: Date.now() / 1000 + 3600 } };

const PAGES: Array<[string, string, string]> = [
  ['crm/numbat-labs', 'CRM record: Numbat Labs', 'Account record. Account code: NULA. Segment: mid-market. Billing contact: Old Person.'],
  ['contracts/numbat-labs-msa', 'MSA: Numbat Labs', 'Master services agreement with Numbat Labs (account code NULA). Payment terms: Net 45.'],
  ['contracts/amendment-one', 'Amendment No. 1: NULA', 'Executed amendment for NULA: payment terms change to Net 30.'],
  ['crm/ocelot-freight', 'CRM record: Ocelot Freight', 'Account record for Ocelot Freight, also known as OCFR. Renewal owner: the platform team.'],
  ['notes/renewal-playbook', 'Renewal playbook', 'Confirm the billing contact, check payment terms, send the renewal quote 60 days before the term ends.'],
];
const FACTS = `INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source, valid_from) VALUES
  ('default', 'numbat-labs', 'The billing contact for Numbat Labs is New Person.', 'fact', 'world', 'user update', '2026-09-01'),
  ('default', 'ocelot-freight', 'Ocelot Freight renewal moves to the platform team.', 'fact', 'world', 'user update', '2026-09-02'),
  ('default', 'numbat-labs', 'Numbat Labs payment terms are disputed.', 'fact', 'private', 'user update', '2026-09-03')`;
const CALLS: Array<[string, Record<string, unknown>]> = [
  ['search', { query: 'NULA billing contact' }],
  ['search', { query: 'Numbat Labs payment terms' }],
  ['search', { query: 'OCFR renewal' }],
  ['search', { query: 'renewal quote' }],
  ['query', { query: 'Numbat Labs payment terms', expand: false }],
  ['query', { query: 'OCFR renewal owner', expand: false }],
];

/** Opens an engine; assigned in beforeAll (the canonical PGLite lifecycle, test/helpers/reset-pglite.ts). */
let open: (dataDir?: string) => Promise<PGLiteEngine>;

async function brain(withFactsAndNames: boolean): Promise<PGLiteEngine> {
  const engine = await open();
  await asOwner(engine, async tx => {
    for (const [slug, title, body] of PAGES) {
      const text = withFactsAndNames ? body : body.replace(/\(?account code NULA\)?|Account code: NULA\.|, also known as OCFR/g, '');
      await importFromContent(tx, slug, serializeMarkdown({}, text, '', { type: 'note', title, tags: [] }), { noEmbed: true, forceRechunk: true });
    }
    if (withFactsAndNames) await tx.executeRaw(FACTS);
  });
  await engine.setConfig('search.query_facts_arm', 'false');
  await engine.setConfig('search.query_facts_block', 'false');
  return engine;
}

async function capture(engine: PGLiteEngine): Promise<Record<string, unknown>> {
  const out: Record<string, unknown> = {};
  for (const [name, args] of CALLS) {
    const res = await withEnv({ GBRAIN_BACKUP_CHECK: '0' }, () => dispatchToolCall(engine, name, args, REMOTE));
    // Per-call stage timings vary run to run (pinned in test/search/stage-timings-ops.test.ts); the rest is compared.
    const { timings, ...retrieval } = (res._meta?.retrieval ?? {}) as Record<string, unknown>;
    expect(timings).toBeDefined();
    out[`${name} ${args.query}`] = { content: res.content.map(c => c.text), retrieval };
  }
  return out;
}

/** Dates the importer stamps from today are the only run-to-run variance. */
const stable = (v: unknown) => JSON.parse(JSON.stringify(v).replace(/\d{4}-\d{2}-\d{2}(?=\\?")/g, 'DATE'));

let withBoth: PGLiteEngine;
let withNeither: PGLiteEngine;
const opened: PGLiteEngine[] = [];
beforeAll(async () => {
  open = async (dataDir?: string) => {
    const engine = new PGLiteEngine();
    await engine.connect(dataDir ? { database_path: dataDir } : {});
    await engine.initSchema();
    opened.push(engine);
    return engine;
  };
  withBoth = await brain(true);
  withNeither = await brain(false);
}, 180_000);
afterAll(async () => { for (const engine of opened) await engine.disconnect().catch(() => {}); });

describe('byte-identical results before and after C5', () => {
  test('a brain with saved facts and declared names, and one with neither', async () => {
    const got = stable({ with: await capture(withBoth), without: await capture(withNeither) });
    if (process.env.GBRAIN_TEST_UPDATE_GOLDENS === '1') {
      mkdirSync(dirname(GOLDEN), { recursive: true });
      writeFileSync(GOLDEN, JSON.stringify(got, null, 2) + '\n');
    }
    const want = JSON.parse(readFileSync(GOLDEN, 'utf8'));
    expect(got).toEqual(want);
    // The fixture exercises what C5 must not change: a saved fact, a declared
    // name in both directions, and a fan-out that splices a page in.
    const w = got.with as Record<string, { content: string[] }>;
    expect(w['search NULA billing contact'].content.join('\n')).toContain('New Person');
    expect(w['search NULA billing contact'].content.join('\n')).toContain('NULA = Numbat Labs');
    expect(w['search Numbat Labs payment terms'].content[0]).toContain('contracts/amendment-one');
    expect(JSON.stringify(got.without)).not.toContain('Saved facts');
  });
});

describe('declaration keyword precheck', () => {
  test('a row without any declaration keyword yields nothing; one with a keyword still parses', () => {
    expect(aliasDeclarations([{ slug: 'x', title: 'Note: Thing', chunk_text: 'No other name here. THING-2 is a code.' }], 'Thing')).toEqual([]);
    for (const label of ['Account code:', 'also known as', 'aka', 'Short name:', 'Ticker:', 'Code name:', 'TICKER']) {
      expect(aliasDeclarations([{ slug: 'x', title: 'Co: Widget Co', chunk_text: `Widget Co ${label} WDGT` }], 'Widget Co pricing'), label)
        .toEqual([{ name: 'Widget Co', alias: 'WDGT', slug: 'x' }]);
    }
  });
});

describe('a fresh fact is never hidden', () => {
  test('remember then search in the same process', async () => {
    const engine = await brain(false);
    try {
      const before = await withEnv({ GBRAIN_BACKUP_CHECK: '0' }, () => dispatchToolCall(engine, 'search', { query: 'Numbat Labs escalation owner' }, REMOTE));
      expect(before.content.map(c => c.text).join('\n')).not.toContain('Saved facts');
      const saved = await withEnv({ GBRAIN_BACKUP_CHECK: '0' }, () => dispatchToolCall(engine, 'remember',
        { fact: 'The Numbat Labs escalation owner is Alice Example.', provenance: 'test', entity: 'numbat-labs' }, { ...WRITER, writeWaitMs: 30_000 }));
      expect(saved.isError, saved.content[0].text).not.toBe(true);
      const after = await withEnv({ GBRAIN_BACKUP_CHECK: '0' }, () => dispatchToolCall(engine, 'search', { query: 'Numbat Labs escalation owner' }, REMOTE));
      expect(after.content.map(c => c.text).join('\n')).toContain('escalation owner is Alice Example');
    } finally {
      await engine.disconnect();
    }
  }, 60_000);

  test('a fact saved by another process is found by the next search', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'gbrain-c5-'));
    const dataDir = join(dir, 'brain.pglite');
    try {
      let engine = await open(dataDir);
      await importFromContent(engine, 'crm/numbat-labs', serializeMarkdown({}, 'Account record for Numbat Labs.', '', { type: 'note', title: 'CRM record: Numbat Labs', tags: [] }), { noEmbed: true, forceRechunk: true });
      const before = await withEnv({ GBRAIN_BACKUP_CHECK: '0' }, () => dispatchToolCall(engine, 'search', { query: 'Numbat Labs escalation owner' }, REMOTE));
      expect(before.content.map(c => c.text).join('\n')).not.toContain('Saved facts');
      await engine.disconnect();
      const child = spawnSync('bun', ['-e', `
        const engines = await import(${JSON.stringify(join(import.meta.dir, '../src/core/pglite-engine.ts'))});
        const e = new engines.PGLiteEngine();
        await e.connect({ database_path: ${JSON.stringify(dataDir)} });
        await e.executeRaw("INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source) VALUES ('default', 'numbat-labs', 'The Numbat Labs escalation owner is Alice Example.', 'fact', 'world', 'other process')");
        await e.disconnect();`], { encoding: 'utf8', env: { ...process.env, GBRAIN_HOME: dir } });
      expect(child.status, child.stderr).toBe(0);
      engine = await open(dataDir);
      const after = await withEnv({ GBRAIN_BACKUP_CHECK: '0' }, () => dispatchToolCall(engine, 'search', { query: 'Numbat Labs escalation owner' }, REMOTE));
      expect(after.content.map(c => c.text).join('\n')).toContain('escalation owner is Alice Example');
      await engine.disconnect();
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  }, 120_000);
});