Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #6177: size an in-cycle dream patterns run to the cycle budget.
*
* A patterns child at the 100-reflection cap can need about 30 minutes; an
* in-cycle run with less budget spent tokens and was killed. The phase records
* each child's cost in the DB-only state key `dream.patterns.last_run`
* (`{duration_ms, reflections, at, outcome, budget_skips}`; not a user
* setting: `config set` refuses it and `config unset` resets it), and
* `planPatternsRun` sizes the next in-cycle run from it before any spend.
*/
import type { BrainEngine } from '../engine.ts';
import type { Action } from '../agent-output.ts';
import type { PhaseResult } from '../cycle.ts';
import {
PATTERNS_CHILD_READ_BUDGET_DEFAULT_KB, PATTERNS_CHILD_READ_BUDGET_KEY, PATTERNS_MIN_INTERVAL_DEFAULT_HOURS, PATTERNS_MIN_INTERVAL_KEY, readPhaseConfigNumber,
} from './phase-config-values.ts';
export const PATTERNS_LAST_RUN_KEY = 'dream.patterns.last_run';
/** Reflections a first in-cycle run submits with no history (or min_evidence, if larger). */
export const PATTERNS_FIRST_BATCH = 25;
/** Margin over the recorded milliseconds per reflection. */
const MARGIN = 1.25;
/** Consecutive budget skips after which the next cycle probes. */
const PROBE_AFTER_SKIPS = 3;
/** A record older than this no longer predicts cost; the next cycle probes. */
const STALE_MS = 7 * 86_400_000;
export interface PatternsLastRun {
duration_ms: number;
/** Reflections the child was given. */
reflections: number;
/** ISO time the child ended. */
at: string;
/** `timeout` = the child was still running at its budget, so duration is a lower bound. */
outcome: 'completed' | 'timeout' | 'failed';
/** In-cycle runs skipped for budget since this child. */
budget_skips: number;
}
export type PatternsPlan =
| { kind: 'submit'; n: number; basis: 'full' | 'first_batch' | 'history' | 'probe' }
| { kind: 'skip'; reason: 'budget_below_recent_runtime'; n: number };
/**
* Pure. `budgetMs` null = a direct run with no cycle deadline: full size.
* With history, n = budget / (ms per reflection × 1.25); a timed-out run is a
* lower bound on cost, so the next submission is also at most half of it.
* With no usable history (none, or a failed child), a conservative first
* batch. Three budget skips or a week-old record decay to a min_evidence
* probe, so the planner cannot skip forever. Below min_evidence it skips.
*/
export function planPatternsRun(input: { budgetMs: number | null; lastRun: PatternsLastRun | null; reflections: number;
minEvidence: number; nowMs: number }): PatternsPlan {
const { budgetMs, lastRun, reflections, minEvidence } = input;
if (budgetMs === null) return { kind: 'submit', n: reflections, basis: 'full' };
if (!lastRun || lastRun.outcome === 'failed' || lastRun.reflections <= 0) {
return { kind: 'submit', n: Math.min(reflections, Math.max(PATTERNS_FIRST_BATCH, minEvidence)), basis: 'first_batch' };
}
const age = input.nowMs - Date.parse(lastRun.at);
if (lastRun.budget_skips >= PROBE_AFTER_SKIPS || !(age <= STALE_MS)) {
return { kind: 'submit', n: Math.min(reflections, minEvidence), basis: 'probe' };
}
const msPerReflection = Math.max(1, lastRun.duration_ms / lastRun.reflections) * MARGIN;
let n = Math.min(reflections, Math.floor(budgetMs / msPerReflection));
if (lastRun.outcome === 'timeout') n = Math.min(n, Math.floor(lastRun.reflections / 2));
return n < minEvidence ? { kind: 'skip', reason: 'budget_below_recent_runtime', n } : { kind: 'submit', n, basis: 'history' };
}
/** The recorded last run, or null when unset or unreadable. */
export async function readPatternsLastRun(engine: BrainEngine): Promise<PatternsLastRun | null> {
try {
const value = JSON.parse((await engine.getConfig(PATTERNS_LAST_RUN_KEY)) ?? '') as Partial<PatternsLastRun>;
if (typeof value.duration_ms !== 'number' || typeof value.reflections !== 'number' || typeof value.at !== 'string') return null;
const outcome = value.outcome === 'completed' || value.outcome === 'timeout' ? value.outcome : 'failed';
return { duration_ms: value.duration_ms, reflections: value.reflections, at: value.at, outcome, budget_skips: Number(value.budget_skips) || 0 };
} catch {
return null;
}
}
/**
* Record a child's cost; any end other than completed or timeout is `failed`.
* #6296: a child dead-lettered at its own timeout_ms (`timeout exceeded`,
* `wall-clock timeout exceeded`) is a timeout, so the next plan halves.
*/
export async function recordPatternsLastRun(engine: BrainEngine,
run: { duration_ms: number; reflections: number; outcome: string; error_text?: string | null }): Promise<void> {
const timedOut = run.outcome === 'timeout' || (run.outcome === 'dead' && /^(wall-clock )?timeout exceeded$/.test(run.error_text ?? ''));
const outcome: PatternsLastRun['outcome'] = timedOut ? 'timeout' : run.outcome === 'completed' ? 'completed' : 'failed';
const record: PatternsLastRun = { duration_ms: run.duration_ms, reflections: run.reflections, at: new Date().toISOString(), outcome, budget_skips: 0 };
await engine.setConfig(PATTERNS_LAST_RUN_KEY, JSON.stringify(record)).catch(() => undefined);
}
export async function recordPatternsBudgetSkip(engine: BrainEngine, lastRun: PatternsLastRun): Promise<void> {
await engine.setConfig(PATTERNS_LAST_RUN_KEY, JSON.stringify({ ...lastRun, budget_skips: lastRun.budget_skips + 1 })).catch(() => undefined);
}
/** The skip's next step: a direct run has no cycle deadline, so it is not sized, and records last_run when it ends. */
export function patternsBudgetSkipFix(): Action {
return {
argv: ['gbrain', 'dream', '--phase', 'patterns'], consent: ['paid'], actor: 'agent', requires_exclusive: false,
why: 'A direct run is not limited by the cycle budget and records its cost for the next cycle. It is a paid model run, so ask the user first. To forget the recorded cost instead: gbrain config unset dream.patterns.last_run',
docs: 'docs/guides/dream-patterns.md#budget-sizing',
};
}
/**
* The phase's sizing step: plan from the recorded last run, or the budget
* skip result (the skip is counted toward the probe, nothing is submitted).
*/
export async function sizePatternsRun(engine: BrainEngine, input: { budgetMs: number | null; reflections: number; minEvidence: number }):
Promise<{ kind: 'submit'; plan: Extract<PatternsPlan, { kind: 'submit' }> } | { kind: 'skip'; result: PhaseResult }> {
const lastRun = await readPatternsLastRun(engine);
const plan = planPatternsRun({ ...input, lastRun, nowMs: Date.now() });
if (plan.kind === 'submit') return { kind: 'submit', plan };
if (lastRun) await recordPatternsBudgetSkip(engine, lastRun);
const budgetMs = input.budgetMs ?? 0;
return { kind: 'skip', result: { phase: 'patterns', status: 'skipped', duration_ms: 0,
summary: `patterns: the ${Math.round(budgetMs / 1000)}s cycle budget fits ${plan.n} of ${input.reflections} reflections ` +
`at the recorded runtime (need ≥${input.minEvidence}); nothing was submitted. Run it outside the cycle: gbrain dream --phase patterns`,
details: { reason: 'insufficient_cycle_budget', cause: plan.reason, reflections_selected: input.reflections,
reflections_submitted: 0, reflections_fit: plan.n, budget_ms: budgetMs, last_run: lastRun,
fix: patternsBudgetSkipFix(), reset_command: `gbrain config unset ${PATTERNS_LAST_RUN_KEY}` } } };
}
/** #6297: state key prefix of the time each partition's last completed patterns child ended. */
export const PATTERNS_CADENCE_KEY = 'dream.patterns.last_completed_at';
/**
* The owner partition's cadence key: per source and source incarnation, so a
* re-created source starts fresh. The external partition appends `.external`,
* so the owner pass never throttles it.
*/
export async function patternsCadenceKey(engine: BrainEngine, sourceId: string): Promise<string> {
const [source] = await engine.executeRaw<{ incarnation: string | null }>('SELECT incarnation FROM sources WHERE id = $1', [sourceId]);
return `${PATTERNS_CADENCE_KEY}.${sourceId}${source?.incarnation ? `.${source.incarnation}` : ''}`;
}
/**
* #6297: an in-cycle run (autopilot, bare `gbrain dream`) is skipped while
* the partition's last completed child ended less than
* `dream.patterns.min_interval_hours` (default 6, 0 off) ago. Every
* maintenance pass writes new reflections, so the evidence watermark alone
* re-ran a paid child on every pass. A direct `gbrain dream --phase patterns`
* or `--once` is not checked (the caller decides). An absent or unreadable
* stamp fails open.
*/
export async function patternsCadenceSkip(engine: BrainEngine, cadenceKey: string, nowMs = Date.now()): Promise<PhaseResult | null> {
const setting = await readPhaseConfigNumber(engine, PATTERNS_MIN_INTERVAL_KEY);
if (setting.warning) process.stderr.write(`[dream] ${setting.warning}\n`);
const hours = setting.value ?? PATTERNS_MIN_INTERVAL_DEFAULT_HOURS;
if (hours <= 0) return null;
const lastMs = Date.parse((await engine.getConfig(cadenceKey)) ?? '');
if (!Number.isFinite(lastMs)) return null;
const nextMs = lastMs + hours * 3_600_000;
if (nowMs >= nextMs) return null;
const next = new Date(nextMs).toISOString();
return { phase: 'patterns', status: 'skipped', duration_ms: 0,
summary: `patterns: the last completed run ended at ${new Date(lastMs).toISOString()}; in-cycle runs wait ${hours}h (${PATTERNS_MIN_INTERVAL_KEY}), so the next one is eligible at ${next}. Nothing was submitted.`,
details: { reason: 'patterns_min_interval', code: 'patterns_min_interval', last_completed_at: new Date(lastMs).toISOString(), next_eligible_at: next,
min_interval_hours: hours, cadence_key: cadenceKey,
fix: { argv: ['gbrain', 'dream', '--phase', 'patterns'], consent: ['paid'], actor: 'agent', requires_exclusive: false,
why: `A direct run is not held to ${PATTERNS_MIN_INTERVAL_KEY}. It is a paid model run, so ask the user first; otherwise the next in-cycle run after ${next} runs on its own.`,
verify: { argv: ['gbrain', 'config', 'get', cadenceKey] }, docs: 'docs/guides/dream-patterns.md#cadence' } as Action } };
}
/** #6297: the patterns child's get_page budget in bytes (`dream.patterns.child_read_budget_kb`, default 200 KB), or null when off. */
export async function patternsChildReadBudgetBytes(engine: BrainEngine): Promise<number | null> {
const setting = await readPhaseConfigNumber(engine, PATTERNS_CHILD_READ_BUDGET_KEY);
if (setting.warning) process.stderr.write(`[dream] ${setting.warning}\n`);
const kb = setting.value ?? PATTERNS_CHILD_READ_BUDGET_DEFAULT_KB;
return kb > 0 ? kb * 1024 : null;
}