Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.2 KB
Raw Blame
/**
 * #5827 — link reads on a thin-client install, driven through the real CLI
 * dispatcher (`__testing.main`) with a recorded `callRemoteTool`.
 *
 * Contracts protected:
 *   - the link commands forward an ambient GBRAIN_SOURCE / .gbrain-source
 *     binding as `source_id` (they declare it now), and an empty result says
 *     which binding narrowed it plus the exact `--all-sources` rerun command;
 *   - mixed versions: when the brain host answers with an unknown-parameter
 *     warning for a scope param the client sent (flag, env or dotfile), the
 *     command fails instead of printing the host's unscoped result;
 *   - `gbrain links` is the CLI name with `get_links` kept as an alias.
 * Regression that fails it: the CLI printing the unscoped result (exit 0) or
 * dropping the ambient scope, as on the wave-5 base. The stub response is
 * built with the server's own warning builder (`buildUnknownParamWarnBlock`).
 *
 * Serial file: mock.module patches config.ts and mcp-client.ts process-wide.
 */
import { describe, test, expect, beforeAll, beforeEach, afterAll, mock } from 'bun:test';
import { mkdtempSync, rmSync, writeFileSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { withEnv } from './helpers/with-env.ts';
import { buildUnknownParamWarnBlock } from '../src/mcp/validate-params.ts';

type Call = { name: string; params: Record<string, unknown> };
const calls: Call[] = [];
let respond: (call: Call) => unknown = () => ({ content: [{ type: 'text', text: '[]' }] });

const realConfig = await import('../src/core/config.ts');
mock.module('../src/core/config.ts', () => ({
  ...realConfig,
  loadConfig: () => ({
    engine: 'postgres',
    remote_mcp: { issuer_url: 'https://brain.example.test', mcp_url: 'https://brain.example.test/mcp', oauth_client_id: 'cid' },
  }),
  isThinClient: () => true,
}));

const realMcpClient = await import('../src/core/mcp-client.ts');
mock.module('../src/core/mcp-client.ts', () => ({
  ...realMcpClient,
  callRemoteTool: async (_cfg: unknown, name: string, params: Record<string, unknown>) => {
    const c = { name, params: { ...params } };
    calls.push(c);
    return respond(c);
  },
}));

const { __testing } = await import('../src/cli/main.ts');

class ExitSignal extends Error {
  constructor(readonly code: number) { super(`process.exit(${code})`); }
}

let cwd: string;
let dotfileDir: string;
const savedCwd = process.cwd();

beforeAll(() => {
  cwd = mkdtempSync(join(tmpdir(), 'gbrain-5827-thin-'));
  dotfileDir = mkdtempSync(join(tmpdir(), 'gbrain-5827-dot-'));
  writeFileSync(join(dotfileDir, '.gbrain-source'), 'wiki\n');
});

afterAll(() => {
  process.chdir(savedCwd);
  rmSync(cwd, { recursive: true, force: true });
  rmSync(dotfileDir, { recursive: true, force: true });
});

beforeEach(() => {
  calls.length = 0;
  respond = () => ({ content: [{ type: 'text', text: '[]' }] });
});

async function run(argv: string[], opts: { env?: Record<string, string | undefined>; dir?: string } = {}) {
  const out: string[] = [];
  const err: string[] = [];
  const saved = { log: console.log, error: console.error, exit: process.exit, argv: process.argv,
    stderr: process.stderr.write };
  console.log = (...a: unknown[]) => { out.push(a.map(String).join(' ')); };
  console.error = (...a: unknown[]) => { err.push(a.map(String).join(' ')); };
  process.stderr.write = ((chunk: unknown) => { err.push(String(chunk)); return true; }) as typeof process.stderr.write;
  (process as unknown as { exit: (code?: number) => never }).exit = ((code?: number) => {
    throw new ExitSignal(code ?? 0);
  }) as never;
  process.argv = [saved.argv[0]!, 'gbrain', ...argv];
  process.chdir(opts.dir ?? cwd);
  let code = 0;
  try {
    await withEnv({ GBRAIN_SOURCE: undefined, GBRAIN_NO_BANNER: '1', ...opts.env }, () => __testing.main());
  } catch (e) {
    if (!(e instanceof ExitSignal)) throw e;
    code = e.code;
  } finally {
    console.log = saved.log;
    console.error = saved.error;
    process.stderr.write = saved.stderr;
    (process as unknown as { exit: typeof saved.exit }).exit = saved.exit;
    process.argv = saved.argv;
    process.chdir(savedCwd);
  }
  return { code, log: out.join('\n'), stderr: err.join('\n') };
}

/** What a pre-#5827 host sends back: the unscoped result plus a WP3 warning per ignored key. */
function oldHost(ignoredKeys: string[], body: unknown = [{ from_slug: 'x', to_slug: 'y' }]) {
  return (c: Call) => {
    const warnings = ignoredKeys.filter((k) => k in c.params).map((param) => ({ code: 'unknown_param', param }));
    return {
      content: [
        { type: 'text', text: JSON.stringify(body) },
        ...(warnings.length ? [{ type: 'text', text: buildUnknownParamWarnBlock(warnings as never) }] : []),
      ],
      ...(warnings.length ? { _meta: { warnings } } : {}),
    };
  };
}

describe('#5827 thin-client link reads follow ambient scope', () => {
  test('GBRAIN_SOURCE is sent as source_id; an empty result names the binding and the --all-sources rerun', async () => {
    const r = await run(['backlinks', 'companies/acme-example'], { env: { GBRAIN_SOURCE: 'business' } });
    expect(r.code).toBe(0);
    expect(calls).toEqual([{ name: 'get_backlinks', params: { slug: 'companies/acme-example', source_id: 'business' } }]);
    expect(r.stderr).toContain(
      '[gbrain] backlinks: no results within source business (set by GBRAIN_SOURCE). ' +
      'To read every source you can see: gbrain backlinks companies/acme-example --all-sources',
    );
  });

  test('a .gbrain-source pin is sent as source_id and named in the hint', async () => {
    const r = await run(['links', 'people/alice-example'], { dir: dotfileDir });
    expect(calls[0]).toEqual({ name: 'get_links', params: { slug: 'people/alice-example', source_id: 'wiki' } });
    expect(r.stderr).toContain('no results within source wiki (set by .gbrain-source)');
    expect(r.stderr).toContain('gbrain links people/alice-example --all-sources');
  });

  test('a non-empty narrowed result prints no hint, and --all-sources goes on the wire', async () => {
    respond = () => ({ content: [{ type: 'text', text: JSON.stringify([{ from_slug: 'a', to_slug: 'b' }]) }] });
    const r = await run(['backlinks', 'companies/acme-example'], { env: { GBRAIN_SOURCE: 'business' } });
    expect(r.code).toBe(0);
    expect(r.stderr).not.toContain('no results within source');
    calls.length = 0;
    await run(['graph', 'people/alice-example', '--all-sources'], { env: { GBRAIN_SOURCE: 'business' } });
    expect(calls[0]).toEqual({ name: 'traverse_graph', params: { slug: 'people/alice-example', all_sources: true } });
  });

  test('the get_links alias still dispatches', async () => {
    await run(['get_links', 'people/alice-example', '--source-id', 'wiki']);
    expect(calls[0]).toEqual({ name: 'get_links', params: { slug: 'people/alice-example', source_id: 'wiki' } });
  });

  test('--source with --source-id is refused before the wire', async () => {
    const r = await run(['backlinks', 'companies/acme-example', '--source', 'business', '--source-id', 'wiki']);
    expect(r.code).toBe(1);
    expect(r.stderr).toContain('Pass either --source or --source-id/--all-sources, not both.');
    expect(calls).toHaveLength(0);
  });
});

describe('#5827 mixed versions: a host that ignores a scope param fails loudly', () => {
  const origins: Array<[string, string[], () => { env?: Record<string, string | undefined>; dir?: string }]> = [
    ['--source-id flag', ['backlinks', 'companies/acme-example', '--source-id', 'business'], () => ({})],
    ['--source flag', ['backlinks', 'companies/acme-example', '--source', 'business'], () => ({})],
    ['GBRAIN_SOURCE', ['backlinks', 'companies/acme-example'], () => ({ env: { GBRAIN_SOURCE: 'business' } })],
    ['.gbrain-source', ['backlinks', 'companies/acme-example'], () => ({ dir: dotfileDir })],
  ];
  for (const [origin, argv, opts] of origins) {
    test(`source_id from ${origin}`, async () => {
      respond = oldHost(['source_id', 'all_sources']);
      const r = await run(argv, opts());
      expect(calls[0]?.params.source_id).toBeDefined();
      // Exit 1 is raised before the result is formatted, so nothing reaches stdout.
      expect(r.code).toBe(1);
      expect(r.stderr).toContain(
        'the brain host does not support source_id on get_backlinks; upgrade the host (gbrain upgrade on the brain host)',
      );
    });
  }

  test('all_sources is checked the same way', async () => {
    respond = oldHost(['source_id', 'all_sources']);
    const r = await run(['links', 'people/alice-example', '--all-sources']);
    expect(r.code).toBe(1);
    expect(r.stderr).toContain('the brain host does not support all_sources on get_links');
  });

  test('a host that honors the scope prints the result', async () => {
    respond = oldHost([]);
    const r = await run(['backlinks', 'companies/acme-example', '--source-id', 'business']);
    expect(r.code).toBe(0);
    expect(r.stderr).not.toContain('does not support');
  });

  test('an ignored non-scope param this op declares is a stderr warning, not a failure', async () => {
    respond = oldHost(['direction']);
    const r = await run(['graph', 'people/alice-example', '--direction', 'in']);
    expect(r.code).toBe(0);
    expect(r.stderr).toContain('the brain host ignored parameter "direction" on traverse_graph');
  });
});