Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.4 KB
Raw Blame
import { afterEach, describe, expect, test } from 'bun:test';
import { once } from 'node:events';
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { startPersistenceIpcServer, persistenceSocketPathForConfig, type PersistenceIpcRequest } from '../src/core/persistence/ipc.ts';
import { runDeferredPersistenceCommand } from '../src/commands/persistence-delegate.ts';
import { withEnv } from './helpers/with-env.ts';
import { __testing as capture } from '../src/commands/capture.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { acquireLock, releaseLock } from '../src/core/pglite-lock.ts';
import { OperationError } from '../src/core/ops/contract.ts';
import { parseTakesMutation } from '../src/commands/takes-mutation.ts';
import { PENDING_WRITE_EXIT_CODE } from '../src/core/exit-codes.ts';

const BRAIN = '10000000-0000-4000-8000-000000000001';
const ID = '20000000-0000-4000-8000-000000000001';
const dirs: string[] = [];
afterEach(() => { for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }); });

async function withOwner(run: (dir: string, calls: PersistenceIpcRequest[], connect: () => Promise<BrainEngine>) => Promise<void>) {
  const dir = mkdtempSync(join(tmpdir(), 'gb-cli-ipc-'));
  dirs.push(dir);
  const databasePath = join(dir, 'db');
  const config = { engine: 'pglite' as const, database_path: databasePath };
  mkdirSync(join(dir, '.gbrain', 'persistence'), { recursive: true });
  mkdirSync(databasePath, { recursive: true });
  const lock = await acquireLock(databasePath);
  // Real ownership, with the same diagnostic command label a serve writes.
  const metadataPath = lock.lockPath ?? join(databasePath, '.gbrain-lock', 'lock');
  writeFileSync(metadataPath, JSON.stringify({ ...JSON.parse(readFileSync(metadataPath, 'utf8')), subcommand: 'serve' }));
  writeFileSync(join(dir, '.gbrain', 'config.json'), JSON.stringify(config));
  writeFileSync(join(dir, '.gbrain', 'persistence', `${BRAIN}.cli.json`), JSON.stringify({
    id: BRAIN, credential: 'a'.repeat(64), lane: 'cli',
  }), { mode: 0o600 });
  const calls: PersistenceIpcRequest[] = [];
  const binding = await startPersistenceIpcServer(persistenceSocketPathForConfig(config)!, {
    brainId: BRAIN,
    dispatch: async request => {
      calls.push(request);
      if (request.params.slug === 'test/pending') {
        const error = new OperationError('write_pending', 'Accepted; waiting for owner.');
        error.writeRequest = { request_id: request.params.request_id as string, state: 'queued', retry_after_ms: 100 };
        throw error;
      }
      return request.operation === 'forget' ? { id: request.params.id, expired: true, protocol_version: 1 }
        : { slug: request.params.slug ?? 'inbox/from-owner', status: 'created', revision: ID,
          write_request: { request_id: request.params.request_id, state: 'committed', retry_after_ms: null } };
    },
  });
  let connects = 0;
  try {
    await withEnv({ GBRAIN_HOME: dir, GBRAIN_BRAIN_ID: 'host', GBRAIN_SOURCE: 'client-source',
      GBRAIN_DATABASE_URL: undefined, DATABASE_URL: undefined }, async () => {
      await run(dir, calls, async () => { connects++; throw new Error('A delegated CLI must not connect an engine.'); });
    });
    expect(connects).toBe(0);
  } finally {
    if (binding) { const closed = once(binding.server, 'close'); binding.close(); await closed; }
    await releaseLock(lock);
  }
}

describe('CLI-only persistence delegation before engine connection', () => {
  test('capture retries preserve raw content, ID, event fields, and source without generated time or slug', async () => {
    await withOwner(async (dir, calls, connect) => {
      const file = join(dir, 'input.md');
      const raw = '# An example event\r\n\r\nOriginal input.\r\n';
      writeFileSync(file, raw);
      const args = ['--file', file, '--type', 'event', '--who', 'example-person', '--what', 'met', '--request-id', ID, '--json'];
      await runDeferredPersistenceCommand('capture', args, connect);
      await runDeferredPersistenceCommand('capture', args, connect);
      expect(calls).toHaveLength(2);
      expect(calls[0].params).toEqual(calls[1].params);
      expect(calls[0].operation).toBe('capture');
      expect(calls[0].params).toMatchObject({ content: raw, request_id: ID, who: 'example-person', what: 'met', type: 'event',
        source_kind: 'capture-cli', local_file: file });
      expect(calls[0].params).not.toHaveProperty('source_uri');
      expect(calls[0].params).not.toHaveProperty('slug');
      expect(calls[0].params.content).not.toContain('captured_at:');
      expect(calls[0].routing.source).toBe('client-source');
    });
  });

  test('generic call forwards exact revision and request ID before connecting', async () => {
    await withOwner(async (_dir, calls, connect) => {
      const params = { slug: 'test/page', content: 'replacement', expected_revision: BRAIN, request_id: ID };
      await runDeferredPersistenceCommand('call', ['--source', 'call-source', 'put_page', JSON.stringify(params)], connect);
      expect(calls).toHaveLength(1);
      expect(calls[0].params).toEqual(params);
      expect(calls[0].routing.source).toBe('call-source');
    });
  });

  test('fact extraction delegates stable input and request identity before connecting', async () => {
    await withOwner(async (_dir, calls, connect) => {
      const params = { turn_text: 'A synthetic recorded preference.', visibility: 'private', request_id: ID };
      await runDeferredPersistenceCommand('call', ['--source', 'call-source', 'extract_facts', JSON.stringify(params)], connect);
      expect(calls).toHaveLength(1);
      expect(calls[0].operation).toBe('extract_facts');
      expect(calls[0].params).toEqual(params);
      expect(calls[0].routing.source).toBe('call-source');
    });
  });

  test('forget uses the frozen verb with a stable opaque fact ID and request UUID', async () => {
    await withOwner(async (_dir, calls, connect) => {
      await runDeferredPersistenceCommand('forget', ['42', '--reason', 'correction', '--request-id', ID, '--json'], connect);
      expect(calls).toHaveLength(1);
      expect(calls[0].operation).toBe('forget');
      expect(calls[0].params).toEqual({ id: '42', reason: 'correction', request_id: ID });
    });
  });

  test('generic take mutation preserves provenance source independently of CLI source routing', async () => {
    await withOwner(async (_dir, calls, connect) => {
      await runDeferredPersistenceCommand('call', ['--source', 'call-source', 'takes_add', JSON.stringify({
        slug: 'test/page', claim: 'A claim', kind: 'fact', holder: 'world', source: 'meeting notes', request_id: ID,
      })], connect);
      expect(calls[0].operation).toBe('takes_add');
      expect(calls[0].params.source).toBe('meeting notes');
      expect(calls[0].routing.source).toBe('call-source');
      expect(calls[0].params.request_id).toBe(ID);
    });
  });

  test('capture parses both UUID flag forms and forwards preconditions', () => {
    expect(capture.parseArgs(['body', `--request-id=${ID}`, '--expected-revision', BRAIN])).toMatchObject({
      content: 'body', request_id: ID, expected_revision: BRAIN,
    });
    expect(() => capture.parseArgs(['body', '--request-id'])).toThrow('requires a UUID');
    expect(() => capture.parseArgs(['body', '--no-embed'])).toThrow('Unsupported capture option');
  });

  test('actual CLI capture, forget, and call reach the owner before competing for the engine', async () => {
    await withOwner(async (dir, calls) => {
      const file = join(dir, 'capture.md');
      writeFileSync(file, '# Example input\n');
      const invocations = [
        ['capture', '--file', file, '--request-id', ID, '--json'],
        ['forget', '42', `--request-id=${ID}`, '--reason', 'correction', '--json'],
        ['call', 'put_page', JSON.stringify({ slug: 'test/page', content: 'body', request_id: ID })],
      ];
      for (const args of invocations) {
        const child = Bun.spawn([process.execPath, join(import.meta.dir, '../src/cli.ts'), ...args], {
          cwd: dir, env: { ...process.env, GBRAIN_NO_BANNER: '1', GBRAIN_BACKUP_CHECK: '0' },
          stdout: 'pipe', stderr: 'pipe',
        });
        const [stdout, stderr, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
        expect({ code, stderr }).toMatchObject({ code: 0 });
        expect(() => JSON.parse(stdout)).not.toThrow();
      }
      expect(calls.map(call => call.operation)).toEqual(['capture', 'forget', 'put_page']);
      expect(calls.every(call => call.params.request_id === ID)).toBe(true);
    });
  });

  test('actual CLI take mutations preserve source, resolver, local directory, and replay IDs before opening PGLite', async () => {
    await withOwner(async (dir, calls) => {
      const invocations = [
        ['add', 'test/page', '--claim', 'Example claim', '--kind', 'fact', '--who', 'me', '--source', 'meeting notes', '--source-id', 'explicit-source'],
        ['update', 'test/page', '--row', '1', '--weight', '0.8', '--dir', dir],
        ['supersede', 'test/page', '--row', '1', '--claim', 'Corrected', '--source', 'correction notes', '--since', '2026-09'],
        ['resolve', 'test/page', '--row', '2', '--outcome', 'false', '--source', 'resolution evidence', '--by', 'people/owner-example'],
      ];
      for (const args of invocations) {
        const child = Bun.spawn([process.execPath, join(import.meta.dir, '../src/cli.ts'), 'takes', ...args, `--request-id=${ID}`, '--json'], {
          cwd: dir, env: { ...process.env, GBRAIN_NO_BANNER: '1', GBRAIN_BACKUP_CHECK: '0' }, stdout: 'pipe', stderr: 'pipe',
        });
        const [stdout, stderr, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
        expect({ code, stderr }).toMatchObject({ code: 0 });
        expect(JSON.parse(stdout).write_request.request_id).toBe(ID);
      }
      expect(calls.map(call => call.operation)).toEqual(['takes_add', 'takes_update', 'takes_supersede', 'takes_resolve']);
      expect(calls[0].params).toMatchObject({ holder: 'me', source: 'meeting notes' });
      expect(calls[0].routing.source).toBe('explicit-source');
      expect(calls[1].params.local_dir).toBe(dir);
      expect(calls[2].params).toMatchObject({ source: 'correction notes', since: '2026-09' });
      expect(calls[3].params).toMatchObject({ quality: 'incorrect', evidence: 'resolution evidence', resolved_by: 'people/owner-example' });
      expect(calls[3].params).not.toHaveProperty('source');
    });
  });

  test('pending CLI take returns its receipt and same-ID retry guidance without reporting a completed mutation', async () => {
    await withOwner(async (dir, calls) => {
      const child = Bun.spawn([process.execPath, join(import.meta.dir, '../src/cli.ts'), 'takes', 'update', 'test/pending',
        '--row', '1', '--weight', '0.8', '--request-id', ID, '--json'], {
        cwd: dir, env: { ...process.env, GBRAIN_NO_BANNER: '1', GBRAIN_BACKUP_CHECK: '0', GBRAIN_WRITE_WAIT_MS: '0' }, stdout: 'pipe', stderr: 'pipe',
      });
      const [stdout, stderr, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
      expect(code).toBe(PENDING_WRITE_EXIT_CODE);
      expect(JSON.parse(stdout).write_request).toMatchObject({ request_id: ID, state: 'queued' });
      expect(stderr).toContain(`--request-id ${ID}`);
      expect(stdout + stderr).not.toContain('Updated take');
      expect(calls).toHaveLength(1);
    });
  });

  test('take parser validates whole numeric values and preserves explicit revision/replay intent', () => {
    expect(parseTakesMutation(['update', 'test/page', '--row=2', '--weight', '0.3', `--request-id=${ID}`, '--expected-revision', BRAIN])).toMatchObject({
      params: { row_num: 2, weight: 0.3, request_id: ID, expected_revision: BRAIN },
    });
    expect(() => parseTakesMutation(['update', 'test/page', '--row', '2junk'])).toThrow('positive integer');
    expect(() => parseTakesMutation(['resolve', 'test/page', '--row', '1', '--quality', 'correct', '--outcome', 'false'])).toThrow('mutually exclusive');
    expect(() => parseTakesMutation(['resolve', 'test/page', '--row', '1', '--quality', 'correct', '--source', 'a', '--evidence', 'b'])).toThrow('different evidence');
    expect(() => parseTakesMutation(['update', 'test/page', '--row', '1', '--force', '--expected-revision', BRAIN])).toThrow('mutually exclusive');
  });
});