Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.9 KB
Raw Blame
/**
 * Keyless `gbrain dream` exit-0 contract — TODOS.md "P2 — Keyless `gbrain
 * dream` contract test".
 *
 * The documented nightly cron (INSTALL_FOR_AGENTS.md Step 7 / the dream.ts
 * docstring's `0 2 * * * gbrain dream --json`) runs `gbrain dream`
 * unconditionally, including on `init --no-embedding` installs (keyless
 * machines). The contract: a full keyless dream MUST exit 0 with the
 * documented degraded posture — key-needing phases skip or refuse with
 * structured, documented messages; nothing crashes; the cron never sees a
 * nonzero from "no keys" alone.
 *
 * What the cycle actually does keyless today (pinned here, verified against
 * a live run):
 *   - chat-dependent phases skip cleanly (`propose_takes` → the gateway's
 *     "no Anthropic API key configured" diagnosis);
 *   - the embed phase clean-skips when `embedding_disabled` is set
 *     (runPhaseEmbed in src/core/cycle.ts, the cycle-side twin of the
 *     CLI's runEmbed/isKeylessStaleRefusal) — status 'skipped', reason
 *     'embedding_disabled', no provider call and no phase error;
 *   - the report status is still 'partial' on this fixture because lint
 *     and orphans warn on the one-page seed brain, never 'failed', and
 *     `gbrain dream` exits 1 only on 'failed' or a failed phase (src/commands/dream.ts).
 *
 * Test shape mirrors test/agent-scheduler-contract.test.ts (keyless
 * PGLite brain, real CLI spawn, exit-code assertions). Non-serial on
 * purpose: no process.env mutation — the child env is built from an
 * ALLOWLIST, so every provider credential the canonical fold recognizes
 * (src/core/ai/provider-env.ts mergedProviderEnv: ANTHROPIC_API_KEY,
 * OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY,
 * VOYAGE_API_KEY, OPENROUTER_API_KEY, VOYAGE_API_KEY,
 * DASHSCOPE_API_KEY, AZURE_OPENAI_*) is absent by construction, and the
 * fixture's config.json sets no config-based keys either.
 */
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'fs';
import { tmpdir } from 'os';
import { join, resolve, dirname } from 'path';
import { spawnSync, execFileSync } from 'child_process';

const REPO = resolve(import.meta.dir, '..');
const CLI = join(REPO, 'src', 'cli.ts');
const SKIP = process.env.GBRAIN_TEST_SKIP_SUBPROCESS === '1';

interface PhaseResultish {
  phase: string;
  status: 'ok' | 'warn' | 'fail' | 'skipped';
  summary: string;
  details?: Record<string, unknown>;
  error?: { class: string; code: string; message: string };
}
interface CycleReportish {
  schema_version: string;
  status: string;
  brain_dir: string | null;
  phases: PhaseResultish[];
  totals: Record<string, number>;
}
interface RunResult { exitCode: number; stdout: string; stderr: string }

describe.skipIf(SKIP)('keyless `gbrain dream` exits 0 (nightly-cron contract)', () => {
  let home = '';
  let repoDir = '';
  let env: Record<string, string>;

  function gbrain(args: string[], timeoutMs: number): RunResult {
    const res = spawnSync(process.execPath, ['run', CLI, ...args], {
      cwd: REPO, // near-repo cwd keeps Bun's transpile cache warm
      env,
      encoding: 'utf8',
      timeout: timeoutMs,
    });
    return { exitCode: res.status ?? -1, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
  }

  /**
   * `dream --json` prints the CycleReport as the LAST pretty-printed JSON
   * object on stdout; on the first sync of a checkout the sync phase's
   * full-import writes human lines to stdout first (the #394 quieting covers
   * the embed phase, not sync's import). Parse from the first line that is
   * exactly '{'.
   */
  function parseReport(stdout: string): CycleReportish {
    const lines = stdout.split('\n');
    const start = lines.findIndex((l) => l === '{');
    if (start === -1) throw new Error(`no JSON object found on stdout:\n${stdout.slice(-2000)}`);
    return JSON.parse(lines.slice(start).join('\n')) as CycleReportish;
  }

  function failedPhases(report: CycleReportish): string[] {
    return report.phases.filter((p) => p.status === 'fail').map((p) => p.phase);
  }

  function byName(report: CycleReportish, phase: string): PhaseResultish {
    const p = report.phases.find((x) => x.phase === phase);
    if (!p) throw new Error(`phase ${phase} missing from report: ${report.phases.map((x) => x.phase).join(', ')}`);
    return p;
  }

  beforeAll(() => {
    home = mkdtempSync(join(tmpdir(), 'gb-dream-keyless-'));
    repoDir = join(home, 'brain');

    const bunDir = dirname(process.execPath || '/usr/local/bin');
    env = {
      // Allowlist-built env: NO inherited vars, so every ambient provider
      // key/endpoint is stripped by construction (see file docstring).
      PATH: `${bunDir}:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`,
      HOME: home,
      GBRAIN_HOME: home,
      TMPDIR: tmpdir(),
      // Keep the startup update-check marker off: env -i children have no
      // NODE_ENV=test, and a stale cache would fire a detached, real-network
      // `gbrain check-update --refresh-cache` per spawn + an
      // UPGRADE_AVAILABLE stderr line that would pollute the posture pins.
      GBRAIN_SKIP_STARTUP_HOOKS: '1',
    };

    // Keyless brain — init --no-embedding's persisted end state.
    mkdirSync(join(home, '.gbrain'), { recursive: true });
    writeFileSync(
      join(home, '.gbrain', 'config.json'),
      JSON.stringify({
        engine: 'pglite',
        database_path: join(home, '.gbrain', 'brain.pglite'),
        embedding_disabled: true,
      }) + '\n',
    );
    const init = gbrain(['init', '--migrate-only'], 120_000);
    if (init.exitCode !== 0) throw new Error(`init --migrate-only failed (${init.exitCode}):\n${init.stderr.slice(-2000)}`);

    // A real checkout with ONE REAL PAGE (anti-vacuity: an engine-only brain
    // skips the whole filesystem half of the cycle; the documented install
    // has a brain repo, so the sync/lint/extract phases must run keyless
    // too). Repo-local git identity — HOME=tmp has no global gitconfig.
    mkdirSync(join(repoDir, 'people'), { recursive: true });
    const git = (args: string[]) =>
      execFileSync('git', ['-C', repoDir, ...args], {
        stdio: ['ignore', 'pipe', 'pipe'],
        timeout: 30_000,
        env: {
          ...env,
          GIT_AUTHOR_DATE: '2026-08-01T00:00:00Z',
          GIT_COMMITTER_DATE: '2026-08-01T00:00:00Z',
        },
      });
    writeFileSync(
      join(repoDir, 'people', 'alice-example.md'),
      '# Alice Example\n\nA real page so nothing here passes vacuously.\n',
    );
    git(['init', '-q', '-b', 'main']);
    git(['config', 'user.email', '[email protected]']);
    git(['config', 'user.name', 'Dream Keyless Test']);
    git(['add', '-A']);
    git(['commit', '-q', '-m', 'seed page']);

    // Wire the checkout as the brain dir the way pre-v0.18 default-source
    // brains do (dream.ts resolveBrainDir tier 3: the sync.repo_path config
    // key) — no --dir on the cron line, exactly like the documented install.
    const cfg = gbrain(['config', 'set', 'sync.repo_path', repoDir], 60_000);
    if (cfg.exitCode !== 0) throw new Error(`config set sync.repo_path failed (${cfg.exitCode}):\n${cfg.stderr.slice(-2000)}`);
  }, 240_000);

  afterAll(() => {
    rmSync(home, { recursive: true, force: true });
  });

  test('1. full keyless dream --json exits 0 with the documented degraded posture', () => {
    const r = gbrain(['dream', '--json'], 180_000);
    if (r.exitCode !== 0) {
      throw new Error(`keyless dream exited ${r.exitCode}\nstderr:\n${r.stderr.slice(-2500)}\nstdout:\n${r.stdout.slice(-1500)}`);
    }
    expect(r.exitCode).toBe(0);

    const report = parseReport(r.stdout);
    expect(report.schema_version).toBe('1');
    // 'partial', never 'failed': lint/orphans warn on the seed brain (see
    // file docstring) and dream only exits 1 on report.status === 'failed'.
    expect(report.status).toBe('partial');

    // Anti-vacuity: the cycle really ran the filesystem half — the seed page
    // synced into the brain on the first pass.
    expect(byName(report, 'sync').status).toBe('ok');
    expect(report.totals.pages_synced).toBeGreaterThanOrEqual(1);

    // Documented keyless/degraded skip posture, pinned to the real strings:
    // chat-dependent proposal phase names the missing key + the remedy...
    const propose = byName(report, 'propose_takes');
    expect(propose.status).toBe('skipped');
    expect(propose.summary).toContain('no Anthropic API key configured');
    expect(propose.summary).toContain('ANTHROPIC_API_KEY');
    // ...and synthesize skips on its own config gate, not a key crash.
    const synthesize = byName(report, 'synthesize');
    expect(synthesize.status).toBe('skipped');
    expect(synthesize.summary).toContain('dream.synthesize.session_corpus_dir is unset');

    // No phase fails keyless: embed clean-skips on the deferred-setup
    // sentinel instead of surfacing EmbeddingDisabledError as a failure.
    expect(failedPhases(report)).toEqual([]);
    const embed = byName(report, 'embed');
    expect(embed.status).toBe('skipped');
    expect(embed.summary).toBe('embeddings disabled; no provider call made');
    expect(embed.details?.reason).toBe('embedding_disabled');
    expect(report.totals.pages_embedded).toBe(0);

    // No phase reports an error at all, and nothing anywhere smells like an
    // unhandled programmer error.
    for (const p of report.phases) {
      expect(p.error).toBeUndefined();
      const text = `${p.summary} ${p.error?.message ?? ''}`;
      expect(text).not.toMatch(/TypeError|ReferenceError|is not a function|undefined is not/);
    }
  }, 300_000);

  test('2. a second invocation is also 0 (idempotent nightly re-run)', () => {
    const r = gbrain(['dream', '--json'], 180_000);
    if (r.exitCode !== 0) {
      throw new Error(`second keyless dream exited ${r.exitCode}\nstderr:\n${r.stderr.slice(-2500)}\nstdout:\n${r.stdout.slice(-1500)}`);
    }
    expect(r.exitCode).toBe(0);

    const report = parseReport(r.stdout);
    expect(report.status).toBe('partial');
    // Same degraded posture on re-run — embed still clean-skips and nothing
    // new broke because the first cycle already banked its work.
    expect(failedPhases(report)).toEqual([]);
    expect(byName(report, 'embed').status).toBe('skipped');
    expect(byName(report, 'embed').details?.reason).toBe('embedding_disabled');
  }, 300_000);

  test('3. the plain (human) spelling exits 0 too, naming the degraded posture', () => {
    const r = gbrain(['dream'], 180_000);
    if (r.exitCode !== 0) {
      throw new Error(`plain keyless dream exited ${r.exitCode}\nstderr:\n${r.stderr.slice(-2500)}\nstdout:\n${r.stdout.slice(-1500)}`);
    }
    expect(r.exitCode).toBe(0);
    // printHuman's partial rendering: the header line + the embed skip
    // reason so an operator reading the cron log sees WHY embed shows -.
    expect(r.stdout).toContain('Dream cycle (partial)');
    expect(r.stdout).toContain('embeddings disabled; no provider call made');
    expect(r.stdout).not.toContain('✗ embed');
  }, 300_000);
});