Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Spend posture + USD-limit parsing — the single spend-control surface for
* gbrain's cost gates (issue #2139). Two concerns live here:
*
* 1. `spend.posture` (DB-plane config): `'gated'` (default) makes every cost
* gate behave as before; `'tokenmax'` makes them INFORMATIONAL — print the
* estimate, proceed, and keep ledgering spend. The operator who sets
* `tokenmax` has declared "cost is not my constraint." Posture removes the
* CEILING, never the ACCOUNTING (the spend ledger still records every
* dollar). It is deliberately SEPARATE from `search.mode=tokenmax` (which
* governs retrieval payload size, not embedding spend); the gate prints a
* hint linking the two when only the search mode is set.
*
* 2. `parseUsdLimit` / `formatUsdLimit`: first-class `off` / `unlimited` /
* `none` on the USD gate knobs (so operators stop setting sentinel values
* like `100000`). The parse layer represents "no limit" as `Infinity` so
* comparisons stay special-case-free (`cost > Infinity` is never true).
* `formatUsdLimit` renders it as the string `'unlimited'` — NEVER serialize
* raw `Infinity`, because `JSON.stringify(Infinity)` emits `null`, which is
* ambiguous in audit/ledger rows. At the budget-machinery boundary, callers
* convert `Infinity` → `undefined` ("no cap"), which `BudgetTracker` already
* treats as cap-absent.
*
* LEAF module: imports only the engine type so any cost-gate site can pull it
* in without a circular dependency.
*/
import type { BrainEngine } from './engine.ts';
export const SPEND_POSTURE_CONFIG_KEY = 'spend.posture';
export type SpendPosture = 'gated' | 'tokenmax';
/**
* Resolve `spend.posture` from DB-plane config. Fail-open to `'gated'` on a
* missing/unknown value or a config-read error — a posture probe must never
* crash a sync, and an unrecognized value must never silently disable gates.
*/
export async function resolveSpendPosture(engine: BrainEngine): Promise<SpendPosture> {
try {
const raw = await engine.getConfig(SPEND_POSTURE_CONFIG_KEY);
return normalizeSpendPosture(raw);
} catch {
return 'gated';
}
}
/** Pure normalizer (testable without an engine). Anything but `tokenmax` → `gated`. */
export function normalizeSpendPosture(raw: unknown): SpendPosture {
if (typeof raw === 'string' && raw.trim().toLowerCase() === 'tokenmax') return 'tokenmax';
return 'gated';
}
/** True iff `raw` is a valid `spend.posture` value (for `config set` validation). */
export function isValidSpendPosture(raw: unknown): boolean {
return typeof raw === 'string' && ['gated', 'tokenmax'].includes(raw.trim().toLowerCase());
}
const OFF_TOKENS = new Set(['off', 'unlimited', 'none']);
/**
* Parse a USD-limit config value.
* - `'off'` / `'unlimited'` / `'none'` (case-insensitive) → `Infinity` (no limit)
* - a finite positive number (or `0` when `allowZero`) → that number
* - anything else (garbage, negative, empty, NaN) → `def`
*
* `allowZero` distinguishes the two knob semantics:
* - `sync.cost_gate_min_usd` uses `allowZero: true` — `0` means "block on any
* nonzero spend" (a real operator choice). `off` is the no-limit escape.
* - the backfill caps reject `0` (fall back to the default); only `off`
* disables them. `off` semantics ≠ `0` (issue #2139).
*/
export function parseUsdLimit(
raw: unknown,
def: number,
opts: { allowZero?: boolean } = {},
): number {
if (raw === null || raw === undefined) return def;
if (typeof raw === 'string') {
const t = raw.trim().toLowerCase();
if (t === '') return def;
if (OFF_TOKENS.has(t)) return Infinity;
}
const n = Number(raw);
if (!Number.isFinite(n)) return def;
if (n < 0) return def;
if (n === 0) return opts.allowZero ? 0 : def;
return n;
}
/**
* Render a USD limit for human/JSON output. `Infinity` → `'unlimited'` (NEVER
* the raw value — `JSON.stringify(Infinity)` is `null`). Finite values are
* returned as-is so callers can `$${formatUsdLimit(x)}` or embed in JSON.
*/
export function formatUsdLimit(n: number): string | number {
return Number.isFinite(n) ? n : 'unlimited';
}
/**
* Convert a parsed USD limit to the budget-machinery cap representation:
* `Infinity` → `undefined` ("no cap", which `BudgetTracker` treats as
* cap-absent), finite → the number. Keeps `null` out of ledger rows.
*/
export function usdLimitToCap(n: number): number | undefined {
return Number.isFinite(n) ? n : undefined;
}