Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.9 KB
Raw Blame
/**
 * GST-1158 F2: an attested call to a contract v3 personal tool answers with its result in structuredContent.
 *
 * 1. Protects: each v3 personal tool (query, get_page, get_timeline, get_backlinks, find_experts, whois, entity,
 *    context_pack, volunteer_context, get_write_request, forget_fact) called as an attested person returns its parsed
 *    result in structuredContent (an array as structuredContent.results), holding every field v3.json freezes, while
 *    content keeps the JSON (context_pack: its text alone, as memory_recall); its refusals carry structuredContent.error;
 *    a read whose answer with structuredContent passes the result cap is refused whole; unattested callers and other
 *    tools are unchanged.
 * 2. Fails when: a v3 tool's structuredContent is missing or drops a frozen field, content changes for a non-text tool,
 *    a refusal lacks structuredContent.error, an attested frame over the cap is sent, or the rewrite reaches an
 *    unattested call or a tool outside v3.
 * 3. Existing coverage: test/qm-memory-tools.test.ts pins the memory pair; test/qm-memory-contract.test.ts pins v3.json.
 * 4. Real seams: OAuth client-credentials tokens verified by the provider, MCP dispatch with x-qm-actor, a repo-less
 *    brain on PGLite and Postgres; writes through the persistence coordinator; no embedding provider (keyless).
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { readFileSync } from 'node:fs';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
import { sqlQueryForEngine } from '../src/core/sql-query.ts';
import { dispatchToolCall, type ToolResult } from '../src/mcp/dispatch.ts';
import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
import { addMember, bindCredential } from '../src/core/access/members.ts';
import { linkMember } from '../src/core/access/actor.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { QM_PERSONAL_OPS } from '../src/core/ops/qm-memory.ts';
import { mintLegacyToken } from '../src/core/token-mint.ts';
import { startHttpTransport } from '../src/mcp/http-transport.ts';
import { RateLimiter } from '../src/mcp/rate-limit.ts';
import { QM_CONTRACT_PATHS } from '../scripts/build-qm-memory-contract.ts';
import type { AuthInfo } from '../src/core/ops/contract.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';

const SRC = 'source-a';
const ALICE_ID = 'U0ALICE';
const PERSON = 'people/bob-example';
const COMPANY = 'companies/acme-example';
const BIG = 'notes/big-example';

/** Checks a value against a v3 frozen shape: a type string, a one-row array of shapes, or an object of shapes. */
function conforms(shape: unknown, value: unknown, at = '$'): string[] {
  if (Array.isArray(shape)) {
    if (!Array.isArray(value)) return [at + ' is not an array'];
    return value.flatMap((v, i) => conforms(shape[0], v, at + '[' + i + ']'));
  }
  if (shape && typeof shape === 'object') {
    if (!value || typeof value !== 'object' || Array.isArray(value)) return [at + ' is not an object'];
    return Object.entries(shape).flatMap(([k, s]) => k in (value as object) ? conforms(s, (value as Record<string, unknown>)[k], at + '.' + k) : [at + '.' + k + ' is missing']);
  }
  const ok = String(shape).split(' | ').some(t => {
    if (t.startsWith('"')) return value === JSON.parse(t);
    if (t === 'null') return value === null;
    if (t === 'array') return Array.isArray(value);
    if (t === 'object') return !!value && typeof value === 'object' && !Array.isArray(value);
    return typeof value === t;
  });
  return ok ? [] : [at + ' is ' + JSON.stringify(value) + ', not ' + String(shape)];
}

const v3 = JSON.parse(readFileSync(QM_CONTRACT_PATHS[3], 'utf8'));
const frozen = (op: string) => v3.personal_tools.tools.find((t: { name: string }) => t.name === op).result;

for (const kind of testBackends()) {
  describe('contract v3 personal tools over MCP dispatch (' + kind + ', repo-less)', () => {
    let engine: BrainEngine;
    let close: () => Promise<void>;
    const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
    const tokens: Record<string, string> = {};
    let receipt = '';
    let factId = 0;

    async function call(token: string, op: string, params: Record<string, unknown>, actor: string | null = ALICE_ID) {
      const out: ToolResult = await dispatchToolCall(engine, op, { ...params }, {
        remote: true, transport: 'http', auth: await provider().verifyAccessToken(tokens[token]!) as unknown as AuthInfo, sourceId: SRC,
        ...(actor !== null ? { actor: { header: actor } } : {}), writeWaitMs: 30_000,
      });
      let json: unknown = undefined;
      try { json = JSON.parse(out.content[0]?.text ?? ''); } catch { /* plain text */ }
      return { out, json, structured: out.structuredContent as Record<string, any> | undefined };
    }
    const local = (op: string, params: Record<string, unknown>) => dispatchToolCall(engine, op, params, { remote: false, sourceId: SRC });

    beforeAll(async () => {
      if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
      else { engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema(); close = () => engine.disconnect(); }
      __resetPrivateVisibilityCacheForTests();
      await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [SRC]);
      await addMember(engine, 'alice-example');
      await importFromContent(engine, PERSON, '---\ntype: person\ntitle: Bob Example\nemail: [email protected]\n---\n# Bob Example\n\nBob Example keeps the harbor ledger at [[' + COMPANY + ']].\n', { sourceId: SRC });
      await importFromContent(engine, COMPANY, '---\ntype: company\ntitle: Acme Example\n---\n# Acme Example\n\nAcme Example harbor ledger budget notes.\n', { sourceId: SRC });
      await importFromContent(engine, BIG, '---\ntype: note\ntitle: Big Example\n---\n# Big Example\n\n' + 'harbor ledger row '.repeat(8_000) + '\n', { sourceId: SRC });
      expect((await local('add_timeline_entry', { slug: COMPANY, date: '2026-09-02', summary: 'Acme Example opened a harbor office' })).isError).toBeFalsy();
      expect((await local('add_link', { from: PERSON, to: COMPANY, link_type: 'works_at' })).isError).toBeFalsy();
      const register = async (name: string) => {
        const c = await provider().registerClientManual('v3-' + name + '-' + randomUUID().slice(0, 8), ['client_credentials'], 'read write', [], SRC);
        tokens[name] = (await provider().exchangeClientCredentials(c.clientId, c.clientSecret ?? '')).access_token;
        return c.clientId;
      };
      await bindCredential(engine, { kind: 'client', id: await register('qm') }, { attestActor: 'qm', attestOps: [...QM_PERSONAL_OPS, 'memory_recall', 'memory_write', 'get_links'] });
      await register('plain');
      await linkMember(engine, 'alice-example', 'qm', ALICE_ID);
      const saved = await call('qm', 'memory_write', { facts: [{ fact: 'Alice prefers the harbor ledger review on Mondays', provenance: 'turn 1' }], idempotency_key: randomUUID() });
      receipt = saved.structured!.request_id;
      factId = Number(saved.structured!.fact_ids[0]);
    }, 120_000);

    afterAll(async () => {
      await disposePersistenceConsumer(engine).catch(() => undefined);
      await close?.();
    });

    test('each personal tool answers an attested call with its parsed result in structuredContent, holding every frozen field', async () => {
      const cases: Array<[string, Record<string, unknown>, string?]> = [
        ['query', { query: 'harbor ledger' }],
        ['get_page', { slug: PERSON }],
        ['get_timeline', { slug: COMPANY }],
        ['get_backlinks', { slug: COMPANY }],
        ['get_backlinks', { slug: COMPANY, group: 'page' }, 'with_group_page'],
        ['find_experts', { topic: 'harbor ledger' }],
        ['whois', { query: '[email protected]' }],
        ['whois', { query: 'Nobody Example' }],
        ['entity', { name: 'Bob Example' }],
        ['entity', { name: 'Nobody Example' }],
        ['entity', { names: ['Bob Example', 'Nobody Example'] }, 'with_names'],
        ['context_pack', { entities: 'Bob Example' }],
        ['volunteer_context', { window: 'user: I am meeting Bob Example about the Acme Example harbor ledger' }],
        ['get_write_request', { request_id: receipt }],
        ['forget_fact', { id: factId, request_id: randomUUID() }],
      ];
      const seen = new Set<string>();
      for (const [op, params, variant] of cases) {
        const { out, json, structured } = await call('qm', op, params);
        expect({ op, isError: out.isError === true }).toEqual({ op, isError: false });
        expect({ op, has: structured !== undefined }).toEqual({ op, has: true });
        const result = frozen(op);
        const shape = variant ? result[variant] : result.structured_content;
        expect({ op, params, problems: conforms(shape, structured) }).toEqual({ op, params, problems: [] });
        if (op === 'context_pack') {
          expect(out.content).toHaveLength(1);
          expect(typeof out.content[0]!.text).toBe('string');
          expect(out.content[0]!.text).toContain('Bob Example');
          expect(structured!.text).toBeUndefined();
        } else {
          expect(structured).toEqual(Array.isArray(json) ? { results: json } : json as Record<string, unknown>);
        }
        seen.add(op);
      }
      expect([...seen].sort()).toEqual([...QM_PERSONAL_OPS].sort());
      const rows = (await call('qm', 'query', { query: 'harbor ledger' })).structured!.results;
      expect(rows.length).toBeGreaterThan(0);
      expect((await call('qm', 'whois', { query: '[email protected]' })).structured).toMatchObject({ ambiguous: false, matches: [{ slug: PERSON, source_id: SRC }] });
      expect((await call('qm', 'get_write_request', { request_id: receipt })).structured!.state).toBe('committed');
      expect(frozen('get_write_request').states.known).toContain('committed');
    }, 120_000);

    test('a refusal of a personal tool under attestation carries structuredContent.error with its code', async () => {
      const cases: Array<[string, Record<string, unknown>, string]> = [
        ['get_page', { slug: 'people/nobody-example' }, 'page_not_found'],
        ['get_write_request', { request_id: randomUUID() }, 'not_found'],
        ['forget_fact', { id: 987_654_321 }, 'fact_not_found'],
        ['query', {}, 'invalid_params'],
      ];
      for (const [op, params, code] of cases) {
        const { out, json } = await call('qm', op, params);
        expect({ op, isError: out.isError, code: (json as Record<string, unknown>).code }).toEqual({ op, isError: true, code });
        expect(out.structuredContent?.error).toMatchObject({ code, message: (json as Record<string, unknown>).message });
        expect(v3.errors.codes.map((c: { code: string }) => c.code)).toContain(code);
      }
    }, 60_000);

    test('unattested calls and tools outside v3 are unchanged: no structuredContent, the same JSON content', async () => {
      const plain = await call('plain', 'get_page', { slug: PERSON }, null);
      expect(plain.out.isError).toBeFalsy();
      expect(plain.structured).toBeUndefined();
      expect((plain.json as Record<string, unknown>).slug).toBe(PERSON);
      const missing = await call('plain', 'get_page', { slug: 'people/nobody-example' }, null);
      expect(missing.out.isError).toBe(true);
      expect(missing.structured).toBeUndefined();
      const attestedOther = await call('qm', 'get_links', { slug: PERSON });
      expect(attestedOther.out.isError).toBeFalsy();
      expect(attestedOther.structured).toBeUndefined();
      expect(Array.isArray(attestedOther.json)).toBe(true);
      const plainQuery = await call('plain', 'query', { query: 'harbor ledger' }, null);
      expect(plainQuery.structured).toBeUndefined();
      expect(Array.isArray(plainQuery.json)).toBe(true);
    }, 60_000);

    test('the transport\'s scope refusal of a personal tool carries structuredContent.error under x-qm-actor, and not without it', async () => {
      const legacy = await mintLegacyToken(engine, { name: 'v3-read-' + randomUUID().slice(0, 8), scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] });
      await bindCredential(engine, { kind: 'token', id: legacy.id }, { attestActor: 'qm', attestOps: [...QM_PERSONAL_OPS] });
      const server = await startHttpTransport({ port: 0, engine, surface: 'full', limiters: {
        ip: new RateLimiter({ limit: 10_000, windowMs: 60_000, lruCap: 100 }),
        token: new RateLimiter({ limit: 10_000, windowMs: 60_000, lruCap: 100 }),
      } });
      try {
        const post = async (headers: Record<string, string>) => {
          const res = await fetch('http://127.0.0.1:' + server.port + '/mcp', {
            method: 'POST', headers: { authorization: 'Bearer ' + legacy.token, 'content-type': 'application/json', ...headers },
            body: JSON.stringify({ jsonrpc: '2.0', id: 9, method: 'tools/call', params: { name: 'forget_fact', arguments: { id: factId } } }),
          });
          return (await res.json() as { result: Record<string, any> }).result;
        };
        const attested = await post({ 'x-qm-actor': ALICE_ID });
        expect(attested.isError).toBe(true);
        expect(attested.structuredContent.error).toMatchObject({ code: 'insufficient_scope' });
        const bare = await post({});
        expect(bare.isError).toBe(true);
        expect(bare.structuredContent).toBeUndefined();
      } finally {
        server.stop(true);
      }
    }, 60_000);

    test('an attested read whose answer with structuredContent passes the result cap is refused whole; the unattested read still fits', async () => {
      await engine.setConfig('mcp.max_result_bytes_http', String(256 * 1024));
      try {
        const plain = await call('plain', 'get_page', { slug: BIG, body: 'full' }, null);
        expect(plain.out.isError).toBeFalsy();
        const attested = await call('qm', 'get_page', { slug: BIG, body: 'full' });
        expect({ isError: attested.out.isError, code: (attested.json as Record<string, unknown>).code }).toEqual({ isError: true, code: 'result_too_large' });
        expect(attested.out.structuredContent?.error).toMatchObject({ code: 'result_too_large' });
        const window = await call('qm', 'get_page', { slug: BIG, body: 'outline' });
        expect(window.out.isError).toBeFalsy();
        expect(conforms(frozen('get_page').structured_content, window.structured)).toEqual([]);
        expect(window.structured!.body).toBe('outline');
      } finally {
        await engine.setConfig('mcp.max_result_bytes_http', String(1024 * 1024));
      }
    }, 60_000);
  });
}