Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Activation control for proactive surfaces (#5575: CEO-20, DX-10, DX-13).
*
* Facts, takes, timeline entries and pages at `agent_written` or lower that
* carry a write-gate flag in an instruction family (standing_instruction,
* override, exfiltration, credential) are never injected by a proactive
* surface (hook turn context, context engine, context_pack, volunteer and
* retrieval reflex, core and hot-memory delivery) until the owner confirms
* them, which raises their tier above `agent_written`. Explicit reads
* (query, search, recall, get_page) still return them, labeled
* "unconfirmed, agent-written". Deterministic: one indexed query per table,
* zero model calls. `trust.agent_activation=allow` opts out.
*
* Proactive surfaces partition their candidates here (after ranking, before
* rendering) so they can say how much they withheld: the suppression notice
* carries a count and the review command, never the content.
*/
import type { BrainEngine } from '../engine.ts';
import type { Notice } from '../agent-output.ts';
import { admitsTrust, minTrust, storedTrustTier, type TrustTier } from '../trust/tier.ts';
import { guestView, loadGuestMarks, unattributedGuest, withGuestSourceSql, type GuestStamp } from '../guests/marker.ts';
import { activationSuppressedSql, type EligibilityTable } from './sql.ts';
import type { ReadEligibility } from './policy.ts';
type Exec = Pick<BrainEngine, 'executeRaw'>;
export interface ActivationRef { table: EligibilityTable; id: number }
export interface ActivationVerdict {
/** Row tier, for labels. */
tier: TrustTier;
/** Below the effective read floor (never shown, not counted as suppressed). */
belowFloor: boolean;
/** Withheld by activation control (counted in the suppression notice). */
suppressed: boolean;
/**
* Carries an instruction-family write-gate flag the owner has not confirmed, whatever the policy:
* under `trust.agent_activation=allow` (the default) a kept row is injected with the
* "unconfirmed, agent-written" label, so it never reaches proactive context unlabeled.
*/
unconfirmed: boolean;
}
const TABLE_SQL: Readonly<Record<EligibilityTable, string>> = {
facts: 'facts', takes: 'takes', timeline_entries: 'timeline_entries', pages: 'pages',
};
/** Tier and suppression state for each referenced row; rows that no longer exist are absent. */
export async function activationVerdicts(engine: Exec, refs: readonly ActivationRef[], policy: ReadEligibility): Promise<Map<string, ActivationVerdict>> {
const out = new Map<string, ActivationVerdict>();
const byTable = new Map<EligibilityTable, number[]>();
for (const r of refs) if (Number.isFinite(r.id)) byTable.set(r.table, [...(byTable.get(r.table) ?? []), r.id]);
for (const [table, ids] of byTable) {
const rows = await engine.executeRaw<{ id: number | string; trust_tier: string; flagged: boolean }>(
`SELECT a.id, a.trust_tier, ${activationSuppressedSql(table, 'a')} AS flagged FROM ${TABLE_SQL[table]} a WHERE a.id = ANY($1::bigint[])`, [[...new Set(ids)]]);
for (const row of rows) {
const tier = storedTrustTier(row.trust_tier);
const flagged = row.flagged === true;
out.set(`${table}:${Number(row.id)}`, {
tier,
belowFloor: policy.floor ? !admitsTrust(tier, policy.floor) : false,
suppressed: policy.suppressFlagged === true && flagged,
unconfirmed: flagged,
});
}
}
return out;
}
export interface ActivationPartition<T> {
/** `unconfirmed`: the kept row carries an unconfirmed instruction-family flag; render its label. */
kept: Array<{ item: T; tier: TrustTier; unconfirmed: boolean }>;
/** Items activation control withheld (authorized for an explicit read, not for injection). */
withheld: number;
}
/**
* Splits proactive candidates into what may be injected and how many were
* withheld. An item whose row cannot be read is dropped (fail-closed: a
* proactive surface never injects what it could not check). Order is kept.
*/
export async function partitionForActivation<T>(
engine: Exec, items: readonly T[], refOf: (item: T) => ActivationRef, policy: ReadEligibility,
): Promise<ActivationPartition<T>> {
if (items.length === 0) return { kept: [], withheld: 0 };
let verdicts: Map<string, ActivationVerdict>;
try { verdicts = await activationVerdicts(engine, items.map(refOf), policy); }
catch { return { kept: [], withheld: 0 }; }
const kept: ActivationPartition<T>['kept'] = [];
let withheld = 0;
for (const item of items) {
const ref = refOf(item);
const v = verdicts.get(`${ref.table}:${ref.id}`);
if (!v || v.belowFloor) continue;
if (v.suppressed) { withheld++; continue; }
kept.push({ item, tier: v.tier, unconfirmed: v.unconfirmed });
}
return { kept, withheld };
}
/** The command that lists every unconfirmed item for the owner (DX-7 `gbrain trust review`). */
export const TRUST_REVIEW_COMMAND = ['gbrain', 'trust', 'review'] as const;
/** DX-10: the structured suppression notice. A count and the review command; never the withheld content. */
export function activationSuppressionNotice(withheld: number, surface: string): Notice | null {
if (withheld <= 0) return null;
return {
code: 'memory_suppressed',
kind: 'info',
why: `${withheld} unconfirmed agent-written ${withheld === 1 ? 'memory was' : 'memories were'} not used in ${surface} because ${withheld === 1 ? 'it reads' : 'they read'} like instructions. They stay searchable; the owner reviews them with gbrain trust review.`,
fix: { argv: [...TRUST_REVIEW_COMMAND], consent: [], actor: 'user', requires_exclusive: false,
why: 'Lists unconfirmed agent-written memories with the command to confirm or drop each; only the owner can confirm.' },
};
}
/** The wire form proactive results carry alongside their text (DX-10). */
export interface SuppressionSummary { withheld: number; review: string }
export function suppressionSummary(withheld: number): SuppressionSummary | undefined {
return withheld > 0 ? { withheld, review: TRUST_REVIEW_COMMAND.join(' ') } : undefined;
}
export interface PageKey { source_id: string; slug: string }
/**
* Page variant for surfaces that hold (source_id, slug) rather than ids
* (retrieval reflex pointers, volunteered pages): verdicts per live page
* key, with the label fields. Missing pages are absent (callers drop them).
*/
export async function pageActivationVerdicts(engine: Exec, keys: readonly PageKey[], policy: ReadEligibility):
Promise<Map<string, ActivationVerdict & { origin: unknown; guest?: GuestStamp }>> {
const out = new Map<string, ActivationVerdict & { origin: unknown; guest?: GuestStamp }>();
if (keys.length === 0) return out;
const rows = await withGuestSourceSql(guestSql => engine.executeRaw<{ id: number; source_id: string; slug: string; trust_tier: string; write_origin: unknown; flagged: boolean; guest: boolean }>(
`SELECT a.id, a.source_id, a.slug, a.trust_tier, a.write_origin, ${activationSuppressedSql('pages', 'a')} AS flagged,
${guestSql('s.config', 'a.source_id')} AS guest FROM pages a LEFT JOIN sources s ON s.id = a.source_id
WHERE a.deleted_at IS NULL AND (a.source_id, a.slug) IN (SELECT * FROM unnest($1::text[], $2::text[]))`,
[keys.map(k => k.source_id), keys.map(k => k.slug)]));
// GBRA-504: a page in a guest source carries its guest mark (one batched read), or reads unattributed.
const marks = rows.some(r => r.guest === true) ? await loadGuestMarks(engine, rows.filter(r => r.guest === true).map(r => Number(r.id))) : null;
for (const row of rows) {
const tier = row.guest === true ? minTrust(storedTrustTier(row.trust_tier), 'external_untrusted') : storedTrustTier(row.trust_tier);
const flagged = row.flagged === true;
out.set(pageKey(row), { tier, origin: row.write_origin, belowFloor: policy.floor ? !admitsTrust(tier, policy.floor) : false,
suppressed: policy.suppressFlagged === true && flagged, unconfirmed: flagged,
...(row.guest === true ? { guest: guestView(marks?.get(Number(row.id)) ?? unattributedGuest(), false) } : {}) });
}
return out;
}
export const pageKey = (k: PageKey) => `${k.source_id}\u0000${k.slug}`;