Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
17.8 KB
Raw Blame
/**
 * attach-mode e2e [ENG-tests-2, CX-P1.5, CX2-1, CX2-12]: machine-1 fixture
 * (scripted interview → confirm → render → git init + commit + local bare
 * 'origin') cloned to a machine-2 dir with a SECOND sandboxed GBRAIN_HOME:
 *
 *   - `runBootstrap(['attach'])` on the clone: exit 0, machine-2 receipt
 *     written with brain_created_by_bootstrap: false, ordered todo steps
 *     returned (register_source → hooks_repair → mcp_add → verify).
 *   - hooks repair on machine 2 (env-pinned fake ExecRunner): MCP argv
 *     recorded, settings.local.json written with the _gbrain marker entries,
 *     receipt registration appended.
 *   - template clone (initialized: false via `render --minimal`) REFUSED
 *     with the agent-readable message pointing at `bootstrap render`.
 *   - absent agent.json REFUSED as not-a-workspace.
 *
 * Serial: sandboxed GBRAIN_HOME env mutation across the whole file.
 */
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { execFileSync } from 'node:child_process';
import {
  chmodSync,
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  rmSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

import { runBootstrap } from '../../src/commands/bootstrap.ts';

import type { ExecRunner } from '../../src/core/bootstrap/repo.ts';
import { attachWorkspace } from '../../src/core/bootstrap/attach.ts';
import { readManifest, readReceipt } from '../../src/core/bootstrap/format.ts';
import { initState, setAnswer, confirm, readBackHash } from '../../src/core/bootstrap/interview.ts';
import { realpathOrResolve } from '../../src/core/path-confine.ts';
import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
import { addSource } from '../../src/core/sources-ops.ts';
import { importFromFile } from '../../src/core/import-file.ts';
import { verifyWorkspace } from '../../src/core/bootstrap/verify.ts';
import { operations, type OperationContext } from '../../src/core/operations.ts';
import type { CapabilityReport } from '../../src/core/capability.ts';
import { CORPUS_DIR } from '../helpers/bootstrap-corpus.ts';

// Cold-path opt-out (conservative): bootstrap-arc file — attach semantics on
// a brain whose init path should stay the genuine cold build.
delete process.env.GBRAIN_PGLITE_SNAPSHOT;

/** Keyless capability report — machine 2 re-ingests + verifies with ZERO keys. */
const KEYLESS: CapabilityReport = {
  embeddings: { available: false },
  extraction: { available: false },
  search: 'keyword-only',
  mode: 'keyless',
};

/** A page authored ONLY on machine 1, committed to the repo, cloned to machine 2. */
const MACHINE1_PAGE_SLUG = 'companies/summit-robotics';
/** A distinctive fact that exists nowhere but machine 1's authored repo page. */
const MACHINE1_MARKER = 'The flagship warehouse pilot runs at the Rivermouth fulfillment center.';

const SAVED_ENV: Record<string, string | undefined> = {};
const ENV_KEYS = [
  'GBRAIN_HOME', 'GBRAIN_DATABASE_URL', 'DATABASE_URL', 'GBRAIN_BRAIN_ID',
  'GBRAIN_SOURCE', 'GBRAIN_HOOKS', 'GBRAIN_BOOTSTRAP_ABORT_AFTER',
  'CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT', 'CODEX_HOME', 'CODEX_SANDBOX', 'CODEX_CI',
];

const ANSWERS: Record<string, string> = {
  AGENT_NAME: 'Beacon',
  PRINCIPAL_NAME: 'Pat Example',
  AGENT_PURPOSE: 'Keep the research corpus current and draft the weekly memo without re-briefing.',
  AGENT_TOP_JOBS: '- corpus upkeep\n- weekly memo\n- meeting prep',
  PRINCIPAL_CONTEXT: 'Runs a small research group; builds internal tooling; values signal over noise.',
  VOICE_REGISTER: 'Direct: three options, the second one wins.',
};

let machine1Home: string; // GBRAIN_HOME parent for machine 1
let machine2Home: string; // GBRAIN_HOME parent for machine 2
let ws1: string; // machine-1 workspace (bootstrap-created fixture)
let ws2: string; // machine-2 clone
let bareOrigin: string; // local bare 'origin'
let cloneParent: string;

/** Recording in-process ExecRunner — the env-pinned fake for MCP registration. */
const recorded: string[][] = [];
const fakeRunner: ExecRunner = async (argv: string[]) => {
  recorded.push([...argv]);
  if (argv[0] === 'claude' && argv[1] === 'mcp' && argv[2] === 'list') {
    return { code: 0, stdout: 'gbrain: stdio serve', stderr: '' };
  }
  if (argv[0] === 'claude' || argv[0] === 'codex') {
    return { code: 0, stdout: '', stderr: '' };
  }
  // git and anything else runs for real via a spawn-free refusal — the attach
  // + hooks paths under test never need a real subprocess beyond claude/codex.
  return { code: 0, stdout: '', stderr: '' };
};

async function captureStd<T>(fn: () => Promise<T>): Promise<{ result: T; out: string; err: string }> {
  const origLog = console.log;
  const origErr = console.error;
  let out = '';
  let err = '';
  console.log = (...args: unknown[]) => { out += args.map(String).join(' ') + '\n'; };
  console.error = (...args: unknown[]) => { err += args.map(String).join(' ') + '\n'; };
  try {
    const result = await fn();
    return { result, out, err };
  } finally {
    console.log = origLog;
    console.error = origErr;
  }
}

function git(cwd: string, args: string[]): string {
  return execFileSync('git', ['-C', cwd, ...args], { stdio: ['ignore', 'pipe', 'pipe'] })
    .toString()
    .trim();
}

beforeAll(async () => {
  for (const k of ENV_KEYS) SAVED_ENV[k] = process.env[k];
  for (const k of ENV_KEYS) delete process.env[k];

  machine1Home = mkdtempSync(join(tmpdir(), 'gb-att1-'));
  machine2Home = mkdtempSync(join(tmpdir(), 'gb-att2-'));
  ws1 = mkdtempSync(join(tmpdir(), 'gb-att-ws1-'));
  cloneParent = mkdtempSync(join(tmpdir(), 'gb-att-cl-'));
  ws2 = join(cloneParent, 'workspace-clone');
  bareOrigin = join(cloneParent, 'origin.git');

  // ── Machine 1: the committed lifecycle flow (interview → confirm → render).
  process.env.GBRAIN_HOME = machine1Home;
  expect(initState(ws1).ok).toBe(true);
  for (const [key, value] of Object.entries(ANSWERS)) {
    const r = setAnswer(ws1, key, value);
    if (!r.ok) throw new Error(r.message);
  }
  for (const [key, value] of [
    ['MCP_SCOPE', 'project'],
    ['HOOKS_CONSENT', 'yes'],
    ['PERSIST_CRON', 'no'],
  ] as const) {
    const r = setAnswer(ws1, key, value);
    if (!r.ok) throw new Error(r.message);
  }
  const h = readBackHash(ws1);
  if (!h.ok) throw new Error(h.message);
  expect(confirm(ws1, h.hash).ok).toBe(true);
  const renderCode = await (await captureStd(() => runBootstrap(['render', '--workspace', ws1]))).result;
  expect(renderCode).toBe(0);
  expect(readManifest(ws1).state).toBe('initialized');

  // Author a corpus page into machine 1's brain/ BEFORE the commit — a real
  // synthetic page carrying a machine-1-only fact (the Rivermouth marker). It
  // lives ONLY in the repo, so machine 2 can only learn it by re-ingesting the
  // clone [multi-device promise: hot facts arrive via the repo].
  const corpusPage = readFileSync(join(CORPUS_DIR, 'pages', 'companies__summit-robotics.md'), 'utf8');
  mkdirSync(join(ws1, 'brain', 'companies'), { recursive: true });
  writeFileSync(
    join(ws1, 'brain', 'companies', 'summit-robotics.md'),
    `${corpusPage.trimEnd()}\n\n## Operations\n\n${MACHINE1_MARKER}\n`,
  );

  // git init + commit + local bare 'origin' + clone → machine 2.
  git(ws1, ['init', '-q', '-b', 'main']);
  git(ws1, ['config', 'user.email', '[email protected]']);
  git(ws1, ['config', 'user.name', 'Test']);
  git(ws1, ['add', '-A']);
  git(ws1, ['commit', '-q', '-m', 'bootstrap fixture']);
  execFileSync('git', ['init', '-q', '--bare', bareOrigin]);
  // The bare origin's default HEAD (master) must match the pushed branch or
  // `git clone` checks out an EMPTY tree ("remote HEAD refers to nonexistent
  // ref") and machine 2 sees no agent.json.
  execFileSync('git', ['-C', bareOrigin, 'symbolic-ref', 'HEAD', 'refs/heads/main']);
  git(ws1, ['remote', 'add', 'origin', bareOrigin]);
  git(ws1, ['push', '-q', 'origin', 'main']);
  execFileSync('git', ['clone', '-q', bareOrigin, ws2]);

  // ── Machine 2 from here on: a SECOND sandboxed GBRAIN_HOME.
  process.env.GBRAIN_HOME = machine2Home;
}, 120_000);

afterAll(() => {
  for (const k of ENV_KEYS) {
    if (SAVED_ENV[k] === undefined) delete process.env[k];
    else process.env[k] = SAVED_ENV[k];
  }
  for (const dir of [machine1Home, machine2Home, ws1, cloneParent]) {
    try {
      rmSync(dir, { recursive: true, force: true });
    } catch {
      /* best effort */
    }
  }
});

describe('bootstrap attach (machine-2 adoption, serial e2e)', () => {
  test('attach on a machine-2 clone: exit 0, receipt written with brain_created_by_bootstrap false, steps printed', async () => {
    const { result: code, out } = await captureStd(() =>
      runBootstrap(['attach', '--workspace', ws2, '--harness', 'claude-code']),
    );
    expect(code).toBe(0);
    expect(out).toContain('attached workspace for agent "Beacon"');
    expect(out).toContain("source 'workspace'");
    // The ordered todo-list the dispatcher relays.
    expect(out).toContain('gbrain sources add');
    expect(out).toContain('bootstrap hooks --harness claude-code --repair');
    expect(out).toContain('gbrain bootstrap verify');

    const receipt = readReceipt(join(machine2Home, '.gbrain'));
    expect(receipt).not.toBeNull();
    expect(receipt!.workspace_dir).toBe(realpathOrResolve(ws2));
    expect(receipt!.agent_name).toBe('Beacon');
    expect(receipt!.source_id).toBe('workspace');
    // Attach ADOPTS an existing brain — never claims brain ownership [CX2-12].
    expect(receipt!.brain_created_by_bootstrap).toBe(false);
    expect(receipt!.created_paths).toEqual([]);
    // Attach records repo_url from the adopted origin so the no-daemon push
    // gate (repoPhaseComplete) recognizes the repo phase as done on this
    // machine — without it the per-turn/session-end pushes defer forever, and
    // attach is the ONLY install path in a cloud sandbox.
    expect((receipt as { repo_url?: string }).repo_url).toContain('origin.git');
  }, 60_000);

  test('attach steps are the ordered machine-2 todo list; re-attach preserves the same-workspace receipt', () => {
    const before = readReceipt(join(machine2Home, '.gbrain'));
    expect(before).not.toBeNull();
    const res = attachWorkspace(ws2, {
      harness: 'claude-code',
      gbrainHomeDir: join(machine2Home, '.gbrain'),
      createdBy: 'test-reattach',
    });
    expect(res.steps.map((s) => s.kind)).toEqual(['register_source', 'hooks_repair', 'mcp_add', 'verify']);
    // Same-workspace re-attach preserves ownership fields (no laundering).
    const after = readReceipt(join(machine2Home, '.gbrain'));
    expect(after!.created_at).toBe(before!.created_at);
    expect(after!.brain_created_by_bootstrap).toBe(false);
  }, 30_000);

  test('hooks repair on machine 2: MCP argv recorded via the fake runner, settings.local.json carries the marker entries, receipt updated', async () => {
    // Absolute fake gbrain binary for registration/hook command strings —
    // never executed by this test.
    const fakeBin = join(machine2Home, 'gbrain');
    writeFileSync(fakeBin, '#!/bin/sh\nexit 0\n');
    chmodSync(fakeBin, 0o755);

    recorded.length = 0;
    const { result: code } = await captureStd(() =>
      runBootstrap(
        ['hooks', '--workspace', ws2, '--harness', 'claude-code', '--repair', '--gbrain-bin', fakeBin],
        { runner: fakeRunner },
      ),
    );
    expect(code).toBe(0);

    // MCP registration went through the env-pinned fake runner with the
    // source binding [G1].
    const flat = recorded.map((argv) => argv.join(' '));
    expect(flat.some((c) => c.startsWith('claude mcp add gbrain') && c.includes('GBRAIN_SOURCE=workspace'))).toBe(true);
    expect(flat).toContain('claude mcp list');

    // Machine-local hook wiring re-rendered with the marker entries.
    const settingsPath = join(ws2, '.claude', 'settings.local.json');
    expect(existsSync(settingsPath)).toBe(true);
    const raw = readFileSync(settingsPath, 'utf8');
    expect(raw).toContain('"_gbrain"');
    expect(raw).toContain('"bootstrap-v1"');
    const settings = JSON.parse(raw) as { hooks: Record<string, unknown> };
    expect(Object.keys(settings.hooks)).toEqual(
      expect.arrayContaining(['SessionStart', 'UserPromptSubmit', 'Stop', 'SessionEnd']),
    );

    const receipt = readReceipt(join(machine2Home, '.gbrain'));
    expect(receipt!.registrations).toEqual([
      { host: 'claude-code', scope: 'project', detail: 'mcp+hooks' },
    ]);
  }, 60_000);

  test('machine-2 full round-trip: repo page re-ingests into a FRESH brain, verify passes, and a machine-1-only fact is recalled', async () => {
    // A fresh machine-2 PGLite brain — nothing pre-seeded. The only path a fact
    // can reach it is the cloned repo tree. Hermetic in-memory engine (the
    // proven in-process verify pattern) so teardown is clean.
    const engine = new PGLiteEngine();
    await engine.connect({});
    await engine.initSchema();
    try {
      // Register the cloned brain/ as the workspace source (what `bootstrap
      // attach` → `gbrain sources add` does on machine 2).
      await addSource(engine, { id: 'workspace', localPath: join(ws2, 'brain'), force: true });

      // Precondition: the machine-1-authored page is NOT in the fresh DB — it
      // exists ONLY as a committed repo file cloned from machine 1.
      expect(await engine.getPage(MACHINE1_PAGE_SLUG, { sourceId: 'workspace' })).toBeNull();
      const clonedFile = join(ws2, 'brain', 'companies', 'summit-robotics.md');
      expect(existsSync(clonedFile)).toBe(true);
      expect(readFileSync(clonedFile, 'utf8')).toContain(MACHINE1_MARKER);

      // Re-ingest through the REAL per-file import path (the primitive `gbrain
      // sync` runs on each changed file), scoped to the workspace source.
      const rel = join('companies', 'summit-robotics.md');
      const imp = await importFromFile(engine, clonedFile, rel, { sourceId: 'workspace', noEmbed: true });
      expect(imp.status).toBe('imported');
      expect(imp.slug).toBe(MACHINE1_PAGE_SLUG);

      // The page + its machine-1-authored content now live in machine 2's DB.
      const page = await engine.getPage(MACHINE1_PAGE_SLUG, { sourceId: 'workspace' });
      expect(page).not.toBeNull();
      expect(page!.title).toBe('Summit Robotics');
      expect(page!.compiled_truth ?? '').toContain(MACHINE1_MARKER);

      // The clone's origin is a local bare path gh cannot prove private; drop it
      // so repo_privacy resolves to the honest local-only pass. The multi-device
      // fact transport under test is orthogonal to remote-privacy verification.
      execFileSync('git', ['-C', ws2, 'remote', 'remove', 'origin']);

      // `bootstrap verify` core runs GREEN on machine 2, keyless.
      const res = await verifyWorkspace(engine, ws2, {
        sourceId: 'workspace',
        gbrainHomeDir: join(machine2Home, '.gbrain'),
        capabilities: KEYLESS,
        skipHooksSmoke: true,
      });
      if (!res.ok) console.error(res.report);
      expect(res.ok).toBe(true);
      expect(res.checks.find((c) => c.id === 'roundtrip')!.ok).toBe(true);

      // Recall the machine-1-only fact through the REAL keyword-search query op.
      // The Rivermouth marker was authored on machine 1 and reached machine 2
      // ONLY via the repo, so a hit proves the multi-device promise end to end.
      const queryOp = operations.find((o) => o.name === 'query')!;
      const ctx: OperationContext = {
        engine,
        config: { engine: 'pglite' } as never,
        logger: { info: () => {}, warn: () => {}, error: () => {} },
        dryRun: false,
        remote: false,
        sourceId: 'workspace',
      };
      const markerHit = await queryOp.handler(ctx, { query: 'Rivermouth fulfillment center warehouse', limit: 10, expand: false });
      expect(JSON.stringify(markerHit)).toContain(MACHINE1_PAGE_SLUG);
      const goldHit = await queryOp.handler(ctx, { query: 'warehouse navigation robots startup', limit: 10, expand: false });
      expect(JSON.stringify(goldHit)).toContain(MACHINE1_PAGE_SLUG);
    } finally {
      // The query op fires retrieval telemetry (last_retrieved_at / search
      // stats) as a background write. PGLite serializes one connection, so a
      // yield-then-flush drains that in-flight write BEFORE close() — issuing
      // db.close() with a query still queued otherwise deadlocks disconnect.
      await new Promise((r) => setTimeout(r, 100));
      await engine.executeRaw('SELECT 1').catch(() => {});
      await engine.disconnect();
    }
  }, 240_000);

  test('template clone (initialized: false) is REFUSED with the agent-readable render pointer [CX2-1]', async () => {
    const ws3 = mkdtempSync(join(tmpdir(), 'gb-att-ws3-'));
    try {
      // `render --minimal` writes the canonical placeholder manifest —
      // exactly what a template-repo clone carries.
      const { result: renderCode } = await captureStd(() => runBootstrap(['render', '--minimal', '--workspace', ws3]));
      expect(renderCode).toBe(0);
      expect(readManifest(ws3).state).toBe('template');

      const { result: code, err } = await captureStd(() => runBootstrap(['attach', '--workspace', ws3]));
      expect(code).toBe(1);
      expect(err).toContain('uninitialized template');
      expect(err).toContain('gbrain bootstrap render');
      // No receipt overwrite from the refused attach: the machine-2 receipt
      // still points at ws2.
      expect(readReceipt(join(machine2Home, '.gbrain'))!.workspace_dir).toBe(realpathOrResolve(ws2));
    } finally {
      rmSync(ws3, { recursive: true, force: true });
    }
  }, 60_000);

  test('absent agent.json is REFUSED as not-a-workspace', async () => {
    const ws4 = mkdtempSync(join(tmpdir(), 'gb-att-ws4-'));
    try {
      const { result: code, err } = await captureStd(() => runBootstrap(['attach', '--workspace', ws4]));
      expect(code).toBe(1);
      expect(err).toContain('not an agent workspace');
      expect(err).toContain('agent.json');
    } finally {
      rmSync(ws4, { recursive: true, force: true });
    }
  }, 30_000);
});