Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.4 KB
Raw Blame
/**
 * B5 — `gbrain protocol` document shape (buildProtocolDocument, src/commands/protocol.ts).
 *
 * The protocol document is the machine-readable face of the frozen
 * MEMORY_VERBS v1 contract (docs/protocol/MEMORY_VERBS_v1.md). The builder
 * composes it as:
 *
 *   VERB_NAMES.map(n => operationsByName[n]).filter(Boolean) → buildToolDefs → doc.verbs
 *
 * That `.filter(Boolean)` means a verb whose operation-catalog lookup fails
 * (e.g. a rename in operations.ts / verbs.ts that misses VERB_NAMES) would
 * SILENTLY SHRINK the published protocol instead of failing. Test 1 pins the
 * strongest available form — ordered deep-equality of Object.keys(doc.verbs)
 * against VERB_NAMES — so any dropped (or reordered, or extra) verb fails
 * loudly here.
 *
 * Pure unit test: imports the builder and asserts on the in-memory document.
 * No env mutation, no mock.module, no serial requirement.
 */

import { describe, expect, test } from 'bun:test';
import { buildProtocolDocument } from '../src/commands/protocol.ts';
import { MEMORY_VERBS_VERSION, VERB_NAMES } from '../src/core/verbs.ts';
import { validateAgainstSchema } from '../src/core/verbs/conformance.ts';

interface VerbEntry {
  description: string;
  input_schema: {
    type: string;
    properties: Record<string, unknown>;
    required: string[];
  };
  annotations?: Record<string, unknown>;
  response_schema: Record<string, unknown> | undefined;
}

const doc = buildProtocolDocument();
const verbs = doc.verbs as Record<string, VerbEntry>;

describe('buildProtocolDocument — MEMORY_VERBS v1 document shape', () => {
  test('doc.verbs keys deep-equal VERB_NAMES in order — a failed tool-def lookup must FAIL the doc, not shrink it', () => {
    // Ordered deep-equality is deliberate: the builder maps VERB_NAMES in
    // order and .filter(Boolean) can only DROP entries, so any lookup miss
    // (or a stray extra verb, or reordering) breaks this exact-match.
    expect(Object.keys(verbs)).toEqual([...VERB_NAMES]);
  });

  test('every verb entry has a non-empty input_schema.properties and a defined response_schema', () => {
    for (const name of VERB_NAMES) {
      const entry = verbs[name];
      expect(entry).toBeDefined();

      // Live-emitted input schema (from the Operation defs via buildToolDefs).
      expect(entry.input_schema.type).toBe('object');
      expect(Object.keys(entry.input_schema.properties).length).toBeGreaterThan(0);
      expect(Array.isArray(entry.input_schema.required)).toBe(true);

      // Hand-authored response registry (RESPONSE_SCHEMAS) — an undefined
      // entry here means a verb shipped without a response contract.
      expect(entry.response_schema).toBeDefined();
      const rs = entry.response_schema as Record<string, unknown>;
      expect(rs.type).toBe('object');

      // Every v1 response envelope requires + stamps protocol_version: 1.
      expect(rs.required as string[]).toContain('protocol_version');
      const pv = (rs.properties as Record<string, Record<string, unknown>>).protocol_version;
      expect(pv.const).toBe(1);

      // The doc's descriptions come from the live op defs — never empty.
      expect(typeof entry.description).toBe('string');
      expect(entry.description.length).toBeGreaterThan(0);
    }
  });

  test('protocol_version is the LITERAL frozen value 1', () => {
    // Deliberately NOT compared to MEMORY_VERBS_VERSION — the builder assigns
    // from that constant, so such a comparison would be a tautology. The
    // literal pins the frozen v1 wire value; if anyone bumps the constant,
    // this test is the reviewer-visible tripwire.
    expect(doc.protocol_version).toBe(1);
    // And the single source of truth itself stays frozen at 1 (v0.45.7 grew
    // the verb set 5 → 7 WITHOUT bumping this — additive-forever).
    expect(MEMORY_VERBS_VERSION).toBe(1);
    expect(doc.protocol).toBe('MEMORY_VERBS');
    expect(typeof doc.versioning_policy).toBe('string');
  });

  test('error_schema carries the documented uniform error contract', () => {
    const errorSchema = doc.error_schema as Record<string, unknown>;
    expect(errorSchema).toBeDefined();
    expect(errorSchema.type).toBe('object');

    // Envelope: { error, message } required; suggestion/detail/protocol_version optional.
    expect(errorSchema.required).toEqual(['error', 'message']);

    const props = errorSchema.properties as Record<string, Record<string, unknown>>;
    const codes = props.error.enum as string[];

    // The seven codes documented in docs/protocol/MEMORY_VERBS_v1.md
    // ("Error contract (uniform across all verbs)"). Containment, not
    // equality: the contract is additive-forever, so NEW codes may appear,
    // but removing a documented code is a breaking change and must fail.
    const documentedCodes = [
      'invalid_params',
      'provenance_required',
      'not_found',
      'scope_denied',
      'unavailable',
      'budget_unsatisfiable', // RESERVED — schema-listed, never returned in v1
      'internal',
    ];
    for (const code of documentedCodes) {
      expect(codes).toContain(code);
    }

    // "Every verb error carries a POPULATED suggestion" — the schema must
    // document the field (and detail, the freeform-specifics channel).
    expect(props.suggestion).toBeDefined();
    expect(props.suggestion.type).toBe('string');
    expect(props.detail).toBeDefined();

    // Error envelopes ride the same frozen version stamp.
    expect(props.protocol_version.const).toBe(1);
  });

  test('recall advertises optional budget accounting without changing its required fields or version', () => {
    const schema = verbs.recall.response_schema!;
    expect(schema.required).toEqual(['facts', 'total', 'protocol_version']);
    expect(validateAgainstSchema({ facts: [], total: 0, protocol_version: 1 }, schema)).toEqual([]);
    const properties = schema.properties as Record<string, any>;
    expect(properties.protocol_version.const).toBe(1);
    expect(properties.budget_packing).toMatchObject({
      type: 'object', required: ['policy', 'applied', 'reason', 'facts', 'results'],
      properties: {
        policy: { type: 'string', enum: ['facts_first', 'query_first'] },
        applied: { type: 'boolean' },
        reason: { type: 'string', enum: ['no_query', 'no_positive_finite_budget', 'budget_below_one', 'no_candidates', 'first_items_exceed_budget', 'packed'] },
      },
    });
    for (const arm of ['facts', 'results']) {
      expect(properties.budget_packing.properties[arm]).toMatchObject({
        type: 'object', required: ['candidates', 'kept', 'dropped', 'used'],
        properties: {
          candidates: { type: 'integer' }, kept: { type: 'integer' },
          dropped: { type: 'integer' }, used: { type: 'integer' },
        },
      });
    }
  });

  test.each([
    { policy: 'unknown' }, { applied: 'yes' }, { reason: 'unknown' },
    { facts: { candidates: 1, kept: 1, dropped: 0, used: 0.5 } },
    { results: { kept: 0, dropped: 0, used: 0 } },
  ])('recall schema rejects malformed opted-in accounting: %j', invalid => {
    const arm = { candidates: 0, kept: 0, dropped: 0, used: 0 };
    const valid = { facts: [], total: 0, protocol_version: 1,
      budget_packing: { policy: 'query_first', applied: true, reason: 'no_candidates', facts: arm, results: arm } };
    expect(validateAgainstSchema(valid, verbs.recall.response_schema!)).toEqual([]);
    expect(validateAgainstSchema({ ...valid, budget_packing: { ...valid.budget_packing, ...invalid } },
      verbs.recall.response_schema!).length).toBeGreaterThan(0);
  });
});