Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.28: cumulative cost meter for dream-cycle phases (auto-think + drift).
*
* v0.37.x: kept as a thin adapter over `BudgetTracker` semantics. The public
* class shape (`BudgetMeter`, `SubmitEstimate`, `BudgetCheckResult`) is
* preserved so every existing dream-cycle call site keeps working. The
* audit JSONL grew a `schema_version: 1` field on every line (A2 amended:
* schema-stable, not byte-stable — reorderings are tolerated, field
* renames are breaking). `test/fixtures/dream-budget-schema-v1.jsonl`
* pins the documented field set.
*
* Per Codex P1 #10: each subagent submit estimates max-cost from
* `model + max_output_tokens`, accumulates per-cycle, refuses next submit
* if cumulative > budget. Pricing resolves through the canonical chat table
* (`canonicalLookup`), so any provider carried there is gated. A model absent
* from canonical (a router or proxy alias) is metered at a conservative
* Sonnet-tier fallback rate with a `BUDGET_METER_NO_PRICING` warn (once per
* process); `dream.budget.allow_unpriced=true` restores the old bypass.
* Local model servers (Ollama, LM Studio, llama-server) cost $0.
*
* Budget values: 0 spends nothing, `Infinity` (config `unlimited`) is no cap.
*
* Ledger lives at `~/.gbrain/audit/dream-budget-YYYY-Www.jsonl` (ISO-week
* rotation, same pattern as shell-audit; filename math now goes through
* `src/core/audit-week-file.ts` per T4). Each line is one submit's cost
* estimate + actual usage when reported back.
*/
import { mkdirSync, appendFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { isoWeekFilename, resolveAuditDir } from '../audit-week-file.ts';
import { estimateMaxCostUsd, ANTHROPIC_PRICING } from '../anthropic-pricing.ts';
import { canonicalLookup, type ModelPricing } from '../model-pricing.ts';
import type { BrainEngine } from '../engine.ts';
import { splitProviderModelId } from '../model-id.ts';
import { overrideFor, type PricingOverrides } from '../budget/reservation-cost.ts';
import { pricingSetCommand } from '../budget/no-pricing.ts';
// Re-exported beside loadAllowUnpriced so meter call sites read both knobs from one module.
export { loadPricingOverrides } from '../budget/budget-tracker.ts';
/** Local model servers bill nothing; their models are priced at $0, never at the fallback. */
const LOCAL_MODEL_PROVIDERS = new Set(['ollama', 'lmstudio', 'llama-server']);
/** Rate for models absent from the canonical table: Sonnet tier, derived from canonical. */
const FALLBACK_PRICING: ModelPricing = canonicalLookup('anthropic:claude-sonnet-4-6') ?? { input: 3.0, output: 15.0 };
/**
* Parse a dream budget config value. `0` (or a negative value) spends
* nothing, `unlimited` is no cap (Infinity); an empty or non-numeric value
* uses `fallback`.
*/
export function parseBudgetUsd(raw: string | number | null | undefined, fallback: number): number {
if (typeof raw === 'string' && raw.trim().toLowerCase() === 'unlimited') return Infinity;
if (raw === null || raw === undefined || (typeof raw === 'string' && raw.trim() === '')) return fallback;
const value = Number(raw);
return Number.isFinite(value) ? Math.max(0, value) : fallback;
}
/** `dream.budget.allow_unpriced=true` lets unpriced models bypass the gate. */
export async function loadAllowUnpriced(engine: Pick<BrainEngine, 'getConfig'>): Promise<boolean> {
// An unreadable config keeps the default: unpriced models are metered.
const raw = await Promise.resolve(engine.getConfig?.('dream.budget.allow_unpriced')).catch(() => null);
return typeof raw === 'string' && ['true', '1', 'yes', 'on'].includes(raw.trim().toLowerCase());
}
export interface BudgetMeterOpts {
/** USD cap for the whole cycle. 0 (or negative) spends nothing; Infinity is no cap. */
budgetUsd: number;
/** Let models absent from the pricing table bypass the gate (default: meter them at the fallback rate). */
allowUnpriced?: boolean;
/** Phase label for telemetry: 'auto_think' | 'drift'. */
phase: string;
/**
* #4312 operator price overrides (`pricing.overrides`, parsed by
* parsePricingOverrides). Consulted before the shipped tables, the same
* lookup BudgetTracker uses, so a rate the operator declared (a proxy
* route, or $0 for a flat-rate subscription lane) prices dream-cycle gates
* the same way it prices every other cost cap.
*/
pricingOverrides?: PricingOverrides;
/** Optional override for the audit file path (tests). */
auditPath?: string;
}
export interface SubmitEstimate {
/** Resolved Anthropic model id (e.g. 'claude-opus-4-7'). */
modelId: string;
/** Best-guess input token count. Caller computes from prompt size. */
estimatedInputTokens: number;
/** Max output tokens passed to the LLM call. Upper-bounds the output cost. */
maxOutputTokens: number;
/** Logical label for the submit (synthesize / verdict / drift / ...). */
label?: string;
}
export interface BudgetCheckResult {
allowed: boolean;
estimatedCostUsd: number;
cumulativeCostUsd: number;
budgetUsd: number;
reason?: string;
/** True when the model wasn't in the pricing map (metered at the fallback rate, or bypassed when allowed). */
unpriced?: boolean;
}
/** One-process memo: warn-once on missing pricing per model. */
const _unpricedWarnings = new Set<string>();
function auditFilePath(override?: string): string {
if (override) return override;
return join(resolveAuditDir(), isoWeekFilename('dream-budget'));
}
function writeLedgerLine(path: string, entry: object): void {
try {
mkdirSync(dirname(path), { recursive: true });
appendFileSync(path, JSON.stringify(entry) + '\n');
} catch {
// Best-effort. Audit failure must not gate the cycle.
}
}
export class BudgetMeter {
private cumulativeUsd = 0;
private readonly auditPath: string;
private unpricedSubmitsThisCycle = 0;
constructor(private readonly opts: BudgetMeterOpts) {
this.auditPath = auditFilePath(opts.auditPath);
}
/**
* Max-cost estimate for a planned submit.
*
* Prices through `canonicalLookup` first. `estimateMaxCostUsd` reads
* ANTHROPIC_PRICING, which CLAUDE.md defines as a DERIVED view of the one
* canonical chat-pricing table — so reaching for it directly made every
* non-Anthropic model unpriceable here even when the canonical table has
* its rates, and an unpriceable model disables the gate entirely (see
* `check`). Anthropic ids resolve identically either way, since the derived
* view is generated from canonical.
*
* Returns null only for models absent from the canonical table too; the
* caller keeps the existing warn-and-allow behaviour for those.
*/
private estimateCost(estimate: SubmitEstimate): number | null {
// #4312: an operator override wins over every table, as in BudgetTracker.
const override = overrideFor(estimate.modelId, this.opts.pricingOverrides);
if (override) {
const cost = (estimate.estimatedInputTokens / 1_000_000) * override.input +
(estimate.maxOutputTokens / 1_000_000) * override.output;
return Number.isFinite(cost) ? cost : null;
}
if (LOCAL_MODEL_PROVIDERS.has(splitProviderModelId(estimate.modelId).provider ?? '')) return 0;
const p = canonicalLookup(estimate.modelId);
const raw = p
? (estimate.estimatedInputTokens / 1_000_000) * p.input +
(estimate.maxOutputTokens / 1_000_000) * p.output
: estimateMaxCostUsd(
estimate.modelId,
estimate.estimatedInputTokens,
estimate.maxOutputTokens,
);
// A non-finite estimate must not reach the accumulator. Both tables are
// plain object literals, so a model id colliding with an inherited key
// ('constructor', 'toString', '__proto__') resolves to a truthy
// Object.prototype value whose .input/.output are undefined, and the
// arithmetic yields NaN. `cumulative + NaN` is NaN, `NaN > budget` is
// false, so a single such submit would silently disable the gate for the
// rest of the cycle. Treated as unpriceable instead, which routes into
// the documented warn-and-allow branch for that one submit and leaves
// the running total intact. (The same shape exists on the
// estimateMaxCostUsd path today; not changed here.)
return raw !== null && Number.isFinite(raw) ? raw : null;
}
/**
* Check whether a planned submit fits within the remaining budget.
* Records the attempt to the ledger regardless of allow/deny.
* Caller is responsible for skipping the actual LLM call when allowed=false.
*/
check(estimate: SubmitEstimate): BudgetCheckResult {
const priced = this.estimateCost(estimate);
const budgetUsd = Math.max(0, this.opts.budgetUsd);
if (priced === null) {
this.unpricedSubmitsThisCycle++;
if (!_unpricedWarnings.has(estimate.modelId)) {
_unpricedWarnings.add(estimate.modelId);
process.stderr.write(
`[budget] BUDGET_METER_NO_PRICING: model "${estimate.modelId}" has no canonical pricing. ` +
(this.opts.allowUnpriced
? `Budget gate disabled for this model (dream.budget.allow_unpriced=true). `
: `Metering it at the Sonnet-tier fallback rate; set dream.budget.allow_unpriced=true to bypass. `) +
`To meter its real price, look it up and register it: ${pricingSetCommand(estimate.modelId, 'chat')}\n`,
);
}
}
// An unpriced model bypasses the gate only when the operator opted in.
if (priced === null && this.opts.allowUnpriced) {
writeLedgerLine(this.auditPath, {
schema_version: 1,
phase: this.opts.phase,
ts: new Date().toISOString(),
event: 'submit_unpriced',
model: estimate.modelId,
label: estimate.label,
allowed: true,
estimated_input_tokens: estimate.estimatedInputTokens,
max_output_tokens: estimate.maxOutputTokens,
});
return {
allowed: true,
estimatedCostUsd: 0,
cumulativeCostUsd: this.cumulativeUsd,
budgetUsd,
unpriced: true,
};
}
const cost = priced ?? (
(estimate.estimatedInputTokens / 1_000_000) * FALLBACK_PRICING.input +
(estimate.maxOutputTokens / 1_000_000) * FALLBACK_PRICING.output
);
if (priced === null) {
const allowed = this.cumulativeUsd + cost <= budgetUsd;
if (allowed) this.cumulativeUsd += cost;
writeLedgerLine(this.auditPath, {
schema_version: 1,
phase: this.opts.phase,
ts: new Date().toISOString(),
event: 'submit_unpriced',
model: estimate.modelId,
label: estimate.label,
allowed,
estimated_input_tokens: estimate.estimatedInputTokens,
max_output_tokens: estimate.maxOutputTokens,
estimated_cost_usd: cost,
cumulative_cost_usd: this.cumulativeUsd,
budget_usd: budgetUsd,
});
return {
allowed,
estimatedCostUsd: cost,
cumulativeCostUsd: this.cumulativeUsd,
budgetUsd,
unpriced: true,
...(allowed ? {} : { reason: `BUDGET_EXHAUSTED: projected $${(this.cumulativeUsd + cost).toFixed(4)} > cap $${budgetUsd.toFixed(2)} (unpriced model at fallback rate)` }),
};
}
const projected = this.cumulativeUsd + cost;
if (projected > budgetUsd) {
writeLedgerLine(this.auditPath, {
schema_version: 1,
phase: this.opts.phase,
ts: new Date().toISOString(),
event: 'submit_denied',
model: estimate.modelId,
label: estimate.label,
estimated_cost_usd: cost,
cumulative_cost_usd: this.cumulativeUsd,
budget_usd: budgetUsd,
});
return {
allowed: false,
estimatedCostUsd: cost,
cumulativeCostUsd: this.cumulativeUsd,
budgetUsd,
reason: `BUDGET_EXHAUSTED: projected $${projected.toFixed(4)} > cap $${budgetUsd.toFixed(2)}`,
};
}
this.cumulativeUsd += cost;
writeLedgerLine(this.auditPath, {
schema_version: 1,
phase: this.opts.phase,
ts: new Date().toISOString(),
event: 'submit',
model: estimate.modelId,
label: estimate.label,
estimated_cost_usd: cost,
cumulative_cost_usd: this.cumulativeUsd,
budget_usd: budgetUsd,
});
return { allowed: true, estimatedCostUsd: cost, cumulativeCostUsd: this.cumulativeUsd, budgetUsd };
}
/** Cumulative cost spent so far this cycle. */
get totalSpent(): number { return this.cumulativeUsd; }
/** Count of submits whose model had no canonical pricing. */
get unpricedSubmits(): number { return this.unpricedSubmitsThisCycle; }
}
/** Test helper: reset the once-per-process warning memo. */
export function _resetBudgetMeterWarningsForTest(): void {
_unpricedWarnings.clear();
}
/** Re-export the pricing map for callers that need to introspect it. */
export { ANTHROPIC_PRICING };