Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
20.7 KB
Raw Blame
/**
 * #5888 — automatic capture must not store a second copy of a claim the agent
 * just saved, must never drop a correction, and hot memory injects one line
 * per duplicate group.
 *
 * Protects (each case runs on the unmanaged writer and through the real
 * managed coordinator, PGLite): the reproduced `remember` + writeback pair on
 * two entities ends with one active row; a lagging corpus sweep of the same
 * conversation dedups across lanes; negation and changed-number pairs at an
 * injected cosine of 0.97 both survive; a 0.93 paraphrase is kept and counted
 * in shadow mode only; subject-relative claims for two people stay two
 * facts; the 15-minute window, the visibility rule and fail-open hold.
 * Fails when: dedup stays per entity (2d8801b4), a capture lane drops by
 * cosine, or the dedup read error aborts the write.
 * Existing coverage: none at this boundary (dedup tests were per entity).
 * Seams: chat + embedding transports only. Synthetic names only.
 * Backends: PGLite here; with a safe DATABASE_URL also Postgres
 * (test/e2e/capture-dedup-postgres.test.ts). The managed arm runs on a source
 * with a claimed worktree, so every write goes through the coordinator.
 */
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { acquireWorktree, claimWorktree, getWorktreeBinding, MANAGED_WRITER_PROBE_WAIT_MS } from '../src/core/persistence/ownership.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';
import { asOwner } from './helpers/owner-tier.ts';
import { configureGateway, resetGateway, __setChatTransportForTests, __setEmbedTransportForTests } from '../src/core/ai/gateway.ts';
import { runFactsPipeline, type FactsBackstopCtx } from '../src/core/facts/backstop.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { disposePersistenceConsumer, persistenceConsumerStatus } from '../src/core/persistence/service.ts';
import { getBrainHotMemoryMeta, __resetHotMemoryCacheForTests } from '../src/core/facts/meta-hook.ts';
import { readHeartbeatTail } from '../src/core/context/hook-heartbeat.ts';
import { buildMemoryWritebackCheck } from '../src/commands/doctor/checks/memory-writeback.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { assembleDeltaContext } from '../src/core/context/turn-context.ts';

const DIM = 1536;
const MODEL = 'openai:text-embedding-3-large';
const ENTITIES = [['people/alice-example', 'Alice Example', 'person'], ['people/bob-example', 'Bob Example', 'person'],
  ['companies/acme-example', 'Acme Example', 'company']] as const;
let engine: BrainEngine;
let sourceId: string;
let home: string;
const vectors = new Map<string, number[]>();
let nextAxis = 2;

/** Unit vector at the given cosine to the shared base axis; unknown texts get their own axis. */
function at(cosine: number): number[] {
  const v = Array(DIM).fill(0);
  v[0] = cosine;
  v[nextAxis++] = Math.sqrt(1 - cosine * cosine);
  return v;
}
function embedding(text: string): number[] {
  if (!vectors.has(text)) { const v = Array(DIM).fill(0); v[nextAxis++] = 1; vectors.set(text, v); }
  return vectors.get(text)!;
}
function extracts(facts: Array<{ fact: string; entity: string | null }>) {
  __setChatTransportForTests(async () => ({
    text: JSON.stringify({ facts: facts.map(f => ({ ...f, kind: 'fact', confidence: 1, notability: 'high' })) }),
    blocks: [], stopReason: 'end', model: 'test:stub', providerId: 'test',
    usage: { input_tokens: 1, output_tokens: 1, cache_read_tokens: 0, cache_creation_tokens: 0 },
  }));
}
/**
 * Waits until this engine's persistence consumer has finished every claimed
 * publication: a receipt reads committed before the publishing task releases
 * the worktree lock, so the next step must not race that tail.
 */
async function settled() {
  for (const deadline = Date.now() + 10_000; Date.now() < deadline; await new Promise(r => setTimeout(r, 10))) {
    const s = persistenceConsumerStatus(engine);
    if (s.active_preparations === 0 && s.active_worktrees === 0) return;
  }
  throw new Error('persistence consumer did not settle');
}
async function capture(source: FactsBackstopCtx['source'], sessionId: string | null, extra: Partial<FactsBackstopCtx> = {}) {
  const r = await runFactsPipeline(`A synthetic turn ${Math.random()}`, { engine, sourceId, sessionId, source, mode: 'inline', remote: false, ...extra });
  await settled();
  return r;
}
async function remember(fact: string, entity: string) {
  const r = await dispatchToolCall(engine, 'remember', { fact, entity, provenance: 'user told me' }, { remote: false, sourceId });
  expect(r.isError).toBeFalsy();
  await settled();
}
async function active() {
  return engine.executeRaw<{ id: number; fact: string; entity_slug: string | null; visibility: string; source: string }>(
    'SELECT id::int AS id,fact,entity_slug,visibility,source FROM facts WHERE source_id=$1 AND expired_at IS NULL ORDER BY id', [sourceId]);
}
async function withGuardPaused(edit: () => Promise<unknown>) {
  const [{ enabled }] = await engine.executeRaw<{ enabled: boolean }>('SELECT enabled FROM persistence_brain WHERE singleton=1');
  if (enabled) { await disposePersistenceConsumer(engine); await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1'); }
  try { await edit(); } finally { if (enabled) await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1'); }
}
/** Backdates a fixture row; a managed brain's writer guard is paused for the edit, as the connector fixture does. */
async function age(fact: string, minutes: number) {
  await withGuardPaused(() => engine.executeRaw(`UPDATE facts SET created_at=now()-($3::int * interval '1 minute') WHERE source_id=$1 AND fact=$2`,
    [sourceId, fact, minutes]));
  await settled();
}
async function hotFacts() {
  __resetHotMemoryCacheForTests();
  const meta = await getBrainHotMemoryMeta('search', { engine, remote: false, sourceId } as OperationContext);
  return ((meta?.brain_hot_memory as { facts: Array<{ fact: string; entity_slug: string | null; entity_slugs?: string[] }> } | undefined)?.facts) ?? [];
}
/** A fresh source with the three synthetic entity pages; `managed` claims a worktree so writes go through the coordinator. */
async function freshSource(mode: 'unmanaged' | 'managed') {
  sourceId = `cd-${randomUUID().slice(0, 8)}`;
  const root = mkdtempSync(join(home, 'root-'));
  await disposePersistenceConsumer(engine);
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [sourceId, mode === 'managed' ? root : null]);
  if (mode === 'managed') {
    await claimWorktree(engine, sourceId, root);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  }
  for (const [slug, title, type] of ENTITIES) {
    const body = `${title} is a synthetic entity.`;
    if (mode === 'unmanaged') { await engine.putPage(slug, { type, title, compiled_truth: body }, { sourceId }); continue; }
    const r = await dispatchToolCall(engine, 'put_page', { slug, content: `---\ntitle: ${title}\ntype: ${type}\n---\n\n${body}\n` }, { remote: false, sourceId });
    expect(r.isError).toBeFalsy();
  }
  await settled();
}

for (const backend of testBackends()) describe(`capture dedup on ${backend}`, () => {
let close: (() => Promise<void>) | undefined;
beforeAll(async () => {
  if (backend === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
  else { const pglite = new PGLiteEngine(); await pglite.connect({}); await pglite.initSchema(); engine = pglite; }
  await engine.setConfig('embedding_model', MODEL);
  await engine.setConfig('embedding_dimensions', String(DIM));
  // #6091: capture-lane facts are admitted only while memory.auto_writeback allows the lane.
  await engine.setConfig('memory.auto_writeback', 'all');
}, 120_000);
afterAll(async () => { await disposePersistenceConsumer(engine); if (close) await close(); else await engine.disconnect(); });
beforeEach(() => {
  home = mkdtempSync(join(tmpdir(), 'gbrain-capture-dedup-'));
  vectors.clear();
  configureGateway({ embedding_model: MODEL, embedding_dimensions: DIM, env: { OPENAI_API_KEY: 'synthetic-only' } });
  __setEmbedTransportForTests((async ({ values }: { values: string[] }) => ({ values, warnings: [], usage: { tokens: 1 },
    embeddings: values.map(embedding) })) as never);
});
afterEach(async () => {
  __setChatTransportForTests(null); __setEmbedTransportForTests(null); resetGateway();
  await disposePersistenceConsumer(engine);
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  rmSync(home, { recursive: true, force: true });
});

for (const mode of ['unmanaged', 'managed'] as const) {
  describe(`capture dedup (${mode})`, () => {
    const run = (fn: () => Promise<void>) => withEnv({ GBRAIN_HOME: home }, async () => { await freshSource(mode); await fn(); });

    if (mode === 'managed') {
      // The preflight waits up to MANAGED_WRITER_PROBE_WAIT_MS for the worktree
      // lock: a writer finishing its previous publication is not a conflict.
      const holdLock = async (ms: number) => {
        const lock = await acquireWorktree((await getWorktreeBinding(engine, sourceId))!, 0, undefined, engine);
        expect(lock).not.toBeNull();
        return { released: new Promise<void>(resolve => setTimeout(() => { void lock!.release().then(resolve); }, ms)) };
      };
      test('the fact preflight waits out a writer that releases within the bound', () => run(async () => {
        const { released } = await holdLock(200);
        extracts([{ fact: 'Bob Example owns the Acme Example launch checklist', entity: 'people/bob-example' }]);
        expect(await capture('hook:writeback', 'sess-lock')).toMatchObject({ inserted: 1 });
        await released;
      }), 60_000);
      test('a writer busy past the bound still refuses with writer_lock_unavailable', () => run(async () => {
        const { released } = await holdLock(MANAGED_WRITER_PROBE_WAIT_MS + 1500);
        extracts([{ fact: 'Bob Example owns the Acme Example budget review', entity: 'people/bob-example' }]);
        await expect(capture('hook:writeback', 'sess-lock-2')).rejects.toMatchObject({ code: 'writer_lock_unavailable' });
        await released;
      }), 60_000);
    }

    test('remember then a writeback of the same claim on another entity ends with one active row and one hot fact', () => run(async () => {
      const claim = 'Alice Example will lead the Acme Example renewal in November';
      await remember(claim, 'people/alice-example');
      extracts([{ fact: claim, entity: 'companies/acme-example' }]);
      const r = await capture('hook:writeback', 'sess-1');
      expect(r).toMatchObject({ inserted: 0, duplicate: 1 });
      expect((await active()).map(f => [f.entity_slug, f.visibility])).toEqual([['people/alice-example', 'world']]);
      expect((await hotFacts()).map(f => f.entity_slug)).toEqual(['people/alice-example']);
      expect((await readHeartbeatTail(50)).filter(e => e.event === 'writeback_dedup').map(e => [e.reason, e.duplicate]))
        .toEqual([['hook:writeback', 1]]);
      const check = await buildMemoryWritebackCheck(engine);
      expect(check.details).toMatchObject({ cross_lane_duplicates_7d: 1, near_duplicates_shadow_7d: 0 });
    }), 60_000);

    test('the turn time anchors the window: a late sweep of a turn written next to remember still dedups', () => run(async () => {
      const claim = 'Alice Example signed the Acme Example contract';
      await remember(claim, 'people/alice-example');
      await age(claim, 120);
      extracts([{ fact: claim, entity: 'companies/acme-example' }]);
      expect(await capture('hook:writeback', 'sess-2', { turnAt: new Date(Date.now() - 115 * 60_000) })).toMatchObject({ inserted: 0, duplicate: 1 });
      expect(await capture('hook:writeback', 'sess-2')).toMatchObject({ inserted: 1, duplicate: 0 });
    }), 60_000);

    test('a corpus sweep two hours after writeback of the same conversation dedups across lanes; another conversation does not', () => run(async () => {
      const claim = 'Alice Example joined the Acme Example board';
      extracts([{ fact: claim, entity: 'people/alice-example' }]);
      expect(await capture('hook:writeback', 'sess-9')).toMatchObject({ inserted: 1 });
      await age(claim, 120);
      extracts([{ fact: claim, entity: 'companies/acme-example' }]);
      expect(await capture('sweep:corpus', 'sweep:corpus:sess-9.txt')).toMatchObject({ inserted: 0, duplicate: 1 });
      expect(await capture('sweep:corpus', 'sweep:corpus:sess-other.txt')).toMatchObject({ inserted: 1, duplicate: 0 });
      expect((await active()).length).toBe(2);
    }), 60_000);

    test('negation and changed-number pairs at cosine 0.97 on one entity both survive', () => run(async () => {
      const pairs = [['Alice Example is moving to NYC', 'Alice Example is not moving to NYC'], ['Acme Example MRR is $50k', 'Acme Example MRR is $60k']];
      for (const [first, second] of pairs) {
        vectors.set(first, at(1));
        vectors.set(second, at(0.97));
        extracts([{ fact: first, entity: 'companies/acme-example' }]);
        expect(await capture('hook:writeback', 'sess-3')).toMatchObject({ inserted: 1 });
        extracts([{ fact: second, entity: 'companies/acme-example' }]);
        expect(await capture('hook:writeback', 'sess-3')).toMatchObject({ inserted: 1, duplicate: 0 });
      }
      expect((await active()).map(f => f.fact)).toEqual(pairs.flat());
      if (mode === 'managed') {
        const published = await engine.executeRaw<{ n: number }>(`SELECT count(*)::int AS n FROM persistence_requests WHERE source_id=$1
          AND operation='extract_facts' AND state='committed' AND intent->>'kind'='managed_facts_entity'`, [sourceId]);
        expect(published[0].n).toBe(4);
      }
      expect((await readHeartbeatTail(50)).filter(e => e.event === 'writeback_dedup')).toEqual([]);
    }), 60_000);

    test('a same-entity paraphrase at cosine 0.93 is kept and counted in shadow mode only', () => run(async () => {
      vectors.set('Alice Example prefers async updates', at(1));
      vectors.set('Alice Example likes asynchronous updates', at(0.93));
      extracts([{ fact: 'Alice Example prefers async updates', entity: 'people/alice-example' }]);
      await capture('hook:compact', 'sess-4');
      extracts([{ fact: 'Alice Example likes asynchronous updates', entity: 'people/alice-example' }]);
      expect(await capture('hook:compact', 'sess-4')).toMatchObject({ inserted: 1, duplicate: 0 });
      expect((await active()).length).toBe(2);
      expect((await readHeartbeatTail(50)).filter(e => e.event === 'writeback_dedup').map(e => [e.reason, e.duplicate, e.near_duplicate]))
        .toEqual([['hook:compact', 0, 1]]);
      expect((await buildMemoryWritebackCheck(engine)).details).toMatchObject({ cross_lane_duplicates_7d: 0, near_duplicates_shadow_7d: 1 });
    }), 60_000);

    test('a subject-relative claim for two people in one session stays two facts', () => run(async () => {
      extracts([{ fact: 'Prefers email', entity: 'people/alice-example' }, { fact: 'Prefers email', entity: 'people/bob-example' }]);
      expect(await capture('hook:writeback', 'sess-5')).toMatchObject({ inserted: 2, duplicate: 0 });
      extracts([{ fact: 'Prefers email', entity: 'people/bob-example' }]);
      expect(await capture('hook:writeback', 'sess-5')).toMatchObject({ inserted: 0, duplicate: 1 });
      expect((await active()).map(f => f.entity_slug)).toEqual(['people/alice-example', 'people/bob-example']);
      expect((await hotFacts()).length).toBe(2);
    }), 60_000);

    test('visibility and time bounds: world candidates ignore private facts; a different session 16 minutes later is kept', () => run(async () => {
      const claim = 'Bob Example runs the Acme Example offsite';
      extracts([{ fact: claim, entity: 'people/bob-example' }]);
      expect(await capture('hook:writeback', 'sess-6')).toMatchObject({ inserted: 1 });
      expect(await capture('hook:writeback', 'sess-7', { visibility: 'world' })).toMatchObject({ inserted: 1, duplicate: 0 });
      const later = 'Bob Example owns the Acme Example budget';
      await remember(later, 'people/bob-example');
      await age(later, 16);
      extracts([{ fact: later, entity: 'people/bob-example' }]);
      expect(await capture('hook:writeback', 'sess-8')).toMatchObject({ inserted: 1, duplicate: 0 });
      expect((await active()).map(f => [f.fact === claim, f.visibility])).toEqual([[true, 'private'], [true, 'world'], [false, 'world'], [false, 'private']]);
    }), 60_000);

    test('a dedup read failure inserts the candidate and warns with the lane', () => run(async () => {
      const claim = 'Alice Example reviews the Acme Example budget';
      await remember(claim, 'people/alice-example');
      extracts([{ fact: claim, entity: 'companies/acme-example' }]);
      // Transaction handles inherit from the engine, so the wrapper keeps `this`.
      const original = Object.getPrototypeOf(engine).executeRaw as BrainEngine['executeRaw'];
      const warnings: string[] = [];
      const warn = console.warn;
      engine.executeRaw = function (this: BrainEngine, sql: string, ...rest: unknown[]) {
        if (sql.includes('gbrain_fact_fingerprint($3) AND expired_at IS NULL')) return Promise.reject(new Error('forced read failure'));
        return (original as (...args: unknown[]) => Promise<unknown>).call(this, sql, ...rest);
      } as typeof engine.executeRaw;
      console.warn = (...args: unknown[]) => { warnings.push(args.join(' ')); };
      try {
        expect(await capture('hook:writeback', 'sess-10')).toMatchObject({ inserted: 1, duplicate: 0 });
      } finally {
        delete (engine as { executeRaw?: unknown }).executeRaw;
        console.warn = warn;
      }
      expect(warnings.some(w => w.includes('capture dedup read failed: lane=hook:writeback'))).toBe(true);
      expect((await active()).length).toBe(2);
    }), 60_000);

    test('explicit remember is never dropped; hot memory collapses the identical pair (accepted residual S2)', () => run(async () => {
      const claim = 'Alice Example chairs the Acme Example review';
      extracts([{ fact: claim, entity: 'people/alice-example' }]);
      await capture('hook:writeback', 'sess-11');
      await remember(claim, 'people/alice-example');
      expect((await active()).map(f => f.visibility)).toEqual(['private', 'world']);
      const hot = await hotFacts();
      expect(hot.map(f => [f.fact, f.entity_slug])).toEqual([[claim, 'people/alice-example']]);
    }), 60_000);
  });
}

describe('hot memory collapse (V2)', () => {
  const insert = (fact: string, entity_slug: string) => asOwner(engine, tx => tx.insertFact({ fact, entity_slug, source: 'fixture', visibility: 'world' }, { source_id: sourceId }));

  test('an identical claim on two entities that names one of them injects once with both labels; distinct facts still fill topK', () => withEnv({ GBRAIN_HOME: home }, async () => {
    await freshSource('unmanaged');
    const claim = 'Alice Example will lead the Acme Example renewal in November';
    await insert(claim, 'people/alice-example');
    const newest = await insert(claim, 'companies/acme-example');
    await insert('Prefers email', 'people/alice-example');
    await insert('Prefers email', 'people/bob-example');
    for (let i = 1; i <= 3; i++) await insert(`Distinct synthetic fact number ${i}`, 'people/bob-example');
    __resetHotMemoryCacheForTests();
    const meta = await getBrainHotMemoryMeta('search', { engine, remote: true, sourceId } as OperationContext, { topK: 6 });
    const facts = (meta!.brain_hot_memory as { facts: Array<{ id: number; fact: string; entity_slug: string; entity_slugs?: string[] }> }).facts;
    expect(facts.length).toBe(6);
    const renewal = facts.filter(f => f.fact === claim);
    expect(renewal).toEqual([expect.objectContaining({ id: newest.id, entity_slug: 'companies/acme-example', entity_slugs: ['companies/acme-example', 'people/alice-example'] })]);
    expect(facts.filter(f => f.fact === 'Prefers email').map(f => [f.entity_slug, f.entity_slugs])).toEqual([['people/bob-example', undefined], ['people/alice-example', undefined]]);
    const delta = await assembleDeltaContext(engine, { sourceId, since: new Date(Date.now() - 60_000).toISOString() } as never);
    expect(delta.facts!.filter(f => f.fact === claim).map(f => f.entity_slugs)).toEqual([['companies/acme-example', 'people/alice-example']]);
  }), 60_000);
});
});