Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `decide()`: one logical decision over typed questions, provider-agnostic.
*
* policy → egress gate (typed provenance) → budget admission → pack
* (64k/32k, split before send) → provider (bounded concurrency, one
* deadline) → strict validation (malformed / mixed model fail the whole
* decision) → spend ledger rows → typed answers.
*
* Failures throw DecideError with a catalogued reason; every caller takes its
* slot's documented fail direction. Receipts are written by the slot code,
* which owns the outcome reducer (see recordDecisionReceipts).
* Contract: docs/architecture/decide.md.
*/
import { randomUUID } from 'node:crypto';
import type { BrainEngine } from '../../engine.ts';
import { loadConfigSnapshot } from '../../config-snapshot.ts';
import { usageCostUsd } from '../../budget/reservation-cost.ts';
import {
applyOpenAICompatConfig, applyResolveAuth, authToHeaders, chat, decideTransport, getCurrentBudgetTracker, requireConfig,
} from '../gateway.ts';
import { invokeAI, isAIInvocationPolicyError, responseInvocationUsage } from '../invocation-guard.ts';
import { recordOnTracker } from '../budget-record.ts';
import { getRecipe } from '../recipes/index.ts';
import { typesafeApiKey } from '../recipes/typesafe.ts';
import { providerKind, readDecideConfig, type DecideConfig } from './config.ts';
import { checkEgress } from './egress.ts';
import { estimateContextTokens, orderQuestions, parseRetryAfterMs, planBatches, RateLimitedError, runBatches } from './pack.ts';
import {
buildLlmPrompt, llmCapability, llmChatModel, llmModelIdentity, LLM_ANSWER_SCHEMA, LLM_SYSTEM_PROMPT, parseLlmReply,
} from './providers/llm-structured.ts';
import { buildTypeSafeRequest, classifyTypeSafeHttpError, parseTypeSafeResponse, toWireQuestion } from './providers/typesafe.ts';
import { SLOT_SPECS } from './slots.ts';
import { dailySpend, recordSpend } from './store.ts';
import {
DecideError, type DecideAnswer, type DecideLane, type DecideQuestion, type DecideRequest, type DecideResult, type EvidenceItem,
} from './types.ts';
export * from './types.ts';
export interface DecideContext {
/** Needed for egress page checks, the spend ledger and the daily cap. */
engine: BrainEngine | null;
/** Typed decide config; loaded from the engine's config snapshot when omitted. */
config?: DecideConfig;
sourceId?: string;
now?: () => number;
}
const BACKGROUND_DEFAULT_MS = 60_000;
let testClock: (() => number) | undefined;
/** Drive runDecide's deadline arithmetic from `clock` when the caller passes no `now`; returns the restore. */
export function __setDecideClockForTests(clock: (() => number) | undefined): () => void {
const prev = testClock;
testClock = clock;
return () => { testClock = prev; };
}
export async function loadDecideConfig(engine: BrainEngine | null, opts: { evalSlots?: string } = {}): Promise<DecideConfig> {
return readDecideConfig(engine ? await loadConfigSnapshot(engine) : null, { ...opts, typesafeKey: hasTypesafeKey() });
}
/** TypeSafe key presence in the gateway env snapshot (falls back to process env before configure). */
export function hasTypesafeKey(): boolean {
try { return typesafeApiKey(requireConfig().env) !== null; } catch { return typesafeApiKey(process.env) !== null; }
}
function stateText(state: Record<string, EvidenceItem>): Record<string, string> {
return Object.fromEntries(Object.entries(state).map(([k, v]) => [k, v.text]));
}
function emptyResult(provider: string, lane: DecideLane, refused: Record<string, string>): DecideResult {
return {
decision_id: randomUUID(), provider, model_alias: provider, model_resolved: '', answers: {}, refused,
usage: { input_tokens: 0, output_tokens: 0 }, cost_usd: 0, latency_ms: 0, batches: 0, lane,
};
}
export async function runDecide(req: DecideRequest, ctx: DecideContext): Promise<DecideResult> {
const now = ctx.now ?? testClock ?? Date.now;
const started = now();
const cfg = ctx.config ?? await loadDecideConfig(ctx.engine);
const provider = req.provider ?? cfg.slots[req.slot].provider;
const lane = req.lane ?? SLOT_SPECS[req.slot].lane;
const kind = providerKind(provider);
if (kind === 'none') throw new DecideError('no_provider', 'decide: no provider configured');
if (req.questions.length === 0) return emptyResult(provider, lane, {});
if (new Set(req.questions.map((q) => q.id)).size !== req.questions.length) throw new Error('decide: question ids must be unique');
const verdict = await checkEgress(ctx.engine, cfg, provider, req.state, req.questions, { consent: req.consent, slot: req.slot });
const refusedIds = new Set(Object.keys(verdict.refused));
const allowed = req.questions.filter((q) => !refusedIds.has(q.id));
const withFallback = async (result: DecideResult): Promise<DecideResult> => {
if (refusedIds.size === 0 || cfg.egressFallback === 'none' || cfg.egressFallback === provider || verdict.stateRefused === 'denied_source') return result;
const refusedQuestions = req.questions.filter((q) => refusedIds.has(q.id));
try {
result.fallback = await runDecide({ ...req, questions: refusedQuestions, provider: cfg.egressFallback }, { ...ctx, config: cfg });
} catch {
// Fallback failure: refused items keep the slot's fail direction.
}
return result;
};
if (allowed.length === 0) return withFallback(emptyResult(provider, lane, verdict.refused));
const deadlineAt = started + (req.deadlineMs ?? (lane === 'hot' ? cfg.timeoutMs : BACKGROUND_DEFAULT_MS));
if (now() >= deadlineAt) throw new DecideError('late', 'decide: no time left in the budget');
const ordered = orderQuestions(allowed);
const state = stateText(req.state);
const result = kind === 'typesafe'
? await runTypesafe(req, ctx, cfg, { provider, lane, deadlineAt, ordered, state, now })
: await runLlm(req, cfg, { provider, lane, deadlineAt, ordered, state, now });
result.refused = verdict.refused;
result.latency_ms = now() - started;
return withFallback(result);
}
interface RunArgs {
provider: string;
lane: DecideLane;
deadlineAt: number;
ordered: DecideQuestion[];
state: Record<string, string>;
now: () => number;
}
function deadlineSignal(deadlineAt: number, now: () => number, caller?: AbortSignal): { signal: AbortSignal; done: () => void } {
const ctrl = new AbortController();
const t = setTimeout(() => ctrl.abort(new DecideError('timeout', 'decide: deadline exceeded')), Math.max(0, deadlineAt - now()));
const onAbort = () => ctrl.abort(caller!.reason);
if (caller?.aborted) onAbort();
else caller?.addEventListener('abort', onAbort, { once: true });
return { signal: ctrl.signal, done: () => { clearTimeout(t); caller?.removeEventListener('abort', onAbort); } };
}
/** Attach the settled batches' answers to a failed decision (#6519); a policy error passes through bare. */
function withPartial(err: unknown, answers: Record<string, DecideAnswer>, models: Set<string>): unknown {
if (err instanceof DecideError && Object.keys(answers).length > 0) {
err.partial = { answers: { ...answers }, model_resolved: models.size === 1 ? [...models][0]! : null };
}
return err;
}
function asDecideError(err: unknown, signal: AbortSignal, caller?: AbortSignal): unknown {
if (err instanceof DecideError || isAIInvocationPolicyError(err)) return err;
if (signal.aborted) return caller?.aborted ? new DecideError('provider_error', 'decide: caller aborted') : new DecideError('timeout', 'decide: deadline exceeded');
return new DecideError('provider_error', `decide: transport failed (${err instanceof Error ? err.name : 'error'})`);
}
async function runTypesafe(req: DecideRequest, ctx: DecideContext, cfg: DecideConfig, a: RunArgs): Promise<DecideResult> {
const recipe = getRecipe('typesafe');
const tp = recipe?.touchpoints.decide;
if (!recipe || !tp) throw new DecideError('provider_error', 'decide: TypeSafe recipe missing');
const gw = requireConfig();
if (!typesafeApiKey(gw.env)) throw new DecideError('no_key', 'decide: TYPESAFE_API_KEY is not set');
const modelId = a.provider.replace(/^typesafe:/, '');
const url = `${applyOpenAICompatConfig(recipe, gw).baseURL.replace(/\/$/, '')}${tp.path}`;
const headers = { ...authToHeaders(applyResolveAuth(recipe, gw, 'reranker')), 'Content-Type': 'application/json' };
const stateTokens = estimateContextTokens(a.state);
const plan = planBatches(stateTokens, a.ordered.map((q) => estimateContextTokens(toWireQuestion(q))));
const bodies = plan.map((b) => JSON.stringify(buildTypeSafeRequest(modelId, a.state, b.indices.map((i) => a.ordered[i]!))));
if (bodies.some((body) => Buffer.byteLength(body, 'utf8') > tp.max_payload_bytes)) {
throw new DecideError('payload_too_large', 'decide: request exceeds the payload byte cap');
}
const budgetKind = req.budgetKind ?? 'decide';
const estimatedTokens = plan.reduce((n, b) => n + b.estimatedInputTokens, 0);
// [R18] (#5980): an id with no shipped tariff and no operator price is
// refused before transport. `?? 0` here would admit it as free against the
// daily and remote-share budgets and write $0 spend rows for a real bill.
if (usageCostUsd(a.provider, 1, 0, budgetKind, cfg.pricingOverrides) === null) {
throw new DecideError('unpriced_model', `decide: ${a.provider} has no price; register one with gbrain pricing set ${a.provider} --rate <usd-per-1M-input-tokens> --source <url>`);
}
const priced = (tokens: number) => usageCostUsd(a.provider, tokens, 0, budgetKind, cfg.pricingOverrides)!;
if (budgetKind === 'decide' && ctx.engine) {
const spent = await dailySpend(ctx.engine, a.now()).catch(() => ({ total: 0, remote: 0 }));
const estimate = priced(estimatedTokens);
if (spent.total + estimate > cfg.dailyUsd) throw new DecideError('budget_exhausted', 'decide: daily budget exhausted');
if (req.remote && spent.remote + estimate > cfg.dailyUsd * cfg.remoteShare) throw new DecideError('budget_exhausted', 'decide: remote share of the daily budget exhausted');
}
const tracker = getCurrentBudgetTracker();
const reservation = tracker?.reserve({ modelId: a.provider, estimatedInputTokens: estimatedTokens, maxOutputTokens: 0, kind: budgetKind, label: 'gateway.decide' });
const { signal, done } = deadlineSignal(a.deadlineAt, a.now, req.signal);
const transport = decideTransport();
const models = new Set<string>();
const answers: Record<string, DecideAnswer> = {};
let inputTokens = 0;
let outputTokens = 0;
const spendRow = (tokens: number, outcome: 'ok' | 'failed' | 'timeout' | 'malformed', model?: string) => {
if (!ctx.engine) return;
recordSpend(ctx.engine, {
request_id: randomUUID(), source_id: ctx.sourceId ?? null, slot: req.slot, provider: a.provider,
model_resolved: model ?? null, lane: a.lane, remote: req.remote === true, input_tokens: tokens,
cost_usd: priced(tokens), outcome,
});
};
try {
await runBatches(plan.length, async (i) => {
const batch = plan[i]!;
const questions = batch.indices.map((j) => a.ordered[j]!);
let charged = false;
try {
const response = await invokeAI(
{ operation: 'gateway.decide', kind: 'decide', model: a.provider, maxInputTokens: batch.estimatedInputTokens },
() => transport(url, { method: 'POST', headers, body: bodies[i]!, signal }),
responseInvocationUsage,
);
if (response.status === 429) {
spendRow(batch.estimatedInputTokens, 'failed');
charged = true;
throw new RateLimitedError(parseRetryAfterMs(response.headers.get('retry-after'), a.now()));
}
if (!response.ok) throw await classifyTypeSafeHttpError(response);
let json: unknown;
try { json = await response.json(); } catch { throw new DecideError('malformed_response', 'decide: response is not JSON'); }
const parsed = parseTypeSafeResponse(json, questions);
const tokens = parsed.inputTokens ?? batch.estimatedInputTokens;
inputTokens += tokens;
outputTokens += parsed.outputTokens ?? 0;
models.add(parsed.model);
spendRow(tokens, 'ok', parsed.model);
charged = true;
Object.assign(answers, parsed.answers);
} catch (err) {
if (!charged) {
// #7272: a 4xx refusal (402 billing, 401/403 auth, 400/404 model) never ran, so it costs
// nothing; 408 and 429 are not refusals of the request itself and 429 is charged above.
const refused = err instanceof DecideError && err.status !== undefined && err.status >= 400 && err.status < 500 && err.status !== 408 && err.status !== 429;
const tokens = refused ? 0 : batch.estimatedInputTokens;
inputTokens += tokens;
const reason = err instanceof DecideError ? err.reason : signal.aborted ? 'timeout' : 'failed';
spendRow(tokens, reason === 'timeout' ? 'timeout' : reason === 'malformed_response' ? 'malformed' : 'failed');
}
if (err instanceof RateLimitedError) throw err;
throw asDecideError(err, signal, req.signal);
}
}, { concurrency: a.lane === 'hot' ? cfg.maxConcurrency : cfg.backgroundConcurrency, deadlineAt: a.deadlineAt, signal, lane: a.lane, now: a.now });
} catch (err) {
throw withPartial(asDecideError(err, signal, req.signal), answers, models);
} finally {
done();
recordOnTracker(tracker, { modelId: a.provider, reservation, inputTokens, outputTokens: 0, kind: budgetKind, label: 'gateway.decide' });
}
if (models.size > 1) throw withPartial(new DecideError('mixed_model', `decide: batches answered by ${models.size} different models`), answers, models);
const modelResolved = [...models][0] ?? modelId;
return {
decision_id: randomUUID(), provider: a.provider, model_alias: modelId, model_resolved: modelResolved, answers, refused: {},
usage: { input_tokens: inputTokens, output_tokens: outputTokens }, cost_usd: priced(inputTokens), latency_ms: 0,
batches: plan.length, lane: a.lane,
};
}
async function runLlm(req: DecideRequest, cfg: DecideConfig, a: RunArgs): Promise<DecideResult> {
const model = llmChatModel(a.provider);
const capability = llmCapability(a.provider);
if (capability === 'unknown') throw new DecideError('llm_capability', `decide: ${model} has no chat route`);
const plan = planBatches(estimateContextTokens(a.state), a.ordered.map((q) => estimateContextTokens(toWireQuestion(q))));
const { signal, done } = deadlineSignal(a.deadlineAt, a.now, req.signal);
const models = new Set<string>();
const answers: Record<string, DecideAnswer> = {};
let inputTokens = 0;
let outputTokens = 0;
let baseUrl: string | undefined;
try {
const recipe = getRecipe(model.split(':')[0]!);
baseUrl = recipe ? requireConfig().base_urls?.[recipe.id] ?? recipe.base_url_default : undefined;
} catch { /* identity falls back to the requested id */ }
try {
await runBatches(plan.length, async (i) => {
const questions = plan[i]!.indices.map((j) => a.ordered[j]!);
const reply = await chat({
model, system: LLM_SYSTEM_PROMPT, messages: [{ role: 'user', content: buildLlmPrompt(a.state, questions) }],
...(capability === 'structured' ? { responseSchema: LLM_ANSWER_SCHEMA } : {}),
temperature: 0, abortSignal: signal, purpose: `decide:${req.slot}`, maxTokens: 64 + questions.length * 96,
// The egress gate cleared this provider only; a chain hop would send the pack elsewhere.
allowFallback: false,
});
inputTokens += reply.usage.input_tokens;
outputTokens += reply.usage.output_tokens;
models.add(llmModelIdentity(model, reply.responseModel, baseUrl));
Object.assign(answers, parseLlmReply(reply.text, questions));
}, { concurrency: a.lane === 'hot' ? cfg.maxConcurrency : cfg.backgroundConcurrency, deadlineAt: a.deadlineAt, signal, lane: a.lane, now: a.now });
} catch (err) {
throw withPartial(asDecideError(err, signal, req.signal), answers, models);
} finally {
done();
}
if (models.size > 1) throw withPartial(new DecideError('mixed_model', 'decide: batches answered by different models'), answers, models);
return {
decision_id: randomUUID(), provider: a.provider, model_alias: model, model_resolved: [...models][0] ?? model, answers, refused: {},
usage: { input_tokens: inputTokens, output_tokens: outputTokens }, cost_usd: 0, latency_ms: 0, batches: plan.length, lane: a.lane,
uncalibrated: true,
};
}