Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.3 KB
Raw Blame
/**
 * Renders the error code registry (agent contract v1, A2) for people and
 * agents: `docs/guides/error-codes.md` (generated by `bun run
 * build:error-codes`, drift-checked by test/error-codes-doc.test.ts) and
 * `gbrain errors <code>` / `gbrain errors --changed`, offline, from the same
 * rows so the two can never disagree.
 */
import { CODES, codeEntry, exitCodeForCode, codeRetryable, type CodeEntry, type RegistryCode } from './error-catalogue.ts';
import { docsUrl, shellQuote, type ErrorClass } from './agent-output.ts';

export interface ErrorCodeRow {
  code: string;
  class: ErrorClass;
  meaning: string;
  why: string;
  next_step: string;
  effects: string[];
  actor: string;
  verify: string;
  exit_code: number;
  retryable: boolean;
  docs: string;
  legacy_error?: string;
  renamed_from?: string;
  reasons?: readonly string[];
  /** Reasons whose class and exit replace the code's. */
  reason_overrides?: Array<{ reason: string; class: ErrorClass; exit_code: number }>;
}

const CLASS_WHY: Record<ErrorClass, string> = {
  caller: 'The request itself was wrong or no longer matches the brain; nothing was changed.',
  consent: 'The step needs the user\'s decision before it runs.',
  retryable: 'A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.',
  unavailable: 'A capability this request needs is not configured or not reachable on this brain.',
  server: 'The server failed; this is not a caller mistake.',
  host_only: 'Only the operator of the brain host can change what blocks this.',
};

const CLASS_ACTOR: Record<ErrorClass, string> = {
  caller: 'agent', consent: 'user', retryable: 'agent', unavailable: 'agent', server: 'host_admin', host_only: 'host_admin',
};

export function errorCodeRow(code: string): ErrorCodeRow | undefined {
  const e = codeEntry(code);
  if (!e) return undefined;
  const fixCmd = e.fix?.argv ? shellQuote(e.fix.argv) : undefined;
  const verify = e.fix?.verify?.argv ? shellQuote(e.fix.verify.argv)
    : e.class === 'server' || e.class === 'unavailable' || e.class === 'host_only' ? 'gbrain doctor --json' : 'repeat the read that failed';
  return {
    code,
    class: e.class,
    meaning: e.summary,
    why: e.why ?? CLASS_WHY[e.class],
    next_step: fixCmd ? `${e.suggestion} Run: ${fixCmd}` : e.suggestion,
    effects: [...(e.effects ?? e.fix?.consent ?? [])],
    actor: e.actor ?? e.fix?.actor ?? CLASS_ACTOR[e.class],
    verify,
    exit_code: exitCodeForCode(code),
    retryable: codeRetryable(code),
    docs: e.docs,
    ...(e.legacy_error ? { legacy_error: e.legacy_error } : {}),
    ...(e.renamed_from ? { renamed_from: e.renamed_from } : {}),
    ...(e.reasons?.length ? { reasons: e.reasons } : {}),
    ...(e.reason_overrides ? { reason_overrides: Object.entries(e.reason_overrides).map(([reason, o]) => ({ reason, class: o.class, exit_code: o.exit ?? 1 })) } : {}),
  };
}

const overrideLine = (o: { reason: string; class: ErrorClass; exit_code: number }) => `reason ${o.reason}: ${o.class}, exit ${o.exit_code}${o.class === 'retryable' ? ', retryable' : ', not retryable'}`;

/** Codes whose wire `error` value stays frozen under v1 while `code` carries the canonical value. */
export function changedCodeRows(): ErrorCodeRow[] {
  return (Object.keys(CODES) as RegistryCode[])
    .filter(c => (CODES[c] as CodeEntry).legacy_error !== undefined || (CODES[c] as CodeEntry).renamed_from !== undefined)
    .map(c => errorCodeRow(c)!);
}

const cell = (s: string) => s.replace(/\|/g, '\\|').replace(/\n/g, ' ');

export function renderErrorCodeText(r: ErrorCodeRow): string {
  return [
    `${r.code} (${r.class}, exit ${r.exit_code}${r.retryable ? ', retryable' : ''})`,
    `  meaning:   ${r.meaning}`,
    `  why:       ${r.why}`,
    `  next step: ${r.next_step}`,
    `  who acts:  ${r.actor}${r.effects.length ? ` · consent: ${r.effects.join(', ')}` : ''}`,
    `  verify:    ${r.verify}`,
    ...(r.legacy_error ? [`  legacy:    some surfaces keep error: "${r.legacy_error}" with code: "${r.code}"`] : []),
    ...(r.reasons?.length ? [`  reasons:   ${r.reasons.join(', ')}`] : []),
    ...(r.reason_overrides ?? []).map(o => `  override:  ${overrideLine(o)}`),
    `  docs:      ${docsUrl(r.docs)}`,
  ].join('\n');
}

/** The whole generated guide. Deterministic: sorted by code. */
export function renderErrorCodesMarkdown(): string {
  const rows = (Object.keys(CODES) as string[]).sort().map(c => errorCodeRow(c)!);
  const out: string[] = [
    '<!-- GENERATED by `bun run build:error-codes` from src/core/error-registry.ts. Do not edit by hand. -->',
    '# Error codes',
    '',
    'Every gbrain error carries a stable `code`. Read `code` first and fall back to `error`',
    '(older servers send only `error`); then follow `fix.next` as described in',
    '[AGENT_OPERATOR_v1](../protocol/AGENT_OPERATOR_v1.md). Exit codes are in [exit codes](exit-codes.md).',
    'Offline, `gbrain errors <code>` prints the same row and `gbrain errors --changed` the legacy pairs.',
    '',
    '**Say to your agent:** *"gbrain returned an error code I don\'t recognize. Look it up and tell me what to do."*',
    '',
    '## Legacy `error` values',
    '',
    'Under contract v1 an `error` value never changes. Where a surface sends a legacy value in',
    '`error`, it also sends the canonical value in `code`:',
    '',
    '| `error` (frozen) | `code` (canonical) | Meaning |',
    '|---|---|---|',
    ...changedCodeRows().map(r => `| \`${r.legacy_error ?? r.renamed_from}\` | \`${r.code}\` | ${cell(r.meaning)} |`),
    '',
    '## Codes',
    '',
  ];
  for (const r of rows) {
    out.push(`### ${r.code}`, '', `<a id="${r.code}"></a>`, '');
    out.push('| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |');
    out.push('|---|---|---|---|---|---|---|');
    out.push(`| ${cell(r.meaning)} | ${cell(r.why)} | ${cell(r.next_step)} | ${r.actor}${r.effects.length ? ` · ${r.effects.join(', ')}` : ''} | \`${cell(r.verify)}\` | ${r.exit_code} | ${r.retryable ? 'yes' : 'no'} |`);
    if (r.reasons?.length) out.push('', `Reasons: ${r.reasons.map(x => `\`${x}\``).join(', ')}.`);
    for (const o of r.reason_overrides ?? []) out.push('', `Override: ${overrideLine(o).replace(o.reason, `\`${o.reason}\``)}.`);
    if (r.docs !== `docs/guides/error-codes.md#${r.code}`) out.push('', `More: [${r.docs}](../../${r.docs})`);
    out.push('');
  }
  return `${out.join('\n').trimEnd()}\n`;
}