Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.2 KB
Raw Blame
/**
 * MEMORY_VERBS v1 + WP4 — surface-mode tests.
 *
 *   - 'verbs' filters to EXACTLY the seven protocol verbs
 *   - 'starter' filters to STARTER_OPS (membership pinned; every member
 *     exists in operations)
 *   - monotonicity: allowedOpNames(verbs) ⊆ starter ⊆ full (ENG-1)
 *   - 'full' is the identity (existing installs unchanged)
 *   - dispatch-layer allowedOps is FAIL-CLOSED: a hidden op is uncallable
 *     (unknown_tool), not merely unlisted [c2]
 *   - flag parsing is strict (unknown value rejects loudly)
 *   - resolution: flag > config mcp_surface > 'full'
 *   - D2 ceiling: effective = min(ceiling, client row ?? default); the
 *     GBRAIN_MCP_FORCE_SURFACE kill switch is NARROW-ONLY (FOV-6a)
 */

import { afterAll, afterEach, beforeAll, describe, expect, it } from 'bun:test';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { operations } from '../src/core/operations.ts';
import { VERB_NAMES } from '../src/core/verbs.ts';
import { BRAIN_TOOL_ALLOWLIST } from '../src/core/minions/tools/brain-allowlist.ts';
import {
  filterOpsForSurface,
  allowedOpNames,
  parseSurfaceFlag,
  resolveSurface,
  STARTER_OPS,
  minSurface,
  clampSurface,
  effectiveSurfaceForClient,
  resolveClientRowSurface,
  __resetSurfaceWarnCachesForTests,
} from '../src/mcp/surface.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { __setUsageLogPathForTests } from '../src/core/verbs/usage-log.ts';
import { withEnv } from './helpers/with-env.ts';

let engine: PGLiteEngine;
let home: string;

beforeAll(async () => {
  // Sidecar writes go to a temp file via the test seam — no global env mutation.
  home = mkdtempSync(join(tmpdir(), 'gbrain-surface-test-'));
  __setUsageLogPathForTests(join(home, 'usage.jsonl'));
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
});

afterAll(async () => {
  await engine.disconnect();
  __setUsageLogPathForTests(null);
  try { rmSync(home, { recursive: true, force: true }); } catch { /* best-effort */ }
});

describe('filterOpsForSurface', () => {
  it("'verbs' returns exactly the seven protocol verbs", () => {
    const names = filterOpsForSurface(operations, 'verbs').map(o => o.name).sort();
    expect(names).toEqual([...VERB_NAMES].sort());
  });

  it("'full' is the identity — existing installs see every op", () => {
    expect(filterOpsForSurface(operations, 'full')).toEqual(operations);
  });

  it("'starter' returns exactly the ops whose name is in STARTER_OPS", () => {
    const names = filterOpsForSurface(operations, 'starter').map(o => o.name).sort();
    expect(names).toEqual(operations.filter(o => STARTER_OPS.has(o.name)).map(o => o.name).sort());
  });
});

describe('STARTER_OPS (WP4)', () => {
  it('every member exists in operations (membership pin)', () => {
    const known = new Set(operations.map(o => o.name));
    const missing = [...STARTER_OPS].filter(name => !known.has(name));
    expect(missing).toEqual([]);
  });

  it('is composed programmatically: verbs + FOV-6b fallback daily ops + whoami + request_tools', () => {
    // ENG-1: the verb slice is a spread of VERB_NAMES — all SEVEN post-#4028
    // verbs (context_pack/delta included), never a hand-count.
    for (const v of VERB_NAMES) expect(STARTER_OPS.has(v)).toBe(true);
    // FOV-6b fallback: the reviewed brain-tool allow-list, imported not copied.
    for (const name of BRAIN_TOOL_ALLOWLIST) expect(STARTER_OPS.has(name)).toBe(true);
    // FOV-4: the agent lane must not strand agent-scope clients.
    expect(STARTER_OPS.has('submit_agent')).toBe(true);
    expect(STARTER_OPS.has('get_agent_job')).toBe(true);
    expect(STARTER_OPS.has('whoami')).toBe(true);
    // D4: request_tools is listed on starter (+full) …
    expect(STARTER_OPS.has('request_tools')).toBe(true);
  });

  it('D4: request_tools is NOT on the verbs surface', () => {
    expect(allowedOpNames(operations, 'verbs').has('request_tools')).toBe(false);
    expect(allowedOpNames(operations, 'starter').has('request_tools')).toBe(true);
    expect(allowedOpNames(operations, 'full').has('request_tools')).toBe(true);
  });

  it('receipt helpers are on starter/full while the frozen verb surface stays unchanged', () => {
    for (const name of ['get_write_request', 'list_write_requests', 'cancel_write_request']) {
      expect(allowedOpNames(operations, 'starter').has(name)).toBe(true);
      expect(allowedOpNames(operations, 'full').has(name)).toBe(true);
      expect(allowedOpNames(operations, 'verbs').has(name)).toBe(false);
    }
    expect(filterOpsForSurface(operations, 'verbs').map(op => op.name).sort()).toEqual([...VERB_NAMES].sort());
  });

  it('monotonicity (ENG-1): allowedOpNames(verbs) ⊆ starter ⊆ full', () => {
    const verbs = allowedOpNames(operations, 'verbs');
    const starter = allowedOpNames(operations, 'starter');
    const full = allowedOpNames(operations, 'full');
    for (const name of verbs) expect(starter.has(name)).toBe(true);
    for (const name of starter) expect(full.has(name)).toBe(true);
    // And the ladder is strictly widening at each step.
    expect(verbs.size).toBeLessThan(starter.size);
    expect(starter.size).toBeLessThan(full.size);
  });
});

describe('dispatch allowedOps — fail-closed [c2]', () => {
  it('a hidden op returns unknown_tool even when called by name', async () => {
    const allowed = allowedOpNames(operations, 'verbs');
    const res = await dispatchToolCall(engine, 'get_page', { slug: 'x' }, {
      remote: true,
      sourceId: 'default',
      allowedOps: allowed,
      surface: 'verbs',
    });
    expect(res.isError).toBe(true);
    const body = JSON.parse(res.content[0].text);
    expect(body.error).toBe('unknown_tool');
  });

  it('a surfaced verb still dispatches under the same allowedOps set', async () => {
    const allowed = allowedOpNames(operations, 'verbs');
    const res = await dispatchToolCall(engine, 'entity', { name: 'zzz-nobody' }, {
      remote: true,
      sourceId: 'default',
      allowedOps: allowed,
      surface: 'verbs',
    });
    expect(res.isError ?? false).toBe(false);
    const body = JSON.parse(res.content[0].text);
    expect(body.found).toBe(false);
  });

  it('without allowedOps (full surface) every op stays callable — pre-existing behavior', async () => {
    const res = await dispatchToolCall(engine, 'get_stats', {}, {
      remote: true,
      sourceId: 'default',
    });
    expect(res.isError ?? false).toBe(false);
  });
});

describe('parseSurfaceFlag + resolveSurface', () => {
  it('parses verbs/starter/full, rejects unknown values loudly, requires a value', () => {
    expect(parseSurfaceFlag(['--surface', 'verbs'])).toBe('verbs');
    expect(parseSurfaceFlag(['--surface', 'starter'])).toBe('starter');
    expect(parseSurfaceFlag(['--surface', 'full'])).toBe('full');
    expect(parseSurfaceFlag(['serve'])).toBe(null);
    expect(() => parseSurfaceFlag(['--surface', 'all'])).toThrow(/Unknown --surface/);
    expect(() => parseSurfaceFlag(['--surface'])).toThrow(/requires a value/);
    expect(() => parseSurfaceFlag(['--surface', '--http'])).toThrow(/requires a value/);
  });

  it('resolution: flag > config mcp_surface > full', () => {
    expect(resolveSurface('verbs', { mcp_surface: 'full' })).toBe('verbs');
    expect(resolveSurface(null, { mcp_surface: 'verbs' })).toBe('verbs');
    expect(resolveSurface(null, { mcp_surface: 'starter' })).toBe('starter');
    expect(resolveSurface(null, {})).toBe('full');
    expect(resolveSurface(null, null)).toBe('full');
    expect(resolveSurface(null, { mcp_surface: 'bogus' as never })).toBe('full');
  });
});

// ---------------------------------------------------------------------------
// WP4 — D2 ceiling resolution + GBRAIN_MCP_FORCE_SURFACE kill switch (FOV-6a)
// ---------------------------------------------------------------------------

describe('D2 ceiling resolution (effectiveSurfaceForClient)', () => {
  afterEach(() => {
    __resetSurfaceWarnCachesForTests();
  });

  it('minSurface orders verbs < starter < full', () => {
    expect(minSurface('verbs', 'full')).toBe('verbs');
    expect(minSurface('full', 'verbs')).toBe('verbs');
    expect(minSurface('starter', 'full')).toBe('starter');
    expect(minSurface('full', 'starter')).toBe('starter');
    expect(minSurface('verbs', 'starter')).toBe('verbs');
    expect(minSurface('full', 'full')).toBe('full');
  });

  it('D2 pin: a verbs-pinned server + full client row still serves verbs', () => {
    expect(effectiveSurfaceForClient({ ceiling: 'verbs', clientSurface: 'full', defaultSurface: null })).toBe('verbs');
  });

  it('client row narrows below the ceiling', () => {
    expect(effectiveSurfaceForClient({ ceiling: 'full', clientSurface: 'starter', defaultSurface: null })).toBe('starter');
    expect(effectiveSurfaceForClient({ ceiling: 'full', clientSurface: 'verbs', defaultSurface: null })).toBe('verbs');
  });

  it('NULL row surface falls to the config default, bounded by the ceiling', () => {
    expect(effectiveSurfaceForClient({ ceiling: 'full', clientSurface: null, defaultSurface: 'starter' })).toBe('starter');
    expect(effectiveSurfaceForClient({ ceiling: 'verbs', clientSurface: null, defaultSurface: 'full' })).toBe('verbs');
  });

  it('NULL row + unset default = the ceiling (pre-WP4 behavior, existing clients untouched)', () => {
    expect(effectiveSurfaceForClient({ ceiling: 'full', clientSurface: null, defaultSurface: null })).toBe('full');
    expect(effectiveSurfaceForClient({ ceiling: 'starter', clientSurface: null, defaultSurface: null })).toBe('starter');
  });

  // FOV-6a pins, deliberately NEXT to the D2 ceiling test above.
  it('kill switch narrows: force=verbs clamps a full resolution to verbs', async () => {
    await withEnv({ GBRAIN_MCP_FORCE_SURFACE: 'verbs' }, () => {
      expect(effectiveSurfaceForClient({ ceiling: 'full', clientSurface: 'full', defaultSurface: null })).toBe('verbs');
      expect(clampSurface('full')).toBe('verbs');
    });
  });

  it('kill switch can NEVER widen: force=full over a verbs ceiling still serves verbs', async () => {
    await withEnv({ GBRAIN_MCP_FORCE_SURFACE: 'full' }, () => {
      expect(effectiveSurfaceForClient({ ceiling: 'verbs', clientSurface: 'full', defaultSurface: null })).toBe('verbs');
      expect(clampSurface('verbs')).toBe('verbs');
      expect(clampSurface('starter')).toBe('starter');
    });
  });

  it('unknown kill-switch value is ignored (warn once), surface stays as configured', async () => {
    await withEnv({ GBRAIN_MCP_FORCE_SURFACE: 'everything' }, () => {
      const warnings: string[] = [];
      expect(clampSurface('starter', msg => warnings.push(msg))).toBe('starter');
      expect(clampSurface('starter', msg => warnings.push(msg))).toBe('starter');
      expect(warnings.length).toBe(1);
      expect(warnings[0]).toContain('GBRAIN_MCP_FORCE_SURFACE');
    });
  });
});

describe('resolveClientRowSurface (amendment 18)', () => {
  afterEach(() => __resetSurfaceWarnCachesForTests());

  it('threads known values, null/undefined = no per-client surface', () => {
    expect(resolveClientRowSurface('starter', 'c1')).toBe('starter');
    expect(resolveClientRowSurface('verbs', 'c1')).toBe('verbs');
    expect(resolveClientRowSurface('full', 'c1')).toBe('full');
    expect(resolveClientRowSurface(null, 'c1')).toBe(null);
    expect(resolveClientRowSurface(undefined, 'c1')).toBe(null);
  });

  it('unknown value → ignored + warn-logged once per client', () => {
    const warnings: string[] = [];
    const warn = (msg: string) => warnings.push(msg);
    expect(resolveClientRowSurface('tier-gold', 'client-a', warn)).toBe(null);
    expect(resolveClientRowSurface('tier-gold', 'client-a', warn)).toBe(null);
    expect(resolveClientRowSurface('tier-gold', 'client-b', warn)).toBe(null);
    expect(warnings.length).toBe(2); // once per client, not per request
    expect(warnings[0]).toContain('client-a');
    expect(warnings[1]).toContain('client-b');
  });
});

describe('stdio surface resolution: GBRAIN_SURFACE > --surface > config > full', () => {
  it('env wins, then the flag, then config, then the default; each with its source', async () => {
    const { resolveStdioSurface } = await import('../src/mcp/surface.ts');
    expect(resolveStdioSurface('full', { mcp_surface: 'starter' }, 'verbs')).toEqual({ surface: 'verbs', source: 'env' });
    expect(resolveStdioSurface('full', { mcp_surface: 'starter' }, undefined)).toEqual({ surface: 'full', source: 'flag' });
    expect(resolveStdioSurface(null, { mcp_surface: 'starter' }, '')).toEqual({ surface: 'starter', source: 'config' });
    expect(resolveStdioSurface(null, null, undefined)).toEqual({ surface: 'full', source: 'default' });
  });

  it('an invalid env value is ignored (never fatal) and reported', async () => {
    const { resolveStdioSurface, surfaceEnvInvalidNotice } = await import('../src/mcp/surface.ts');
    const r = resolveStdioSurface('starter', null, 'everything');
    expect(r).toEqual({ surface: 'starter', source: 'flag', invalidEnv: 'everything' });
    const notice = surfaceEnvInvalidNotice('everything', r.surface, r.source);
    expect(notice).toMatchObject({ code: 'surface_env_invalid', kind: 'info' });
    expect(notice.why).toContain('use verbs, starter or full');
    expect(notice.why).toContain("serves 'starter' (source: --surface)");
  });

  it('serve --http ignores GBRAIN_SURFACE and says so on stderr', async () => {
    const { withEnv } = await import('./helpers/with-env.ts');
    const { runServe } = await import('../src/commands/serve.ts');
    const errors: string[] = [];
    let served: string | undefined;
    const origError = console.error;
    console.error = (...args: unknown[]) => { errors.push(args.map(String).join(' ')); };
    try {
      await withEnv({ GBRAIN_SURFACE: 'verbs' }, () => runServe({ disconnect: async () => {} } as never, ['--http', '--surface', 'starter'], {
        runServeHttp: async (_e: unknown, o: { surface?: string }) => { served = o.surface; },
        exit: () => {}, log: () => {}, stallWatchdogMs: 0,
      } as never));
    } finally {
      console.error = origError;
    }
    expect(served).toBe('starter');
    expect(errors.join('\n')).toContain('GBRAIN_SURFACE is ignored with --http');
    expect(errors.join('\n')).toContain('surface=starter (source: --surface)');
  });

  it('the stdio session surface widens one allow-set and never passes --access read-only', async () => {
    const { createStdioSurfaceState } = await import('../src/mcp/surface.ts');
    const changes: Array<{ from: string; to: string; added: string[] }> = [];
    const session = createStdioSurfaceState(operations, { surface: 'starter', source: 'flag', readOnly: false, onWiden: c => changes.push(c) });
    expect(session.allowedOps?.has('get_health')).toBe(false);
    session.widen('full');
    expect(session.surface).toBe('full');
    expect(session.allowedOps).toBeUndefined();
    expect(session.surfacedOps.some(op => op.name === 'get_health')).toBe(true);
    expect(changes[0]?.added).toContain('get_health');
    const ro = createStdioSurfaceState(operations, { surface: 'starter', source: 'flag', readOnly: true });
    ro.widen('full');
    expect(ro.allowedOps?.has('put_page')).toBe(false);
    expect(ro.allowedOps?.has('get_timeline')).toBe(true);
  });
});