Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.6 KB
Raw Blame
/**
 * Agent contract v1 `--json` guard (A0/D2): under the guard, fd 1 carries
 * exactly one JSON document. Interposed stdout writes and console.log go to
 * stderr; only writeStdoutFinal (or writeNdjsonLine) reaches fd 1; a non-zero
 * exit that wrote no document gets the fallback document; spawnCliChild
 * pipes a child's stdout to stderr. Child processes, because the guard
 * patches process-global stdout/exit.
 */
import { describe, expect, test } from 'bun:test';
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const HELPER = join(import.meta.dir, '..', 'src', 'core', 'cli-force-exit.ts');

async function run(body: string): Promise<{ out: string; err: string; code: number }> {
  const dir = mkdtempSync(join(tmpdir(), 'gbrain-json-guard-'));
  const script = join(dir, 'run.ts');
  writeFileSync(script, `import * as g from ${JSON.stringify(HELPER)};\n${body}\n`);
  try {
    const proc = Bun.spawn([process.execPath, script], { stdout: 'pipe', stderr: 'pipe' });
    const [out, err, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
    return { out, err, code };
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

describe('#6629 json_document_missing event', () => {
  test('the event names the release, guard and exit code, and carries no argv values', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-6629-'));
    const dir = mkdtempSync(join(tmpdir(), 'gbrain-6629-run-'));
    const script = join(dir, 'run.ts');
    const src = join(import.meta.dir, '..', 'src');
    writeFileSync(script, `import * as g from ${JSON.stringify(HELPER)};
import { agentJsonGuardMode } from ${JSON.stringify(join(src, 'cli', 'json-guard.ts'))};
const { json } = agentJsonGuardMode(['doctor', '--json', '--fast', 'private-arg-value']);
g.installStdoutPipeDelivery({ json });
console.log('forgot the document');
process.exit(0);`);
    try {
      const proc = Bun.spawn([process.execPath, script], { stdout: 'pipe', stderr: 'pipe', env: { ...process.env, GBRAIN_HOME: home } });
      expect(await proc.exited).toBe(0);
      const raw = readFileSync(join(home, '.gbrain', 'agent-contract', 'events.jsonl'), 'utf8').trim();
      const { ts, ...event } = JSON.parse(raw.split('\n').pop()!);
      expect(typeof ts).toBe('string');
      const { VERSION } = await import('../src/version.ts');
      expect(event).toEqual({ transport: 'cli', command: 'doctor', code: 'json_document_missing', outcome: 'committed', version: VERSION, guard: 'document', exit_code: 0 });
      expect(raw).not.toContain('private-arg-value');
    } finally {
      rmSync(home, { recursive: true, force: true });
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

describe('--json guard (document mode)', () => {
  test('console.log and stdout.write go to stderr; the final document alone reaches fd 1', async () => {
    const r = await run(`g.installStdoutPipeDelivery({ json: 'document' });
console.log('human progress line');
process.stdout.write('more noise\\n');
await g.writeStdoutFinal(JSON.stringify({ ok: true }) + '\\n');
g.flushThenExit(0);`);
    expect(r.code).toBe(0);
    expect(JSON.parse(r.out)).toEqual({ ok: true });
    expect(r.err).toContain('human progress line');
    expect(r.err).toContain('more noise');
  });

  test('a direct non-zero exit with no document writes the fallback document', async () => {
    const r = await run(`g.installStdoutPipeDelivery({ json: 'document' });
console.log('Error: something human');
g.noteRenderedErrorCode('invalid_params');
process.exit(2);`);
    expect(r.code).toBe(2);
    const doc = JSON.parse(r.out);
    expect(doc).toEqual({
      error: 'command_failed', code: 'invalid_params',
      message: 'The command exited with status 2 without writing its JSON result.',
      suggestion: 'Re-run without --json to read the error on stderr, or run `gbrain doctor --json`.',
      exit_code: 2, contract_version: 1,
    });
  });

  test('a document already written is never followed by a fallback', async () => {
    const r = await run(`g.installStdoutPipeDelivery({ json: 'document' });
await g.writeStdoutFinal(JSON.stringify({ error: 'x', code: 'x' }) + '\\n');
process.exit(1);`);
    expect(r.code).toBe(1);
    expect(JSON.parse(r.out)).toEqual({ error: 'x', code: 'x' });
  });

  test('exit 0 without a document writes nothing to fd 1 (a bug D5 fails; E11 hook fires)', async () => {
    const r = await run(`g.installStdoutPipeDelivery({ json: 'document' });
g.setJsonDocumentMissingHook(() => process.stderr.write('HOOK_FIRED\\n'));
console.log('forgot the document');
process.exit(0);`);
    expect(r.code).toBe(0);
    expect(r.out).toBe('');
    expect(r.err).toContain('HOOK_FIRED');
  });

  test('ndjson: lines reach fd 1; a failing exit appends a status:error line', async () => {
    const r = await run(`g.installStdoutPipeDelivery({ json: 'ndjson' });
await g.writeNdjsonLine({ n: 1 });
console.log('noise');
process.exit(1);`);
    const lines = r.out.trim().split('\n').map(l => JSON.parse(l));
    expect(lines[0]).toEqual({ n: 1 });
    expect(lines[1]).toMatchObject({ status: 'error', error: 'command_failed', exit_code: 1 });
  });

  test('spawnCliChild pipes the child stdout to stderr under the guard', async () => {
    const r = await run(`g.installStdoutPipeDelivery({ json: 'document' });
const child = g.spawnCliChild(process.execPath, ['-e', 'console.log("child says hi")']);
await new Promise(res => child.on('close', res));
await g.writeStdoutFinal(JSON.stringify({ ok: 1 }) + '\\n');
g.flushThenExit(0);`);
    expect(JSON.parse(r.out)).toEqual({ ok: 1 });
    expect(r.err).toContain('child says hi');
  });

  test('without the guard, installStdoutPipeDelivery keeps stdout as-is', async () => {
    const r = await run(`g.installStdoutPipeDelivery();
console.log('plain');
g.flushThenExit(0);`);
    expect(r.out).toBe('plain\n');
  });
});

// ── D2: command migrations (real CLI subprocesses, isolated GBRAIN_HOME) ──
import { runCli } from './helpers/cli-spawn.ts';
import { mkdirSync } from 'node:fs';

function onlyDocument(stdout: string): Record<string, unknown> {
  const doc = JSON.parse(stdout);
  expect(typeof doc).toBe('object');
  return doc;
}

describe('D2 command migrations: init', () => {
  test('init --pglite --no-embedding --json: one document carrying the first-run decision bundle', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-json-init-'));
    try {
      const r = await runCli(['init', '--pglite', '--no-embedding', '--json'], { home, cwd: home, timeoutMs: 120_000 });
      expect(r.exitCode).toBe(0);
      const doc = onlyDocument(r.stdout);
      expect(doc).toMatchObject({ status: 'success', engine: 'pglite', contract_version: 1 });
      const bundle = (doc.notices as Array<Record<string, any>>).find(n => n.code === 'first_run_decisions')!;
      expect(bundle).toMatchObject({ kind: 'ask', contract_version: 1 });
      expect(bundle.user_message).toContain('Nothing needs an answer now');
      const searchMode = bundle.decisions.find((d: { id: string }) => d.id === 'search_mode');
      expect(searchMode.options.map((o: { id: string }) => o.id)).toEqual(['conservative', 'balanced', 'tokenmax']);
      expect(searchMode.options[0].argv).toEqual(['gbrain', 'config', 'set', 'search.mode', 'conservative']);
      // Progress lines and the picker's event went to stderr.
      expect(r.stderr).toContain('Setting up local brain with PGLite');
      expect(r.stdout).not.toContain('search_mode_picker');
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  }, 150_000);

  test('init --json usage failure: legacy one-line keys plus the v1 envelope, exit 2', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-json-init-'));
    try {
      const r = await runCli(['init', '--mcp-only', '--json', '--mcp-url', 'http://127.0.0.1:1/mcp', '--oauth-client-id', 'cid', '--oauth-client-secret', 'cs'], { home, cwd: home });
      expect(r.exitCode).toBe(2);
      expect(r.stdout.trim().split('\n')).toHaveLength(1);
      expect(onlyDocument(r.stdout)).toMatchObject({ status: 'error', reason: 'missing_issuer_url', error: 'invalid_params', code: 'invalid_params', contract_version: 1 });
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  });

  test('init --json on a malformed config: config_error document, config untouched', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-json-init-'));
    try {
      mkdirSync(join(home, '.gbrain'));
      writeFileSync(join(home, '.gbrain', 'config.json'), '{broken');
      const r = await runCli(['init', '--pglite', '--json'], { home, cwd: home });
      expect(r.exitCode).toBe(1);
      const doc = onlyDocument(r.stdout);
      expect(doc).toMatchObject({ status: 'error', reason: 'invalid_existing_config', code: 'config_error' });
      expect(typeof doc.suggestion).toBe('string');
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  });
});

describe('D2 command migrations: doctor, sync, embed on a keyless brain', () => {
  let home = '';
  const cli = (args: string[]) => runCli(args, { home, cwd: home, timeoutMs: 120_000 });

  test('setup: keyless PGLite brain + a git-backed source', async () => {
    home = mkdtempSync(join(tmpdir(), 'gbrain-json-cmds-'));
    expect((await cli(['init', '--pglite', '--no-embedding', '--json'])).exitCode).toBe(0);
    const repo = join(home, 'notes');
    mkdirSync(repo);
    writeFileSync(join(repo, 'example.md'), '---\ntitle: Example\n---\nHello world\n');
    const git = (args: string[]) => Bun.spawnSync(['git', '-c', '[email protected]', '-c', 'user.name=fixture', ...args], { cwd: repo });
    git(['init', '-q']); git(['add', '.']); git(['commit', '-qm', 'init']);
    expect((await cli(['sources', 'add', 'notes', '--path', repo])).exitCode).toBe(0);
  }, 150_000);

  test('doctor --json --fast: one report document', async () => {
    const r = await cli(['doctor', '--json', '--fast']);
    expect(onlyDocument(r.stdout)).toMatchObject({ schema_version: 2 });
    expect(typeof onlyDocument(r.stdout).health_score).toBe('number');
  }, 120_000);

  test('sync --json success: one envelope; a failing sync: one v1 error document', async () => {
    const ok = await cli(['sync', '--source', 'notes', '--no-pull', '--json']);
    expect(ok.exitCode).toBe(0);
    expect(onlyDocument(ok.stdout)).toMatchObject({ schema_version: 1, source_id: 'notes', added: 1 });
    const bad = await cli(['sync', '--source', 'no-such-source', '--no-pull', '--json']);
    expect(bad.exitCode).toBe(1);
    const doc = onlyDocument(bad.stdout);
    expect(typeof doc.code).toBe('string');
    expect(typeof doc.suggestion).toBe('string');
    expect(doc.contract_version).toBe(1);
  }, 120_000);

  test('embed --json: keyless --stale is a result document (exit 0); --all is embedding_disabled (exit 1)', async () => {
    const stale = await cli(['embed', '--stale', '--json']);
    expect(stale.exitCode).toBe(0);
    expect(onlyDocument(stale.stdout)).toMatchObject({ failures: 0 });
    const all = await cli(['embed', '--all', '--json']);
    expect(all.exitCode).toBe(1);
    const doc = onlyDocument(all.stdout) as { code?: string; reason?: string; fix?: { argv?: string[] } };
    expect(doc).toMatchObject({ code: 'embedding_disabled', reason: 'disabled_by_choice' });
    expect(doc.fix?.argv?.[0]).toBe('gbrain'); // the readiness enablement command (A7)
  }, 120_000);

  test('sync status|unblock --json: the one document on stdout, nothing JSON on stderr (#6386)', async () => {
    for (const verb of ['status', 'unblock']) {
      const r = await cli(['sync', verb, '--source', 'notes', '--json']);
      expect(r.exitCode).toBe(0);
      expect(onlyDocument(r.stdout)).toMatchObject({ source_id: 'notes' });
      expect(r.stderr.split('\n').some(line => line.startsWith('{'))).toBe(false);
    }
  }, 120_000);

  test('doctor --json with no brain: the no_brain envelope', async () => {
    const empty = mkdtempSync(join(tmpdir(), 'gbrain-json-nobrain-'));
    try {
      const r = await runCli(['doctor', '--json'], { home: empty, cwd: empty });
      expect(r.exitCode).toBe(1);
      expect(onlyDocument(r.stdout)).toMatchObject({ code: 'no_brain', fix: { argv: ['gbrain', 'init', '--pglite', '--no-embedding'] } });
    } finally {
      rmSync(empty, { recursive: true, force: true });
    }
  });

  test('teardown', () => { rmSync(home, { recursive: true, force: true }); });
});

describe('D2 command migrations: embed --facts on a brain with an embedding model', () => {
  test('embed --stale --facts --dry-run --json: one document on stdout, no copy on stderr (#6386)', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-json-facts-'));
    try {
      const cli = (args: string[]) => runCli(args, { home, cwd: home, timeoutMs: 120_000, env: { OPENAI_API_KEY: undefined } });
      expect((await cli(['init', '--pglite', '--embedding-model', 'openai:text-embedding-3-small', '--json'])).exitCode).toBe(0);
      const r = await cli(['embed', '--stale', '--facts', '--source', 'default', '--dry-run', '--json']);
      expect(r.exitCode).toBe(0);
      expect(onlyDocument(r.stdout)).toMatchObject({ source_id: 'default', dryRun: true, stopped: 'preview' });
      expect(r.stderr.split('\n').some(line => line.startsWith('{'))).toBe(false);
      const plain = await cli(['embed', '--stale', '--facts', '--source', 'default', '--dry-run']);
      expect(plain.exitCode).toBe(0);
      expect(onlyDocument(plain.stdout)).toMatchObject({ source_id: 'default', dryRun: true });
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  }, 150_000);
});