Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.2 KB
Raw Blame
/**
 * Tests for `doctorReportRemote()` — the focused thin-client doctor that
 * powers the run_doctor MCP op.
 *
 * Strategy: build a fresh PGLite engine + initSchema, run the report, assert
 * all 5 checks present + healthy. Uses the canonical PGLite test pattern
 * (beforeAll + afterAll, not beforeEach) per CLAUDE.md test-isolation rules.
 */

import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { doctorReportRemote, computeDoctorReport, type DoctorReport, type Check } from '../src/commands/doctor.ts';
import { operationsByName, type OperationContext } from '../src/core/operations.ts';

let engine: PGLiteEngine;
let tmpHome: string;
let priorHome: string | undefined;

beforeAll(async () => {
  // v0.37.10.0: doctorReportRemote reads from ~/.gbrain audit files
  // (reranker_health, sync_failures, etc.). Without isolation, host state
  // leaks into the test and makes the assertion non-deterministic. Pin
  // GBRAIN_HOME to a tempdir so audit reads return empty.
  tmpHome = mkdtempSync(join(tmpdir(), 'gbrain-doctor-remote-'));
  priorHome = process.env.GBRAIN_HOME;
  process.env.GBRAIN_HOME = tmpHome;
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
});

afterAll(async () => {
  await engine.disconnect();
  if (priorHome === undefined) delete process.env.GBRAIN_HOME;
  else process.env.GBRAIN_HOME = priorHome;
  rmSync(tmpHome, { recursive: true, force: true });
});

describe('doctorReportRemote', () => {
  test('runs all 5 checks on a fresh PGLite brain', async () => {
    const report = await doctorReportRemote(engine);
    expect(report.schema_version).toBe(2);
    expect(report.checks.length).toBeGreaterThanOrEqual(5);
    const names = report.checks.map(c => c.name);
    expect(names).toContain('connection');
    expect(names).toContain('schema_version');
    expect(names).toContain('brain_score');
    expect(names).toContain('sync_failures');
    expect(names).toContain('queue_health');
  });

  test('connection check passes against a healthy engine', async () => {
    const report = await doctorReportRemote(engine);
    const conn = report.checks.find(c => c.name === 'connection');
    expect(conn).toBeDefined();
    expect(conn!.status).toBe('ok');
    expect(conn!.message).toContain('Connected');
  });

  test('schema_version check shows the latest version', async () => {
    const report = await doctorReportRemote(engine);
    const sv = report.checks.find(c => c.name === 'schema_version');
    expect(sv).toBeDefined();
    // Fresh PGLite at LATEST_VERSION → status ok with "(latest)"
    expect(sv!.status).toBe('ok');
    expect(sv!.message.toLowerCase()).toContain('latest');
  });

  test('queue_health is informational on PGLite', async () => {
    const report = await doctorReportRemote(engine);
    const q = report.checks.find(c => c.name === 'queue_health');
    expect(q).toBeDefined();
    expect(q!.status).toBe('ok');
    // PGLite-specific message
    expect(q!.message).toContain('PGLite');
  });

  test('extract_atoms_backlog is on the remote surface: ok on a fresh brain, message never leaks GBRAIN_HOME (#4576)', async () => {
    const report = await doctorReportRemote(engine);
    const check = report.checks.find(c => c.name === 'extract_atoms_backlog');
    expect(check).toBeDefined();
    expect(check!.status).toBe('ok');
    expect(check!.message).toContain('no pages awaiting atom extraction');
    // The thin-client message is read by remote callers — never a server path.
    expect(check!.message).not.toContain(tmpHome);
    expect(JSON.stringify(check!.details ?? {})).not.toContain(tmpHome);
    expect((check!.details as Record<string, unknown>).backlog).toBe(0);
  });

  test('full report on healthy brain is "healthy" status', async () => {
    const report = await doctorReportRemote(engine);
    expect(report.status).toMatch(/healthy|warnings/);
    expect(report.health_score).toBeGreaterThanOrEqual(70);
  });
});

describe('computeDoctorReport — score + status math', () => {
  function check(status: Check['status']): Check {
    return { name: `check-${status}`, status, message: '' };
  }

  test('all-ok → healthy + 100', () => {
    const r = computeDoctorReport([check('ok'), check('ok'), check('ok')]);
    expect(r.status).toBe('healthy');
    expect(r.health_score).toBe(100);
  });

  test('one warn → warnings + score - 5', () => {
    const r = computeDoctorReport([check('ok'), check('warn'), check('ok')]);
    expect(r.status).toBe('warnings');
    expect(r.health_score).toBe(95);
  });

  test('one fail → unhealthy + score - 20', () => {
    const r = computeDoctorReport([check('ok'), check('fail'), check('ok')]);
    expect(r.status).toBe('unhealthy');
    expect(r.health_score).toBe(80);
  });

  test('mix of fail + warn → unhealthy (fail dominates)', () => {
    const r = computeDoctorReport([check('warn'), check('fail'), check('warn')]);
    expect(r.status).toBe('unhealthy');
    expect(r.health_score).toBe(70);
  });

  test('score floor at 0', () => {
    const fails: Check[] = [];
    for (let i = 0; i < 10; i++) fails.push(check('fail'));
    const r = computeDoctorReport(fails);
    expect(r.health_score).toBe(0);
  });

  test('schema_version is always 2', () => {
    const r: DoctorReport = computeDoctorReport([check('ok')]);
    expect(r.schema_version).toBe(2);
  });
});

// #4592 — the thin-client doctor report is an admin-scope aggregate on the same
// trust boundary as get_stats/get_health: a source-scoped remote grant must not
// read the brain-wide page count back out of the `connection` check (the same
// subtraction leak, one op over). Seeded AFTER the fresh-brain suite above so
// those assertions keep their empty brain.
describe('doctorReportRemote — source scope (#4592)', () => {
  const SRCA = 'scopesrca';
  const SRCB = 'scopesrcb';
  const message = (r: DoctorReport, name: string) => r.checks.find(c => c.name === name)!.message;
  const put = (sourceId: string, slug: string) =>
    engine.putPage(slug, { title: slug, type: 'note', compiled_truth: `# ${slug}\n\nbody\n` }, { sourceId });

  beforeAll(async () => {
    await engine.executeRaw(
      `INSERT INTO sources (id, name) VALUES ('${SRCA}', '${SRCA}'), ('${SRCB}', '${SRCB}') ON CONFLICT (id) DO NOTHING`,
    );
    await put(SRCA, 'notes/alpha');
    await put(SRCA, 'notes/beta');
    await put(SRCB, 'notes/gamma');
  });

  test('sourceIds confines the connection page count instead of reporting brain-wide', async () => {
    const report = await doctorReportRemote(engine, { sourceIds: [SRCA] });
    expect(message(report, 'connection')).toBe('Connected, 2 pages');
  });

  test('run_doctor threads a remote federated grant into the count', async () => {
    const ctx = {
      engine,
      remote: true,
      auth: { token: 't', clientId: 'c', scopes: ['admin'], allowedSources: [SRCB] },
    } as unknown as OperationContext;
    const report = await operationsByName.run_doctor.handler(ctx, {}) as DoctorReport;
    expect(message(report, 'connection')).toBe('Connected, 1 pages');
  });

  test('differential: mutating an EXCLUDED source moves nothing a scoped report shows', async () => {
    const before = await doctorReportRemote(engine, { sourceIds: [SRCA] });
    await put(SRCB, 'notes/delta');
    const after = await doctorReportRemote(engine, { sourceIds: [SRCA] });
    expect(message(after, 'connection')).toBe(message(before, 'connection'));
    expect(message(after, 'brain_score')).toBe(message(before, 'brain_score'));
  });

  test('contextual_retrieval_coverage counts only the granted source (#5004 unsealed pages, #4592 class)', async () => {
    // putPage caps chunker_version below the safe-chunk fence, so every page
    // here is "unsealed" and the check reports a count. A caller granted only
    // SRCA must read SRCA's count: adding an unsealed page to SRCB moves nothing.
    const ctx = {
      engine,
      remote: true,
      auth: { token: 't', clientId: 'c', scopes: ['admin'], allowedSources: [SRCA] },
    } as unknown as OperationContext;
    const before = await operationsByName.run_doctor.handler(ctx, {}) as DoctorReport;
    expect(message(before, 'contextual_retrieval_coverage')).toContain('below the safe-chunk index version');
    await put(SRCB, 'notes/epsilon');
    const after = await operationsByName.run_doctor.handler(ctx, {}) as DoctorReport;
    expect(message(after, 'contextual_retrieval_coverage')).toBe(message(before, 'contextual_retrieval_coverage'));
  });

  test('extract_atoms_backlog / drift / orphan probes never name or count an excluded source (wave review)', async () => {
    // 12 eligible-but-unextracted pages in the EXCLUDED source: brain-wide the
    // backlog is >= 12 (and the drain hint may name the source); a caller
    // granted only SRCA must see a zero backlog and no trace of SRCB anywhere
    // in the report — details.backlog_by_source, messages, fix hints.
    const body = 'x'.repeat(600);
    for (let i = 0; i < 12; i++) {
      await engine.putPage(`articles/leak-${i}`, { title: `leak-${i}`, type: 'article', compiled_truth: body }, { sourceId: SRCB });
    }
    const wide = await doctorReportRemote(engine);
    const wideBacklog = wide.checks.find(c => c.name === 'extract_atoms_backlog')!;
    expect(Number((wideBacklog.details as { backlog: number }).backlog)).toBeGreaterThanOrEqual(12);

    const scoped = await doctorReportRemote(engine, { sourceIds: [SRCA] });
    const scopedBacklog = scoped.checks.find(c => c.name === 'extract_atoms_backlog')!;
    expect(Number((scopedBacklog.details as { backlog: number }).backlog)).toBe(0);
    expect(JSON.stringify(scoped)).not.toContain(SRCB);
  });
});

describe('doctorReportRemote — managed drift advice (#5477)', () => {
  test('a managed brain is told --no-pull without --include-gitignored; unmanaged wording is unchanged', async () => {
    const root = mkdtempSync(join(tmpdir(), 'gbrain-doctor-drift-'));
    const sourceId = 'doctor-drift-advice-test';
    try {
      mkdirSync(join(root, 'notes'), { recursive: true });
      writeFileSync(join(root, 'notes', 'misrouted.md'), '# Misrouted\n');
      await engine.executeRaw('INSERT INTO sources (id, name, local_path) VALUES ($1, $1, $2) ON CONFLICT (id) DO UPDATE SET local_path = EXCLUDED.local_path', [sourceId, root]);
      await engine.putPage('notes/misrouted', { title: 'Misrouted', type: 'note', compiled_truth: '# Misrouted\n' });
      const drift = async () => (await doctorReportRemote(engine)).checks.find(c => c.name === 'multi_source_drift')!;

      const unmanaged = await drift();
      expect(unmanaged.message).toBe(
        "1 page slug(s) appear at 'default' but NOT at the intended source " +
        '(e.g., notes/misrouted (intended=doctor-drift-advice-test)). Likely pre-v0.30.3 misroutes OR an incomplete initial sync. ' +
        'Verify on the brain host: `gbrain sources status` then `gbrain sync --source <id> --full`.',
      );

      await engine.executeRaw('UPDATE persistence_brain SET enabled = true WHERE singleton = 1');
      const managed = await drift();
      expect(managed.message).toContain('then `gbrain sync --source <id> --no-pull --full`.');
      expect(managed.message).not.toContain('--include-gitignored');
    } finally {
      await engine.executeRaw('UPDATE persistence_brain SET enabled = false WHERE singleton = 1');
      await engine.executeRaw("DELETE FROM pages WHERE slug = 'notes/misrouted' AND source_id = 'default'");
      await engine.executeRaw('DELETE FROM sources WHERE id = $1', [sourceId]);
      rmSync(root, { recursive: true, force: true });
    }
  });
});

describe('run_doctor canonical projection readiness', () => {
  test('the real handler excludes private and ungranted pending pages while local callers can diagnose them', async () => {
    await engine.executeRaw("INSERT INTO sources(id,name) VALUES ('readiness-visible','readiness-visible'),('readiness-hidden','readiness-hidden') ON CONFLICT DO NOTHING");
    await engine.putPage('notes/current-example', { title: 'Example', type: 'note', compiled_truth: 'current' }, { sourceId: 'readiness-visible' });
    await engine.putPage('notes/private-example', { title: 'Private example', type: 'note', compiled_truth: 'private', frontmatter: { visibility: 'private' } }, { sourceId: 'readiness-hidden' });
    await engine.executeRaw("UPDATE pages SET text_projection_revision=knowledge_revision WHERE source_id='readiness-visible'");
    const ctx = {
      engine, remote: true, sourceId: 'readiness-hidden',
      auth: { allowedSources: ['readiness-visible', 'readiness-hidden'] },
    } as unknown as OperationContext;
    const check = (report: DoctorReport) => report.checks.find(c => c.name === 'text_projection_readiness')!;
    // #6803: doctor also counts the queue by class, within the caller's visible scope.
    const counts = (pending: number, oldest: number | null) => ({ pending, failed: 0, sealable: 0, sealable_with_visual: 0, reimport: 0, ocr_required: 0,
      protected: 0, archived: 0, oldest_age_seconds: oldest, as_of: expect.any(String) });
    const remote = check(await operationsByName.run_doctor.handler(ctx, {}) as DoctorReport);
    expect(remote.status).toBe('ok');
    expect(remote.details).toEqual({ readiness: 'ready', ready: true, ...counts(0, null) });
    const local = check(await operationsByName.run_doctor.handler({ ...ctx, remote: false }, {}) as DoctorReport);
    expect(local.status).toBe('warn');
    expect(local.details).toEqual({ readiness: 'projection_pending', ready: false, ...counts(1, expect.any(Number)) });
    const restricted = check(await operationsByName.run_doctor.handler({ ...ctx, auth: { ...ctx.auth!, allowedSources: ['readiness-visible'] } }, {}) as DoctorReport);
    expect(restricted.status).toBe('ok');
    expect(JSON.stringify(restricted)).not.toContain('readiness-hidden');
    expect(JSON.stringify(local)).not.toContain('notes/private-example');
    await engine.executeRaw("UPDATE pages SET text_projection_revision=NULL WHERE source_id='readiness-visible'");
    const pending = check(await operationsByName.run_doctor.handler(ctx, {}) as DoctorReport);
    expect(pending.status).toBe('warn');
    expect(pending.details).toEqual({ readiness: 'projection_pending', ready: false, ...counts(0, null) });
  });
});