Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
19.9 KB
Raw Blame
/**
 * #6091 / W2.1: an explicit `memory.auto_writeback off` stops every ambient
 * capture lane — the serve compact harvest, the sweep's `.seg-` backstop and
 * (D1) the SessionEnd `<sid>.txt` transcript lane — while an unset value keeps
 * today's behavior for the compact and SessionEnd lanes. Read errors, plane
 * drift and invalid modes hold (no extraction, nothing terminal). A file banked
 * under explicit off is never extracted later, even after the operator turns
 * writeback back on, and a resumed session extracts only its new turns.
 *
 * Serial: real PGLite engines, module-global harvest queue, GBRAIN_HOME env.
 */
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { __setChatTransportForTests, resetGateway, type ChatResult } from '../src/core/ai/gateway.ts';
import { __resetFactsQueueForTests } from '../src/core/facts/queue.ts';
import type { CapabilityReport } from '../src/core/capability.ts';
import { CORPUS_INGESTED_SUFFIX, runMaintenanceSweep } from '../src/core/sweep.ts';
import { __drainCheckpointHarvestForTests, __resetCheckpointHarvestForTests, scheduleCheckpointHarvest } from '../src/core/context/checkpoint-harvest.ts';
import { appendSegmentLedger, gcCorpusArtifacts, segmentFileName, writeSegment } from '../src/core/context/corpus-segments.ts';
import { brainIdentity, recordCaptureIfOff } from '../src/core/context/capture-consent.ts';
import { parseCorpusTurns } from '../src/core/context/corpus-turns.ts';
import { runHook } from '../src/commands/hook.ts';
import { discoverTranscripts } from '../src/core/cycle/transcript-discovery.ts';

const KEYED: CapabilityReport = {
  embeddings: { available: false },
  extraction: { available: true, provider: 'anthropic' },
  search: 'keyword-only',
  mode: 'keyed',
};

let engine: PGLiteEngine;
let homeDir: string;
let corpusDir: string;
let savedHome: string | undefined;
const tmpDirs: string[] = [];
let prompts: string[] = [];
let onCall: (() => Promise<void>) | null = null;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
}, 120_000);

afterAll(async () => {
  await engine.disconnect();
  for (const d of tmpDirs) rmSync(d, { recursive: true, force: true });
});

beforeEach(async () => {
  __resetCheckpointHarvestForTests();
  homeDir = mkdtempSync(join(tmpdir(), 'gb-consent-home-'));
  tmpDirs.push(homeDir);
  savedHome = process.env.GBRAIN_HOME;
  process.env.GBRAIN_HOME = homeDir;
  corpusDir = join(homeDir, '.gbrain', 'transcripts', 'corpus');
  mkdirSync(corpusDir, { recursive: true });
  await engine.setConfig('dream.synthesize.session_corpus_dir', corpusDir);
  await engine.unsetConfig('memory.auto_writeback');
  await engine.executeRaw('DELETE FROM facts').catch(() => {});
  prompts = [];
  onCall = null;
  __setChatTransportForTests(async (opts): Promise<ChatResult> => {
    prompts.push(JSON.stringify(opts));
    if (onCall) await onCall();
    return {
      text: JSON.stringify({ facts: [{ fact: 'chose the blue deployment window', kind: 'decision', entity: null, confidence: 1, notability: 'high' }] }),
      blocks: [],
      stopReason: 'end',
      usage: { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0 },
      model: 'test:stub',
      providerId: 'test',
    };
  });
});

afterEach(() => {
  __setChatTransportForTests(null);
  resetGateway();
  __resetFactsQueueForTests();
  if (savedHome === undefined) delete process.env.GBRAIN_HOME;
  else process.env.GBRAIN_HOME = savedHome;
});

/** Both planes, the way `gbrain config set memory.auto_writeback <mode>` writes them. */
async function setMode(mode: string | null, opts: { db?: boolean; file?: boolean } = {}): Promise<void> {
  const cfgPath = join(homeDir, '.gbrain', 'config.json');
  if (opts.file !== false) {
    writeFileSync(cfgPath, JSON.stringify({ engine: 'pglite', ...(mode === null ? {} : { memory: { auto_writeback: mode } }) }) + '\n');
  }
  if (opts.db !== false) {
    if (mode === null) await engine.unsetConfig('memory.auto_writeback');
    else await engine.setConfig('memory.auto_writeback', mode);
  }
}

function bankSegment(sessionId: string, text: string): string {
  const w = writeSegment(corpusDir, sessionId, text);
  appendSegmentLedger(corpusDir, sessionId, w.hash);
  return segmentFileName(sessionId, w.hash);
}

async function factCount(source: string): Promise<number> {
  const rows = await engine.executeRaw<{ n: number }>(`SELECT count(*)::int AS n FROM facts WHERE source = $1`, [source]);
  return Number(rows[0]?.n ?? 0);
}

function sidecar(name: string): Record<string, unknown> | null {
  const p = join(corpusDir, name + CORPUS_INGESTED_SUFFIX);
  return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null;
}

async function harvest(file: string, sessionId: string): Promise<void> {
  scheduleCheckpointHarvest({ engine, sourceId: 'default', sessionId, corpusDir, file, capabilities: KEYED });
  await __drainCheckpointHarvestForTests();
}

const sweep = () => runMaintenanceSweep(engine, { sourceId: 'default', capabilities: KEYED, budgetMs: 30_000 });

const corpusText = (turns: string[]): string =>
  turns.map((t, i) => `${i % 2 === 0 ? '[user]' : '[assistant]'}\n${t}`).join('\n\n') + '\n';

/** A Claude Code transcript + `gbrain hook session-end`, exactly as the harness runs it. */
async function sessionEnd(sessionId: string, turns: string[]): Promise<void> {
  const projects = join(homeDir, 'claude', 'projects', 'p1');
  mkdirSync(projects, { recursive: true });
  mkdirSync(join(homeDir, 'ws'), { recursive: true });
  const transcript = join(projects, `${sessionId}.jsonl`);
  writeFileSync(transcript, turns.map((t, i) => i % 2 === 0
    ? JSON.stringify({ type: 'user', isSidechain: false, message: { role: 'user', content: t } })
    : JSON.stringify({ type: 'assistant', isSidechain: false, message: { role: 'assistant', content: [{ type: 'text', text: t }] } }),
  ).join('\n') + '\n');
  expect(await runHook(['session-end'], {
    stdin: JSON.stringify({ session_id: sessionId, transcript_path: transcript, cwd: join(homeDir, 'ws') }),
    transcriptRoot: join(homeDir, 'claude', 'projects'),
    spawnPush: () => {},
    spawnBackupCheck: () => {},
  })).toBe(0);
}

describe('explicit off stops every ambient lane (#6091)', () => {
  test('serve compact harvest: zero provider calls, terminal writeback_off sidecar', async () => {
    await setMode('off');
    const file = bankSegment('sess-c1', 'User: we picked the blue deployment window.\n');
    await harvest(file, 'sess-c1');
    expect(prompts.length).toBe(0);
    expect(await factCount('hook:compact')).toBe(0);
    expect(sidecar(file)?.skipped).toBe('writeback_off');
  });

  test('sweep backstop on a .seg- segment: zero provider calls, sidecar written', async () => {
    await setMode('off');
    const file = bankSegment('sess-c2', 'User: we picked the blue deployment window.\n');
    await sweep();
    expect(prompts.length).toBe(0);
    expect(await factCount('sweep:corpus')).toBe(0);
    expect(sidecar(file)?.skipped).toBe('writeback_off');
  });

  test('D1: the SessionEnd <sid>.txt transcript lane stops under explicit off', async () => {
    await setMode('off');
    writeFileSync(join(corpusDir, 'sess-c3.txt'), corpusText(['we picked the blue deployment window', 'noted']));
    await sweep();
    expect(prompts.length).toBe(0);
    expect(await factCount('sweep:corpus')).toBe(0);
    expect(sidecar('sess-c3.txt')?.skipped).toBe('writeback_off');
  });

  test('explicit off retires even on a keyless brain', async () => {
    await setMode('off');
    writeFileSync(join(corpusDir, 'sess-c4.txt'), corpusText(['we picked the blue deployment window', 'noted']));
    await runMaintenanceSweep(engine, {
      sourceId: 'default', budgetMs: 30_000,
      capabilities: { embeddings: { available: false }, extraction: { available: false }, search: 'keyword-only', mode: 'keyless' },
    });
    expect(sidecar('sess-c4.txt')?.skipped).toBe('writeback_off');
  });
});

describe('unset keeps today\'s behavior for the compact and SessionEnd lanes', () => {
  test('compact harvest extracts on unset', async () => {
    await setMode(null);
    const file = bankSegment('sess-u1', 'User: we picked the blue deployment window.\n');
    await harvest(file, 'sess-u1');
    expect(prompts.length).toBe(1);
    expect(await factCount('hook:compact')).toBe(1);
  });

  test('SessionEnd transcript extracts on unset', async () => {
    await setMode(null);
    writeFileSync(join(corpusDir, 'sess-u2.txt'), corpusText(['we picked the blue deployment window', 'noted']));
    await sweep();
    expect(prompts.length).toBe(1);
    expect(await factCount('sweep:corpus')).toBe(1);
  });
});

describe('incoherent config holds: nothing extracted, nothing terminal', () => {
  test('invalid mode value holds the compact and SessionEnd lanes', async () => {
    await setMode('sometimes');
    const seg = bankSegment('sess-h1', 'User: we picked the blue deployment window.\n');
    writeFileSync(join(corpusDir, 'sess-h1.txt'), corpusText(['we picked the blue deployment window', 'noted']));
    await harvest(seg, 'sess-h1');
    await sweep();
    expect(prompts.length).toBe(0);
    expect(sidecar(seg)).toBeNull();
    expect(sidecar('sess-h1.txt')).toBeNull();
  });

  test('plane drift (DB row absent, file mirror on) holds', async () => {
    await setMode('salient', { db: false });
    writeFileSync(join(corpusDir, 'sess-h2.txt'), corpusText(['we picked the blue deployment window', 'noted']));
    await sweep();
    expect(prompts.length).toBe(0);
    expect(sidecar('sess-h2.txt')).toBeNull();
  });

  test('a failed dual-write of off (DB row absent, file mirror off) holds, never extracts', async () => {
    await setMode('off', { db: false });
    const seg = bankSegment('sess-h3', 'User: we picked the blue deployment window.\n');
    await harvest(seg, 'sess-h3');
    expect(prompts.length).toBe(0);
    expect(sidecar(seg)).toBeNull();
  });
});

describe('durable revocation: a capture under off never extracts later', () => {
  test('off then on with the worker stopped: the off-period transcript is never extracted', async () => {
    await setMode('off');
    await sessionEnd('sess-r1', ['we picked the blue deployment window', 'noted']);
    expect(existsSync(join(corpusDir, 'sourced', 'sess-r1.src-_unresolved.txt'))).toBe(true); // #6268: the hook writes the spool
    await setMode('salient');
    await sweep();
    expect(prompts.length).toBe(0);
    expect(await factCount('sweep:corpus')).toBe(0);
  });

  test('resumed session: off-period turns stay retired, turns banked under on extract', async () => {
    await setMode('off');
    await sessionEnd('sess-r2', ['old secret plan alpha', 'ack alpha']);
    await setMode('salient');
    await sessionEnd('sess-r2', ['old secret plan alpha', 'ack alpha', 'new public plan beta', 'ack beta']);
    await sweep();
    expect(prompts.length).toBe(1);
    expect(prompts[0]).toContain('new public plan beta');
    expect(prompts[0]).not.toContain('old secret plan alpha');
  });

  test('a rewrite that puts earlier on-period turns before the off-period turns still never extracts them', async () => {
    await setMode('off');
    await sessionEnd('sess-r5', ['old secret plan alpha', 'ack alpha']);
    await sweep();
    expect(prompts.length).toBe(0);
    await setMode('salient');
    await sessionEnd('sess-r5', ['earlier public plan zeta', 'ack zeta', 'old secret plan alpha', 'ack alpha', 'new public plan beta', 'ack beta']);
    await sweep();
    const sent = prompts.join('\n');
    expect(sent).toContain('earlier public plan zeta');
    expect(sent).toContain('new public plan beta');
    expect(sent).not.toContain('old secret plan alpha');
    expect(sent).not.toContain('ack alpha');
  });

  test('a worker-side retire is honored when the rewrite puts new turns first', async () => {
    await setMode('off');
    const full = join(corpusDir, 'sess-r6.txt');
    writeFileSync(full, corpusText(['old secret plan alpha', 'ack alpha']));
    await sweep();
    expect(sidecar('sess-r6.txt')?.skipped).toBe('writeback_off');
    await setMode('salient');
    writeFileSync(full, corpusText(['earlier public plan zeta', 'ack zeta', 'old secret plan alpha', 'ack alpha']));
    rmSync(full + CORPUS_INGESTED_SUFFIX, { force: true });
    await sweep();
    const sent = prompts.join('\n');
    expect(sent).toContain('earlier public plan zeta');
    expect(sent).not.toContain('old secret plan alpha');
  });

  test('appended turns after a worker-side retire: only the new turns extract', async () => {
    await setMode('off');
    const full = join(corpusDir, 'sess-r3.txt');
    writeFileSync(full, corpusText(['old secret plan alpha', 'ack alpha']));
    await sweep();
    expect(sidecar('sess-r3.txt')?.skipped).toBe('writeback_off');
    await setMode('salient');
    writeFileSync(full, corpusText(['old secret plan alpha', 'ack alpha', 'new public plan beta', 'ack beta']));
    rmSync(full + CORPUS_INGESTED_SUFFIX, { force: true });
    await sweep();
    expect(prompts.length).toBe(1);
    expect(prompts[0]).toContain('new public plan beta');
    expect(prompts[0]).not.toContain('old secret plan alpha');
  });

  test('off set while a provider call is in flight: nothing is published', async () => {
    await setMode('salient');
    writeFileSync(join(corpusDir, 'sess-r4.txt'), corpusText(['we picked the blue deployment window', 'noted']));
    onCall = async () => { await setMode('off'); };
    await sweep();
    expect(prompts.length).toBe(1);
    expect(await factCount('sweep:corpus')).toBe(0);
  });
});

describe('two brains on one machine', () => {
  let other: PGLiteEngine;
  let homeB: string;
  beforeAll(async () => {
    other = new PGLiteEngine();
    await other.connect({});
    await other.initSchema();
  }, 120_000);
  afterAll(async () => { await other.disconnect(); });
  beforeEach(async () => {
    homeB = mkdtempSync(join(tmpdir(), 'gb-consent-homeB-'));
    tmpDirs.push(homeB);
    mkdirSync(join(homeB, '.gbrain', 'transcripts', 'corpus'), { recursive: true });
    writeFileSync(join(homeB, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', memory: { auto_writeback: 'salient' } }) + '\n');
    await other.setConfig('memory.auto_writeback', 'salient');
    await other.executeRaw('DELETE FROM facts').catch(() => {});
  });
  const asBrainB = async <T>(fn: () => Promise<T>): Promise<T> => {
    const homeA = process.env.GBRAIN_HOME;
    process.env.GBRAIN_HOME = homeB;
    try { return await fn(); } finally { process.env.GBRAIN_HOME = homeA; }
  };

  test('each brain applies its own mode to its own captures', async () => {
    await setMode('off');
    await sessionEnd('sess-m1', ['alpha said to brain A', 'ack']);
    await asBrainB(async () => {
      await other.setConfig('dream.synthesize.session_corpus_dir', join(homeB, '.gbrain', 'transcripts', 'corpus'));
      await sessionEnd('sess-m2', ['beta said to brain B', 'ack']);
    });
    await sweep();
    expect(prompts.length).toBe(0);
    await asBrainB(() => runMaintenanceSweep(other, { sourceId: 'default', capabilities: KEYED, budgetMs: 30_000 }));
    expect(prompts.length).toBe(1);
    expect(prompts[0]).toContain('beta said to brain B');
  });

  // W4.2: two brains whose hooks bank the same session file in one shared corpus directory.
  const OFF = { engine: 'pglite', memory: { auto_writeback: 'off' } } as never;
  const shared = (sessionId: string, turns: string[]) => {
    const file = join(corpusDir, `${sessionId}.txt`);
    return { file, text: corpusText(turns) };
  };

  test('W4.2: brain B capturing under off never erases brain A\'s off record for the same file', async () => {
    await setMode('off');
    const { file, text } = shared('sess-w42a', ['delta said to brain A under off', 'ack']);
    recordCaptureIfOff(OFF, file, text);
    await asBrainB(async () => { recordCaptureIfOff(OFF, file, text + '\n[user]\nepsilon said to brain B\n'); });
    writeFileSync(file, text);
    await setMode('salient');
    await sweep();
    expect(prompts.length).toBe(0);
  });

  test('W4.2: a pre-upgrade record of this brain is unioned on the first per-brain write and survives an older writer replacing it', async () => {
    await setMode('off');
    const { file, text } = shared('sess-w42b', ['zeta said to brain A before the upgrade', 'ack']);
    const legacy = file + '.capture-off.json';
    writeFileSync(legacy, JSON.stringify({ version: 1, brain: brainIdentity(), source: null, at: new Date().toISOString(),
      turns: parseCorpusTurns(text).map((t) => t.sha256) }) + '\n');
    const later = text + '\n[user]\neta said to brain A after the upgrade\n';
    recordCaptureIfOff(OFF, file, later);
    // An older gbrain on brain B still writes the single legacy file and drops A's turns from it.
    await asBrainB(async () => {
      writeFileSync(legacy, JSON.stringify({ version: 1, brain: brainIdentity(), source: null, at: new Date().toISOString(), turns: [] }) + '\n');
    });
    writeFileSync(file, later);
    await setMode('salient');
    await sweep();
    expect(prompts.length).toBe(0);
  });

  test('W4.2: an unreadable capture-off record holds the file instead of reading as "no record"', async () => {
    const { file, text } = shared('sess-w42c', ['theta said under off, record later corrupted', 'ack']);
    writeFileSync(file + '.capture-off.json', '{"version":1,"brain":');
    writeFileSync(file, text);
    await setMode('salient');
    await sweep();
    expect(prompts.length).toBe(0);
    expect(() => recordCaptureIfOff(OFF, file, text)).toThrow(/unreadable/);
  });

  test('W4.2: GC reaps any brain\'s orphaned record only past the grace period and keeps a live file\'s records', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'gb-consent-gc-'));
    tmpDirs.push(dir);
    const old = new Date(Date.now() - 60 * 60 * 1000);
    const orphanB = join(dir, 'gone.txt.capture-off.bbbbbbbbbbbbbbbbbbbbbbbb.json');
    const freshB = join(dir, 'pending.txt.capture-off.bbbbbbbbbbbbbbbbbbbbbbbb.json');
    const liveA = join(dir, 'live.txt.capture-off.aaaaaaaaaaaaaaaaaaaaaaaa.json');
    for (const p of [orphanB, freshB, liveA]) writeFileSync(p, '{}\n');
    writeFileSync(join(dir, 'live.txt'), '[user]\nhi\n');
    utimesSync(orphanB, old, old);
    utimesSync(liveA, old, old);
    gcCorpusArtifacts(dir, 24 * 60 * 60 * 1000, []);
    expect(existsSync(orphanB)).toBe(false);
    expect(existsSync(freshB)).toBe(true);
    expect(existsSync(liveA)).toBe(true);
  });

  test('pin: a capture record written by another brain in a shared corpus directory is ignored', async () => {
    await setMode('off');
    await sessionEnd('sess-m3', ['gamma in the shared directory', 'ack']);
    await asBrainB(async () => {
      await other.setConfig('dream.synthesize.session_corpus_dir', corpusDir);
      await runMaintenanceSweep(other, { sourceId: 'default', capabilities: KEYED, budgetMs: 30_000 });
    });
    expect(prompts.length).toBe(1);
    expect(prompts[0]).toContain('gamma in the shared directory');
  });
});

describe('dream synthesis never reads off-period turns', () => {
  test('discovery drops turns captured under off and skips a file holding nothing else', async () => {
    await setMode('off');
    await sessionEnd('sess-d1', ['old secret plan alpha', 'ack alpha']);
    await sessionEnd('sess-d2', ['private plan gamma', 'ack gamma']);
    await setMode('salient');
    await sessionEnd('sess-d1', ['earlier public plan zeta', 'ack zeta', 'old secret plan alpha', 'ack alpha', 'new public plan beta', 'ack beta']);
    const found = discoverTranscripts({ corpusDir, minChars: 1 });
    const d1 = found.find((t) => t.basename === 'sess-d1');
    expect(d1?.content).toContain('earlier public plan zeta');
    expect(d1?.content).toContain('new public plan beta');
    expect(d1?.content).not.toContain('old secret plan alpha');
    expect(found.some((t) => t.basename === 'sess-d2')).toBe(false);
  });
});