Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.4 KB
Raw Blame
#!/usr/bin/env bun
/**
 * Generated regions of the agent operator protocol (contract v1, Lane G1).
 *
 *   bun run build:agent-protocol          rewrite the regions
 *   bun run build:agent-protocol --check  exit 1 when a committed region is stale
 *
 * 1. docs/protocol/AGENT_OPERATOR_v1.md "Transcripts": rendered from the
 *    frozen wire goldens in test/fixtures/agent-contract/v1/. Goldens never
 *    store `next`; it is recomputed here with deriveNext (the same decision
 *    table gbrain renders with) and checked against each transcript's
 *    expected value, so a contract change cannot silently rewrite the story.
 * 2. AGENTS.md "Agent operator protocol" quick contract: copied verbatim from
 *    the protocol page's quick-contract region.
 * 3. skills/conventions/agent-operator-protocol.md: the whole protocol page,
 *    bundled with the skills (#6198, D13) so skill links to it resolve in
 *    every copy (skillpack scaffold, harness dirs, plugin trees). Its own
 *    relative links become absolute repo URLs (scripts/portable-skill-links.ts,
 *    which honors the LLMS_REPO_BASE fork override).
 *
 * Adding a transcript (Lane H journey goldens): append a TRANSCRIPTS entry
 * naming its golden file, transport, expected `next` and narration. Journey
 * goldens (`journey/*.json`) are recorded by test/agent-journey.serial.test.ts
 * from real runs; their placeholders render as fixed example values.
 * Drift test: test/agent-protocol-doc.test.ts.
 */
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { deriveNext, type Action, type RenderContext, type Transport } from '../src/core/agent-output.ts';
import { renderConsentRefusal, type ConfirmationPayload } from '../src/core/consent.ts';
import { BUNDLED_PROTOCOL, renderBundledProtocol, repoBlobBase } from './portable-skill-links.ts';

const ROOT = join(import.meta.dir, '..');
const GOLDENS = join(ROOT, 'test', 'fixtures', 'agent-contract', 'v1');
export const PROTOCOL_PATH = join(ROOT, 'docs', 'protocol', 'AGENT_OPERATOR_v1.md');
export const AGENTS_PATH = join(ROOT, 'AGENTS.md');
export const BUNDLED_PROTOCOL_PATH = join(ROOT, BUNDLED_PROTOCOL);
/** Transcripts show the source-checkout base; the wire pins the installed version. */
const DOCS_BASE = 'https://github.com/garrytan/gbrain/blob/master';

const TRANSCRIPT_REGION = 'agent-protocol:transcripts';
const QUICK_BEGIN = /<!-- BEGIN quick-contract[^>]*-->\n/;
const QUICK_END = '<!-- END quick-contract -->';

type Json = Record<string, unknown>;

interface Transcript {
  title: string;
  golden: string;
  transport: Transport;
  expectNext: string;
  setting: string;
  call: string;
  /** Prose for what the agent does, given the rendered value. */
  after: (doc: Json) => string;
  /** The value checked against expectNext when it is not a fix's `next` (an `ask` notice means ask_user). */
  nextOf?: (doc: Json) => string;
}

function contextFor(transport: Transport): RenderContext {
  // A fix that kept its `mcp` was callable when rendered; nothing is preapproved in the goldens.
  return { transport, isCallable: () => true, preapproved: () => false };
}

/** Insert `next` right after `actor`, the position renderAction emits it in. */
function withNext(fix: Json, ctx: RenderContext): Json {
  const next = deriveNext(fix as unknown as Action, ctx);
  const out: Json = {};
  for (const [k, v] of Object.entries(fix)) {
    out[k] = k === 'then' && v && typeof v === 'object' ? withNext(v as Json, ctx) : typeof v === 'string' ? hydrate(v, ctx) : v;
    if (k === 'actor') out.next = next;
  }
  return out;
}

/** Recompute every `fix.next` in a golden value, including JSON carried in text blocks. */
function hydrate(value: unknown, ctx: RenderContext, noticeNexts: string[] = []): unknown {
  if (Array.isArray(value)) return value.map(v => hydrate(v, ctx, noticeNexts));
  if (value && typeof value === 'object') {
    const out: Json = {};
    for (const [k, v] of Object.entries(value as Json)) {
      out[k] = k === 'fix' && v && typeof v === 'object' ? withNext(v as Json, ctx) : hydrate(v, ctx, noticeNexts);
    }
    return out;
  }
  if (typeof value !== 'string') return value;
  const text = value.split('{{DOCS_BASE}}').join(DOCS_BASE).replace(/\{\{([A-Z_]+)\}\}/g, (m, name: string) => JOURNEY_VALUES[name] ?? m);
  if (text.startsWith('{')) {
    try { return JSON.stringify(hydrate(JSON.parse(text), ctx), null, 2); } catch { /* prose */ }
  }
  return text.includes('next: {{next}}') ? text.replace('next: {{next}}', `next: ${noticeNexts.shift() ?? 'report'}`) : text;
}

/**
 * Journey goldens (test/fixtures/agent-contract/v1/journey/, Lane H) are real
 * runs with machine values replaced by placeholders; transcripts show fixed
 * example values instead.
 */
const JOURNEY_VALUES: Record<string, string> = {
  HOME: '/home/alice-example', PID: '48213', UUID: '7f3c2a10-5b6e-4d1a-9c8b-2e4f6a8d0c11', TIME: '2026-10-03T16:20:00.000Z',
  PLAN_HASH: 'ph_5f1c0e9a2b7d4c3e8a6b0d1f', DURATION_S: '0.4', ROOT_IDENTITY: '(device and inode of the content root)', DOCTOR_RUN_ID: '7f3c2a10-5b6e-4d1a-9c8b-2e4f6a8d0c11',
};

function loadGolden(name: string, transport: Transport): Json {
  const raw = JSON.parse(readFileSync(join(GOLDENS, name), 'utf8')) as Json;
  const ctx = contextFor(transport);
  const meta = (raw._meta as { gbrain_notices?: { fix?: Json }[] } | undefined)?.gbrain_notices ?? [];
  const noticeNexts = meta.map(n => (n.fix ? deriveNext(n.fix as unknown as Action, ctx) : 'report'));
  return hydrate(raw, ctx, noticeNexts) as Json;
}

/** The envelope inside an MCP error result, or the document itself. */
function body(doc: Json): Json {
  const content = doc.content as { text: string }[] | undefined;
  return Array.isArray(content) ? JSON.parse(content[0].text) as Json : doc;
}

function step(fix: Json | undefined): string {
  if (!fix) return '';
  const mcp = fix.mcp as { tool: string; arguments: unknown } | undefined;
  return mcp ? `${mcp.tool} ${JSON.stringify(mcp.arguments)}` : String(fix.command ?? '');
}

const fence = (lang: string, text: string) => `\`\`\`${lang}\n${text.replace(/\n$/, '')}\n\`\`\``;

export const TRANSCRIPTS: readonly Transcript[] = [
  {
    title: 'A caller mistake over MCP: `run`',
    golden: 'error-with-fix.json',
    transport: 'stdio',
    expectNext: 'run',
    setting: 'A harness on stdio MCP (surface `full`) lists pages with a sort key that does not exist.',
    call: 'list_pages {"sort":"bogus"}',
    after: (doc) => {
      const env = body(doc);
      const fix = env.fix as Json;
      const verify = step(fix.verify as Json | undefined);
      return `The result is one content block. The agent reads \`code: ${env.code}\` and \`fix.next: ${fix.next}\`, `
        + `so it calls \`${step(fix)}\` itself, then confirms with the read-only \`${verify}\`. `
        + 'Nothing needs the user.';
    },
  },
  {
    title: 'Paid work without approval on the CLI: `ask_user`, exit 3',
    golden: 'confirmation-required.json',
    transport: 'cli',
    expectNext: 'ask_user',
    setting: 'An agent runs remediation from a non-interactive shell without `--yes` or `--max-usd`.',
    call: 'gbrain doctor --remediate --json',
    after: (doc) => {
      const fix = doc.fix as Json;
      const preview = (doc.preview as Json | null)?.command;
      return `Nothing ran and the command exited 3. The agent reads \`fix.next: ${fix.next}\`, relays \`user_message\` `
        + `("${doc.user_message}") and stops. It may offer the read-only preview \`${preview}\`. `
        + `Only after the user agrees does it run \`${fix.command}\`. Passing \`--yes\` on its own would be a consent violation `
        + 'even though gbrain cannot tell the difference.';
    },
  },
  {
    title: 'An empty recall with a notice: `tell_user_to_run`',
    golden: 'bare-array-result.json',
    transport: 'stdio',
    expectNext: 'tell_user_to_run',
    setting: 'A harness on stdio MCP searches a keyless brain and nothing matches.',
    call: 'search {"query":"…"}',
    after: (doc) => {
      const n = ((doc._meta as Json).gbrain_notices as Json[])[0];
      const fix = n.fix as Json;
      return `\`content[0]\` is still the bare array \`[]\`; the second block is the notice. The agent does not tell the user `
        + `"you have no notes on that". It relays \`user_message\` ("${n.user_message}"). \`fix.next\` is \`${fix.next}\` `
        + `because the fix is the user's to run (\`${fix.command}\`) in their terminal, so the agent offers it rather than running it.`;
    },
  },
  {
    title: 'First run on a keyless brain: one decision bundle, `ask_user` (journey)',
    golden: 'journey/init-first-run.json',
    transport: 'cli',
    expectNext: 'ask_user',
    setting: 'An agent installs gbrain for a user with no provider keys, from a non-interactive shell (H1a journey, recorded from the real CLI).',
    call: 'gbrain init --pglite --no-embedding --json',
    nextOf: (doc) => (((doc.notices as Json[]).find(n => n.code === 'first_run_decisions')?.kind) === 'ask' ? 'ask_user' : ''),
    after: (doc) => {
      const bundle = (doc.notices as Json[]).find(n => n.code === 'first_run_decisions') as Json;
      const ids = (bundle.decisions as Json[]).map(d => `\`${d.id}\` (default \`${d.default}\`)`).join(', ');
      return `stdout is one document; the brain is ready and nothing blocks using it. The agent first does the \`harness_wiring\` step: connecting gbrain to itself is part of the install, not a setting. `
        + `It then reports the install and relays the \`first_run_decisions\` \`user_message\` ("${bundle.user_message}") once in that reply, without waiting for an answer. `
        + `The settings in effect are ${ids}; each option carries the exact argv to apply it when the user picks one.`;
    },
  },
  {
    title: 'A caller mistake over stdio MCP, recorded: `run` (journey)',
    golden: 'journey/caller-mistake.json',
    transport: 'stdio',
    expectNext: 'run',
    setting: 'A harness on `gbrain serve --surface verbs` passes a string where `recall` expects a number (H1a journey, recorded from a real stdio session).',
    call: 'recall {"query":"quokka-journey-marker","limit":"abc"}',
    after: (doc) => {
      const env = body(doc);
      const fix = env.fix as Json;
      return `One content block, \`code: ${env.code}\`, \`class: ${env.class}\`. Nothing ran, so \`fix.next: ${fix.next}\`: the agent calls `
        + `\`${step(fix)}\` exactly as given (its other arguments kept, the bad one corrected) and gets the recall it wanted.`;
    },
  },
  {
    title: 'A second session on a locked brain: status-only serve, `tell_user_to_run` (journey)',
    golden: 'journey/status-only-lock-held.json',
    transport: 'stdio',
    expectNext: 'tell_user_to_run',
    setting: 'A second agent session starts `gbrain serve` while another session\'s serve owns the PGLite brain. The handshake still completes, with one tool, `gbrain_status` (H1a journey, recorded).',
    call: 'gbrain_status {}',
    after: (doc) => {
      const env = body(doc);
      const options = ((env.decisions as Json[])[0].options as Json[]).map(o => `\`${o.id}\``).join(' or ');
      return `\`reason: ${env.reason}\` names the owner (\`lock_owner.pid\`). \`fix.next\` is \`${(env.fix as Json).next}\` because only the user can close `
        + `the other session: the agent relays \`user_message\` and offers ${options}. Calling \`gbrain_status\` again after the owner exits `
        + 'opens the brain in place and the full tool list arrives through `tools/list_changed`.';
    },
  },
];

function renderTranscript(t: Transcript, i: number): string {
  const doc = loadGolden(t.golden, t.transport);
  const env = body(doc);
  const fixNext = t.nextOf ? t.nextOf(doc) : String(((env.fix as Json | undefined)?.next)
    ?? ((((doc._meta as Json | undefined)?.gbrain_notices as Json[] | undefined)?.[0]?.fix as Json | undefined)?.next) ?? '');
  if (fixNext !== t.expectNext) {
    throw new Error(`transcript "${t.golden}": next is ${fixNext}, expected ${t.expectNext}. Update the narration with the contract change.`);
  }
  const parts = [
    `### ${i + 1}. ${t.title}`,
    '',
    t.setting,
    '',
    fence(t.transport === 'cli' ? 'bash' : 'text', t.call),
    '',
  ];
  if (t.transport === 'cli') {
    parts.push('stdout (`--json`):', '', fence('json', JSON.stringify(doc, null, 2)), '');
    if (doc.code === 'confirmation_required') {
      const human = renderConsentRefusal(doc as unknown as ConfirmationPayload, { json: false });
      parts.push('Without `--json`, the same refusal prints as an `[AGENT]` block:', '', fence('text', human.stdout ?? ''), '');
    }
  } else if (doc.isError || !Array.isArray(doc.content)) {
    parts.push('gbrain returns (`isError: true`, the envelope shown parsed):', '', fence('json', JSON.stringify(env, null, 2)), '');
  } else {
    const content = doc.content as { text: string }[];
    parts.push('gbrain returns these content blocks:', '');
    content.forEach((c, j) => parts.push(`\`content[${j}]\`:`, '', fence(j === 0 ? 'json' : 'text', c.text), ''));
  }
  parts.push(t.after(doc));
  return parts.join('\n');
}

function replaceRegion(text: string, region: string, inner: string): string {
  // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp -- `region` is a constant region name defined in this build script, never input
  const begin = new RegExp(`(<!-- BEGIN GENERATED ${region}[^>]*-->\\n)[\\s\\S]*?(<!-- END GENERATED ${region} -->)`);
  if (!begin.test(text)) throw new Error(`region ${region} not found`);
  return text.replace(begin, (_m, a: string, b: string) => `${a}${inner}${b}`);
}

export function quickContract(protocol: string): string {
  const m = QUICK_BEGIN.exec(protocol);
  const end = protocol.indexOf(QUICK_END);
  if (!m || end < 0) throw new Error('quick-contract region not found in AGENT_OPERATOR_v1.md');
  return protocol.slice(m.index + m[0].length, end);
}

/** Fresh text for every generated file, from the committed protocol page and goldens. */
export function renderAgentProtocolDocs(protocol: string, agents: string): { protocol: string; agents: string; bundled: string } {
  const transcripts = `${TRANSCRIPTS.map(renderTranscript).join('\n\n')}\n`;
  const freshProtocol = replaceRegion(protocol, TRANSCRIPT_REGION, transcripts);
  return {
    protocol: freshProtocol,
    agents: replaceRegion(agents, 'agent-protocol:quick-contract', quickContract(protocol)),
    bundled: renderBundledProtocol(freshProtocol, repoBlobBase()),
  };
}

if (import.meta.main) {
  const current = {
    protocol: readFileSync(PROTOCOL_PATH, 'utf8'),
    agents: readFileSync(AGENTS_PATH, 'utf8'),
    bundled: existsSync(BUNDLED_PROTOCOL_PATH) ? readFileSync(BUNDLED_PROTOCOL_PATH, 'utf8') : '',
  };
  const fresh = renderAgentProtocolDocs(current.protocol, current.agents);
  if (process.argv.includes('--check')) {
    const stale = [
      ...(fresh.protocol !== current.protocol ? ['docs/protocol/AGENT_OPERATOR_v1.md'] : []),
      ...(fresh.agents !== current.agents ? ['AGENTS.md'] : []),
      ...(fresh.bundled !== current.bundled ? [BUNDLED_PROTOCOL] : []),
    ];
    if (stale.length) {
      console.error(`${stale.join(', ')}: generated agent-protocol regions are stale. Run: bun run build:agent-protocol`);
      process.exit(1);
    }
    console.log('agent protocol docs: up to date');
  } else {
    writeFileSync(PROTOCOL_PATH, fresh.protocol);
    writeFileSync(AGENTS_PATH, fresh.agents);
    writeFileSync(BUNDLED_PROTOCOL_PATH, fresh.bundled);
    console.log(`wrote docs/protocol/AGENT_OPERATOR_v1.md and AGENTS.md generated regions, and ${BUNDLED_PROTOCOL}`);
  }
}