Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Consent primitive (agent operator contract v1, A4). CLI command handlers
* call `requireConsent()` before paid, destructive, credential, egress or
* persistent-install work. It resolves with the Authorization that covers the
* request or throws `confirmation_required` (exit 3) carrying the consent
* payload. Core library paths never prompt: they take an Authorization.
*
* Trust boundary: requireConsent runs only in trusted local CLI handlers, so
* a `host_admin` action is never authorizable from MCP (no MCP path calls
* it). User preapprovals live only in the host's file plane
* (~/.gbrain/config.json), which no MCP or HTTP operation writes; a
* `consent.*` row in the DB plane is never read.
*
* Consent honesty: an agent can always pass `--yes`. This gate forces a stop
* and supplies relay text; it cannot prove a human agreed. The enforced rails
* are the spend cap on the Authorization and the plan-hash binding below.
*/
import { createHash, randomBytes } from 'node:crypto';
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname } from 'node:path';
import { CONTRACT_VERSION, cliRenderContext, renderAction, shellQuote, type Action, type Actor, type CliErrorRender, type Effect, type RenderContext, type RenderedAction } from './agent-output.ts';
import { agentBlock } from './agent-markers.ts';
import { writeJsonDocument } from './cli-force-exit.ts';
import { recordAgentContractEvent } from './agent-contract-log.ts';
import { gbrainPath } from './config.ts';
import { PREAPPROVE_PAID_MAX_USD_PER_RUN, PREAPPROVE_PERSISTENT_INSTALL, preapprovalCommand, readConsentPreapprovals, type ConsentPreapprovals } from './consent-preapproval.ts';
import { isInteractive, readLine, type LineRead } from './interaction.ts';
import { OperationError, opError } from './ops/contract.ts';
import { SPEND_POSTURE_CONFIG_KEY, normalizeSpendPosture } from './spend-posture.ts';
export * from './consent-preapproval.ts';
export type CapSource = 'derived' | 'default' | 'user';
export interface Authorization {
consented_effects: Effect[];
/** null only when no paid effect. */
cap_usd: number | null;
cap_source: CapSource | null;
via: 'yes' | 'max_usd' | 'tokenmax' | 'preapproval' | 'apply_flag' | 'non_interactive_flag' | 'tty_prompt';
/** destructive: binds the persisted approved selection. */
approval_token?: string;
}
type Via = Authorization['via'];
export interface ConsentRequest {
command: string;
effects: Effect[];
actor: Actor;
what: string; why: string; risk: string;
user_message: string;
/** The exact command that runs once approved. */
argv: string[];
preview_argv?: string[];
est_usd?: number | null;
plan_hash?: string;
/** destructive: persisted with the approval (A4 destructive rail). */
selection?: unknown;
/** Raw argv, for --yes/--max-usd/--expect/--apply/--trust/--non-interactive. */
args: readonly string[];
}
/** The ambient inputs requireConsent reads; every field defaults to the live process. */
export interface ConsentEnv {
/** DB-plane config read (`engine.getConfig`) for `spend.posture`; absent → `gated`. */
getConfig?: (key: string) => Promise<string | null>;
/** Default: the host file plane (readConsentPreapprovals()). */
preapprovals?: ConsentPreapprovals;
/** The command's configured cost cap (e.g. a `*.budget_usd` key); counts as a user cap. */
configuredCapUsd?: number;
/** Default: isInteractive(). */
interactive?: boolean;
/** Default: interaction.readLine (EOF/timeout = decline). */
readLine?: (opts: { prompt: string; timeoutMs?: number }) => Promise<LineRead>;
/** One-line stderr notes (cap printed, preapproval honoured). */
note?: (line: string) => void;
}
/**
* Cap for paid work that has no estimate and no user cap. Matches the
* per-command defaults already shipped (enrich and extract-conversation-facts
* `DEFAULT_MAX_COST_USD`).
*/
export const DEFAULT_PAID_CAP_USD = 5;
/** `--yes` without `--max-usd`: estimate × 1.5, never below this floor. */
export const DERIVED_CAP_MULTIPLIER = 1.5;
export const DERIVED_CAP_FLOOR_USD = 0.25;
/**
* What `--non-interactive` authorizes, per command. It is never a blanket
* `--yes`: `apply-migrations` (where it historically meant `--yes`) gets the
* autopilot install its Phase F performs, nothing paid or destructive. The
* post-upgrade caller (`src/commands/upgrade.ts`, applyMigrations) passes
* `--yes --non-interactive` to apply-migrations, whose only consent effect
* is that same install. Every other command: nothing.
*/
export const NON_INTERACTIVE_AUTHORIZES: Readonly<Record<string, readonly Effect[]>> = {
'apply-migrations': ['persistent_install'],
};
// ── flags ──────────────────────────────────────────────────────────────────
export interface ConsentFlags {
yes: boolean;
/** Finite positive `--max-usd` / `--max-cost`; anything else is not an authorization. */
maxUsd: number | null;
expect: string | null;
apply: boolean;
nonInteractive: boolean;
}
function flagValue(args: readonly string[], names: readonly string[]): string | null {
for (let i = 0; i < args.length; i++) {
const a = args[i];
for (const n of names) {
if (a === n) return args[i + 1] ?? null;
if (a.startsWith(`${n}=`)) return a.slice(n.length + 1);
}
}
return null;
}
export function parseConsentFlags(args: readonly string[]): ConsentFlags {
const end = args.indexOf('--');
const opts = end >= 0 ? args.slice(0, end) : args;
const usd = Number(flagValue(opts, ['--max-usd', '--max-cost']));
return {
yes: opts.includes('--yes'),
maxUsd: Number.isFinite(usd) && usd > 0 ? usd : null,
expect: flagValue(opts, ['--expect']),
apply: opts.includes('--apply') || opts.includes('--trust'),
nonInteractive: opts.includes('--non-interactive'),
};
}
// ── caps ───────────────────────────────────────────────────────────────────
const stderrLine = (line: string) => { process.stderr.write(`${line}\n`); };
const ceilCents = (usd: number) => Math.ceil(usd * 100 - 1e-9) / 100;
/** `--yes` without `--max-usd`: estimate × 1.5, floor $0.25, rounded up to the cent. */
export function derivedCapUsd(estUsd: number): number {
return ceilCents(Math.max(estUsd * DERIVED_CAP_MULTIPLIER, DERIVED_CAP_FLOOR_USD));
}
function capFor(req: ConsentRequest, flags: ConsentFlags, paidVia: Via, pre: ConsentPreapprovals, env: ConsentEnv): { cap_usd: number; cap_source: CapSource } {
if (flags.maxUsd !== null) return { cap_usd: flags.maxUsd, cap_source: 'user' };
if (paidVia === 'preapproval') return { cap_usd: pre.paid!.max_usd_per_run!, cap_source: 'user' };
if (env.configuredCapUsd !== undefined) return { cap_usd: env.configuredCapUsd, cap_source: 'user' };
const note = env.note ?? stderrLine;
if (typeof req.est_usd === 'number' && Number.isFinite(req.est_usd)) {
const cap = derivedCapUsd(req.est_usd);
note(`[consent] ${req.command}: cost cap $${cap.toFixed(2)} (the $${req.est_usd.toFixed(2)} estimate x${DERIVED_CAP_MULTIPLIER}). Set your own with --max-usd <usd>.`);
return { cap_usd: cap, cap_source: 'derived' };
}
note(`[consent] ${req.command}: no cost estimate, so the default $${DEFAULT_PAID_CAP_USD.toFixed(2)} cap applies. Set your own with --max-usd <usd>.`);
return { cap_usd: DEFAULT_PAID_CAP_USD, cap_source: 'default' };
}
// ── the matrix ─────────────────────────────────────────────────────────────
interface Coverage { flags: ConsentFlags; pre: ConsentPreapprovals; tokenmax: boolean }
/** Which mechanism authorizes one effect, or null. The published consent matrix. */
function coverEffect(effect: Effect, req: ConsentRequest, c: Coverage): Via | null {
const { flags, pre } = c;
if (effect === 'destructive') {
if (!flags.yes) return null;
return !req.plan_hash || flags.expect === req.plan_hash ? 'yes' : null;
}
if (effect === 'paid') {
if (flags.maxUsd !== null) return 'max_usd';
if (flags.yes) return 'yes';
if (c.tokenmax) return 'tokenmax';
const limit = pre.paid?.max_usd_per_run;
if (limit !== undefined && (req.est_usd == null || req.est_usd <= limit)) return 'preapproval';
return null;
}
if (flags.yes) return 'yes';
if (flags.apply) return 'apply_flag';
if (flags.nonInteractive && NON_INTERACTIVE_AUTHORIZES[req.command]?.includes(effect)) return 'non_interactive_flag';
if (effect === 'persistent_install' && pre.persistent_install) return 'preapproval';
return null;
}
const VIA_ORDER: readonly Via[] = ['yes', 'max_usd', 'apply_flag', 'non_interactive_flag', 'tokenmax', 'preapproval'];
async function spendPostureIsTokenmax(env: ConsentEnv): Promise<boolean> {
if (!env.getConfig) return false;
try {
return normalizeSpendPosture(await env.getConfig(SPEND_POSTURE_CONFIG_KEY)) === 'tokenmax';
} catch {
return false;
}
}
async function promptConsent(req: ConsentRequest, env: ConsentEnv): Promise<boolean> {
const read = await (env.readLine ?? readLine)({ prompt: `${req.what}: ${req.user_message} [y/N] ` });
return read.kind === 'line' && /^y(es)?$/i.test(read.text);
}
/**
* CLI command handlers only. Resolves with the authorization or throws
* OperationError('confirmation_required') (`isConsentRefusal`, exit 3,
* printed by `printConsentRefusal`), or `preview_changed` when `--expect`
* names a different plan than the one being applied.
*/
export async function requireConsent(req: ConsentRequest, env: ConsentEnv = {}): Promise<Authorization> {
if (req.effects.length === 0) return { consented_effects: [], cap_usd: null, cap_source: null, via: 'yes' };
const flags = parseConsentFlags(req.args);
if (req.effects.includes('destructive') && req.plan_hash && flags.expect !== null && flags.expect !== req.plan_hash) {
throw previewChangedError(req, flags.expect);
}
const pre = env.preapprovals ?? readConsentPreapprovals();
const tokenmax = req.effects.includes('paid') && await spendPostureIsTokenmax(env);
const vias = req.effects.map(e => coverEffect(e, req, { flags, pre, tokenmax }));
let via: Via;
if (vias.every((v): v is Via => v !== null)) {
via = VIA_ORDER.find(v => vias.includes(v))!;
} else if (env.interactive ?? isInteractive()) {
if (!(await promptConsent(req, env))) throw consentRefusal(req, 'declined');
via = 'tty_prompt';
} else {
throw consentRefusal(req, 'refused');
}
if (via !== 'tty_prompt' && vias.includes('preapproval')) {
const keys = req.effects.filter((_, i) => vias[i] === 'preapproval')
.map(e => (e === 'paid' ? PREAPPROVE_PAID_MAX_USD_PER_RUN : PREAPPROVE_PERSISTENT_INSTALL));
(env.note ?? stderrLine)(`[consent] ${req.command}: proceeding under the user's preapproval ${keys.join(', ')} (remove with: gbrain config unset <key>).`);
recordAgentContractEvent({ command: req.command, transport: 'cli', code: 'confirmation_required', effects: [...req.effects], outcome: 'preapproved' });
}
const paidIdx = req.effects.indexOf('paid');
const cap = paidIdx >= 0
? capFor(req, flags, via === 'tty_prompt' ? 'tty_prompt' : vias[paidIdx]!, pre, env)
: { cap_usd: null, cap_source: null };
const approval_token = req.effects.includes('destructive') && req.plan_hash && req.selection !== undefined
? persistApproval(req.selection, req.plan_hash)
: undefined;
return { consented_effects: [...req.effects], ...cap, via, ...(approval_token ? { approval_token } : {}) };
}
// ── refusal payload + rendering ────────────────────────────────────────────
/** The exit-3 `--json` document (and the data behind the human `[AGENT]` block). */
export interface ConfirmationPayload {
status: 'confirmation_required';
error: 'confirmation_required';
code: 'confirmation_required';
message: string;
suggestion: string;
effects: Effect[];
actor: Actor;
why: string;
risk: string;
est_usd: number | null;
user_message: string;
fix: RenderedAction;
preview: { argv: string[]; command: string } | null;
plan_hash?: string;
preapprove_argv?: string[];
docs_cmd: string[];
contract_version: 1;
}
/** The approved command: `--yes`, plus `--expect <plan_hash>` for destructive work, so it runs verbatim once approved. */
export function consentFix(req: ConsentRequest): Action {
const argv = [...req.argv];
if (!argv.includes('--yes')) argv.push('--yes');
if (req.effects.includes('destructive') && req.plan_hash && !argv.includes('--expect')) argv.push('--expect', req.plan_hash);
return {
argv, consent: [...req.effects], actor: req.actor, why: req.why, user_message: req.user_message,
requires_exclusive: false,
...(req.preview_argv ? { preview_argv: req.preview_argv } : {}),
...(req.plan_hash ? { plan_hash: req.plan_hash } : {}),
};
}
/**
* Destructive approvals bind the plan: the approved command already carries
* `--yes --expect <plan_hash>`. Paid payloads offer a per-run preapproval
* (`gbrain config set consent.preapprove.paid.max_usd_per_run <usd>`);
* destructive ones never do.
*/
export function confirmationPayload(req: ConsentRequest, ctx: RenderContext): ConfirmationPayload {
const destructive = req.effects.includes('destructive');
const rendered = renderAction(consentFix(req), ctx);
const paid = req.effects.includes('paid');
return {
status: 'confirmation_required',
error: 'confirmation_required',
code: 'confirmation_required',
message: `${req.what} needs the user's approval before it runs; nothing was changed.`,
suggestion: `Ask the user: ${req.user_message} If they agree, run: ${rendered.command}`,
effects: [...req.effects],
actor: req.actor,
why: req.why,
risk: req.risk,
est_usd: req.est_usd ?? null,
user_message: req.user_message,
fix: rendered,
preview: rendered.preview_argv ? { argv: rendered.preview_argv, command: shellQuote(rendered.preview_argv) } : null,
...(req.plan_hash ? { plan_hash: req.plan_hash } : {}),
...(paid && !destructive ? { preapprove_argv: preapprovalCommand(PREAPPROVE_PAID_MAX_USD_PER_RUN, '<usd>') } : {}),
docs_cmd: ['gbrain', 'errors', 'confirmation_required'],
contract_version: CONTRACT_VERSION,
};
}
/** A `confirmation_required` OperationError carrying its payload. */
export interface ConsentRefusal extends OperationError { consent: ConfirmationPayload }
export function isConsentRefusal(e: unknown): e is ConsentRefusal {
return e instanceof OperationError && e.code === 'confirmation_required' && (e as Partial<ConsentRefusal>).consent !== undefined;
}
/** The exit-3 refusal for `req`, rendered for `ctx` (no prompt, no log): for gates outside requireConsent. */
export function buildConsentRefusal(req: ConsentRequest, ctx: RenderContext = cliRenderContext()): ConsentRefusal {
const payload = confirmationPayload(req, ctx);
const e = opError('confirmation_required', payload.message, payload.suggestion, { why: req.why, fix: consentFix(req) }) as ConsentRefusal;
e.consent = payload;
return e;
}
function consentRefusal(req: ConsentRequest, outcome: 'refused' | 'declined'): ConsentRefusal {
const e = buildConsentRefusal(req);
recordAgentContractEvent({ command: req.command, transport: 'cli', code: 'confirmation_required', effects: [...req.effects], outcome });
return e;
}
function previewChangedError(req: ConsentRequest, expected: string): OperationError {
recordAgentContractEvent({ command: req.command, transport: 'cli', code: 'preview_changed', effects: [...req.effects], outcome: 'refused' });
return opError('preview_changed',
`The plan changed since it was approved (--expect ${expected}, current plan ${req.plan_hash}); nothing was changed.`,
'Preview again, show the user the new plan, and re-run with the new --expect value only if they approve it.',
{ why: 'An approval covers exactly the plan the user saw; a different plan needs a new approval.',
...(req.preview_argv ? { fix: { argv: req.preview_argv, consent: [], actor: 'agent', requires_exclusive: false,
why: 'Shows the current plan and its plan_hash.' } } : {}) });
}
/**
* Exit-3 output for a refusal. `--json`: the payload document on stdout.
* Human: the `[AGENT]` block (fenced `[SHOW USER]` relay of user_message) on
* stdout and the one-line error on stderr. Pure: callers write the strings.
*/
export function renderConsentRefusal(p: ConfirmationPayload, opts: { json: boolean }): CliErrorRender {
if (opts.json) return { stdout: `${JSON.stringify(p, null, 2)}\n`, exitCode: 3 };
const preview = p.preview ? ` To look first (read-only): ${p.preview.command}` : '';
const preapprove = p.preapprove_argv ? `To stop asking for runs under a limit the user picks: ${shellQuote(p.preapprove_argv)}` : '';
const block = agentBlock({
ask: p.user_message,
why: p.why,
risk: p.risk,
consent: p.effects.join(', '),
actor: p.fix.actor,
next: p.fix.next,
if_yes: [p.fix.command, preapprove].filter(Boolean).join(' — '),
if_no: `Nothing runs; nothing was changed.${preview}`,
}, { showUser: p.user_message });
return { stdout: block, stderr: `Error [confirmation_required]: ${p.message}\n`, exitCode: 3 };
}
/** Write a refusal and return its exit code (3). The one way a CLI handler reports `confirmation_required`. */
export function printConsentRefusal(e: ConsentRefusal, opts: { json: boolean }): number {
const out = renderConsentRefusal(e.consent, opts);
// D2: under the --json guard only writeStdoutFinal reaches fd 1 (the payload / [AGENT] block is the final document).
if (out.stdout) void writeJsonDocument(out.stdout, t => process.stdout.write(t));
if (out.stderr) process.stderr.write(out.stderr);
return out.exitCode;
}
// ── derived-cap exhaustion ─────────────────────────────────────────────────
/** `--max-usd` for the resume: twice the cap that ran out, rounded up to the cent. */
export function resumeMaxUsd(capUsd: number): number {
return ceilCents(Math.max(capUsd * 2, DERIVED_CAP_FLOOR_USD));
}
/**
* The exit-1 error for paid work that stopped at its derived cap: names the
* checkpoint and the exact resume command (`--max-usd <n>`). BudgetTracker
* logs `derived_cap_exhausted` to E11 when it throws; this only shapes the
* report.
*/
export function derivedCapExhaustedError(opts: { command: string; argv: readonly string[]; spentUsd: number; capUsd: number; checkpoint?: string }): OperationError {
const argv: string[] = [];
for (let i = 0; i < opts.argv.length; i++) {
const a = opts.argv[i];
if (a === '--max-usd' || a === '--max-cost') { i++; continue; }
if (a.startsWith('--max-usd=') || a.startsWith('--max-cost=')) continue;
argv.push(a);
}
const n = resumeMaxUsd(opts.capUsd);
argv.push('--max-usd', n.toFixed(2));
const where = opts.checkpoint ? ` Progress is checkpointed (${opts.checkpoint}).` : '';
return opError('derived_cap_exhausted',
`${opts.command} stopped at its $${opts.capUsd.toFixed(2)} cost cap (derived from the estimate) after spending $${opts.spentUsd.toFixed(2)}.${where}`,
`Ask the user whether to continue with a $${n.toFixed(2)} cap, then run: ${shellQuote(argv)}`,
{ why: 'The estimate was low; the derived cap stops the run instead of spending past what was approved.',
fix: { argv, consent: ['paid'], actor: 'agent', requires_exclusive: false,
why: `Resumes from the checkpoint under a $${n.toFixed(2)} cap.`,
user_message: `The run spent its $${opts.capUsd.toFixed(2)} budget before finishing. Continue with up to $${n.toFixed(2)} more?` } });
}
// ── destructive rail: plan hash + persisted approval ───────────────────────
/** The effective selection previews, hashes, approval, apply and verification share. */
export interface PlanSelection {
brain: string;
source: string | null;
operation: string;
records: ReadonlyArray<{ id: string; revision?: string | number | null; source_incarnation?: string | number | null }>;
parameters: Record<string, unknown>;
effects: readonly Effect[];
}
function canonicalJson(v: unknown): string {
if (Array.isArray(v)) return `[${v.map(canonicalJson).join(',')}]`;
if (v && typeof v === 'object') {
return `{${Object.keys(v).sort().filter(k => (v as Record<string, unknown>)[k] !== undefined)
.map(k => `${JSON.stringify(k)}:${canonicalJson((v as Record<string, unknown>)[k])}`).join(',')}}`;
}
return JSON.stringify(v ?? null);
}
/** Stable over key order, record order and effect order; changes with any record, revision or parameter. */
export function computePlanHash(sel: PlanSelection): string {
const normal = {
brain: sel.brain,
source: sel.source,
operation: sel.operation,
records: [...sel.records].map(r => ({ id: r.id, revision: r.revision ?? null, source_incarnation: r.source_incarnation ?? null }))
.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
parameters: sel.parameters,
effects: [...new Set(sel.effects)].sort(),
};
return `ph_${createHash('sha256').update(canonicalJson(normal)).digest('hex').slice(0, 24)}`;
}
export interface StoredApproval {
approval_token: string;
plan_hash: string;
selection: unknown;
approved_at: string;
}
const TOKEN_RE = /^apr_[0-9a-f]{32}$/;
const approvalPath = (token: string) => gbrainPath('consent', 'approvals', `${token}.json`);
/** Persist the approved selection under GBRAIN_HOME; returns the approval token. */
export function persistApproval(selection: unknown, planHash: string): string {
const token = `apr_${randomBytes(16).toString('hex')}`;
const record: StoredApproval = { approval_token: token, plan_hash: planHash, selection, approved_at: new Date().toISOString() };
const path = approvalPath(token);
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
return token;
}
export function readApproval(token: string): StoredApproval | null {
if (!TOKEN_RE.test(token)) return null;
try {
const r = JSON.parse(readFileSync(approvalPath(token), 'utf8')) as StoredApproval;
return r.approval_token === token && typeof r.plan_hash === 'string' ? r : null;
} catch {
return null;
}
}
export type ApprovalCheck =
| { ok: true; approval: StoredApproval }
| { ok: false; reason: 'missing' }
| { ok: false; reason: 'changed'; changed: string[]; added: string[]; removed: string[] };
/**
* Apply-time check (run under the brain's lock): recompute the plan hash of
* the selection as it is now. A changed record or a newly matching record
* means the user approved something else, so the caller re-asks.
*/
export function verifyApproval(token: string, current: PlanSelection): ApprovalCheck {
const approval = readApproval(token);
if (!approval) return { ok: false, reason: 'missing' };
if (computePlanHash(current) === approval.plan_hash) return { ok: true, approval };
const byId = (records: PlanSelection['records'] | undefined) => new Map((records ?? []).map(r =>
[r.id, canonicalJson([r.revision ?? null, r.source_incarnation ?? null])]));
const before = byId((approval.selection as Partial<PlanSelection> | null)?.records);
const after = byId(current.records);
const changed = [...after.keys()].filter(id => before.has(id) && before.get(id) !== after.get(id));
return {
ok: false, reason: 'changed', changed,
added: [...after.keys()].filter(id => !before.has(id)),
removed: [...before.keys()].filter(id => !after.has(id)),
};
}
/** verifyApproval as a guard: throws `preview_changed` (re-ask) unless the approval still covers the selection. */
export function assertApproval(token: string, current: PlanSelection, opts: { command: string; preview_argv?: string[] }): StoredApproval {
const check = verifyApproval(token, current);
if (check.ok) return check.approval;
recordAgentContractEvent({ command: opts.command, transport: 'cli', code: 'preview_changed', effects: [...current.effects], outcome: check.reason });
const detail = check.reason === 'missing'
? 'no stored approval matches that token'
: `${check.changed.length} changed, ${check.added.length} newly matching, ${check.removed.length} no longer matching record(s)`;
throw opError('preview_changed', `The approved plan no longer matches the brain (${detail}); nothing was changed.`,
'Preview again, show the user the new plan, and apply only with their new approval.',
{ why: 'An approval covers exactly the records the user saw.', reason: check.reason,
...(opts.preview_argv ? { fix: { argv: opts.preview_argv, consent: [], actor: 'agent', requires_exclusive: false,
why: 'Shows the current plan and its plan_hash.' } } : {}) });
}