Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain trust` owner subcommands (#5575: CEO-2, CEO-9, DX-2, DX-3, DX-7,
* DX-10, DX-13, DX-14, DX-15, ENG-15): review, confirm, release, drop,
* revert, explain, allow, disable. `backfill` lives in the dispatch module
* (src/cli/commands/trust.ts).
*
* Every action previews the target, asks the owner to type its token on an
* interactive terminal when the action raises trust (trust/confirm.ts; piped
* input, agents and --yes never confirm), then applies it bound to the
* previewed state. The backend is the local engine, or, while a resident
* `gbrain serve` holds a PGLite brain, that owner's 0600 administration
* socket (trust/owner-ipc.ts): the prompt still happens here, in the
* invoking terminal, and the owner re-validates the binding.
*/
import { createHash } from 'node:crypto';
import type { BrainEngine } from '../core/engine.ts';
import type { GBrainConfig } from '../core/config.ts';
import { jsonRequested, setCliExitVerdict, writeStdoutFinal } from '../core/cli-force-exit.ts';
import { OperationError, opError, type OperationContext } from '../core/ops/contract.ts';
import type { Principal } from '../core/persistence/model.ts';
import { maintenanceAttribution } from '../core/persistence/attribution.ts';
import { requireOwnerConfirmation } from '../core/trust/confirm.ts';
import {
applyOwnerAction, previewOwnerAction, type OwnerActionInput, type OwnerActionPreview, type OwnerActionResult,
} from '../core/trust/owner-actions.ts';
import {
buildTrustReview, explainTrust, parseTrustReviewKind, parseTrustSince, renderTrustExplanation, renderTrustReview,
type TrustExplanation, type TrustReview, type TrustReviewFilter,
} from '../core/trust/review.ts';
import { trustLabel } from '../core/trust/tier.ts';
import { PENDING_WRITE_EXIT_CODE } from '../core/exit-codes.ts';
import { acceptPendingCovers, acceptPendingRequested, pendingReceiptOf, pollCommand } from '../core/persistence/write-wait.ts';
import { getCliOptions } from '../core/cli-options.ts';
import { cliRenderContext } from '../core/agent-output.ts';
import { reportPersistenceCliError } from './persistence-delegate.ts';
import { writeCliError } from '../cli/cli-error.ts';
export const TRUST_OWNER_USAGE = [
'Usage: gbrain trust <review|confirm|release|drop|revert|explain|allow|disable|backfill|scan> [options]',
' review [--from <source>] [--kind <kind>] [--since <7d|date>] [--json]',
' Everything waiting for you: trust proposals (tp<id>), pages an agent edit lowered, unconfirmed standing',
' preferences (f<id>), held writes (h<id>), agent pages flagged as instructions (p:<source>/<slug>) and your',
' allow rules (a<id>), grouped by day and page, each with its exact commands.',
' review --accept-all (--from <source> | --kind <kind> | --since <when>)...',
' Accept every listed item matching the filters (at least one filter) after one typed confirmation. A flagged',
' page is never included: read it, then run trust confirm on it.',
' confirm <f<id>|t<id>|p:<source>/<slug>|tp<id>|h<id>> [--source <id>]',
' Mark it "confirmed by you" (accepts a proposal; releases a held write). Asks you to type its token.',
' release <h<id>> Release a held write into memory as "confirmed by you" (asks for its token).',
' drop <tp<id>|h<id>> Dismiss a proposal, or drop a held write. Nothing gains trust.',
' revert <tp<id>|p:<source>/<slug>> [--version <id>] [--source <id>]',
' Restore the page version before an agent edit (or the version you name) with its own tier.',
' explain <ref|phrase> [--source <id>]',
' Tier, origin (including what a derived row came from), write-gate receipts, pending decisions and where',
' the row is used.',
' allow --source <id> [--uri-prefix <prefix>] [--reason-family <family>] [--reason <text>]',
' allow --remove <a<id>>',
' Stop holding instruction-like content from a source (matches the server-stamped source URI, never',
' frontmatter). Listed in review; adding one asks for its token.',
' disable --all [--undo]',
' Kill switch: write_gate.external_mode=off, write_gate.agent_mode=off, trust.agent_activation=allow.',
' --undo restores what disable replaced. Local only; asks for its token.',
' Refs: f<id> fact, t<id> take, h<id> held write, tp<id> trust proposal, a<id> allow rule, p:<source>/<slug> page',
' (a bare slug works when it lives in one source, or with --source). --yes never confirms; these commands need',
' you at a terminal on the brain host.',
].join('\n');
/** Where the owner actions run: this process's engine, or the resident owner over its local socket. */
export interface TrustBackend {
review(filter: TrustReviewFilter): Promise<TrustReview>;
explain(query: string, source: string | null): Promise<TrustExplanation[]>;
preview(input: OwnerActionInput): Promise<OwnerActionPreview>;
apply(input: OwnerActionInput, binding: string, confirmed: boolean): Promise<OwnerActionResult>;
}
export function localTrustBackend(engine: BrainEngine, config?: GBrainConfig): TrustBackend {
let principal: Promise<Principal> | undefined;
const by = () => (principal ??= maintenanceAttribution(engine).then(a => a.principal));
return {
review: filter => buildTrustReview(engine, filter),
explain: (query, source) => explainTrust(engine, query, { source }),
preview: input => previewOwnerAction(engine, input),
apply: async (input, binding, confirmed) => applyOwnerAction(engine, input, {
binding, confirmation: confirmed ? { via: 'tty' } : null, by: await by(), ...(config ? { config } : {}),
}),
};
}
const OWNER_SUBCOMMANDS = ['review', 'confirm', 'release', 'drop', 'revert', 'explain', 'allow', 'disable'] as const;
export const isTrustOwnerSubcommand = (sub: string | undefined): boolean => (OWNER_SUBCOMMANDS as readonly string[]).includes(sub ?? '');
function flag(args: string[], name: string): string | undefined {
const at = args.indexOf(name);
if (at < 0) return undefined;
const value = args[at + 1];
if (value === undefined || value.startsWith('--')) throw opError('invalid_params', `${name} needs a value.`, `Pass ${name} <value>; gbrain trust --help shows the forms.`);
return value;
}
const VALUE_FLAGS = ['--from', '--kind', '--since', '--source', '--version', '--uri-prefix', '--reason-family', '--reason', '--remove'];
function positionals(args: string[]): string[] {
const out: string[] = [];
for (let i = 0; i < args.length; i++) {
if (VALUE_FLAGS.includes(args[i]!)) { i++; continue; }
if (!args[i]!.startsWith('--')) out.push(args[i]!);
}
return out;
}
function reviewFilter(args: string[]): TrustReviewFilter {
const from = flag(args, '--from');
const kind = flag(args, '--kind');
const since = flag(args, '--since');
return { ...(from ? { sourceId: from } : {}), ...(kind ? { kind: parseTrustReviewKind(kind) } : {}), ...(since ? { since: parseTrustSince(since) } : {}) };
}
function actionInput(sub: string, args: string[]): OwnerActionInput {
const [ref] = positionals(args);
const source = flag(args, '--source') ?? null;
if (sub === 'allow') {
const remove = flag(args, '--remove');
if (remove) return { action: 'allow_remove', ref: remove };
return { action: 'allow', source, uri_prefix: flag(args, '--uri-prefix') ?? null, reason_family: flag(args, '--reason-family') ?? null, reason: flag(args, '--reason') ?? null };
}
if (sub === 'disable') {
if (!args.includes('--all')) throw opError('invalid_params', 'trust disable needs --all.', 'Run gbrain trust disable --all (or --all --undo to turn the protections back on).');
return { action: args.includes('--undo') ? 'enable' : 'disable' };
}
if (!ref) throw opError('invalid_params', `trust ${sub} needs a ref.`, 'Pass a ref such as f12, h4, tp7 or p:default/notes/alice-example; gbrain trust review lists them.');
const version = flag(args, '--version');
if (version !== undefined && !/^\d{1,18}$/.test(version)) throw opError('invalid_params', '--version takes a version id.', 'gbrain history with the page slug lists its version ids.');
return { action: sub as OwnerActionInput['action'], ref, source, ...(version ? { version: Number(version) } : {}) };
}
const LOCAL_CTX = { remote: false } as OperationContext;
/** One owner action: preview, typed confirmation when it raises trust, then apply bound to the preview. */
export async function runOwnerAction(backend: TrustBackend, input: OwnerActionInput): Promise<{ preview: OwnerActionPreview; result: OwnerActionResult }> {
const preview = await backend.preview(input);
if (preview.raises) await requireOwnerConfirmation(LOCAL_CTX, { ref: preview.ref, token: preview.token, summary: preview.summary, command: preview.command });
return { preview, result: await backend.apply(input, preview.binding, preview.raises) };
}
function resultLine(r: OwnerActionResult): string {
const tier = r.tier ? ` (now "${trustLabel(r.tier)}"${r.prior_tier && r.prior_tier !== r.tier ? `, was "${trustLabel(r.prior_tier)}"` : ''})` : '';
return `${r.ref}: ${r.status}${tier}`;
}
/**
* The longest summary one item may have in the accept-all confirmation. A longer item is skipped, never shortened: the
* owner confirms only text they were shown in full, and the item is released or confirmed on its own (#7820).
*/
const ACCEPT_ALL_ITEM_MAX = 1_000;
/**
* DX-15: accept every matching item after one typed confirmation. An item whose preview fails, whose summary is too
* long to show in one list, or that is a flagged page (its preview names the page, not the flagged text) is listed as
* skipped: it is not in the confirmation and is never applied (#7820, #7116).
*/
async function acceptAll(backend: TrustBackend, args: string[], json: boolean): Promise<void> {
const filter = reviewFilter(args);
if (!filter.sourceId && !filter.kind && !filter.since) {
throw opError('invalid_params', 'review --accept-all needs at least one filter: --from <source>, --kind <kind> or --since <when>.',
'Narrow it first, e.g. gbrain trust review --accept-all --from default --since 7d; run gbrain trust review to see what would match.');
}
const review = await backend.review(filter);
// A contradiction has no single accept: each of its commands decides it differently, so --accept-all leaves it for the owner.
const contradictions = review.items.filter(item => item.kind === 'contradiction')
.map(item => ({ ref: item.ref, reason: 'contradiction', next: 'Decide it with one of its commands: gbrain trust review --kind contradiction' }));
const flagged = review.items.filter(item => item.kind === 'flagged_page' || item.flagged).map(item => ({ ref: item.ref, reason: 'confirm_on_its_own', next: `gbrain trust confirm ${item.ref}` }));
const inputs = review.items.filter(item => item.kind !== 'contradiction' && item.kind !== 'flagged_page' && !item.flagged)
.map(item => ({ action: item.kind === 'hold' ? 'release' : 'confirm', ref: item.ref, source: item.source_id } as OwnerActionInput));
const skipLines = () => { for (const s of contradictions) console.log(`${s.ref}: skipped (a contradiction; ${s.next})`); };
if (inputs.length === 0 && flagged.length === 0) {
if (json) await writeStdoutFinal(`${JSON.stringify({ accepted: [], skipped: contradictions }, null, 2)}\n`); else if (contradictions.length) skipLines(); else console.log('Nothing matches those filters.');
return;
}
const settled = await Promise.allSettled(inputs.map(input => backend.preview(input)));
const skipped = [...flagged, ...settled.flatMap((s, i) => {
const next = `gbrain trust ${inputs[i]!.action} ${inputs[i]!.ref}`;
if (s.status === 'rejected') return [{ ref: inputs[i]!.ref!, reason: 'preview_failed', error: s.reason instanceof OperationError ? s.reason.toJSON() : String(s.reason), next }];
return s.value.summary.length > ACCEPT_ALL_ITEM_MAX ? [{ ref: inputs[i]!.ref!, reason: 'summary_too_long', next }] : [];
})];
const previewed = settled.flatMap((s, i) => s.status === 'fulfilled' && s.value.summary.length <= ACCEPT_ALL_ITEM_MAX ? [{ input: inputs[i]!, preview: s.value }] : []);
const previews = previewed.map(p => p.preview);
const command = ['gbrain', 'trust', 'review', '--accept-all', ...args.filter(a => a !== '--accept-all' && a !== '--json')];
const token = `all-${createHash('sha256').update(previews.map(p => `${p.ref}:${p.binding}`).join('\n')).digest('hex').slice(0, 8)}`;
const why = (reason: string) => reason === 'preview_failed' ? 'its preview failed'
: reason === 'confirm_on_its_own' ? 'a page flagged as instructions is confirmed only after you read it' : 'it is too long to confirm in one list';
const summary = [`Accept ${previews.length} item(s):`, ...previews.map(p => ` ${p.ref.padEnd(6)} ${p.summary}`),
...skipped.map(s => ` ${s.ref.padEnd(6)} skipped: ${why(s.reason)}, so it is not accepted (run ${s.next} on its own)`)].join('\n');
if (previews.length) await requireOwnerConfirmation(LOCAL_CTX, { ref: `${previews.length} items`, token, summary, command });
const accepted: OwnerActionResult[] = [];
const pending: Array<{ ref: string; request_id: string; poll: string }> = [];
let uncovered = 0;
const failed: Array<{ ref: string; error: unknown }> = [];
for (const { input, preview } of previewed) {
try { accepted.push(await backend.apply(input, preview.binding, preview.raises)); }
catch (error) {
const receipt = pendingReceiptOf(error);
if (receipt && !acceptPendingCovers(receipt)) uncovered++;
if (receipt) pending.push({ ref: preview.ref, request_id: receipt.request_id,
poll: pollCommand(receipt.request_id, (error as { fix?: { argv?: readonly string[] } }).fix, cliRenderContext().routing) });
else failed.push({ ref: preview.ref, error: error instanceof OperationError ? error.toJSON() : String(error) });
}
}
if (json) await writeStdoutFinal(`${JSON.stringify({ accepted, pending, failed, skipped: [...contradictions, ...skipped] }, null, 2)}\n`);
else {
skipLines();
for (const r of accepted) console.log(resultLine(r));
for (const p of pending) console.log(`${p.ref}: accepted, still pending (request ${p.request_id}; check with ${p.poll})`);
for (const f of failed) console.log(`${f.ref}: not applied (${(f.error as { message?: string }).message ?? String(f.error)})`);
for (const s of skipped) console.log(`${s.ref}: skipped, ${why(s.reason)}${'error' in s ? ` (${(s.error as { message?: string }).message ?? String(s.error)})` : ''}; run ${s.next} on its own`);
}
if (failed.length) setCliExitVerdict(1);
else if (pending.length && (!acceptPendingRequested(getCliOptions().acceptPending) || uncovered > 0)) setCliExitVerdict(PENDING_WRITE_EXIT_CODE);
else if (skipped.length) setCliExitVerdict(1);
}
/** Renders a refusal through the shared CLI envelope with its contract exit code (3 for consent refusals). */
export async function reportTrustCliError(error: unknown, json: boolean): Promise<boolean> {
if (error instanceof OperationError && !error.writeRequest) {
setCliExitVerdict(writeCliError(error, 'trust', { json }));
return true;
}
return reportPersistenceCliError(error, json);
}
/** Runs one owner subcommand against `backend`. Errors render through the shared CLI error envelope. */
export async function runTrustOwnerCommand(backend: TrustBackend, sub: string, args: string[]): Promise<void> {
const json = jsonRequested(args);
try {
if (sub === 'review') {
if (args.includes('--accept-all')) return await acceptAll(backend, args, json);
const review = await backend.review(reviewFilter(args));
if (json) await writeStdoutFinal(`${JSON.stringify(review, null, 2)}\n`); else console.log(renderTrustReview(review));
return;
}
if (sub === 'explain') {
const query = positionals(args).join(' ');
if (!query) throw opError('invalid_params', 'trust explain needs a ref or a phrase.', 'Pass a ref such as f12, t3, h4, tp7 or p:default/notes/alice-example, or words from a page title or fact.');
const items = await backend.explain(query, flag(args, '--source') ?? null);
if (json) await writeStdoutFinal(`${JSON.stringify({ items }, null, 2)}\n`); else console.log(renderTrustExplanation(items));
return;
}
const { preview, result } = await runOwnerAction(backend, actionInput(sub, args));
if (json) await writeStdoutFinal(`${JSON.stringify({ preview: { ...preview, binding: undefined }, result }, null, 2)}\n`);
else console.log(resultLine(result));
} catch (error) {
if (await reportTrustCliError(error, json)) return;
throw error;
}
}
/**
* DX-2: while a resident serve holds a PGLite brain, run the owner
* subcommand through its administration socket. False when no resident owner
* holds the brain (the caller connects normally).
*/
export async function maybeDelegateTrust(hostConfig: GBrainConfig | null, args: string[]): Promise<boolean> {
const [sub, ...rest] = args;
if (!isTrustOwnerSubcommand(sub) || args.includes('--help') || args.includes('-h')) return false;
const { resolveBrainId } = await import('../core/brain-resolver.ts');
const { getCliOptions } = await import('../core/cli-options.ts');
const { loadMounts } = await import('../core/brain-registry.ts');
const { maybeDelegateLocalAdministration, persistenceConfigForBrain } = await import('../core/persistence/local-client.ts');
const { inspectLockHolder } = await import('../core/pglite-lock.ts');
const brainId = resolveBrainId(getCliOptions().brain, process.cwd());
const config = persistenceConfigForBrain(hostConfig, brainId, brainId === 'host' ? [] : loadMounts());
if (config?.engine !== 'pglite' || !config.database_path || config.database_url || !inspectLockHolder(config.database_path).held) return false;
const call = async (operation: 'trust_read' | 'trust_preview' | 'trust_apply', params: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>> => {
const delegated = await maybeDelegateLocalAdministration(operation, params, config, { timeoutMs });
if (!delegated.handled) throw opError('owner_unavailable', 'The running serve stopped before the trust action; nothing was changed.', 'Run the same command again.');
return delegated.result as Record<string, unknown>;
};
const backend: TrustBackend = {
review: async filter => await call('trust_read', { view: 'review', filter: { source: filter.sourceId, kind: filter.kind, since: filter.since?.toISOString() } }) as unknown as TrustReview,
explain: async (query, source) => (await call('trust_read', { view: 'explain', query, source })).items as TrustExplanation[],
preview: async input => await call('trust_preview', { input }) as unknown as OwnerActionPreview,
apply: async (input, binding, confirmed) => {
const { OWNER_APPLY_TIMEOUT_MS } = await import('../core/trust/release-publish.ts');
return await call('trust_apply', { input, binding, ...(confirmed ? { confirmed: 'tty' } : {}) }, OWNER_APPLY_TIMEOUT_MS) as unknown as OwnerActionResult;
},
};
await runTrustOwnerCommand(backend, sub!, rest);
return true;
}
/**
* DX-7 / CEO-9 for `gbrain decide proposals accept`: an S9 proposal whose new
* fact is less trusted than the fact it supersedes raises trust over the old
* row, so accepting it needs the owner's typed confirmation (one prompt for a
* batch). Proposals that cross no tier return without a prompt and keep
* today's path. Throws `confirmation_required` (non-TTY) or `insufficient_scope`.
*/
export async function confirmTierCrossingAccepts(engine: BrainEngine, ids: readonly number[], command: string[]): Promise<number[]> {
if (ids.length === 0) return [];
const { compareTrust, storedTrustTier } = await import('../core/trust/tier.ts');
const rows = await engine.executeRaw<{ id: number; new_tier: string; old_tier: string }>(
`SELECT p.id, nf.trust_tier AS new_tier, xf.trust_tier AS old_tier FROM decide_proposals p
JOIN facts nf ON nf.id = p.new_fact_id JOIN facts xf ON xf.id = p.old_fact_id
WHERE p.id = ANY($1::bigint[]) AND p.status = 'pending' ORDER BY p.id`, [[...ids]]);
const crossing = rows.filter(r => compareTrust(storedTrustTier(r.new_tier), storedTrustTier(r.old_tier)) < 0);
if (crossing.length === 0) return [];
const refs = crossing.map(r => `#${Number(r.id)}`);
console.error(`[decide] accepting ${refs.join(', ')} lets a less trusted fact supersede a more trusted one; the same check as gbrain trust confirm applies (gbrain trust review lists every trust decision).`);
const token = crossing.length === 1 ? `s9-${Number(crossing[0]!.id)}` : `s9-${createHash('sha256').update(refs.join(',')).digest('hex').slice(0, 8)}`;
await requireOwnerConfirmation(LOCAL_CTX, {
ref: refs.join(', '), token, command: command.filter(a => a !== '--yes' && a !== '--json'),
summary: crossing.map(r => `Accept ${`#${Number(r.id)}`}: a "${trustLabel(storedTrustTier(r.new_tier))}" fact supersedes a "${trustLabel(storedTrustTier(r.old_tier))}" one`).join('\n'),
});
return crossing.map(r => Number(r.id));
}