Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.2 KB
Raw Blame
/**
 * Agent operator contract v1 exit table (docs/designs/AGENT_OPERATOR_WAVE.md
 * A3). Exit 3 means confirmation_required and nothing else: every literal
 * `exit(3)`, `setCliExitVerdict(3)`, `exitCode = 3` and exported exit-code
 * constant equal to 3 in src/ must be listed here, so an unlisted one fails.
 */
import { describe, expect, test } from 'bun:test';
import { readFileSync, readdirSync, statSync } from 'node:fs';
import { join, relative } from 'node:path';
import * as exitCodes from '../src/core/exit-codes.ts';
import { exitCodeForCode } from '../src/core/error-catalogue.ts';

const ROOT = join(import.meta.dir, '..');

function srcFiles(dir: string): string[] {
  const out: string[] = [];
  for (const e of readdirSync(dir)) {
    const full = join(dir, e);
    if (statSync(full).isDirectory()) out.push(...srcFiles(full));
    else if (e.endsWith('.ts')) out.push(full);
  }
  return out;
}

/** The only sanctioned exit-3 sites: the constant itself. */
const ALLOWED_EXIT_3: ReadonlySet<string> = new Set([
  'src/core/exit-codes.ts: CONFIRMATION_REQUIRED_EXIT_CODE',
]);

describe('exit code table', () => {
  test('the published values', () => {
    expect(exitCodes.OK_EXIT_CODE).toBe(0);
    expect(exitCodes.FAILED_EXIT_CODE).toBe(1);
    expect(exitCodes.USAGE_EXIT_CODE).toBe(2);
    expect(exitCodes.CONFIRMATION_REQUIRED_EXIT_CODE).toBe(3);
    expect(exitCodes.PENDING_WRITE_EXIT_CODE).toBe(10);
    expect(exitCodes.BUDGET_STOP_EXIT_CODE).toBe(11);
    expect(exitCodes.NO_RESULTS_EXIT_CODE).toBe(12);
    expect(exitCodes.HARNESS_PENDING_VERIFY_EXIT_CODE).toBe(13);
    expect(exitCodes.HARNESS_CLEANUP_PENDING_EXIT_CODE).toBe(14);
    expect(exitCodes.DOCTOR_ALERT_ACT_EXIT_CODE).toBe(17);
    expect(exitCodes.DOCTOR_ALERT_UNKNOWN_EXIT_CODE).toBe(18);
    expect(exitCodes.SERVE_UNHEALTHY_EXIT_CODE).toBe(69);
    expect(exitCodes.MIGRATIONS_RUNNING_EXIT_CODE).toBe(75);
    expect(exitCodes.TIMEOUT_EXIT_CODE).toBe(124);
    expect(exitCodes.INTERRUPTED_EXIT_CODE).toBe(130);
  });

  test('every constant is distinct', () => {
    const values = Object.values(exitCodes).filter(v => typeof v === 'number');
    expect(new Set(values).size).toBe(values.length);
  });

  test('registry codes map onto the table', () => {
    expect(exitCodeForCode('confirmation_required')).toBe(3);
    expect(exitCodeForCode('invalid_params')).toBe(2);
    expect(exitCodeForCode('unknown_flag')).toBe(2);
    expect(exitCodeForCode('write_pending')).toBe(10);
    expect(exitCodeForCode('pending_verify')).toBe(13);
    expect(exitCodeForCode('bootstrap_cleanup_pending')).toBe(14);
    expect(exitCodeForCode('doctor_alert_act')).toBe(17);
    expect(exitCodeForCode('doctor_alert_unknown')).toBe(18);
    expect(exitCodeForCode('serve_unhealthy_exit')).toBe(69);
    expect(exitCodeForCode('timeout')).toBe(124);
    expect(exitCodeForCode('interrupted')).toBe(130);
    expect(exitCodeForCode('internal_error')).toBe(1);
    expect(exitCodeForCode('approval_required')).toBe(1);
  });

  test('no exit 3 in src/ outside confirmation_required', () => {
    const offenders: string[] = [];
    const patterns: RegExp[] = [
      /\bexit\(\s*3\s*\)/,
      /setCliExitVerdict\(\s*3\s*\)/,
      /\bexitCode\s*=\s*3\b/,
      /flushThenExit\(\s*3\s*[,)]/,
    ];
    for (const file of srcFiles(join(ROOT, 'src'))) {
      const rel = relative(ROOT, file);
      const lines = readFileSync(file, 'utf8').split('\n');
      lines.forEach((line, i) => {
        if (patterns.some(p => p.test(line))) offenders.push(`${rel}:${i + 1}: ${line.trim()}`);
        const constant = /export const ([A-Z0-9_]*EXIT[A-Z0-9_]*)\s*=\s*3\s*;/.exec(line);
        if (constant && !ALLOWED_EXIT_3.has(`${rel}: ${constant[1]}`)) offenders.push(`${rel}:${i + 1}: ${constant[1]} = 3`);
      });
    }
    expect(offenders).toEqual([]);
  });

  test('the exit-codes guide documents every value; the CHANGELOG carries the contract v1 exit changes', () => {
    const doc = readFileSync(join(ROOT, 'docs/guides/exit-codes.md'), 'utf8');
    for (const v of [0, 1, 2, 3, 10, 11, 14, 69, 75, 124, 130]) expect(doc).toContain(`| ${v} |`);
    expect(doc).toContain('CHANGELOG.md#exit-code-changes-by-command');
    expect(readFileSync(join(ROOT, 'CHANGELOG.md'), 'utf8')).toContain('#### Exit code changes by command');
  });
});