Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
3.1 KB
Raw Blame
/**
 * Agent operator protocol page (contract v1, Lane G1) drift checks.
 *
 * - The transcripts in docs/protocol/AGENT_OPERATOR_v1.md are generated from
 *   the frozen goldens in test/fixtures/agent-contract/v1/ and the quick
 *   contract is copied verbatim into AGENTS.md; both must match a fresh
 *   render (regenerate: bun run build:agent-protocol).
 * - skills/conventions/agent-operator-protocol.md is the whole page bundled
 *   with the skills (#6198) and must match a fresh render too.
 * - The quick contract stays at most 10 lines.
 * - The entry points agents read first link the protocol page.
 */
import { describe, expect, test } from 'bun:test';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import {
  AGENTS_PATH, BUNDLED_PROTOCOL_PATH, PROTOCOL_PATH, TRANSCRIPTS, quickContract, renderAgentProtocolDocs,
} from '../scripts/build-agent-protocol.ts';

const ROOT = join(import.meta.dir, '..');
const REGEN = 'Regenerate: bun run build:agent-protocol';

describe('AGENT_OPERATOR_v1.md generated regions', () => {
  const protocol = readFileSync(PROTOCOL_PATH, 'utf8');
  const agents = readFileSync(AGENTS_PATH, 'utf8');

  test('transcripts match the goldens (next recomputed, never stored)', () => {
    expect(renderAgentProtocolDocs(protocol, agents).protocol, REGEN).toBe(protocol);
  });

  test('AGENTS.md carries the quick contract verbatim', () => {
    expect(renderAgentProtocolDocs(protocol, agents).agents, REGEN).toBe(agents);
    expect(agents).toContain(quickContract(protocol));
  });

  test('the skills tree carries a fresh bundled copy of the page', () => {
    expect(renderAgentProtocolDocs(protocol, agents).bundled, REGEN).toBe(readFileSync(BUNDLED_PROTOCOL_PATH, 'utf8'));
  });

  test('the quick contract is at most 10 lines', () => {
    expect(quickContract(protocol).trimEnd().split('\n').length).toBeLessThanOrEqual(10);
  });

  test('transcripts cover run, ask_user and tell_user_to_run', () => {
    expect([...new Set(TRANSCRIPTS.map(t => t.expectNext))].sort()).toEqual(['ask_user', 'run', 'tell_user_to_run']);
  });

  test('Lane H journey transcripts come from recorded journey goldens', () => {
    expect(TRANSCRIPTS.filter(t => t.golden.startsWith('journey/')).length).toBeGreaterThanOrEqual(3);
  });

  test('generated transcripts never carry an unresolved placeholder', () => {
    const region = protocol.slice(protocol.indexOf('<!-- BEGIN GENERATED agent-protocol:transcripts'), protocol.indexOf('<!-- END GENERATED agent-protocol:transcripts'));
    expect(region.length).toBeGreaterThan(1000);
    expect(region).not.toContain('{{next}}');
    expect(region).not.toContain('{{DOCS_BASE}}');
  });
});

describe('entry points link the protocol page', () => {
  const entryPoints = [
    'AGENTS.md',
    'INSTALL_FOR_AGENTS.md',
    'llms.txt',
    'docs/guides/troubleshooting.md',
    'docs/GBRAIN_VERIFY.md',
    'docs/mcp/README.md',
    'docs/guides/error-codes.md',
    'docs/guides/exit-codes.md',
  ];
  for (const rel of entryPoints) {
    test(rel, () => {
      expect(readFileSync(join(ROOT, rel), 'utf8')).toContain('AGENT_OPERATOR_v1.md');
    });
  }
});