Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* decide.* config keys: the registry `gbrain config set` validates against,
* and the typed reader every decide surface uses. All keys are DB-plane.
*
* Key-aware defaults (owner decision 2026-10-01): with no TypeSafe key every
* slot defaults off. With a key, the measured winners (`recommendedSlots` for
* the pinned Jev model: the same set `enable --recommended` turns on) default
* on with that provider and their reference calibrations, and the key counts
* as the egress opt-in for the data those slots send. Nothing is written to
* config. Any explicit setting wins: the slot's mode or provider, an explicit
* decide.provider none, decide.egress.private deny, or a deny on one of the
* slot's consent keys. Eval runs never get key defaults; their arms say
* exactly which slots are on.
*/
import { parsePricingOverrides } from '../../budget/budget-tracker.ts';
import type { PricingOverrides } from '../../budget/reservation-cost.ts';
import { recommendedSlots } from './reference-calibrations.ts';
import { SLOT_SPECS } from './slots.ts';
import { DECIDE_SLOTS, EVIDENCE_CLASSES, type DecideMode, type DecideSlot, type EvidenceClass } from './types.ts';
export const DEFAULT_TYPESAFE_MODEL = 'jev-1.13.0';
export const DEFAULT_TYPESAFE_PROVIDER = `typesafe:${DEFAULT_TYPESAFE_MODEL}`;
export const TYPESAFE_ALIASES = ['jev-latest', 'jev-preview'] as const;
/** S6 suppression boundary default (decide.slots.recall_needed.suppress_below); 0.05 before 2026-09-30. */
export const RECALL_SUPPRESS_BELOW_DEFAULT = 0.1;
type Validator = (value: string) => string | null;
const oneOf = (...values: string[]): Validator => (v) => values.includes(v) ? null : `must be one of ${values.join(', ')}`;
const number = (min: number, max: number, integer = false): Validator => (v) => {
const n = Number(v);
if (!v.trim() || !Number.isFinite(n) || n < min || n > max || (integer && !Number.isInteger(n))) {
return `must be ${integer ? 'an integer' : 'a number'} from ${min} to ${max}`;
}
return null;
};
const bool: Validator = (v) => ['true', 'false', 'on', 'off', '1', '0', 'yes', 'no'].includes(v.trim().toLowerCase()) ? null : 'must be true or false';
const provider: Validator = (v) => isValidProvider(v) ? null : 'must be none, typesafe:<model> or llm:<provider:model>';
const fallback: Validator = (v) => v === 'none' || /^llm:[a-z0-9-]+:.+$/i.test(v) ? null : 'must be none or llm:<provider:model>';
const sourceList: Validator = (v) => {
try {
const parsed = JSON.parse(v);
return Array.isArray(parsed) && parsed.every((s) => typeof s === 'string') ? null : 'must be a JSON array of source ids';
} catch { return 'must be a JSON array of source ids'; }
};
const calibrationRef: Validator = (v) => /^(local:\d+|ref:[a-z0-9._:-]+)$/i.test(v) ? null : 'must be local:<id> or ref:<id>';
/**
* `typesafe:<model>` accepts any model id a gateway or self-hosted Jev may
* publish (#5980: `typesafe:oc/jev-1.13-free`): one or more of
* `[a-z0-9._@/-]`, starting alphanumeric, no whitespace and no second colon.
* An id with no shipped tariff is admitted here and refused at call time
* (`unpriced_model`) until `gbrain pricing set` registers its price.
*/
export function isValidProvider(v: string): boolean {
return v === 'none' || /^typesafe:[a-z0-9][a-z0-9._@/-]*$/i.test(v) || /^llm:[a-z0-9-]+:.+$/i.test(v);
}
const GLOBAL_KEYS: Record<string, Validator> = {
'decide.provider': provider,
'decide.egress_fallback': fallback,
'decide.max_concurrency': number(1, 16, true),
'decide.background_concurrency': number(1, 16, true),
'decide.margin_floor': number(0, 0.5),
'decide.timeout_ms': number(50, 60_000, true),
'decide.query_budget_ms': number(50, 60_000, true),
'decide.budget.daily_usd': number(0, 1000),
'decide.budget.remote_share': number(0, 1),
'decide.egress.private': oneOf('deny', 'allow'),
'decide.egress.deny_sources': sourceList,
'decide.receipts.retention_days': number(1, 365, true),
'decide.calibrate.retest_n': number(0, 1000, true),
'decide.slots.conflict.proposal_floor': number(0, 1),
'decide.slots.conflict.review_withdraw': bool,
'decide.slots.conflict.review_duplicate_page': bool,
'decide.slots.conflict.review_duplicate_entity': bool,
'decide.slots.intent.wait_ms': number(0, 2000, true),
'decide.slots.recall_needed.suppress_below': number(0, 1),
...Object.fromEntries(EVIDENCE_CLASSES.map((c) => [`decide.egress.typesafe.${c}`, oneOf('deny', 'allow')])),
};
const SLOT_KEY_VALIDATORS: Record<string, Validator> = {
mode: oneOf('off', 'on', 'shadow'),
provider,
threshold: number(0, 1),
min_keep: number(0, 100, true),
force_on: bool,
min_action_precision: number(0, 1),
shadow_sample: number(0, 1),
shadow_wait: oneOf('on', 'off'),
calibration: calibrationRef,
};
/** Every registered decide.* key (for `config set` suggestions and docs). */
export const DECIDE_CONFIG_KEYS: readonly string[] = [
...Object.keys(GLOBAL_KEYS),
...DECIDE_SLOTS.flatMap((slot) => Object.keys(SLOT_KEY_VALIDATORS).map((k) => `decide.slots.${slot}.${k}`)),
];
/** Validation error text for a decide.* key/value, or null when valid. Unknown decide.* keys are errors. */
export function validateDecideConfigValue(key: string, value: string): string | null {
const global = GLOBAL_KEYS[key];
if (global) {
const err = global(value);
return err ? `${key} ${err} (got '${value}')` : null;
}
const m = /^decide\.slots\.([a-z_]+)\.([a-z_]+)$/.exec(key);
if (m && (DECIDE_SLOTS as readonly string[]).includes(m[1]!) && SLOT_KEY_VALIDATORS[m[2]!]) {
const err = SLOT_KEY_VALIDATORS[m[2]!]!(value);
return err ? `${key} ${err} (got '${value}')` : null;
}
return `${key} is not a decide key. Known slots: ${DECIDE_SLOTS.join(', ')}; see gbrain decide status`;
}
export interface DecideSlotConfig {
mode: DecideMode;
/** Resolved provider: slot override, else decide.provider. */
provider: string;
threshold?: number;
minKeep?: number;
forceOn: boolean;
minActionPrecision: number;
shadowSample?: number;
shadowWait: boolean;
/** Adopted calibration (`local:<id>` / `ref:<id>`), recorded by enable/adopt. */
calibration?: string;
/** S6 only: suppress reflex injection below this probability (decide.slots.recall_needed.suppress_below). */
suppressBelow?: number;
/** On by the key-aware default (no explicit setting); the key is this slot's egress opt-in. */
keyDefault?: true;
}
export interface DecideConfig {
provider: string;
egressFallback: string;
maxConcurrency: number;
backgroundConcurrency: number;
marginFloor: number;
timeoutMs: number;
queryBudgetMs: number;
dailyUsd: number;
remoteShare: number;
egressPrivate: 'deny' | 'allow';
denySources: string[];
consent: Record<EvidenceClass, boolean>;
retentionDays: number;
retestN: number;
/** S2: how long hybridSearch waits for the intent answer (decide.slots.intent.wait_ms). */
intentWaitMs: number;
slots: Record<DecideSlot, DecideSlotConfig>;
/** GBRAIN_DECIDE_SLOTS eval override, honored only when the caller opts in. */
evalOverride?: string;
/** Operator prices (`pricing.overrides`, written by `gbrain pricing set`): the only way an id without a shipped tariff runs. */
pricingOverrides?: PricingOverrides;
}
const num = (raw: string | undefined, fallbackValue: number, validator: Validator): number =>
raw !== undefined && validator(raw) === null ? Number(raw) : fallbackValue;
const truthy = (raw: string | undefined): boolean => raw !== undefined && ['true', 'on', '1', 'yes'].includes(raw.trim().toLowerCase());
/**
* Typed decide config from a flat config snapshot (engine.getAllConfig()).
* Invalid stored values fall back to defaults (config set validates on write).
* `evalSlots` applies a GBRAIN_DECIDE_SLOTS override (`triage=on,evidence=shadow`);
* only eval commands pass it, and it never bypasses consent, egress or the daily cap.
*/
let evalOverrideEnabled = false;
/** Eval commands (and `dream --eval-run`) opt in to GBRAIN_DECIDE_SLOTS for this process. */
export function enableDecideEvalOverride(enabled = true): void {
evalOverrideEnabled = enabled;
}
function processEvalSlots(): string | undefined {
return evalOverrideEnabled ? process.env.GBRAIN_DECIDE_SLOTS || undefined : undefined;
}
/** The decide.* subset of a config snapshot, or undefined when there is nothing to read (all-off fast path). */
export function pickDecideConfig(snapshot: Record<string, string | undefined> | null | undefined): Record<string, string> | undefined {
const out: Record<string, string> = {};
for (const [k, v] of Object.entries(snapshot ?? {})) if (k.startsWith('decide.') && typeof v === 'string') out[k] = v;
return Object.keys(out).length > 0 || processEvalSlots() ? out : undefined;
}
/**
* `typesafeKey`: a TypeSafe key is present (hasTypesafeKey() in index.ts). Omitted
* means keyless: every slot without an explicit mode is off.
*/
export function readDecideConfig(snapshot: Record<string, string | undefined> | null, opts: { evalSlots?: string; typesafeKey?: boolean } = {}): DecideConfig {
const get = (k: string): string | undefined => snapshot?.[k] ?? undefined;
const evalSlots = opts.evalSlots ?? processEvalSlots();
const globalProvider = get('decide.provider');
const providerValue = globalProvider && isValidProvider(globalProvider) ? globalProvider : 'none';
const evalModes = parseEvalSlots(evalSlots);
const keyDefaultsApply = opts.typesafeKey === true && !evalOverrideEnabled && !evalSlots && globalProvider !== 'none' && get('decide.egress.private') !== 'deny';
const slots = Object.fromEntries(DECIDE_SLOTS.map((slot) => {
const k = (name: string) => get(`decide.slots.${slot}.${name}`);
const minActionPrecision = num(k('min_action_precision'), 0.9, SLOT_KEY_VALIDATORS.min_action_precision!);
const slotProvider = k('provider');
const keyDefault = keyDefaultsApply && k('mode') === undefined && (slotProvider === undefined || slotProvider === DEFAULT_TYPESAFE_PROVIDER)
&& SLOT_SPECS[slot].egressClasses.every((c) => get(`decide.egress.typesafe.${c}`) !== 'deny')
&& recommendedSlots(DEFAULT_TYPESAFE_PROVIDER, () => minActionPrecision).includes(slot);
const rawMode = keyDefault ? 'on' : evalModes[slot] ?? k('mode');
const mode: DecideMode = rawMode === 'on' || rawMode === 'shadow' ? rawMode : 'off';
const threshold = k('threshold');
const minKeep = k('min_keep');
const sample = k('shadow_sample');
const cfg: DecideSlotConfig = {
mode,
provider: keyDefault ? DEFAULT_TYPESAFE_PROVIDER : slotProvider && isValidProvider(slotProvider) ? slotProvider : providerValue,
...(threshold !== undefined && SLOT_KEY_VALIDATORS.threshold!(threshold) === null ? { threshold: Number(threshold) } : {}),
...(minKeep !== undefined && SLOT_KEY_VALIDATORS.min_keep!(minKeep) === null ? { minKeep: Number(minKeep) } : {}),
forceOn: truthy(k('force_on')),
minActionPrecision,
...(sample !== undefined && SLOT_KEY_VALIDATORS.shadow_sample!(sample) === null ? { shadowSample: Number(sample) } : {}),
shadowWait: k('shadow_wait') === 'on',
...(k('calibration') && calibrationRef(k('calibration')!) === null ? { calibration: k('calibration') } : {}),
...(slot === 'recall_needed' ? { suppressBelow: num(k('suppress_below'), RECALL_SUPPRESS_BELOW_DEFAULT, GLOBAL_KEYS['decide.slots.recall_needed.suppress_below']!) } : {}),
...(keyDefault ? { keyDefault: true as const } : {}),
};
return [slot, cfg];
})) as Record<DecideSlot, DecideSlotConfig>;
let denySources: string[] = [];
try {
const raw = get('decide.egress.deny_sources');
if (raw && sourceList(raw) === null) denySources = JSON.parse(raw);
} catch { /* invalid stored value: no denials beyond the private rule */ }
const fb = get('decide.egress_fallback');
const pricingOverrides = parsePricingOverrides(get('pricing.overrides'));
return {
provider: providerValue,
egressFallback: fb && fallback(fb) === null ? fb : 'none',
maxConcurrency: num(get('decide.max_concurrency'), 16, GLOBAL_KEYS['decide.max_concurrency']!),
backgroundConcurrency: num(get('decide.background_concurrency'), 4, GLOBAL_KEYS['decide.background_concurrency']!),
marginFloor: num(get('decide.margin_floor'), 0.05, GLOBAL_KEYS['decide.margin_floor']!),
timeoutMs: num(get('decide.timeout_ms'), 1500, GLOBAL_KEYS['decide.timeout_ms']!),
queryBudgetMs: num(get('decide.query_budget_ms'), 1500, GLOBAL_KEYS['decide.query_budget_ms']!),
dailyUsd: num(get('decide.budget.daily_usd'), 1, GLOBAL_KEYS['decide.budget.daily_usd']!),
remoteShare: num(get('decide.budget.remote_share'), 0.5, GLOBAL_KEYS['decide.budget.remote_share']!),
egressPrivate: get('decide.egress.private') === 'allow' ? 'allow' : 'deny',
denySources,
consent: Object.fromEntries(EVIDENCE_CLASSES.map((c) => [c, get(`decide.egress.typesafe.${c}`) === 'allow'])) as Record<EvidenceClass, boolean>,
retentionDays: num(get('decide.receipts.retention_days'), 7, GLOBAL_KEYS['decide.receipts.retention_days']!),
retestN: num(get('decide.calibrate.retest_n'), 50, GLOBAL_KEYS['decide.calibrate.retest_n']!),
intentWaitMs: num(get('decide.slots.intent.wait_ms'), 250, GLOBAL_KEYS['decide.slots.intent.wait_ms']!),
slots,
...(evalSlots ? { evalOverride: evalSlots } : {}),
...(pricingOverrides ? { pricingOverrides } : {}),
};
}
/** Parse a GBRAIN_DECIDE_SLOTS value (`triage=on,evidence=shadow`); unknown slots and modes are ignored. */
export function parseEvalSlots(raw: string | undefined): Partial<Record<DecideSlot, DecideMode>> {
const out: Partial<Record<DecideSlot, DecideMode>> = {};
for (const part of (raw ?? '').split(',')) {
const [slot, mode] = part.split('=').map((s) => s.trim());
if (slot && (DECIDE_SLOTS as readonly string[]).includes(slot) && (mode === 'on' || mode === 'off' || mode === 'shadow')) {
out[slot as DecideSlot] = mode;
}
}
return out;
}
/** True when every slot is off: callers skip all decide work (byte-identical all-off path). */
export function allSlotsOff(cfg: DecideConfig): boolean {
return DECIDE_SLOTS.every((slot) => cfg.slots[slot].mode === 'off');
}
export function providerKind(provider: string): 'typesafe' | 'llm' | 'none' {
if (provider.startsWith('typesafe:')) return 'typesafe';
if (provider.startsWith('llm:')) return 'llm';
return 'none';
}
export function isTypesafeAlias(provider: string): boolean {
return (TYPESAFE_ALIASES as readonly string[]).includes(provider.replace(/^typesafe:/, ''));
}