Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.8 KB
Raw Blame
/**
 * #6803 part 6: the extraction nudge matches doctor and names the command that finishes.
 *
 * Protects: doctor's links_extraction_lag and the end-of-sync nudge share one predicate (attendance-blocked pages
 * excluded) and one threshold; the warn carries a default fix (plain \`gbrain extract --stale\`) plus both routes with an
 * estimate, and a fix expected to outlast an agent tool call renders tell_user_to_run; extract's routing flag is
 * --source-id, so rendered fixes never pin \`--source <id>\` (extract's fs|db mode selector); \`extract --stale --source <id>\`
 * refuses with invalid_params instead of running brain-wide; \`--source db\` is ambiguous when a source is named db;
 * \`extract --stale\` JSON splits actionable / attendance_blocked / mention_due; the per-source sync line counts only the
 * sync's underived imports.
 * Seams: none. PGLite always, Postgres when DATABASE_URL is set (test/e2e/extraction-nudge-6803-postgres.test.ts).
 */
import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
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 { checkLinksExtractionLag } from '../src/commands/doctor.ts';
import { maybeExtractionNudge } from '../src/commands/sync/report.ts';
import { runExtract } from '../src/commands/extract.ts';
import { printManagedSyncNotes } from '../src/commands/sync-diagnostics.ts';
import type { SyncResult } from '../src/commands/sync.ts';
import { cliRenderContext, renderAction, type Action } from '../src/core/agent-output.ts';
import { pinRouting } from '../src/core/fix-routing.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
import { runCli } from './helpers/cli-spawn.ts';

async function captured<T>(fn: () => Promise<T>): Promise<{ result?: T; error?: unknown; stdout: string; stderr: string }> {
  const out: string[] = [], err: string[] = [];
  const orig = { log: console.log, error: console.error, warn: console.warn, write: process.stdout.write.bind(process.stdout) };
  console.log = (...a: unknown[]) => { out.push(a.map(String).join(' ')); };
  console.error = (...a: unknown[]) => { err.push(a.map(String).join(' ')); };
  console.warn = (...a: unknown[]) => { err.push(a.map(String).join(' ')); };
  process.stdout.write = ((chunk: unknown) => { out.push(String(chunk)); return true; }) as typeof process.stdout.write;
  try { return { result: await fn(), stdout: out.join('\n'), stderr: err.join('\n') }; }
  catch (error) { return { error, stdout: out.join('\n'), stderr: err.join('\n') }; }
  finally { console.log = orig.log; console.error = orig.error; console.warn = orig.warn; process.stdout.write = orig.write; }
}

const teambrain = { brain: 'teambrain', source: 'wiki' };
const cli = (routing?: { brain?: string; source?: string }) => cliRenderContext({ routing });

for (const backend of testBackends()) {
  describe(`${backend}: #6803 extraction lag, nudge and extract --stale`, () => {
    let engine: BrainEngine;
    let close: () => Promise<void>;
    beforeAll(async () => {
      if (backend === 'postgres') {
        const pg = await isolatedPersistencePostgres(requirePostgresTestDatabase());
        engine = pg.engine; close = pg.close;
      } else {
        const pglite = new PGLiteEngine();
        await pglite.connect({}); await pglite.initSchema();
        engine = pglite; close = () => pglite.disconnect();
      }
    }, 120_000);
    afterAll(async () => { await close(); }, 60_000);
    beforeEach(async () => {
      await engine.executeRaw('DELETE FROM pages');
      await engine.executeRaw("DELETE FROM sources WHERE id <> 'default'");
    });

    async function seed(n: number, opts: { prefix?: string; sourceId?: string; blocked?: boolean; fresh?: boolean } = {}): Promise<void> {
      const prefix = opts.prefix ?? 'p', sourceId = opts.sourceId ?? 'default';
      await engine.executeRaw(
        `INSERT INTO pages (slug, source_id, type, title, compiled_truth, timeline, frontmatter, content_hash, created_at, updated_at)
         SELECT $1 || '/' || g, $2, 'concept', 'T' || g, '', '', '{}'::jsonb, $1 || 'h' || g, now() - interval '1 day', now() - interval '1 day'
           FROM generate_series(1, $3::int) g`, [prefix, sourceId, n]);
      if (opts.blocked) await engine.executeRaw(`UPDATE pages SET links_attendance_blocked_revision = knowledge_revision WHERE slug LIKE $1 || '/%'`, [prefix]);
      if (opts.fresh) await engine.executeRaw(`UPDATE pages SET links_extracted_at = now() WHERE slug LIKE $1 || '/%'`, [prefix]);
    }

    test('an attendance-blocked majority: doctor ok and the sync nudge silent', async () => {
      await seed(100, { prefix: 'm', blocked: true });
      await seed(20, { prefix: 'p', fresh: true });
      const check = await checkLinksExtractionLag(engine);
      expect(check.status).toBe('ok');
      expect((check.details as Record<string, unknown>).attendance_blocked).toBe(100);
      const nudge = await captured(() => maybeExtractionNudge(engine));
      expect(nudge.stderr).not.toContain('un-extracted edges');
    });

    test('a real backlog: doctor warns with the plain-route fix and both routes; the nudge prints the same count and both commands', async () => {
      await seed(120);
      const check = await checkLinksExtractionLag(engine);
      expect(check.status).toBe('warn');
      expect(check.message).toContain('gbrain extract --stale');
      expect(check.message).toContain('gbrain extract --stale --catch-up');
      const fix = renderAction(check.fix as Action, cli({ brain: 'teambrain' }));
      expect(fix.argv).toEqual(['gbrain', 'extract', '--stale', '--brain', 'teambrain']);
      expect(fix.verify?.argv).toEqual(['gbrain', 'extract', '--stale', '--dry-run', '--json', '--brain', 'teambrain']);
      expect(fix.next).toBe('run');
      const routes = (check.details as { routes: Array<{ id: string; argv: string[]; label: string }> }).routes;
      expect(routes.map(r => r.id)).toEqual(['plain', 'catch_up']);
      expect(routes[1]!.argv).toContain('--catch-up');
      expect(routes[1]!.label).toContain('estimate at 10 ms RTT; measure your pooler RTT');

      const nudge = await captured(() => maybeExtractionNudge(engine, 'default'));
      expect(nudge.stderr).toContain('120 page(s) have un-extracted edges');
      expect(nudge.stderr).toContain('gbrain extract --stale --source-id default');
      expect(nudge.stderr).toContain('gbrain extract --stale --catch-up --source-id default');
      expect(nudge.stderr).toContain('each run resumes where the last stopped');
      expect(nudge.stderr).not.toMatch(/--source default/);
    });

    test('an estimate over AGENT_TOOL_LIMIT_MS makes the fix the user\'s (tell_user_to_run); host_admin on a remote brain', async () => {
      await seed(2_000);
      const check = await checkLinksExtractionLag(engine);
      expect(check.status).toBe('warn');
      expect(renderAction(check.fix as Action, cli()).next).toBe('tell_user_to_run');
      expect((check.fix as Action).actor).toBe('user');
      expect((check.fix as Action).user_message).toContain('--catch-up');
      const remote = await checkLinksExtractionLag(engine, { remote: true } as { sourceId?: string });
      expect((remote.fix as Action).actor).toBe('host_admin');
    });

    test('a scoped fix and verify pin --source-id and the selected brain, never --source <id>', async () => {
      await engine.executeRaw("INSERT INTO sources (id, name) VALUES ('wiki', 'wiki')");
      await seed(30, { sourceId: 'wiki' });
      const check = await checkLinksExtractionLag(engine, { sourceId: 'wiki' });
      expect(check.status).toBe('warn');
      const fix = renderAction(check.fix as Action, cli(teambrain));
      expect(fix.argv).toEqual(['gbrain', 'extract', '--stale', '--source-id', 'wiki', '--brain', 'teambrain']);
      expect(fix.verify?.argv).toEqual(['gbrain', 'extract', '--stale', '--dry-run', '--json', '--source-id', 'wiki', '--brain', 'teambrain']);
    });

    test('extract --stale --source <id> refuses with invalid_params naming --source-id instead of running brain-wide', async () => {
      await seed(3);
      const run = await captured(() => runExtract(engine, ['--stale', '--source', 'wiki', '--json']));
      expect((run.error as { code?: string })?.code).toBe('invalid_params');
      expect((run.error as { fix?: Action }).fix?.argv).toEqual(['gbrain', 'extract', '--stale', '--source-id', 'wiki', '--json']);
      expect(Number((await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM pages WHERE links_extracted_at IS NOT NULL'))[0]!.n)).toBe(0);
    });

    test('--source db is the read mode, and ambiguous once a source is named db', async () => {
      await seed(3);
      const plain = await captured(() => runExtract(engine, ['--stale', '--source', 'db', '--dry-run', '--json']));
      expect(plain.error).toBeUndefined();
      await engine.executeRaw("INSERT INTO sources (id, name) VALUES ('db', 'db')");
      const ambiguous = await captured(() => runExtract(engine, ['--stale', '--source', 'db', '--dry-run', '--json']));
      expect((ambiguous.error as { code?: string })?.code).toBe('invalid_params');
      expect((ambiguous.error as Error).message).toContain('ambiguous');
      expect((ambiguous.error as { fix?: Action }).fix?.argv).toEqual(['gbrain', 'extract', '--stale', '--source-id', 'db', '--dry-run', '--json']);
    });

    test('extract --stale dry-run and completion JSON split actionable, attendance_blocked and mention_due', async () => {
      await seed(4, { prefix: 'm', blocked: true });
      await seed(3, { prefix: 'p' });
      const dry = await captured(() => runExtract(engine, ['--stale', '--dry-run', '--json']));
      const preview = JSON.parse(dry.stdout.trim().split('\n').filter(l => l.startsWith('{')).pop()!);
      expect(preview).toMatchObject({ action: 'extract_stale_dry_run', actionable: 3, attendance_blocked: 4, complete: false });
      expect('mention_due' in preview).toBe(true);
      const done = await captured(() => runExtract(engine, ['--stale', '--json']));
      const report = JSON.parse(done.stdout.trim().split('\n').filter(l => l.startsWith('{')).pop()!);
      expect(report.action).toBe('extract_stale_done');
      expect(report.actionable).toBe(0);
      expect(typeof report.attendance_blocked).toBe('number');
      expect('mention_due' in report && 'complete' in report).toBe(true);
    });
  });
}

describe('#6803 routing and reporting (engine-free)', () => {
  test('extract routes --source-id: a brain-wide fix gets --source-id, a --source mode selector does not block it, --source is never pinned', () => {
    expect(pinRouting(['gbrain', 'extract', '--stale'], teambrain)).toEqual(['gbrain', 'extract', '--stale', '--brain', 'teambrain', '--source-id', 'wiki']);
    expect(pinRouting(['gbrain', 'extract', 'links', '--source', 'db'], teambrain)).toEqual(['gbrain', 'extract', 'links', '--source', 'db', '--brain', 'teambrain', '--source-id', 'wiki']);
    expect(pinRouting(['gbrain', 'extract', '--stale', '--source-id', 'other'], teambrain)).toEqual(['gbrain', 'extract', '--stale', '--source-id', 'other', '--brain', 'teambrain']);
    expect(pinRouting(['gbrain', 'sync', '--no-pull'], teambrain)).toEqual(['gbrain', 'sync', '--no-pull', '--brain', 'teambrain', '--source', 'wiki']);
  });

  test("the per-source sync line counts this sync's underived imports, not the source's whole stale backlog", () => {
    const lines: string[] = [];
    printManagedSyncNotes({ status: 'synced', links: { pages: 2, created: 1, removed: 0, timeline: 0, skipped: 0, remaining: 500 },
      tail: { status: 'truncated', runs: 1, statistics: 'not_needed', underived: 3 } } as unknown as SyncResult, line => lines.push(line));
    const line = lines.find(l => l.includes('Links:'))!;
    expect(line).toContain('3 page(s) this sync imported still owe extraction');
    expect(line).not.toContain('500');
  });

  test('real CLI: extract --stale --source <id> exits 2 invalid_params with the --source-id command, before any brain opens', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-6803-extract-'));
    try {
      const run = await runCli(['extract', '--stale', '--source', 'wiki', '--json'], { home });
      expect(run.exitCode, run.stderr).toBe(2);
      const env = JSON.parse(run.stdout);
      expect(env.code).toBe('invalid_params');
      expect(env.fix.argv.slice(0, 5)).toEqual(['gbrain', 'extract', '--stale', '--source-id', 'wiki']);
      const fs = await runCli(['extract', '--stale', '--source', 'fs', '--json'], { home });
      expect(fs.exitCode, fs.stderr).toBe(2);
      expect(JSON.parse(fs.stdout).code).toBe('invalid_params');
    } finally { rmSync(home, { recursive: true, force: true }); }
  }, 120_000);
});