Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.3 KB
Raw Blame
/**
 * Throw-only host connect (src/core/engine-connect.ts), the connect the
 * status-only serve re-probes through.
 *
 * Protects: a config that vanished between a re-probe and the connect throws
 * the classified `no_brain` error (the CLI wrapper exits; a status daemon must
 * not), and an engine whose startup fails after the connect is disconnected,
 * so the PGLite lock is free for the next attempt. A one-shot read keeps the
 * config snapshot its startup read through and hands it to the read once
 * (#7147: one bulk config read for the whole command).
 */
import { describe, test, expect } from 'bun:test';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { connectEngineForServe, ONE_SHOT_READ_SHARED_BUFFERS, takeStartupConfigSnapshot, type EngineConnectHooks, type EngineConnectOptions } from '../src/core/engine-connect.ts';
import { runCall } from '../src/commands/call.ts';
import { withoutRequestConfigSnapshot } from '../src/core/config-snapshot.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import type { GBrainConfig } from '../src/core/config.ts';
import { withEnv } from './helpers/with-env.ts';

const hooks = (completeStartup: (e: BrainEngine) => Promise<void> = async () => {}): EngineConnectHooks => ({
  SELECTED_CONFIG_BY_ENGINE: new WeakMap<BrainEngine, GBrainConfig>(), completeStartup,
});

describe('connectEngineForServe', () => {
  test('no config throws no_brain with the keyless-init fix instead of exiting', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-engine-connect-none-'));
    try {
      await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
        const err = await connectEngineForServe(hooks()).then(() => null, (e: unknown) => e as { code?: string; fix?: { argv?: string[] } });
        expect(err?.code).toBe('no_brain');
        expect(err?.fix?.argv).toEqual(['gbrain', 'init', '--pglite', '--no-embedding']);
      });
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  });

  test('a startup failure after the connect disconnects the engine, so the next connect opens the brain', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-engine-connect-partial-'));
    try {
      mkdirSync(join(home, '.gbrain'), { recursive: true });
      writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', database_path: join(home, 'brain.pglite') }));
      await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
        let failed: BrainEngine | null = null;
        const err = await connectEngineForServe(hooks(async e => { failed = e; throw new Error('startup failed'); })).then(() => null, (e: Error) => e);
        expect(err?.message).toBe('startup failed');
        expect(failed).not.toBeNull();
        const engine = await connectEngineForServe(hooks());
        try {
          expect(engine.kind).toBe('pglite');
        } finally {
          await engine.disconnect();
        }
      });
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  }, 60_000);

  test('a one-shot read opens PGLite with the small buffer pool; every other connect keeps the data directory default', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-engine-connect-buffers-'));
    try {
      mkdirSync(join(home, '.gbrain'), { recursive: true });
      writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', database_path: join(home, 'brain.pglite') }));
      await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
        const sharedBuffers = async (opts: EngineConnectOptions) => {
          const engine = await connectEngineForServe(hooks(), opts);
          try { return (await engine.executeRaw<{ shared_buffers: string }>('SHOW shared_buffers'))[0]!.shared_buffers; }
          finally { await engine.disconnect(); }
        };
        expect(ONE_SHOT_READ_SHARED_BUFFERS).toBe('32MB');
        expect(await sharedBuffers({ oneShotRead: true })).toBe('32MB');
        expect(await sharedBuffers({})).toBe('128MB');
        expect(await sharedBuffers({ oneShotRead: false })).toBe('128MB');
      });
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  }, 60_000);

  test('a one-shot read hands its startup config snapshot to the read, once; other connects keep none', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-engine-connect-snapshot-'));
    try {
      mkdirSync(join(home, '.gbrain'), { recursive: true });
      writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', database_path: join(home, 'brain.pglite') }));
      await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
        const configReads: string[] = [];
        const startup = hooks(async e => {
          await withoutRequestConfigSnapshot(() => e.initSchema());
          const db = (e as unknown as { db: { query: (sql: string, ...rest: unknown[]) => Promise<unknown> } }).db;
          const query = db.query.bind(db);
          db.query = (sql: string, ...rest: unknown[]) => { if (/\bFROM config\b/i.test(sql)) configReads.push(sql); return query(sql, ...rest); };
          await e.getConfig('version');
        });
        const engine = await connectEngineForServe(startup, { oneShotRead: true });
        try {
          const snapshot = takeStartupConfigSnapshot(engine);
          expect(snapshot).toBeDefined();
          expect(takeStartupConfigSnapshot(engine)).toBeUndefined();
          await snapshot!.run(async () => { await engine.getConfig('version'); await engine.getConfig('embedding_model'); });
          snapshot!.close();
          expect(configReads.length).toBe(1);
        } finally {
          await engine.disconnect();
        }
        const plain = await connectEngineForServe(hooks());
        try { expect(takeStartupConfigSnapshot(plain)).toBeUndefined(); } finally { await plain.disconnect(); }
      });
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  }, 60_000);
});

describe('gbrain call sizes its connect by the operation scope', () => {
  const stub = {
    executeRaw: async (sql: string) => sql.includes('FROM sources') ? [{ id: 'default' }] : [],
    getStats: async () => ({ pages: 1, chunks: 1 }),
    getTags: async () => [],
  } as unknown as BrainEngine;

  test('a read-scope operation asks for a one-shot read connect, an admin-scope one does not', async () => {
    const asked: (EngineConnectOptions | undefined)[] = [];
    const connect = async (opts?: EngineConnectOptions) => { asked.push(opts); return stub; };
    const home = mkdtempSync(join(tmpdir(), 'gbrain-engine-connect-call-'));
    try {
      await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
        await runCall(connect, ['--source', 'default', 'get_tags', '{"slug":"notes/x"}'], async () => {});
        await runCall(connect, ['--source', 'default', 'get_stats'], async () => {});
      });
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
    expect(asked).toEqual([{ oneShotRead: true }, { oneShotRead: false }]);
  });
});