Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.4 KB
Raw Blame
/**
 * #6764 (d1b): the free conversation relink, `gbrain facts relink --conversation`.
 *
 * Protects: a conversation-extractor fact stored without an entity that names
 * exactly one live entity page is linked for free (write-mode inference, no
 * model), one write per page, on an unmanaged brain (maintenance
 * transaction) and a managed one (one receipted coordinator request); the dry
 * run writes nothing; an unresolvable fact gets a `conversation_unresolved`
 * memo and is named for the paid re-extraction; outcome rows and other pages
 * are untouched. Doctor `unlinked_facts` prescribes this free relink
 * (consent none, agent runs it) for untried rows and the paid re-extraction
 * only once relink tried and failed; the fixture renders the envelope, runs
 * the preview, the argv and the verify, and the finding moves on. The link
 * is stored on the derived row itself (`entity_slug`; conversation pages have
 * no fence, and fence projection skips extractor rows), so the extract_facts
 * reconcile keeps it, and `extract-conversation-facts --force` (unmanaged and
 * managed) carries it to the claim's new row with no second copy. Memoized
 * unresolved rows are left out of the 25% new-fact rule.
 * Regression: doctor prescribing paid re-extraction for rows a free pass links,
 * re-prescribing the free pass after it ran, and a re-extraction dropping a link.
 */
import { afterAll, beforeAll, beforeEach, describe, expect, spyOn, test } from 'bun:test';
import type { BrainEngine } from '../src/core/engine.ts';
import type { GBrainConfig } from '../src/core/config.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { runFactsCommand } from '../src/commands/facts.ts';
import { runConversationRelink, CONVERSATION_RELINK_INTENT } from '../src/core/facts/conversation-relink.ts';
import { runExtractConversationFactsCore } from '../src/commands/extract-conversation-facts.ts';
import { runExtractFacts } from '../src/core/cycle/extract-facts.ts';
import type { ExtractedFact } from '../src/core/facts/extract.ts';
import { unlinkedFactsStats, unlinkedFactsVerdict } from '../src/commands/doctor/checks/unlinked-facts.ts';
import { cliRenderContext, renderAction } from '../src/core/agent-output.ts';
import * as inference from '../src/core/facts/conversation-subject-infer.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { managedBrain } from './helpers/managed-brain.ts';

const MEETING = 'meetings/2026-08-12-lease-review';
const OTHER = 'meetings/2026-08-13-standup';
const LINKED = 'Alice Example signed the lease renewal';
const UNRESOLVED = 'The renewal starts in September';
const TRANSCRIPT = [
  '**Owner Example** (2026-08-12 10:00 AM): Alice Example signed the lease renewal yesterday.',
  '**Beta Example** (2026-08-12 10:01 AM): Good, the renewal starts in September.',
].join('\n');
const config = { engine: 'pglite', embedding_disabled: true } as unknown as GBrainConfig;

let engine: PGLiteEngine;
beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
}, 60_000);
afterAll(async () => { await engine.disconnect(); });

async function seed(db: BrainEngine): Promise<void> {
  for (const slug of [MEETING, OTHER]) {
    await db.putPage(slug, { type: 'meeting' as never, title: slug, compiled_truth: slug === MEETING ? TRANSCRIPT : 'notes', timeline: '', frontmatter: { date: '2026-08-12' } });
  }
  await db.putPage('people/alice-example', { type: 'person' as never, title: 'Alice Example', compiled_truth: '# Alice Example', timeline: '', frontmatter: {} });
  const row = (slug: string, n: number, fact: string, source = 'cli:extract-conversation-facts') => db.executeRaw(
    `INSERT INTO facts (source_id, entity_slug, fact, source, context, row_num, source_markdown_slug, created_at, valid_from)
     VALUES ('default', NULL, $1, $2, $3, $4, $5, now(), now())`, [fact, source, `from ${slug} segment 2026-08-12`, n, slug]);
  await row(MEETING, 0, 'Alice Example signed the lease renewal');
  await row(MEETING, 1, 'The renewal starts in September');
  await row(MEETING, 2, 'EXTRACTION_COMPLETE', 'cli:extract-conversation-facts:terminal');
  await row(OTHER, 0, 'Alice Example will send the deck');
}

async function facts(db: BrainEngine, slug = MEETING) {
  return db.executeRaw<{ fact: string; entity_slug: string | null; context: string | null }>(
    'SELECT fact, entity_slug, context FROM facts WHERE source_id=$1 AND source_markdown_slug=$2 ORDER BY row_num', ['default', slug]);
}

/** Active rows of a claim anywhere in the source. */
const active = (db: BrainEngine, fact: string) => db.executeRaw<{ entity_slug: string | null; source_markdown_slug: string; context: string | null }>(
  'SELECT entity_slug, source_markdown_slug, context FROM facts WHERE source_id=$1 AND fact=$2 AND expired_at IS NULL ORDER BY id', ['default', fact]);

/** `extract-conversation-facts --force` on MEETING, the extractor stubbed to return both claims unlinked. */
async function reextract(db: BrainEngine) {
  const spy = spyOn(process.stderr, 'write').mockImplementation(() => true);
  try {
    return await runExtractConversationFactsCore(db, { sourceId: 'default', slugs: [MEETING], sleepMs: 0, overrideDisabled: true, force: true,
      extractor: async () => [LINKED, UNRESOLVED].map(fact => ({ fact, kind: 'event', confidence: 0.9, entity_slug: null, source: 'test', notability: 'high' }) as ExtractedFact) });
  } finally { spy.mockRestore(); }
}

/** One active copy of the linked claim: a derived row of MEETING carrying the entity and the relink note. */
async function expectKept(db: BrainEngine): Promise<void> {
  const rows = await active(db, LINKED);
  expect(rows).toHaveLength(1);
  expect(rows[0]).toMatchObject({ entity_slug: 'people/alice-example', source_markdown_slug: MEETING });
  expect(rows[0]!.context).toContain('entity relinked from mention');
  expect((await active(db, UNRESOLVED)).map(r => [r.entity_slug, r.source_markdown_slug])).toEqual([[null, MEETING]]);
}

async function cli(db: BrainEngine, argv: string[]): Promise<{ code: number; out: string }> {
  const lines: string[] = [];
  const log = spyOn(console, 'log').mockImplementation((s: unknown) => { lines.push(String(s)); });
  try { return { code: await runFactsCommand(db, argv, config, 'default'), out: lines.join('\n') }; } finally { log.mockRestore(); }
}

describe('#6764 gbrain facts relink --conversation (unmanaged)', () => {
  beforeEach(async () => { await resetPgliteState(engine); await seed(engine); });

  test('the dry run writes nothing and names the paid fallback for the unresolved page', async () => {
    const { code, out } = await cli(engine, ['relink', '--conversation', '--slugs', MEETING, '--dry-run']);
    expect(code).toBe(0);
    expect(out).toContain('DRY RUN: would link 1 conversation fact(s) on 1 page(s) in source default');
    expect(out).toContain(`gbrain extract-conversation-facts --source-id default --slugs ${MEETING} --force --dry-run`);
    expect((await facts(engine)).map(r => r.entity_slug)).toEqual([null, null, null]);
    expect(await engine.executeRaw('SELECT 1 FROM fact_relink_attempts')).toHaveLength(0);
  });

  test('apply links the provable fact on the named page only, memoizes the miss, leaves the outcome row', async () => {
    const { code } = await cli(engine, ['relink', '--conversation', '--slugs', MEETING]);
    expect(code).toBe(0);
    const rows = await facts(engine);
    expect(rows.map(r => r.entity_slug)).toEqual(['people/alice-example', null, null]);
    expect(rows[0]!.context).toBe(`from ${MEETING} segment 2026-08-12 — entity relinked from mention`);
    expect((await facts(engine, OTHER)).map(r => r.entity_slug)).toEqual([null]);
    const attempts = await engine.executeRaw<{ outcome: string; target_slug: string | null }>('SELECT outcome, target_slug FROM fact_relink_attempts ORDER BY outcome');
    expect(attempts).toEqual([{ outcome: 'conversation_unresolved', target_slug: null }, { outcome: 'linked', target_slug: 'people/alice-example' }]);
  });

  test('without --slugs it takes the pages with untried rows; a rerun finds nothing new', async () => {
    const first = await runConversationRelink(engine, config, { sourceId: 'default' });
    expect(first).toMatchObject({ linked: 2, unresolved: 1, reextract_slugs: [MEETING] });
    const again = await runConversationRelink(engine, config, { sourceId: 'default' });
    expect(again).toMatchObject({ linked: 0, unresolved: 0, pages: [] });
  });

  test('a row that moved after the plan is not linked; it is reported as changed', async () => {
    const real = inference.inferConversationSubject;
    const spy = spyOn(inference, 'inferConversationSubject').mockImplementation(async (db, sourceId, visibility, fact) => {
      const result = await real(db, sourceId, visibility, fact);
      if (result.slug) await db.executeRaw(`UPDATE facts SET fact = fact || ' (edited)' WHERE source_markdown_slug = $1 AND fact = $2`, [MEETING, fact]);
      return result;
    });
    try {
      const report = await runConversationRelink(engine, config, { sourceId: 'default', slugs: [MEETING] });
      expect(spy).toHaveBeenCalled();
      expect(report).toMatchObject({ linked: 0, changed: 1, unresolved: 1 });
    } finally { spy.mockRestore(); }
    expect((await facts(engine)).map(r => r.entity_slug)).toEqual([null, null, null]);
  });
});

describe('#6764 the link survives re-extraction and fence reconcile', () => {
  beforeEach(async () => { await resetPgliteState(engine); await seed(engine); });

  test('extract-conversation-facts --force (twice) and the extract_facts reconcile keep one linked copy', async () => {
    await engine.setConfig('facts.entity_inference', 'off'); // the carried link, not write-time inference, must keep it
    try {
      await runConversationRelink(engine, config, { sourceId: 'default', slugs: [MEETING] });
      await expectKept(engine);
      expect(await reextract(engine)).toMatchObject({ pages_processed: 1, pages_failed: 0 });
      await expectKept(engine);
      const reconcile = await runExtractFacts(engine, { sourceId: 'default' });
      expect(reconcile).toMatchObject({ guardTriggered: false, factsDeleted: 0 });
      await expectKept(engine);
      await reextract(engine);
      await expectKept(engine);
      const expired = await engine.executeRaw<{ n: number }>(`SELECT COUNT(*)::int AS n FROM facts WHERE fact=$1 AND expired_at IS NOT NULL`, [LINKED]);
      expect(expired[0]!.n).toBe(1);
    } finally { await engine.unsetConfig('facts.entity_inference'); }
  });
});

describe('#6764 doctor: free relink first, paid re-extraction only for rows it tried', () => {
  beforeEach(async () => { await resetPgliteState(engine); await seed(engine); });

  test('fixture: render the relink envelope, run its preview, its argv and the verify', async () => {
    const before = unlinkedFactsVerdict(await unlinkedFactsStats(engine, ['default']));
    const fix = before.fix!;
    expect(fix).toMatchObject({ consent: [], actor: 'agent', verify: { argv: ['gbrain', 'doctor', '--only', 'unlinked_facts', '--json'] } });
    expect(fix.argv).toEqual(['gbrain', 'facts', 'relink', '--conversation', '--source', 'default', '--slugs', `${MEETING},${OTHER}`]);
    expect(fix.preview_argv).toEqual([...fix.argv!, '--dry-run']);
    expect(renderAction(fix as never, cliRenderContext()).next).toBe('run');
    expect(before.message).toContain('link them for free (preview first): gbrain facts relink --conversation');
    expect((await cli(engine, fix.preview_argv!.slice(2))).code).toBe(0);
    expect((await unlinkedFactsStats(engine, ['default']))!.window.conversation).toBe(3);
    expect((await cli(engine, fix.argv!.slice(2))).code).toBe(0);
    const after = unlinkedFactsVerdict(await unlinkedFactsStats(engine, ['default']));
    expect(after.details).toMatchObject({ window: { conversation: 1 }, conversation: { fix: 'reextract', pages: 1, slugs: [MEETING] } });
    expect(after.fix).toMatchObject({ consent: ['paid', 'egress'], ask_user: true });
    expect(after.fix!.argv).toEqual(['gbrain', 'extract-conversation-facts', '--source-id', 'default', '--slugs', MEETING, '--force', '--max-cost-usd', '<N>']);
    expect(after.message).not.toContain('gbrain facts relink --conversation');
  });

  test('memoized unresolved rows are left out of the 25% new-fact rule and named in the paid fallback', async () => {
    for (let i = 0; i < 24; i++) {
      await engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, source, context, row_num, source_markdown_slug, created_at, valid_from)
        VALUES ('default', NULL, $1, 'cli:extract-conversation-facts', 'from x', $2, $3, now(), now())`, [`Unattributed remark ${i}`, 10 + i, MEETING]);
    }
    expect(unlinkedFactsVerdict(await unlinkedFactsStats(engine, ['default'])).status).toBe('warn');
    await runConversationRelink(engine, config, { sourceId: 'default' });
    const after = unlinkedFactsVerdict(await unlinkedFactsStats(engine, ['default']));
    expect(after.details).toMatchObject({ new_7d: { conversation_unresolved: 25, eligible: 2 }, conversation: { fix: 'reextract', slugs: [MEETING] } });
    expect(after.status).toBe('ok');
  });

  test('the remote report asks the brain host operator to run the relink', async () => {
    const verdict = unlinkedFactsVerdict(await unlinkedFactsStats(engine, ['default']), { thinClient: true });
    expect(verdict.fix).toMatchObject({ actor: 'host_admin', consent: [] });
  });
});

describe('#6764 gbrain facts relink --conversation (managed)', () => {
  test('one receipted coordinator request per page links the row', async () => {
    await managedBrain(async ({ engine: db }) => {
      const report = await runConversationRelink(db, config, { sourceId: 'default', slugs: [MEETING, OTHER] });
      expect(report).toMatchObject({ linked: 2, unresolved: 1, changed: 0 });
      await expectKept(db);
      expect((await facts(db)).map(r => r.entity_slug)).toEqual(['people/alice-example', null, null]);
      expect((await facts(db, OTHER)).map(r => r.entity_slug)).toEqual(['people/alice-example']);
      const requests = await db.executeRaw<{ state: string }>(`SELECT state FROM persistence_requests WHERE intent->>'kind' = $1`, [CONVERSATION_RELINK_INTENT]);
      expect(requests.map(r => r.state)).toEqual(['committed', 'committed']);
      await db.setConfig('facts.entity_inference', 'off'); // the carried link, not write-time inference, must keep it
      expect(await reextract(db)).toMatchObject({ pages_processed: 1, pages_failed: 0 });
      await expectKept(db);
    }, { setup: async ({ engine: db }) => { await seed(db); } });
  }, 120_000);
});