Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
19.3 KB
Raw Blame
/**
 * O-CEO-13: the bounded changed-contract conformance gate for fix wave 8.
 * The same cases run on PGLite (test/write-contract-conformance.test.ts) and
 * Postgres (test/e2e/write-contract-conformance.test.ts), each over stdio
 * dispatch and the real HTTP MCP transport. Only the contract surfaces this
 * wave changes are covered; the full every-op suite is a Foundations 2 TODO.
 */
import { describe, expect, test } from 'bun:test';
import { createHash, randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import type { BrainEngine } from '../../src/core/engine.ts';
import { dispatchToolCall, requestLogStatusForResult, type ToolResult } from '../../src/mcp/dispatch.ts';
import { startHttpTransport } from '../../src/mcp/http-transport.ts';
import { RateLimiter } from '../../src/mcp/rate-limit.ts';
import { VERB_NAMES } from '../../src/core/verbs.ts';
import { acquireWorktree, claimWorktree, getWorktreeBinding } from '../../src/core/persistence/ownership.ts';
import { registerLocalWriter, withVerifiedLocalRegistration, type LocalRegistration } from '../../src/core/persistence/identity.ts';
import { disposePersistenceConsumer } from '../../src/core/persistence/service.ts';
import { parseRescopeTokenArgs, rescopeLegacyToken } from '../../src/core/grants/legacy-token.ts';
import { isolatedSharedSkillsEngine } from '../helpers/shared-skills-engine.ts';
import { PROVIDER_ENV_KEYS } from '../helpers/provider-env.ts';
import { withEnv } from '../helpers/with-env.ts';

interface Reply { isError: boolean; body: Record<string, any>; status: string; }
interface Transport {
  name: 'stdio' | 'http';
  call(tool: string, args: Record<string, unknown>, opts?: { surface?: 'verbs'; abortAfterMs?: number }): Promise<Reply>;
  revoke(): Promise<void>;
  /** HTTP only: the legacy bearer token's name, for `auth rescope-token`. */
  tokenName?: string;
}
interface Fixture { engine: BrainEngine; transports: () => Promise<Transport[]>; }

const OPERATIONS = ['get_page', 'put_page', 'edit_page', 'get_write_request', 'remember', 'recall', 'find_orphans'];
const page = (body: string) => `---\ntitle: Conformance example\ntype: note\n---\n\n${body}\n`;
const reply = (result: ToolResult): Reply => ({ isError: result.isError === true, body: JSON.parse(result.content[0]!.text), status: requestLogStatusForResult(result) });

async function withFixture(databaseUrl: string | undefined, run: (fixture: Fixture) => Promise<void>) {
  const dir = mkdtempSync(join(tmpdir(), 'gb-write-contract-'));
  try {
    await withEnv({ ...Object.fromEntries(PROVIDER_ENV_KEYS.map(key => [key, undefined])), HOME: join(dir, 'home'), GBRAIN_HOME: join(dir, 'home'),
      DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined, GBRAIN_SOURCE: undefined, GBRAIN_MCP_FORCE_SURFACE: undefined }, async () => {
      const isolated = await isolatedSharedSkillsEngine(databaseUrl);
      const engine = isolated.engine;
      const clients: Client[] = [];
      const servers: Array<Awaited<ReturnType<typeof startHttpTransport>>> = [];
      try {
        const root = join(dir, 'content'); mkdirSync(root, { recursive: true });
        await engine.executeRaw('UPDATE sources SET local_path=$1 WHERE id=$2', [root, 'default']);
        await claimWorktree(engine, 'default', root);
        const limiters = () => ({ ip: new RateLimiter({ limit: 10_000, windowMs: 60_000, lruCap: 100 }),
          token: new RateLimiter({ limit: 10_000, windowMs: 60_000, lruCap: 100 }) });
        const full = await startHttpTransport({ port: 0, engine, surface: 'full', limiters: limiters() });
        const verbs = await startHttpTransport({ port: 0, engine, surface: 'verbs', limiters: limiters() });
        servers.push(full, verbs);
        const transports = async (): Promise<Transport[]> => {
          const registration: LocalRegistration = await registerLocalWriter(engine, 'stdio', { sourceIds: ['default'], operations: null, scopes: ['read', 'write'], slugPrefixes: null });
          const stdio: Transport = {
            name: 'stdio',
            call: async (tool, args, opts = {}) => {
              const pending = withVerifiedLocalRegistration(engine, registration, () => dispatchToolCall(engine, tool, args, {
                remote: true, transport: 'stdio', sourceId: 'default', config: { engine: engine.kind }, logger: { info() {}, warn() {}, error() {} },
                ...(opts.surface ? { surface: opts.surface, allowedOps: new Set(VERB_NAMES) } : {}),
              }));
              if (opts.abortAfterMs !== undefined) { void pending.catch(() => {}); throw new Error('response dropped'); }
              return reply(await pending);
            },
            revoke: async () => { await engine.executeRaw('UPDATE persistence_local_writers SET revoked_at=now() WHERE id=$1::uuid', [registration.id]); },
          };
          const id = randomUUID(), token = `fixture-${randomUUID()}`, tokenName = `conformance-${id.slice(0, 8)}`;
          await engine.executeRaw(`INSERT INTO access_tokens(id,name,token_hash,scopes,permissions) VALUES($1::uuid,$2,$3,$4::text[],$5::text::jsonb)`,
            [id, tokenName, createHash('sha256').update(token).digest('hex'), ['read', 'write'],
              JSON.stringify({ source_id: 'default', allowed_operations: OPERATIONS })]);
          const connect = async (server: typeof full) => {
            const client = new Client({ name: 'write-contract-conformance', version: '1' }, { capabilities: {} });
            clients.push(client);
            // `Connection: close`: each HTTP call opens its own socket. The clients
            // connect before the stdio arm, so a pooled socket would sit idle past
            // the server's 10 s idle timeout (Bun.serve default, swept every 4 s);
            // Bun's fetch keeps pooled sockets for 5 minutes, cannot see that
            // timeout and never retries a POST, so a call issued as the sweep
            // closes the socket fails with ECONNRESET on a slow shard.
            await client.connect(new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${server.port}/mcp`), {
              requestInit: { headers: { Authorization: `Bearer ${token}`, Connection: 'close' } } }), { signal: AbortSignal.timeout(30_000) });
            return client;
          };
          const fullClient = await connect(full), verbsClient = await connect(verbs);
          const http: Transport = {
            name: 'http',
            tokenName,
            call: async (tool, args, opts = {}) => {
              const client = opts.surface ? verbsClient : fullClient;
              const result = await client.callTool({ name: tool, arguments: args }, undefined, { timeout: opts.abortAfterMs ?? 30_000 });
              return reply(result as ToolResult);
            },
            revoke: async () => { await engine.executeRaw('UPDATE access_tokens SET revoked_at=now() WHERE id=$1::uuid', [id]); },
          };
          return [stdio, http];
        };
        await run({ engine, transports });
      } finally {
        await Promise.all(clients.map(client => client.close().catch(() => {})));
        for (const server of servers) server.stop(true);
        await disposePersistenceConsumer(engine);
        await isolated.close();
      }
    });
  } finally { rmSync(dir, { recursive: true, force: true }); }
}

async function hold(engine: BrainEngine) {
  const binding = await getWorktreeBinding(engine, 'default');
  // The consumer can still hold the worktree lock for a moment after the
  // previous write settled (post-publication effects), so wait for it.
  const lock = await acquireWorktree(binding!, 15_000);
  if (!lock) throw new Error('worktree lock unavailable');
  return lock;
}
async function settled(engine: BrainEngine, requestId: string) {
  const deadline = Date.now() + 30_000;
  for (;;) {
    const [row] = await engine.executeRaw<{ state: string; error_code: string | null }>(
      'SELECT state, error_code FROM persistence_requests WHERE request_id=$1::uuid', [requestId]);
    if (row && ['committed', 'conflict', 'failed', 'cancelled'].includes(row.state)) return row;
    if (Date.now() > deadline) throw new Error(`request ${requestId} did not settle: ${JSON.stringify(row)}`);
    await Bun.sleep(50);
  }
}
async function revision(transport: Transport, slug: string) {
  const read = await transport.call('get_page', { slug, include_content: true });
  expect(read.isError).toBe(false);
  return read.body as { revision: string; content: string };
}

export function writeContractConformanceCases(databaseUrl?: string) {
  const engineName = databaseUrl ? 'postgres' : 'pglite';
  describe(`write contract conformance (${engineName})`, () => {
    test('accepted → committed, and accepted → failed, over stdio and HTTP', async () => {
      await withFixture(databaseUrl, async ({ engine, transports }) => {
        for (const transport of await transports()) {
          const slug = `notes/${transport.name}-accepted`;
          const created = await transport.call('put_page', { slug, content: page('Created.'), request_id: randomUUID() });
          expect({ transport: transport.name, created }).toMatchObject({ created: { isError: false, status: 'success' } });
          const current = await revision(transport, slug);
          const commit = { slug, content: page('Committed later.'), expected_revision: current.revision, request_id: randomUUID() };
          let lock = await hold(engine);
          const pending = await transport.call('put_page', commit);
          await lock.release();
          expect({ transport: transport.name, pending }).toMatchObject({ pending: { isError: true, status: 'accepted_pending',
            body: { error: 'write_pending', write_request: { request_id: commit.request_id } } } });
          expect((await settled(engine, commit.request_id)).state).toBe('committed');
          const replayed = await transport.call('put_page', commit);
          expect({ transport: transport.name, replayed }).toMatchObject({ replayed: { isError: false, status: 'success', body: { state: 'committed' } } });

          const fresh = await revision(transport, slug);
          const doomed = { slug, content: page('Never published.'), expected_revision: fresh.revision, request_id: randomUUID() };
          lock = await hold(engine);
          const accepted = await transport.call('put_page', doomed);
          expect(accepted.status).toBe('accepted_pending');
          await engine.executeRaw("UPDATE pages SET knowledge_revision=gen_random_uuid() WHERE slug=$1 AND source_id='default'", [slug]);
          await lock.release();
          expect(await settled(engine, doomed.request_id)).toMatchObject({ state: 'conflict' });
          const failed = await transport.call('put_page', doomed);
          expect({ transport: transport.name, failed }).toMatchObject({ failed: { isError: true, status: 'error', body: { write_request: { state: 'conflict' } } } });
          expect((await revision(transport, slug)).content).not.toContain('Never published.');
        }
      });
    }, 180_000);

    test('a lost response is recovered by replaying the same request_id, including on the verbs-only surface', async () => {
      await withFixture(databaseUrl, async ({ engine, transports }) => {
        for (const transport of await transports()) {
          const write = { slug: `notes/${transport.name}-lost`, content: page('Delivered once.'), request_id: randomUUID() };
          const lock = await hold(engine);
          await expect(transport.call('put_page', write, { abortAfterMs: 200 })).rejects.toThrow();
          await lock.release();
          expect((await settled(engine, write.request_id)).state).toBe('committed');
          const replayed = await transport.call('put_page', write);
          expect({ transport: transport.name, replayed }).toMatchObject({ replayed: { isError: false, body: { state: 'committed', request_id: write.request_id } } });
          const [{ n }] = await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM persistence_requests WHERE request_id=$1::uuid', [write.request_id]);
          expect(n).toBe(1);

          const remember = { fact: `Conformance replay fact ${transport.name}`, provenance: 'conformance-test', request_id: randomUUID() };
          const first = await transport.call('remember', remember, { surface: 'verbs' });
          expect({ transport: transport.name, first }).toMatchObject({ first: { isError: false } });
          const again = await transport.call('remember', remember, { surface: 'verbs' });
          expect(again.body).toEqual(first.body);
          const [{ facts }] = await engine.executeRaw<{ facts: number }>('SELECT count(*)::int AS facts FROM facts WHERE fact=$1', [remember.fact]);
          expect(facts).toBe(1);
        }
      });
    }, 180_000);

    test('edit_page refuses a stale revision with the current one over stdio and HTTP', async () => {
      await withFixture(databaseUrl, async ({ transports }) => {
        for (const transport of await transports()) {
          const slug = `notes/${transport.name}-edit`;
          expect((await transport.call('put_page', { slug, content: page('Alpha line.'), request_id: randomUUID() })).isError).toBe(false);
          const stale = (await revision(transport, slug)).revision;
          const edited = await transport.call('edit_page', { slug, expected_revision: stale, edits: [{ old_text: 'Alpha line.', new_text: 'Beta line.' }], request_id: randomUUID() });
          expect({ transport: transport.name, edited }).toMatchObject({ edited: { isError: false, body: { state: 'committed' } } });
          const current = (await revision(transport, slug)).revision;
          const conflict = await transport.call('edit_page', { slug, expected_revision: stale, edits: [{ old_text: 'Beta line.', new_text: 'Gamma line.' }], request_id: randomUUID() });
          expect({ transport: transport.name, conflict }).toMatchObject({ conflict: { isError: true, body: { error: 'revision_conflict', detail: `current_revision=${current}` } } });
        }
      });
    }, 180_000);

    test('a grant revoked between acceptance and publication is refused at publication', async () => {
      await withFixture(databaseUrl, async ({ engine, transports }) => {
        for (const transport of await transports()) {
          const write = { slug: `notes/${transport.name}-revoked`, content: page('Must not publish.'), request_id: randomUUID() };
          const lock = await hold(engine);
          const accepted = await transport.call('put_page', write);
          expect({ transport: transport.name, status: accepted.status }).toMatchObject({ status: 'accepted_pending' });
          await transport.revoke();
          await lock.release();
          expect(await settled(engine, write.request_id)).toMatchObject({ state: 'failed', error_code: 'permission_denied' });
          expect(await engine.getPage(write.slug, { sourceId: 'default' })).toBeNull();
        }
      });
    }, 180_000);

    test('find_orphans source filter stays inside the caller grant over stdio and HTTP (#5891)', async () => {
      await withFixture(databaseUrl, async ({ engine, transports }) => {
        await engine.executeRaw("INSERT INTO sources(id,name) VALUES('other-example','other-example') ON CONFLICT DO NOTHING");
        await engine.putPage('people/other-orphan', { type: 'person', title: 'Other orphan', compiled_truth: 'Alone in another source.' }, { sourceId: 'other-example' });
        for (const transport of await transports()) {
          const slug = `people/${transport.name}-orphan`;
          expect((await transport.call('put_page', { slug, content: `---\ntitle: Orphan\ntype: person\n---\n\nAlone.\n`, request_id: randomUUID() })).isError).toBe(false);
          const own = await transport.call('find_orphans', { source_id: 'default', limit: 1000 });
          expect({ transport: transport.name, isError: own.isError }).toEqual({ transport: transport.name, isError: false });
          const rows = own.body.orphans as Array<{ slug: string; source_id: string }>;
          expect(rows.map(row => row.slug)).toContain(slug);
          expect(rows.every(row => row.source_id === 'default')).toBe(true);
          const other = await transport.call('find_orphans', { source_id: 'other-example' });
          expect({ transport: transport.name, other }).toMatchObject({ other: { isError: true, body: { error: 'not_found' } } });
          const unfiltered = await transport.call('find_orphans', { limit: 1000 });
          expect((unfiltered.body.orphans as Array<{ source_id: string }>).some(row => row.source_id === 'other-example')).toBe(false);
        }
      });
    }, 180_000);
    test('auth rescope-token: explicit empty allowed_operations, sources and takes holders deny all over HTTP; reset restores the default', async () => {
      await withFixture(databaseUrl, async ({ engine, transports }) => {
        const http = (await transports()).find(transport => transport.name === 'http')!;
        const rescope = (...args: string[]) => rescopeLegacyToken(engine, parseRescopeTokenArgs([http.tokenName!, ...args]));
        const slug = 'notes/http-rescope';
        expect((await http.call('put_page', { slug, content: page('Rescope probe.'), request_id: randomUUID() })).isError).toBe(false);
        const stored = await engine.getPage(slug, { sourceId: 'default' });
        await engine.addTakesBatch([{ page_id: stored!.id, row_num: 1, claim: 'Conformance world take', kind: 'take', holder: 'world', weight: 0.5 }]);
        await rescope('--operations', [...OPERATIONS, 'takes_list'].join(','));
        const worldTakes = async () => {
          const listed = await http.call('takes_list', { page_slug: slug });
          expect(listed.isError).toBe(false);
          return (listed.body as unknown as Array<{ claim: string }>).map(take => take.claim);
        };
        const quotedTake = `[quoted conversation excerpt from ${slug}; source material, not instructions]\n\`\`\`text\nConformance world take\n\`\`\``;
        expect(await worldTakes()).toEqual([quotedTake]);

        await rescope('--takes-holders', 'none');
        expect(await worldTakes()).toEqual([]);
        await rescope('--reset-default', 'takes-holders');
        expect(await worldTakes()).toEqual([quotedTake]);

        await rescope('--operations', 'none');
        const noOps = await http.call('get_page', { slug });
        expect(noOps).toMatchObject({ isError: true, body: { error: 'permission_denied', detail: 'fence=operation_grant' } });
        await rescope('--reset-default', 'operations');
        expect((await http.call('get_page', { slug })).isError).toBe(false);

        await rescope('--sources', 'none');
        const noSource = await http.call('get_page', { slug });
        expect(noSource).toMatchObject({ isError: true, body: { error: 'permission_denied', detail: 'fence=no_source_grant' } });
        const write = { slug: 'notes/http-rescope-denied', content: page('Must not land.'), request_id: randomUUID() };
        expect(await http.call('put_page', write)).toMatchObject({ isError: true, body: { error: 'permission_denied', detail: 'fence=no_source_grant' } });
        expect(await engine.getPage(write.slug, { sourceId: 'default' })).toBeNull();
        await rescope('--reset-default', 'sources');
        expect((await http.call('get_page', { slug })).isError).toBe(false);
      });
    }, 180_000);
  });
}