Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.2 KB
Raw Blame
/**
 * Process exit statuses with a contract beyond "0 ok / 1 failed". One home so
 * a new status cannot silently reuse a value a caller already branches on.
 *
 * Agent operator contract v1 table (docs/guides/exit-codes.md):
 *   0 ok · 1 failed (class/retryable in JSON) · 2 usage / invalid input ·
 *   3 confirmation_required (its ONLY meaning) · 10 write pending ·
 *   11 resumable budget stop · 13 harness wired, verification pending ·
 *   12 no results (a lookup matched nothing; opt-in, GBRAIN_FAIL_ON_EMPTY=1) ·
 *   14 harness wired, shared-skills/token cleanup pending ·
 *   15 no edition in force on the as_of date · 16 host upgrade required ·
 *   17 doctor --alert: act · 18 doctor --alert: unknown ·
 *   69 serve exited unhealthy · 75 migration
 *   lock held · 124 timeout · 130 interrupted. `test/exit-codes.test.ts` enumerates every literal
 *   exit 3 in src/ so a new one cannot reuse it.
 */

export const OK_EXIT_CODE = 0;
export const FAILED_EXIT_CODE = 1;
/** Usage error or invalid input (`invalid_params`, `unknown_flag`). */
export const USAGE_EXIT_CODE = 2;
/**
 * The command needs the user's authorization and ran nothing
 * (`confirmation_required`; `--json` prints the consent payload). Agents stop
 * and ask. `mcp expose` and `google` also use 2 for this under v1 (legacy).
 */
export const CONFIRMATION_REQUIRED_EXIT_CODE = 3;
/** The command's own deadline elapsed; work may still be running elsewhere. */
export const TIMEOUT_EXIT_CODE = 124;
/** Interrupted by a signal (SIGINT). */
export const INTERRUPTED_EXIT_CODE = 130;

/** A runner refused because another runner holds the migration lock (EX_TEMPFAIL). */
export const MIGRATIONS_RUNNING_EXIT_CODE = 75;

/**
 * #5232 (O-ENG-1): the write was admitted and is still pending; it may commit
 * later. Distinct from 75, which `gbrain upgrade` reads as "another
 * migration runner holds the lock". Exit 0 means committed; pass
 * `--accept-pending` (or GBRAIN_ACCEPT_PENDING=1) to map pending to 0.
 */
export const PENDING_WRITE_EXIT_CODE = 10;

/**
 * A bounded run stopped at its time budget with work left (`gbrain embed
 * --stale`). Partial and resumable: stdout names the remaining count and the
 * exact resume command. Distinct from 1, which means something failed, and
 * from 3, which agent-facing commands reserve for "ask the user first".
 */
export const BUDGET_STOP_EXIT_CODE = 11;

/**
 * #7177, opt-in with GBRAIN_FAIL_ON_EMPTY=1: a lookup ran and matched nothing
 * (`gbrain recall <entity|text>`, `--grep`, `--question`, `--query`;
 * `gbrain entity <name>` with no page and no text mention). Distinct from 0 so
 * a script that filters stdout can still tell a miss from a hit, and from 1,
 * which means the command failed. A feed read (`--since-last-run`, `--watch`,
 * no filter) that finds nothing new is not a miss. Off by default: a miss
 * exits 0 and --json carries the status.
 */
export const NO_RESULTS_EXIT_CODE = 12;

/**
 * #6661: `gbrain bootstrap harness --token` on a PGLite brain wired every
 * target while no serve answered (`pending_verify`): nothing failed, nothing
 * verified yet. The JSON `fix` names the re-run that completes it once
 * `gbrain serve --http` runs; `--status` stays partial until then.
 */
export const HARNESS_PENDING_VERIFY_EXIT_CODE = 13;

/**
 * #6743: `gbrain bootstrap harness` wired and verified the harness, but the
 * cleanup of earlier shared-skills enrollments or carried token ids is still
 * pending (`bootstrap_cleanup_pending`). The JSON lists each id's state; its
 * `fix` re-runs the command when every id can converge, or names the owner's
 * revoke or leave step when one cannot.
 */
export const HARNESS_CLEANUP_PENDING_EXIT_CODE = 14;

/**
 * W4 `gbrain doctor --alert` (`doctor_alert_act`): a page-class check needs someone now; `--json` `alert.items`
 * carries each check's fix. 0 is `alert.level: none`; 1 stays "doctor itself failed".
 */
export const DOCTOR_ALERT_ACT_EXIT_CODE = 17;

/**
 * W4 `gbrain doctor --alert` (`doctor_alert_unknown`): no page-class check needs action, but at least one did not run
 * fresh (budget, error, last known result, tier). `alert.consecutive_unknown` counts the runs in a row; agent crons
 * page on the second.
 */
export const DOCTOR_ALERT_UNKNOWN_EXIT_CODE = 18;

/**
 * #6543: `gbrain serve` exited on its own because its persistence consumer
 * reported `restart_required` continuously for `GBRAIN_SERVE_RESTART_REQUIRED_EXIT_SECONDS`
 * (`serve_unhealthy_exit`). EX_UNAVAILABLE: a supervisor restarts it.
 */
export const SERVE_UNHEALTHY_EXIT_CODE = 69;

/**
 * GBRA-217: `gbrain get --as-of <date>` answered, but no edition was in force on that date (`valid_time.status` is
 * `not_in_force`, `not_yet_in_force` or `before_recorded_history`). stdout carries the status and why, never a document,
 * so a script cannot mistake expired or future text for the page in force. Distinct from 0 (an edition is in force) and
 * from 1, which means the read failed.
 */
export const VALID_TIME_NOT_IN_FORCE_EXIT_CODE = 15;

/**
 * GBRA-217 (`host_upgrade_required`): the brain host is older than this client and answered a different question (an
 * `as_of` read came back as the current page). Nothing was printed; upgrade the host.
 */
export const HOST_UPGRADE_REQUIRED_EXIT_CODE = 16;