Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { currentVerifiedLocalWriter, existingHostIdFor, readLocalWriter } from './identity.ts';
import type { Principal, SqlEngine, WriteRequest } from './model.ts';
import type { BrainEngine } from '../engine.ts';
import { withWriteAttribution } from './context.ts';
import type { WriteTrust } from '../trust/tier.ts';
import { requestChannelTrust } from '../trust/channel.ts';
export { ownerSourceGateInput, suppliedTrustMarkerView, trustMarkerChanged, writeTrustOfGate } from '../trust/channel.ts';
/**
* The actor the database stamps on rows written inside withCoordinatedWrite
* or withWriteAttribution. `requestId` is persistence_requests.id (globally
* unique), or null for a maintenance write with no journal request.
*/
export interface WriteAttribution {
requestId: string | null;
principal: Principal;
/** The tier and origin of the rows written (trust/tier.ts). Undeclared: rows are stamped `unknown` unless an enclosing scope declared one. */
trust?: WriteTrust;
}
export { withWriteAttribution };
/**
* The HTTP MCP request header a caller uses to say which AI made a write ("Claude Code", "Codex", a job name). The
* host knows which agent is calling through one credential; gbrain does not. It is a label the caller declares and
* gbrain never verifies: it is stored on the write request and shown as `agent_label` by attribution reads, and
* nothing that authorizes (grants, access rules, trust tiers) reads it. Not "writer": that word names the principal
* and the write owner (persistence_local_writers, `gbrain sources writer`). Stdio and the local CLI have no request
* headers and record none; their principal already names the lane.
*/
export const AGENT_LABEL_HEADER = 'X-Gbrain-Agent-Label';
/** A label safe to store and render, or undefined: 1-120 printable ASCII characters after trimming, else dropped. */
export function parseAgentLabel(value: string | null | undefined): string | undefined {
const text = value?.trim();
return text && /^[\x20-\x7e]{1,120}$/.test(text) ? text : undefined;
}
/** A journaled request publishes as itself. */
export function requestAttribution(row: Pick<WriteRequest, 'id' | 'principal_kind' | 'principal_id'>): WriteAttribution {
return { requestId: row.id, principal: { kind: row.principal_kind, id: row.principal_id } };
}
/** A journaled publication: the request's actor, and the tier its preparer declared or its channel earns (#5575 A3). */
export function publicationAttribution(row: Pick<WriteRequest, 'id' | 'principal_kind' | 'principal_id' | 'operation' | 'authority' | 'intent'>, trust?: WriteTrust): WriteAttribution {
const declared = trust ?? requestChannelTrust(row);
return { ...requestAttribution(row), ...(declared ? { trust: declared } : {}) };
}
/** A write by a known principal that has no journal request (manual links, source lifecycle). */
export function principalAttribution(principal: Principal): WriteAttribution {
return { requestId: null, principal };
}
/**
* The executing maintenance principal: the verified local writer of this call
* (server-side owner work), else this installation's local CLI registration,
* else the host itself when the installation has no usable registration.
* Attribution records the actor and never authorizes, so an unreadable
* registration falls back to the host instead of failing the write, and it
* never mints an identity file: an installation without one (an ephemeral
* demo brain, a first direct import) is recorded as `host:unregistered`. The
* registration found is memoized per engine (an in-process rotation keeps
* naming the registration this process started with): per-page maintenance
* loops would otherwise repeat a file read and two queries for every page.
*/
export async function maintenanceAttribution(engine: SqlEngine): Promise<WriteAttribution> {
const verified = currentVerifiedLocalWriter();
if (verified) return principalAttribution(verified.principal);
let registration = installationRegistration.get(engine);
if (!registration) {
registration = readLocalWriter(engine, 'cli').then(local => local.id);
installationRegistration.set(engine, registration);
}
try { return principalAttribution({ kind: 'local_cli', id: await registration }); }
catch {
installationRegistration.delete(engine);
return principalAttribution({ kind: 'application', id: `host:${existingHostIdFor(engine) ?? 'unregistered'}` });
}
}
const installationRegistration = new WeakMap<SqlEngine, Promise<string>>();
/**
* One unmanaged legacy transaction (direct import, extract_facts, extract-takes,
* stale-atom retirement) whose rows carry the maintenance principal. A managed
* brain's guard still refuses these writes: this sets no coordinator capability.
*/
export async function maintenanceTransaction<T>(engine: BrainEngine, fn: (tx: BrainEngine) => Promise<T>, trust?: WriteTrust): Promise<T> {
const attribution = await maintenanceAttribution(engine);
return engine.transaction(tx => withWriteAttribution(tx, trust ? { ...attribution, trust } : attribution, () => fn(tx)));
}