Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* 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`;
}