Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
16.6 KB
Raw Blame
/**
 * A7 readiness (src/core/readiness.ts): the config-plane state/reason table per
 * capability, the one embedding-enablement fix, harness_wiring by state, the
 * exclusive two-step plan and the HTTP view.
 *
 * Protects: every surface (doctor, MCP initialize, whoami, receipts) reads one
 * answer for "what can this install do and what is the fix". A regression that
 * coaches a keyless-by-choice brain, routes an exclusive fix past a running
 * serve, registers a bare `gbrain` binary or reintroduces a wipe recipe fails here.
 */
import { afterEach, describe, expect, test } from 'bun:test';
import {
  BACKUP_REASONS, CHAT_LLM_REASONS, EMBEDDINGS_REASONS, HARNESS_WIRING_REASONS, MIGRATIONS_REASONS, SYNC_REASONS,
  TOOL_SURFACE_REASONS, WORKER_REASONS, WRITEBACK_REASONS,
  __setLockPeekForTests, configReadiness, embeddingEnablement, exclusiveFix, harnessWiringEntry, readinessHttpView,
  type LockOwner, type ReadinessEntry,
} from '../src/core/readiness.ts';
import { renderAction, cliRenderContext, type Action } from '../src/core/agent-output.ts';
import { listRecipes } from '../src/core/ai/recipes/index.ts';
import type { GBrainConfig } from '../src/core/config.ts';
import { withEnv } from './helpers/with-env.ts';

const PROVIDER_ENVS = [...new Set(listRecipes().flatMap(r => r.auth_env?.required ?? []))];

/** Run with every provider key cleared, then `keys` set (no ambient key can leak into a pick). */
function withKeys<T>(keys: Record<string, string>, fn: () => T | Promise<T>): Promise<T> {
  const env: Record<string, string | undefined> = { GBRAIN_MODEL: undefined, GBRAIN_BRAIN_ID: undefined };
  for (const k of PROVIDER_ENVS) env[k] = undefined;
  return withEnv({ ...env, ...keys }, async () => fn());
}

const VOCAB: Record<string, readonly string[]> = {
  embeddings: EMBEDDINGS_REASONS, chat_llm: CHAT_LLM_REASONS, worker: WORKER_REASONS, writeback: WRITEBACK_REASONS,
  backup: BACKUP_REASONS, tool_surface: TOOL_SURFACE_REASONS, sync: SYNC_REASONS, migrations: MIGRATIONS_REASONS,
  harness_wiring: HARNESS_WIRING_REASONS,
};

function entry(entries: ReadinessEntry[], capability: string): ReadinessEntry {
  const found = entries.find(e => e.capability === capability);
  if (!found) throw new Error(`no ${capability} entry`);
  return found;
}

function pglite(extra: Partial<GBrainConfig> = {}): GBrainConfig {
  return { engine: 'pglite', database_path: '/brains/main.pglite', ...extra } as GBrainConfig;
}

afterEach(() => __setLockPeekForTests(null));

describe('config plane: state and reason per capability', () => {
  test('keyless-by-choice brain: embeddings disabled_by_choice, still carrying the enable fix', async () => {
    await withKeys({}, () => {
      __setLockPeekForTests(() => ({ held: false }));
      const { entries } = configReadiness(pglite({ embedding_disabled: true }), { transport: 'cli' });
      const e = entry(entries, 'embeddings');
      expect(e.state).toBe('disabled_by_choice');
      expect(e.reason).toBe('embedding_disabled');
      expect(e.fix?.argv?.slice(0, 4)).toEqual(['gbrain', 'init', '--force', '--embedding-model']);
    });
  });

  test('every entry uses its capability\'s closed vocabulary and declares requires_exclusive on fixes', async () => {
    await withKeys({}, () => {
      __setLockPeekForTests(() => ({ held: false }));
      const cfgs = [pglite({ embedding_disabled: true }), pglite(), pglite({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536 }),
        pglite({ embedding_model: 'nope:model' }), pglite({ memory: { auto_writeback: 'off' } }), pglite({ memory: { auto_writeback: 'bogus' } }),
        pglite({ mcp_surface: 'verbs' }), { engine: 'postgres', database_url: 'postgres://x/y', remote_mcp: { mcp_url: 'https://h/mcp' } } as unknown as GBrainConfig];
      for (const cfg of cfgs) {
        for (const transport of ['cli', 'stdio'] as const) {
          for (const e of configReadiness(cfg, { transport }).entries) {
            expect(VOCAB[e.capability]).toContain(e.reason);
            expect(e.tier).toBe('config');
            if (e.fix) expect(typeof e.fix.requires_exclusive).toBe('boolean');
          }
        }
      }
    });
  });

  test('embeddings: not_configured, key_missing, unknown_model, ok', async () => {
    await withKeys({}, () => {
      expect(entry(configReadiness(pglite(), { transport: 'stdio' }).entries, 'embeddings')).toMatchObject({ state: 'missing', reason: 'not_configured' });
      const keyless = entry(configReadiness(pglite({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536 }), { transport: 'stdio' }).entries, 'embeddings');
      expect(keyless).toMatchObject({ state: 'degraded', reason: 'key_missing' });
      expect(keyless.fix).toMatchObject({ actor: 'user', consent: ['credentials'] });
      expect(keyless.fix?.inputs?.[0]?.name).toBe('OPENAI_API_KEY');
      expect(entry(configReadiness(pglite({ embedding_model: 'nope:model' }), { transport: 'stdio' }).entries, 'embeddings').reason).toBe('unknown_model');
    });
    await withKeys({ OPENAI_API_KEY: 'sk-test' }, () => {
      expect(entry(configReadiness(pglite({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536 }), { transport: 'stdio' }).entries, 'embeddings'))
        .toMatchObject({ state: 'ok', reason: 'configured' });
    });
  });

  test('chat, writeback, tool surface and thin-client rows', async () => {
    await withKeys({}, () => {
      const entries = configReadiness(pglite({ mcp_surface: 'verbs', memory: { auto_writeback: 'off' } }), { transport: 'stdio' }).entries;
      expect(entry(entries, 'chat_llm')).toMatchObject({ state: 'missing', reason: 'not_configured' });
      expect(entry(entries, 'writeback')).toMatchObject({ state: 'disabled_by_choice', reason: 'off_by_choice' });
      expect(entry(entries, 'tool_surface')).toMatchObject({ state: 'ok', reason: 'surface_verbs' });
      expect(entry(configReadiness(pglite(), { transport: 'stdio' }).entries, 'writeback')).toMatchObject({ state: 'missing', reason: 'not_configured' });
      const thin = configReadiness({ engine: 'postgres', remote_mcp: { mcp_url: 'https://h/mcp' } } as unknown as GBrainConfig, { transport: 'cli' });
      for (const cap of ['embeddings', 'chat_llm', 'writeback', 'sync']) expect(entry(thin.entries, cap).state).toBe('not_applicable');
      expect(thin.lock_owner).toBeNull();
    });
    await withKeys({ ANTHROPIC_API_KEY: 'sk-ant-test' }, () => {
      expect(entry(configReadiness(pglite(), { transport: 'stdio' }).entries, 'chat_llm')).toMatchObject({ state: 'ok', reason: 'configured' });
    });
  });
});

describe('embeddingEnablement', () => {
  const run = (cfg: GBrainConfig, keys: Record<string, string>, env: Record<string, string> = {}) =>
    withKeys({ ...keys, ...env }, () => embeddingEnablement(cfg));

  test('default path: keyed provider, in-place init with the resolved datastore and width', async () => {
    const a = await run({ engine: 'pglite', embedding_disabled: true } as GBrainConfig, { VOYAGE_API_KEY: 'v' }, { GBRAIN_HOME: '/home/u' });
    expect(a.argv).toEqual(['gbrain', 'init', '--force', '--embedding-model', 'voyage:voyage-4', '--embedding-dimensions', '1024', '--path', '/home/u/.gbrain/brain.pglite']);
    expect(a).toMatchObject({ actor: 'agent', consent: ['credentials', 'paid'], requires_exclusive: true });
    expect(a.why).toContain('Pages, facts and keyword search are kept');
    expect(a.why).toContain('queued for vectors');
    expect(a.argv?.join(' ')).not.toContain('mv ');
  });

  test('custom path and Postgres target their own datastore', async () => {
    expect((await run(pglite({ embedding_disabled: true }), { VOYAGE_API_KEY: 'v' })).argv?.slice(-2)).toEqual(['--path', '/brains/main.pglite']);
    const pg = await run({ engine: 'postgres', database_url: 'postgres://x/y', embedding_disabled: true } as GBrainConfig, { VOYAGE_API_KEY: 'v' });
    expect(pg.argv).toEqual(['gbrain', 'init', '--force', '--embedding-model', 'voyage:voyage-4', '--embedding-dimensions', '1024']);
  });

  test('mounted brain routes through `embeddings enable --brain`, never init --path', async () => {
    const a = await run(pglite({ embedding_disabled: true }), { VOYAGE_API_KEY: 'v' }, { GBRAIN_BRAIN_ID: 'team' });
    expect(a.argv).toEqual(['gbrain', 'embeddings', 'enable', '--brain', 'team', '--embedding-model', 'voyage:voyage-4', '--embedding-dimensions', '1024']);
  });

  test('multiple providers: the canonical default wins; legacy width picks a provider that fits', async () => {
    expect((await run(pglite({ embedding_disabled: true }), { VOYAGE_API_KEY: 'v', OPENAI_API_KEY: 'o' })).argv?.[4]).toBe('voyage:voyage-4');
    const legacy = await run(pglite({ embedding_disabled: true, embedding_dimensions: 1536 }), { VOYAGE_API_KEY: 'v', OPENAI_API_KEY: 'o' });
    expect(legacy.argv?.[4]).toMatch(/^openai:/);
    expect(legacy.argv?.slice(5, 7)).toEqual(['--embedding-dimensions', '1536']);
  });

  test('no key: the fix asks the user for one (actor user, credentials+paid, inputs)', async () => {
    const a = await run(pglite({ embedding_disabled: true }), {});
    expect(a).toMatchObject({ actor: 'user', consent: ['credentials', 'paid'], requires_exclusive: true });
    expect(a.inputs?.map(i => i.name)).toEqual(['VOYAGE_API_KEY']);
    expect(renderAction(a, cliRenderContext()).next).toBe('tell_user_to_run');
  });

  test('width mismatch refuses to rebuild: names a provider that fits instead', async () => {
    const a = await run(pglite({ embedding_disabled: true, embedding_dimensions: 1536 }), { VOYAGE_API_KEY: 'v' });
    expect(a.actor).toBe('user');
    expect(a.inputs?.map(i => i.name)).toEqual(['OPENAI_API_KEY']);
    expect(a.why).toContain('cannot produce');
    const none = await run(pglite({ embedding_disabled: true, embedding_dimensions: 7 }), { VOYAGE_API_KEY: 'v' });
    expect(none.argv).toEqual(['gbrain', 'migrate', 'embeddings', '--status', '--json']);
    expect(none.requires_exclusive).toBe(false);
  });

  test('an explicitly requested model is honoured', async () => {
    const a = await run(pglite({ embedding_disabled: true, embedding_model: 'openai:text-embedding-3-small' }), { VOYAGE_API_KEY: 'v' });
    expect(a.argv?.[4]).toBe('openai:text-embedding-3-small');
    expect(a.inputs?.map(i => i.name)).toEqual(['OPENAI_API_KEY']);
  });
});

describe('harness_wiring by state', () => {
  const BIN = '/opt/gbrain/bin/gbrain';
  const owner = (transport: 'stdio' | 'http', is_self = false): LockOwner => ({ pid: 4242, transport, is_self });

  test('one harness, no serve: gbrain setup registers the absolute binary behind the hook launcher, --surface starter and --advertise verbs', () => {
    const claude = harnessWiringEntry({ transport: 'cli', harnesses: ['claude-code'], lockOwner: null, gbrainBin: BIN });
    expect(claude.fix?.argv).toEqual(['gbrain', 'setup', 'claude-code', '--no-hooks', '--gbrain-bin', BIN]);
    expect(claude.fix?.why).toContain(`/hook-launcher/gbrain-hook ${BIN} serve --surface starter --advertise verbs`);
    expect(claude.fix?.consent).toEqual(['persistent_install']);
    expect(claude.fix?.why).toContain('~/.claude.json');
    expect(harnessWiringEntry({ transport: 'cli', harnesses: ['codex'], lockOwner: null, gbrainBin: BIN }).fix?.argv)
      .toEqual(['gbrain', 'setup', 'codex', '--no-hooks', '--gbrain-bin', BIN]);
    expect(harnessWiringEntry({ transport: 'cli', harnesses: ['opencode'], lockOwner: null, gbrainBin: BIN }).fix?.argv)
      .toEqual(['gbrain', 'bootstrap', 'hooks', '--harness', 'opencode', '--no-hooks']);
  });

  test('never a bare gbrain binary: unresolved binary yields no registration', () => {
    const e = harnessWiringEntry({ transport: 'cli', harnesses: ['claude-code'], lockOwner: null, gbrainBin: null });
    expect(e.reason).toBe('binary_unresolved');
    expect(e.fix?.argv).toBeUndefined();
  });

  test('serve --http running or a second session: shared HTTP wiring, credentials disclosed', () => {
    const http = harnessWiringEntry({ transport: 'cli', harnesses: ['codex'], lockOwner: owner('http'), gbrainBin: BIN });
    expect(http.reason).toBe('http_serve_running');
    expect(http.fix?.argv).toEqual(['gbrain', 'bootstrap', 'harness', '--harness', 'codex', '--yes']);
    expect(http.fix?.consent).toEqual(['persistent_install', 'credentials']);
    expect(http.fix?.why).toContain('bearer token');
    expect(http.fix?.why).toContain('permissions.allow');
    const second = harnessWiringEntry({ transport: 'cli', harnesses: ['claude-code'], lockOwner: owner('stdio'), gbrainBin: BIN });
    expect(second).toMatchObject({ state: 'degraded', reason: 'multiple_sessions' });
    expect(second.fix?.argv).toEqual(['gbrain', 'bootstrap', 'harness', '--harness', 'claude-code', '--yes']);
    expect(harnessWiringEntry({ transport: 'cli', harnesses: ['claude-code', 'codex'], lockOwner: null, gbrainBin: BIN }).fix?.argv?.[4]).toBe('all');
  });

  test('no harness: per-harness install docs; stdio is wired; http is not applicable', () => {
    const none = harnessWiringEntry({ transport: 'cli', harnesses: [], lockOwner: null, gbrainBin: BIN });
    expect(none.reason).toBe('no_harness_detected');
    expect(none.fix?.docs).toContain('docs/protocol/MEMORY_VERBS_v1.md#');
    expect(harnessWiringEntry({ transport: 'stdio', harnesses: [], lockOwner: null, gbrainBin: null })).toMatchObject({ state: 'ok', reason: 'wired_running' });
    expect(harnessWiringEntry({ transport: 'http', harnesses: [], lockOwner: null, gbrainBin: null }).state).toBe('not_applicable');
  });
});

describe('exclusive fixes and lock ownership', () => {
  const action: Action = { argv: ['gbrain', 'init', '--force', '--embedding-model', 'voyage:voyage-4'], consent: ['credentials', 'paid'], actor: 'agent', why: 'w', requires_exclusive: true };

  test('no owner or a non-exclusive fix: unchanged; an owner-delegating command stays one step', () => {
    expect(exclusiveFix(action, null)).toBe(action);
    const plain = { ...action, requires_exclusive: false };
    expect(exclusiveFix(plain, { pid: 1, transport: 'stdio', is_self: false })).toBe(plain);
    const reindex = { ...action, argv: ['gbrain', 'reindex-code', '--yes'] };
    expect(exclusiveFix(reindex, { pid: 1, transport: 'stdio', is_self: false })).toBe(reindex);
  });

  test('a live serve owner: two-step plan, step one (actor user) stops it, then the command', () => {
    const plan = exclusiveFix(action, { pid: 4242, transport: 'http', is_self: false });
    expect(plan).toMatchObject({ actor: 'user', argv: ['kill', '4242'], requires_exclusive: false, then: action });
    expect(plan.why).toContain('gbrain serve --http');
    const rendered = renderAction(plan, cliRenderContext());
    expect(rendered.next).toBe('tell_user_to_run');
    expect(rendered.then?.next).toBe('ask_user');
  });

  test('config plane reads the lock once, derives the owner transport, and wraps exclusive fixes', async () => {
    await withKeys({ VOYAGE_API_KEY: 'v' }, () => {
      let peeks = 0;
      __setLockPeekForTests(() => { peeks++; return { held: true, isServe: true, pid: 999_999, http: false, acquiredAt: 1_700_000_000_000 }; });
      const cfg = pglite({ embedding_disabled: true });
      const r = configReadiness(cfg, { transport: 'stdio' });
      configReadiness(cfg, { transport: 'cli' });
      expect(peeks).toBe(1);
      expect(r.lock_owner).toEqual({ pid: 999_999, transport: 'stdio', started_at: new Date(1_700_000_000_000).toISOString(), is_self: false });
      const fix = entry(r.entries, 'embeddings').fix!;
      expect(fix.argv).toEqual(['kill', '999999']);
      expect(fix.then?.argv?.[1]).toBe('init');
    });
  });

  test('a non-serve holder is not a lock owner', async () => {
    await withKeys({}, () => {
      __setLockPeekForTests(() => ({ held: true, isServe: false, pid: 77 }));
      expect(configReadiness(pglite(), { transport: 'stdio' }).lock_owner).toBeNull();
    });
  });
});

describe('HTTP view', () => {
  test('http_visible:false entries are stripped and paths redacted; no lock owner', async () => {
    await withKeys({ VOYAGE_API_KEY: 'v' }, () => {
      __setLockPeekForTests(() => ({ held: true, isServe: true, pid: 31337, http: true }));
      const view = configReadiness(pglite({ embedding_disabled: true, database_path: '/home/u/.gbrain/brain.pglite' }), { transport: 'http' });
      expect(view.lock_owner).toBeNull();
      expect(view.entries.every(e => e.http_visible)).toBe(true);
      expect(view.entries.map(e => e.capability)).not.toContain('writeback');
      expect(view.entries.map(e => e.capability)).not.toContain('harness_wiring');
      expect(JSON.stringify(view)).not.toContain('/home/u');
      expect(JSON.stringify(view)).not.toContain('31337');
      expect(readinessHttpView([{ capability: 'backup', state: 'ok', reason: 'covered', why: 'x', tier: 'probed', http_visible: false }])).toEqual([]);
    });
  });
});