Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Write-time trust tiers per channel (#5575: A3, CEO-21, CEO-26/DX-8, ENG-18).
* Deterministic, never guessed: the tier comes from who is writing and through
* which path, and frontmatter or an agent's `content_origin` can only lower it.
*
* - Remote MCP / serve-http / thin-client agent writes: agent_written.
* - Local CLI `remember` / `put_page` / `capture` and the other journaled
* agent verbs: agent_written (a local agent with a shell is
* indistinguishable from the human; only CEO-9 confirmation raises).
* - `content_origin: tool_output` lowers an agent write to external_untrusted.
* - Connector jobs (Google, GitHub), webhook and ingestion-daemon captures and
* third-party transcript imports: external_untrusted.
* - Owner-source sync / import / reconcile / file repair: operator_curated (or
* the source's `sources set-trust` default, never above operator_curated),
* lowered by the page's frontmatter markers: the lower-only `trust_tier`
* marker, `source_kind` / `ingested_via` / `captured_via` channel stamps,
* `transcript_import`, clipper `source_url`, `provenance: auto-extracted`
* and `dream_generated`.
*
* The coordinator declares `preparedTrust ?? requestChannelTrust(row)` once per
* publication (persistence/coordinator.ts, group-publish.ts); preparers that
* know more (sync markers, derivation inputs) declare their own.
*/
import type { BrainEngine } from '../engine.ts';
import type { WriteRequest } from '../persistence/model.ts';
import { CONNECTOR_SOURCE_KINDS } from '../persistence/connector-identity.ts';
import { asciiLower, asciiLowerSql, edgeTrimSql } from '../edge-whitespace.ts';
import {
CONTENT_ORIGINS, OWNER_TIER_FLOOR, TRUST_TIER_RANK, compareTrust, contentOriginTier, effectiveWriteTrust, isTrustTier, minTrust, trustRankSql,
type ContentOrigin, type TrustTier, type WriteTrust,
} from './tier.ts';
/** Journaled verbs an agent (remote or local) calls directly; their rows are agent_written unless lowered. */
export const AGENT_WRITE_OPERATIONS: readonly string[] = [
'put_page', 'put_pages', 'capture', 'edit_page', 'append_page', 'delete_page', 'restore_page', 'revert_version', 'remember',
'add_tag', 'remove_tag', 'add_timeline_entry', 'add_link', 'remove_link', 'takes_add', 'takes_update', 'takes_supersede', 'takes_resolve',
'takes_remove', 'loops_close', 'relink_facts', 'decide_proposal',
];
/**
* Intent kinds whose preparer computes the tier from the page (owner-source sync and import paths), and
* the owner's `quarantine clear`, which only removes a gate-owned marker and keeps the page's tier.
*/
const OWNER_SOURCE_KINDS = ['canonical_reconcile', 'managed_file_import', 'managed_file_repair', 'managed_grandfather', 'managed_quarantine_clear'];
/** The `captured_via` stamp of a Life Chronicle event page (chronicle/publish.ts): model-extracted from its depth page. */
export const CHRONICLE_CAPTURED_VIA = 'life-chronicle:auto';
/** Page frontmatter `source_kind` / `ingested_via` / `captured_via` values written by an ingestion capture (external). */
export const EXTERNAL_CAPTURE_KINDS: readonly string[] = ['webhook', 'file-watcher', 'inbox-folder', 'cron-scheduler', 'ingest_capture'];
/** ...and by an agent through a gbrain verb, or by the Life Chronicle extractor (agent_written). */
const AGENT_CAPTURE_KINDS = ['put_page', 'capture-cli', 'capture-mcp', 'capture', CHRONICLE_CAPTURED_VIA];
/**
* Harnesses whose `transcript_import` pages are the user's own sessions with
* their agent (or their own chat exports): relayed user turns count as
* agent_written. Any other harness is a third-party transcript: external.
*/
export const OWN_SESSION_HARNESSES: readonly string[] = [
'claude-code', 'codex', 'openclaw', 'cursor', 'hermes', 'gemini-cli', 'opencode', 'chatgpt', 'claude', 'grok',
];
/**
* The internal intent kind of a journaled request (`managed_*`, `connector_v2_*`,
* `canonical_reconcile`, `code_projection_reindex`), or ''. A caller's own `kind`
* param (a fact kind on remember, a take kind on takes_add) is not a channel.
*/
function internalIntentKind(intent: Record<string, unknown> | null | undefined): string {
const kind = typeof intent?.kind === 'string' ? intent.kind : '';
return /^(?:managed_|connector_v2_|canonical_|code_projection_)/.test(kind) ? kind : '';
}
/** The origin channel name of a journaled request, e.g. `mcp:put_page`, `cli:remember`, `connector:google`. */
export function requestChannel(row: Pick<WriteRequest, 'operation' | 'authority' | 'intent'>): string {
const kind = internalIntentKind(row.intent);
if (kind.startsWith('connector_v2_') || kind.startsWith('managed_connector_')) return `connector:${kind}`;
if (kind) return kind;
return `${row.authority?.remote === true ? 'mcp' : 'cli'}:${row.operation}`;
}
/** The agent's declared content origin from a request intent (validated at admission); undefined when absent. */
export function intentContentOrigin(intent: Record<string, unknown> | null | undefined): TrustTier | undefined {
const value = intent?.content_origin;
return value === undefined || value === null ? undefined : contentOriginTier(value);
}
/**
* The tier a journaled request earns from its channel alone, or undefined for
* intents whose preparer must declare one (owner-source sync, derived
* maintenance) or that write no tiered rows. Undeclared rows stamp `unknown`.
*/
export function requestChannelTrust(row: Pick<WriteRequest, 'id' | 'operation' | 'authority' | 'intent'>): WriteTrust | undefined {
const kind = internalIntentKind(row.intent);
const declared = row.intent?.content_origin;
const origin = { channel: requestChannel(row), request_id: row.id,
...((CONTENT_ORIGINS as readonly unknown[]).includes(declared) ? { content_origin: declared as ContentOrigin } : {}) };
if (kind.startsWith('connector_v2_') || kind.startsWith('managed_connector_')) return effectiveWriteTrust({ channel: 'external_untrusted', origin });
if (row.authority?.remote === true) {
const lowered = intentContentOrigin(row.intent);
return effectiveWriteTrust({ channel: 'agent_written', lowerTo: lowered ? [lowered] : [], origin });
}
if (kind.startsWith('managed_sync_') || kind.startsWith('managed_maintenance_') || kind.startsWith('managed_facts_')
|| kind.startsWith('managed_atom_') || kind.startsWith('managed_generation_') || OWNER_SOURCE_KINDS.includes(kind)) return undefined;
if (AGENT_WRITE_OPERATIONS.includes(row.operation)) {
const lowered = intentContentOrigin(row.intent);
return effectiveWriteTrust({ channel: 'agent_written', lowerTo: lowered ? [lowered] : [], origin });
}
return undefined;
}
const str = (value: unknown) => (typeof value === 'string' ? value.trim() : '');
/**
* #6533: the `extracted_by` prefix extract_atoms stamps on every atom it writes. Legacy atoms
* (before `dream_generated`) carry only this, so it is an agent_written signal on its own.
*/
export const EXTRACT_ATOMS_EXTRACTOR_PREFIX = 'extract_atoms';
/** The tier a single channel stamp names (`source_kind`, `ingested_via`, `captured_via`), or undefined. */
function stampTier(value: unknown): TrustTier | undefined {
const v = str(value);
if (!v) return undefined;
if (EXTERNAL_CAPTURE_KINDS.includes(v)) return 'external_untrusted';
if (v.startsWith('mcp:') || AGENT_CAPTURE_KINDS.includes(v)) return 'agent_written';
if (v.startsWith('connector:') || (CONNECTOR_SOURCE_KINDS as readonly string[]).includes(v)) return 'external_untrusted';
return undefined;
}
/**
* Every lowering signal in a page's frontmatter (CEO-21). They can only lower:
* a `trust_tier: user_confirmed` marker typed by hand is ignored (it names no
* tier below the channel's), and nothing here can raise.
*/
export function frontmatterTrustCaps(frontmatter: Record<string, unknown> | null | undefined): TrustTier[] {
const fm = frontmatter ?? {};
const caps: TrustTier[] = [];
if (isTrustTier(fm.trust_tier)) caps.push(fm.trust_tier);
for (const key of ['source_kind', 'ingested_via', 'captured_via']) {
const tier = stampTier(fm[key]);
if (tier) caps.push(tier);
}
const transcript = fm.transcript_import as { harness?: unknown } | undefined;
if (transcript && typeof transcript === 'object') {
caps.push(OWN_SESSION_HARNESSES.includes(asciiLower(str(transcript.harness))) ? 'agent_written' : 'external_untrusted');
}
if (str(fm.source_url) && (str(fm.clipped_at) || str(fm.clipper) || str(fm.captured_via) === 'clipper' || str(fm.type) === 'clipping')) {
caps.push('external_untrusted');
}
if (str(fm.provenance) === 'auto-extracted' || fm.dream_generated === true || str(fm.dream_generated) === 'true'
|| str(fm.extracted_by).startsWith(EXTRACT_ATOMS_EXTRACTOR_PREFIX)) caps.push('agent_written');
return caps;
}
/**
* `frontmatterTrustCaps` as SQL over a jsonb frontmatter expression: one rank
* term per signal (NULL when it does not apply), for `LEAST(...)` in the trust
* backfill of claimed sources (trust/claim.ts). `fm` is a trusted alias or
* column expression, never caller input; every literal comes from the lists
* above. Kept in step with `frontmatterTrustCaps` by test/trust-claim.test.ts.
*/
export function frontmatterTrustCapsSql(fm: string): string[] {
const list = (values: readonly string[]) => values.map(v => `'${v.replace(/'/g, "''")}'`).join(',');
const text = (key: string, base = fm) => `(CASE WHEN jsonb_typeof(${base}->'${key}') = 'string' THEN NULLIF(${edgeTrimSql(`${base}->>'${key}'`)}, '') END)`;
const stamp = (key: string) => `CASE WHEN ${text(key)} IN (${list(EXTERNAL_CAPTURE_KINDS)}) THEN ${TRUST_TIER_RANK.external_untrusted}
WHEN ${text(key)} LIKE 'mcp:%' OR ${text(key)} IN (${list(AGENT_CAPTURE_KINDS)}) THEN ${TRUST_TIER_RANK.agent_written}
WHEN ${text(key)} LIKE 'connector:%' OR ${text(key)} IN (${list(CONNECTOR_SOURCE_KINDS)}) THEN ${TRUST_TIER_RANK.external_untrusted} END`;
return [
`CASE WHEN jsonb_typeof(${fm}->'trust_tier') = 'string' THEN NULLIF(${trustRankSql(`(${fm}->>'trust_tier')`)}, 0) END`,
...['source_kind', 'ingested_via', 'captured_via'].map(stamp),
`CASE WHEN jsonb_typeof(${fm}->'transcript_import') IN ('object', 'array') THEN
CASE WHEN ${asciiLowerSql(text('harness', `(${fm}->'transcript_import')`))} IN (${list(OWN_SESSION_HARNESSES)}) THEN ${TRUST_TIER_RANK.agent_written} ELSE ${TRUST_TIER_RANK.external_untrusted} END END`,
`CASE WHEN ${text('source_url')} IS NOT NULL AND (${text('clipped_at')} IS NOT NULL OR ${text('clipper')} IS NOT NULL
OR ${text('captured_via')} = 'clipper' OR ${text('type')} = 'clipping') THEN ${TRUST_TIER_RANK.external_untrusted} END`,
`CASE WHEN ${text('provenance')} = 'auto-extracted' OR ${fm}->'dream_generated' = 'true'::jsonb OR ${text('dream_generated')} = 'true'
OR ${text('extracted_by')} LIKE '${EXTRACT_ATOMS_EXTRACTOR_PREFIX.replace(/_/g, '\\_')}%' THEN ${TRUST_TIER_RANK.agent_written} END`,
];
}
/** A per-source default set by `gbrain sources set-trust` (sources.config.trust_tier), clamped to operator_curated. */
export function sourceDefaultTier(config: Record<string, unknown> | null | undefined): TrustTier {
const value = config?.trust_tier;
return isTrustTier(value) ? minTrust(value, OWNER_TIER_FLOOR) : OWNER_TIER_FLOOR;
}
/**
* The tier of an owner-source sync / import of one page: the source default
* lowered by the page's markers (connector sources are external outright).
*/
export function ownerPageTrust(input: {
frontmatter: Record<string, unknown> | null | undefined;
sourceConfig?: Record<string, unknown> | null;
channel: string;
requestId?: string | null;
sourceUri?: string | null;
}): WriteTrust {
const kind = str(input.sourceConfig?.kind);
const base = (CONNECTOR_SOURCE_KINDS as readonly string[]).includes(kind) ? 'external_untrusted' : sourceDefaultTier(input.sourceConfig);
return effectiveWriteTrust({
channel: base, lowerTo: frontmatterTrustCaps(input.frontmatter),
origin: { channel: input.channel, ...(input.requestId ? { request_id: input.requestId } : {}), ...(input.sourceUri ? { source_uri: input.sourceUri } : {}) },
});
}
/**
* CEO-21: the lower-only `trust_tier` marker a write-through stamps into the
* canonical file when the write is below operator_curated. An existing lower
* marker is kept (min). Returns the frontmatter unchanged at owner tiers.
*/
export function stampTrustMarker(frontmatter: Record<string, unknown>, tier: TrustTier): Record<string, unknown> {
if (compareTrust(tier, OWNER_TIER_FLOOR) >= 0) return frontmatter;
const prior = frontmatter.trust_tier;
const marker = isTrustTier(prior) ? minTrust(prior, tier) : tier;
if (prior === marker) return frontmatter;
return { ...frontmatter, trust_tier: marker };
}
/** The source config `ownerImportTrust` reads. */
export const SOURCE_TRUST_CONFIG_SQL = 'SELECT config FROM sources WHERE id = $1';
/**
* The tier of a journaled owner-source write of one page (managed sync,
* import, reconcile, file repair, grandfather): `ownerPageTrust` from the
* source's config, capped at agent_written when a remote caller admitted it.
*/
export async function ownerImportTrust(engine: Pick<BrainEngine, 'executeRaw'>, row: Pick<WriteRequest, 'id' | 'source_id' | 'authority' | 'intent' | 'operation'>,
frontmatter: Record<string, unknown> | null | undefined, sourceUri?: string | null): Promise<WriteTrust> {
const [source] = await engine.executeRaw<{ config: Record<string, unknown> | string | null }>(SOURCE_TRUST_CONFIG_SQL, [row.source_id]);
const config = typeof source?.config === 'string' ? JSON.parse(source.config) as Record<string, unknown> : source?.config ?? null;
const trust = ownerPageTrust({ frontmatter, sourceConfig: config, channel: requestChannel(row), requestId: row.id, sourceUri });
return row.authority?.remote === true ? { ...trust, tier: minTrust(trust.tier, 'agent_written') } : trust;
}
/** A direct (unmanaged) import declares the tier its caller passed to the write gate (ENG-18); absent: undeclared. */
export function writeTrustOfGate(input: { tier: TrustTier; origin?: { channel?: string | null; connector?: string | null; source_uri?: string | null } | null; requestId?: string | null } | undefined): WriteTrust | undefined {
if (!input) return undefined;
const o = input.origin;
return { tier: input.tier, origin: { channel: o?.channel ?? 'import', ...(o?.connector ? { connector: o.connector } : {}), ...(o?.source_uri ? { source_uri: o.source_uri } : {}),
...(input.requestId ? { request_id: input.requestId } : {}) } };
}
/** The write-gate input for an owner-source page import: `ownerImportTrust` as the gate sees it (ENG-18). */
export async function ownerGateInput(engine: Pick<BrainEngine, 'executeRaw'>, row: Pick<WriteRequest, 'id' | 'source_id' | 'authority' | 'intent' | 'operation'>,
frontmatter: Record<string, unknown> | null | undefined, sourceUri?: string | null) {
const trust = await ownerImportTrust(engine, row, frontmatter, sourceUri);
return { tier: trust.tier, origin: { channel: trust.origin?.channel ?? null, source_uri: trust.origin?.source_uri ?? null }, requestId: row.id };
}
/**
* The write-gate input of an unmanaged owner file import (direct sync / import of a source's files): the source default
* lowered by markers. `sourceUri` (the file's source path) lets an owner allow rule scoped by URI prefix apply.
*/
export async function ownerSourceGateInput(engine: Pick<BrainEngine, 'executeRaw'>, sourceId: string, frontmatter: Record<string, unknown> | null | undefined, sourceUri?: string | null) {
const [source] = await engine.executeRaw<{ config: Record<string, unknown> | string | null }>('SELECT config FROM sources WHERE id = $1', [sourceId]);
const config = typeof source?.config === 'string' ? JSON.parse(source.config) as Record<string, unknown> : source?.config ?? null;
const trust = ownerPageTrust({ frontmatter, sourceConfig: config, channel: 'import' });
return { tier: trust.tier, origin: { channel: 'import', ...(sourceUri ? { source_uri: sourceUri } : {}) }, requestId: null };
}
/**
* The `trust_tier` marker is hash-ephemeral (utils.ts), so an import whose only
* change is adding or removing it would read as unchanged; removing it by hand
* is the owner act that restamps a page on the next sync (CEO-21), so it counts.
*/
/**
* CEO-21: `frontmatter` with its trust_tier marker set back to what the caller
* supplied (removed when it supplied none). No-op detection compares this
* view, so a server-stamped marker never turns an unchanged write into a write.
*/
export function suppliedTrustMarkerView(frontmatter: Record<string, unknown>, supplied: unknown): Record<string, unknown> {
const { trust_tier: _stamped, ...rest } = frontmatter;
return supplied === undefined ? rest : { ...rest, trust_tier: supplied };
}
export function trustMarkerChanged(prior: Record<string, unknown> | null | undefined, next: Record<string, unknown> | null | undefined): boolean {
return (prior?.trust_tier ?? null) !== (next?.trust_tier ?? null);
}