Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.0 KB
Raw Blame
/**
 * Lane B (B1/B2/B6/B7/B8) on the jobs / loops / think / timeline /
 * transcripts / extraction / attribution ops: refusals carry a filled,
 * surface-correct next step, the jobs not-found frozen pair keeps
 * `error: invalid_params` with `code: not_found`, host-only refusals name the
 * exact host command, and MCP text names params, not CLI flags.
 */
import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { operations, type OperationContext } from '../src/core/operations.ts';
import { toAgentError, type Transport } from '../src/core/agent-output.ts';
import { MinionQueue } from '../src/core/minions/queue.ts';

const op = (name: string) => operations.find(o => o.name === name)!;

function stubEngine(rows: unknown[] = []) {
  return {
    kind: 'pglite',
    executeRaw: async () => rows,
    getConfig: async () => null,
  } as unknown as OperationContext['engine'];
}

function ctx(transport: Transport, over: Partial<OperationContext> = {}): OperationContext {
  return {
    engine: stubEngine(), config: { engine: 'pglite' }, logger: { info() {}, warn() {}, error() {} },
    remote: transport !== 'cli', ...(transport === 'cli' ? {} : { transport }), dryRun: false, sourceId: 'notes',
    ...over,
  } as unknown as OperationContext;
}

async function envelopeOf(name: string, c: OperationContext, params: Record<string, unknown>, callable: string[] = []) {
  const transport: Transport = c.remote === false ? 'cli' : c.transport === 'http' ? 'http' : 'stdio';
  try {
    await op(name).handler(c, params);
  } catch (e) {
    return toAgentError(e, { transport, op: name, render: { transport, isCallable: t => callable.includes(t), preapproved: () => false } });
  }
  throw new Error(`${name} did not throw`);
}

describe('jobs ops (real queue)', () => {
  let engine: PGLiteEngine;
  beforeAll(async () => {
    engine = new PGLiteEngine();
    await engine.connect({});
    await engine.initSchema();
  });
  afterAll(async () => { await engine.disconnect(); });
  beforeEach(async () => {
    await resetPgliteState(engine);
    await engine.setConfig('version', '85');
  });

  test('a missing job keeps error invalid_params, reports code not_found, and points at the job list', async () => {
    const cli = await envelopeOf('get_job', ctx('cli', { engine }), { id: 999_999 });
    expect(cli).toMatchObject({ error: 'invalid_params', code: 'not_found', fix: { argv: ['gbrain', 'jobs', 'list', '--json'], next: 'run' } });
    const mcp = await envelopeOf('get_job_progress', ctx('stdio', { engine }), { id: 999_999 }, ['list_jobs']);
    expect(mcp).toMatchObject({ error: 'invalid_params', code: 'not_found', fix: { mcp: { tool: 'list_jobs', arguments: {} }, next: 'run' } });
  });

  test('a wrong-state transition says nothing changed and reads the job, never retries it', async () => {
    const job = await new MinionQueue(engine).add('sync', {});
    await op('cancel_job').handler(ctx('cli', { engine }), { id: job.id });
    const env = await envelopeOf('cancel_job', ctx('cli', { engine }), { id: job.id });
    expect(env).toMatchObject({ error: 'invalid_params', fix: { argv: ['gbrain', 'jobs', 'get', String(job.id), '--json'], next: 'run' } });
    expect(env.suggestion).toContain('Nothing changed');
    expect(env.suggestion).not.toMatch(/retry/i);
  });
});

describe('jobs ops (refusals)', () => {
  test('an agent-fenced missing job shares the frozen not-found envelope', async () => {
    const env = await envelopeOf('get_job', ctx('http', { auth: { clientId: 'client-a', scopes: ['agent'], token: 't' } }), { id: 7 }, ['list_jobs']);
    expect(env).toMatchObject({ error: 'invalid_params', code: 'not_found', fix: { mcp: { tool: 'list_jobs' } } });
  });

  test('no client identity without admin is a scope denial that keeps error permission_denied', async () => {
    const env = await envelopeOf('list_jobs', ctx('http', { auth: { clientId: '', scopes: ['agent'], token: 't' } }), {});
    expect(env).toMatchObject({ error: 'permission_denied', code: 'insufficient_scope', fix: { actor: 'host_admin', next: 'tell_user_to_run' } });
  });

  test('submit_agent on the local CLI points at gbrain agent run with the prompt as a declared input', async () => {
    const env = await envelopeOf('submit_agent', ctx('cli'), { prompt: 'hello' });
    expect(env.error).toBe('invalid_request');
    expect(env.fix).toMatchObject({ argv: ['gbrain', 'agent', 'run', '--', '<prompt>'], consent: ['paid'], inputs: [{ name: 'prompt' }] });
  });

  test('submit_agent names max_turns as an MCP param with an example', async () => {
    const env = await envelopeOf('submit_agent', ctx('http', { auth: { clientId: 'client-a', scopes: ['agent'], token: 't' } }), { prompt: 'hi', max_turns: 500 });
    expect(env.code).toBe('invalid_params');
    expect(env.suggestion).toContain('submit_agent {"max_turns": 20}');
    expect(env.suggestion).not.toMatch(/--max-turns/);
  });
});

describe('loops ops', () => {
  test('a mute outside the write source names the bound source and the exact host command', async () => {
    const env = await envelopeOf('loops_mute', ctx('stdio'), { kind: 'sender', value: '[email protected]', source_id: 'other' });
    expect(env.error).toBe('permission_denied');
    expect(env.suggestion).toContain("source 'notes'");
    expect(env.fix).toMatchObject({
      argv: ['gbrain', 'loops', 'mute', 'sender', '[email protected]', '--source', 'other'], actor: 'user', next: 'tell_user_to_run',
    });
  });

  test('a hostile mute value is never interpolated', async () => {
    const env = await envelopeOf('loops_mute', ctx('stdio'), { kind: 'sender', value: '--yes', source_id: 'other' });
    expect(env.fix).toBeUndefined();
  });

  test('an invalid as_of names the param on MCP', async () => {
    const env = await envelopeOf('open_loops', ctx('http'), { as_of: 'yesterday' });
    expect(env.code).toBe('invalid_params');
    expect(env.suggestion).toContain('`as_of`');
    expect(env.suggestion).not.toMatch(/--as-of/);
  });
});

describe('think', () => {
  test('an unusable explicit model is a caller error on the local CLI naming --model', async () => {
    const env = await envelopeOf('think', ctx('cli'), { question: 'q', model: 'bogusprovider:foo' });
    expect(env.code).toBe('invalid_params');
    expect(env.message).toMatch(/not usable.*unknown_provider/);
    expect(env.suggestion).toMatch(/--model/);
  });
  // GBRA-437 (#9050): a remote caller's unusable model is never an error; the host model answers
  // with MODEL_OVERRIDE_IGNORED:unusable, pinned on real engines in test/think-remote-model.test.ts.
});

describe('add_timeline_entry', () => {
  test('a bad date names the positional on the CLI and the param over MCP', async () => {
    const cli = await envelopeOf('add_timeline_entry', ctx('cli'), { slug: 'notes/x', date: '2026-02-30', summary: 's' });
    expect(cli).toMatchObject({ error: 'invalid_params', message: 'Invalid calendar date "2026-02-30"' });
    expect(cli.suggestion).toContain('the date argument');
    const mcp = await envelopeOf('add_timeline_entry', ctx('http'), { slug: 'notes/x', date: '2026/02/01', summary: 's' });
    expect(mcp.suggestion).toContain('`date`');
  });
});

describe('get_recent_transcripts', () => {
  test('the local-only refusal names the host command with the caller\'s window', async () => {
    const env = await envelopeOf('get_recent_transcripts', ctx('http'), { days: 3, summary: false });
    expect(env).toMatchObject({
      error: 'permission_denied',
      fix: { argv: ['gbrain', 'transcripts', 'recent', '--days', '3', '--full', '--json'], actor: 'host_admin', next: 'tell_user_to_run' },
    });
  });
});

describe('extraction_review', () => {
  test('a remote reject names the exact owner command and asks consent for the soft-delete', async () => {
    const env = await envelopeOf('extraction_review', ctx('stdio'), { action: 'reject', slugs: ['people/alice-example', 'companies/acme-example'] });
    expect(env.error).toBe('permission_denied');
    expect(env.fix).toMatchObject({
      argv: ['gbrain', 'extraction-review', 'reject', '--slugs', 'people/alice-example,companies/acme-example'],
      consent: ['destructive'], actor: 'user', next: 'tell_user_to_run',
    });
  });

  test('an unsafe slug falls back to the pending list', async () => {
    const env = await envelopeOf('extraction_review', ctx('stdio'), { action: 'promote', slugs: ['--yes'] });
    expect(env.fix?.argv).toEqual(['gbrain', 'extraction-pending']);
  });

  test('empty slugs on the CLI renders the flag; the message names no flag', async () => {
    const env = await envelopeOf('extraction_review', ctx('cli'), { action: 'promote', slugs: [] });
    expect(env.message).not.toMatch(/--slugs/);
    expect(env.suggestion).toContain('--slugs slug1,slug2');
    expect(env.fix).toMatchObject({ argv: ['gbrain', 'extraction-pending'], next: 'run' });
  });
});

describe('get_write_attribution', () => {
  test('two row selectors render per surface and the fix attributes the first one', async () => {
    const mcp = await envelopeOf('get_write_attribution', ctx('http'), { slug: 'notes/x', take: 2, timeline: 3 }, ['get_write_attribution']);
    expect(mcp.message).toBe('Pass at most one of fact, take or timeline.');
    expect(mcp.fix).toMatchObject({ mcp: { tool: 'get_write_attribution', arguments: { slug: 'notes/x', take: 2 } }, next: 'run' });
    const cli = await envelopeOf('get_write_attribution', ctx('cli'), { slug: 'notes/x', fact: 1, take: 2 });
    expect(cli.message).toBe('Pass at most one of --fact, --take or --timeline.');
    expect(cli.fix?.argv).toEqual(['gbrain', 'attribution', 'notes/x', '--fact', '1']);
  });

  test('a non-positive row id names the param on MCP', async () => {
    const env = await envelopeOf('get_write_attribution', ctx('http'), { slug: 'notes/x', fact: -1 });
    expect(env.code).toBe('invalid_params');
    expect(env.suggestion).toContain('fact: 1');
    expect(`${env.message} ${env.suggestion}`).not.toMatch(/--fact/);
  });
});