Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Registered numeric knobs for dream-cycle phases that a phase reads through
* `engine.getConfig` at run time. One spec per key carries the accepted
* range, so `gbrain config set` refuses a value the phase would not apply, and
* the phase names the key when a stored value is invalid or out of range
* instead of falling back silently. Neither the refusal nor the warning
* echoes the stored or rejected value.
*/
import { opError, type OperationError } from '../ops/contract.ts';
export const SYNTHESIZE_CONCEPTS_BUDGET_KEY = 'cycle.synthesize_concepts.budget_usd';
export const SYNTHESIZE_CONCEPTS_DEFAULT_BUDGET_USD = 1.5;
export const PROPOSE_TAKES_CALL_TIMEOUT_KEY = 'dream.propose_takes.call_timeout_ms';
export const PROPOSE_TAKES_CALL_TIMEOUT_MIN_MS = 1_000;
/** The gateway's default chat timeout; the gateway still races its own (shorter wins). */
export const PROPOSE_TAKES_CALL_TIMEOUT_MAX_MS = 300_000;
/** #6297: hours between completed in-cycle patterns runs; 0 turns the cadence off. */
export const PATTERNS_MIN_INTERVAL_KEY = 'dream.patterns.min_interval_hours';
export const PATTERNS_MIN_INTERVAL_DEFAULT_HOURS = 6;
export const PATTERNS_MIN_INTERVAL_MAX_HOURS = 720;
/** #6297: kilobytes of get_page results a patterns child reads in full; 0 turns the budget off. */
export const PATTERNS_CHILD_READ_BUDGET_KEY = 'dream.patterns.child_read_budget_kb';
export const PATTERNS_CHILD_READ_BUDGET_DEFAULT_KB = 200;
export const PATTERNS_CHILD_READ_BUDGET_MAX_KB = 100_000;
/** GBRA-216: claim-conflict pairs the claim_conflicts phase files per source per run (facts/claim-conflicts.ts). */
export const CLAIM_CONFLICTS_MAX_PAIRS_KEY = 'dream.claim_conflicts.max_pairs';
export const CLAIM_CONFLICTS_MAX_PAIRS_MAX = 100_000;
interface PhaseConfigSpec {
/** Human range, used in the refusal and the stored-value warnings. */
expected: string;
/** What applies when the key is unset or its stored value is invalid. */
defaultText: string;
/** The value `config set` accepts, or null. */
parse(raw: string): number | null;
/** A stored value the phase holds to the range instead of ignoring; null = invalid. */
clamp?(raw: string): number | null;
}
const finitePositive = (raw: string): number | null => {
const text = raw.trim();
const n = Number(text);
return text !== '' && Number.isFinite(n) && n > 0 ? n : null;
};
const wholeInRange = (raw: string, max: number): number | null => {
const text = raw.trim();
if (!/^\d+$/.test(text)) return null;
const n = Number(text);
return n <= max ? n : null;
};
const SPECS: Record<string, PhaseConfigSpec> = {
[CLAIM_CONFLICTS_MAX_PAIRS_KEY]: {
expected: `a whole number of pairs from 1 to ${CLAIM_CONFLICTS_MAX_PAIRS_MAX}`,
defaultText: '500',
parse: raw => { const n = wholeInRange(raw, CLAIM_CONFLICTS_MAX_PAIRS_MAX); return n !== null && n >= 1 ? n : null; },
},
[PATTERNS_MIN_INTERVAL_KEY]: {
expected: `a number of hours from 0 to ${PATTERNS_MIN_INTERVAL_MAX_HOURS} (0 turns the cadence off)`,
defaultText: String(PATTERNS_MIN_INTERVAL_DEFAULT_HOURS),
parse(raw) {
const text = raw.trim();
const n = Number(text);
return text !== '' && Number.isFinite(n) && n >= 0 && n <= PATTERNS_MIN_INTERVAL_MAX_HOURS ? n : null;
},
},
[PATTERNS_CHILD_READ_BUDGET_KEY]: {
expected: `a whole number of kilobytes from 0 to ${PATTERNS_CHILD_READ_BUDGET_MAX_KB} (0 turns the budget off)`,
defaultText: String(PATTERNS_CHILD_READ_BUDGET_DEFAULT_KB),
parse: raw => wholeInRange(raw, PATTERNS_CHILD_READ_BUDGET_MAX_KB),
},
[SYNTHESIZE_CONCEPTS_BUDGET_KEY]: {
expected: 'a finite number of US dollars above 0',
defaultText: String(SYNTHESIZE_CONCEPTS_DEFAULT_BUDGET_USD),
parse: finitePositive,
},
[PROPOSE_TAKES_CALL_TIMEOUT_KEY]: {
expected: `a whole number of milliseconds from ${PROPOSE_TAKES_CALL_TIMEOUT_MIN_MS} to ${PROPOSE_TAKES_CALL_TIMEOUT_MAX_MS}`,
defaultText: 'scaled with the output cap, 90000 to 300000 ms',
parse(raw) {
if (!/^\d+$/.test(raw.trim())) return null;
const n = Number(raw.trim());
return n >= PROPOSE_TAKES_CALL_TIMEOUT_MIN_MS && n <= PROPOSE_TAKES_CALL_TIMEOUT_MAX_MS ? n : null;
},
clamp(raw) {
const n = finitePositive(raw);
if (n === null) return null;
return Math.min(PROPOSE_TAKES_CALL_TIMEOUT_MAX_MS, Math.max(PROPOSE_TAKES_CALL_TIMEOUT_MIN_MS, Math.floor(n)));
},
},
};
export const PHASE_CONFIG_KEYS: readonly string[] = Object.keys(SPECS);
function specFor(key: string): PhaseConfigSpec {
const spec = SPECS[key];
if (!spec) throw new Error(`not a phase config key: ${key}`);
return spec;
}
/** `config set` validation: the parsed value, or an `invalid_params` refusal naming the key and range. */
export function parsePhaseConfigValue(key: string, value: string): number {
const spec = specFor(key);
const parsed = spec.parse(value);
if (parsed !== null) return parsed;
throw invalidPhaseConfig(key, spec);
}
function invalidPhaseConfig(key: string, spec: PhaseConfigSpec): OperationError {
return opError('invalid_params', `Invalid ${key}: expected ${spec.expected}.`,
`Set ${key} to ${spec.expected} (default: ${spec.defaultText}), or unset it to use the default.`,
{
why: `The phase reads ${key} on every run and would not apply this value. Nothing was written.`,
fix: {
argv: ['gbrain', 'config', 'set', key, '<VALUE>'],
inputs: [{ name: 'VALUE', how: `${spec.expected[0]!.toUpperCase()}${spec.expected.slice(1)}; ask the user when the intended value is unclear.` }],
consent: [], actor: 'agent', requires_exclusive: false,
why: `A value in range is applied on the next run; unset the key to use the default (${spec.defaultText}).`,
verify: { argv: ['gbrain', 'config', 'get', key] },
},
});
}
function storedValueWarning(key: string, spec: PhaseConfigSpec, using: string): string {
return `${key} is set to an invalid value (expected ${spec.expected}); using ${using}. ` +
`Fix: gbrain config set ${key} <value>, or gbrain config unset ${key}. Verify: gbrain config get ${key}`;
}
/**
* Read one phase knob. Unset or unreadable keeps the default with no warning
* (a config lookup never stops a maintenance phase). An accepted value is used
* as-is; a value the spec clamps is held to the range with a warning; anything
* else keeps the default with a warning. `value` is undefined for the default.
*/
export async function readPhaseConfigNumber(
engine: { getConfig?(key: string): Promise<string | null> },
key: string,
): Promise<{ value?: number; warning?: string }> {
const spec = specFor(key);
let raw: string | null | undefined;
try {
raw = await engine.getConfig?.(key);
} catch {
return {};
}
if (raw === null || raw === undefined || String(raw).trim() === '') return {};
const text = String(raw);
const parsed = spec.parse(text);
if (parsed !== null) return { value: parsed };
const clamped = spec.clamp?.(text) ?? null;
if (clamped !== null) return { value: clamped, warning: storedValueWarning(key, spec, String(clamped)) };
return { warning: storedValueWarning(key, spec, `the default (${spec.defaultText})`) };
}