Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import type { BrainEngine } from '../engine.ts';
import type { ParsedPage } from '../import-file.ts';
import { factsAbsorbWriteKey } from '../facts/dead-absorb-retry.ts';
import { isFactsBackstopEligible } from '../facts/eligibility.ts';
import { isFactsExtractionEnabled } from '../facts/extract.ts';
import { resolvePageWriteNotabilityFilter } from '../facts/notability-filter.ts';
import { MinionQueue } from '../minions/queue.ts';
import type { MinionJobStatus } from '../minions/types.ts';
import type { PageSnapshot } from '../page-state/types.ts';
import { OperationError, opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { readManagedMode } from './managed-mode.ts';
import { isConnectorIntentKind } from './connector-identity.ts';
import { connectorFactsSession } from '../facts/retire.ts';
import { authorizeStoredRequest, authorizeWrite } from './authority.ts';
import { completeEffect } from './effect-journal.ts';
import { guardEffectSource } from './effect-recovery.ts';
import { derivedExtractionSkip } from './derived-extraction-gate.ts';
import { isGuestWrite, skipsGuestNote } from '../guests/derived.ts';
import { bodyUnread, isSegmentedPage } from '../page-body/page-shape.ts';
import type { PersistenceEffect } from './effect-model.ts';
import type { WriteRequest } from './model.ts';
export type FactsBackstopStatus = { queued: true } | { skipped: string };
export async function authorizeFactsBackstop(engine: BrainEngine, row: WriteRequest, lock = false): Promise<void> {
if (derivedExtractionSkip(row.authority) === 'slug_bound_client') {
throw opError('permission_denied', 'A confined writer cannot extract into unnamed entity pages.',
`The write of ${row.slug} came from a slug-bound client, so facts are not extracted into entity pages outside its prefixes; the page itself is written. Widening that client's grant is the brain host operator's decision.`);
}
await authorizeStoredRequest(engine, row, lock);
await authorizeWrite(engine, row.authority, 'extract_facts', row.slug, lock);
// A grant may have become confined while the page itself remains in scope.
if (row.principal_kind === 'oauth_client') {
const [current] = await engine.executeRaw<{ bound_slug_prefixes: unknown }>('SELECT bound_slug_prefixes FROM oauth_clients WHERE client_id=$1', [row.principal_id]);
if (current?.bound_slug_prefixes != null) throw opError('permission_denied', 'The current writer grant is confined.',
`OAuth client ${row.principal_id} is now bound to slug prefixes, so facts from ${row.slug} are not extracted; the page itself is written. Widening the grant is the brain host operator's decision.`,
{ fix: readFix('Lists the OAuth clients with their bound slug prefixes, read-only.', { argv: ['gbrain', 'auth', 'clients', '--json'] }) });
} else if (row.principal_kind === 'local_cli' || row.principal_kind === 'local_stdio') {
const [current] = await engine.executeRaw<{ prefixes: unknown }>("SELECT grant_ceiling->'slugPrefixes' AS prefixes FROM persistence_local_writers WHERE id=$1::uuid", [row.principal_id]);
if (current?.prefixes != null) throw opError('permission_denied', 'The current writer grant is confined.',
`Local writer ${row.principal_id} now has slug prefixes, so facts from ${row.slug} are not extracted; the page itself is written. Replacing the grant is the user's decision.`,
{ fix: readFix('Lists the local writer registrations and their grants, read-only.', { argv: ['gbrain', 'auth', 'local-writer', 'list', '--json'] }) });
}
}
/** Job states from which a facts-absorb job can still start, and so can still be superseded by a newer revision. */
const STARTABLE_JOB_STATES: readonly MinionJobStatus[] = ['waiting', 'delayed', 'paused', 'waiting-children', 'active'];
/**
* Whether an extraction bound to this page row has yet to read it: a
* facts-backstop effect still in the outbox, or a facts-absorb job that can
* still start. Both carry the page id and revision, so the next revision ends
* them as `superseded`.
*/
async function extractionPendingForPage(engine: BrainEngine, pageId: number): Promise<boolean> {
const [row] = await engine.executeRaw<{ pending: boolean }>(
`SELECT EXISTS (SELECT 1 FROM persistence_effects
WHERE kind = 'facts-backstop' AND state IN ('queued', 'running') AND data->>'page_id' = $1)
OR EXISTS (SELECT 1 FROM minion_jobs
WHERE name = 'facts-absorb' AND status = ANY($2::text[]) AND data->>'page_id' = $1) AS pending`,
[String(pageId), [...STARTABLE_JOB_STATES]]);
return row?.pending === true;
}
async function extractionCompletedForPage(engine: BrainEngine, pageId: number): Promise<boolean> {
const [row] = await engine.executeRaw<{ done: boolean }>(
`SELECT EXISTS (SELECT 1 FROM minion_jobs
WHERE name = 'facts-absorb' AND status = 'completed' AND data->>'page_id' = $1
AND result->>'skipped' IS NULL) AS done`,
[String(pageId)]);
return row?.done === true;
}
/**
* #6042: the extractor reads compiled_truth only. When the page was live and
* already eligible before this write and the write keeps its compiled_truth
* (a title, tag, frontmatter or timeline change, such as `repair timeline`
* writing back rows the database already holds), there is nothing new to
* extract, provided an extraction already completed for this page. A page no
* extraction ever completed for still queues one (#6071, maintainer decision B),
* and so does a page with an extraction still pending: this write supersedes it,
* so the write must queue in its place.
*/
async function bodyAlreadyOffered(engine: BrainEngine, slug: string, page: ParsedPage, before: PageSnapshot | null): Promise<boolean> {
const live = before && !before.page.deleted_at ? before.page : null;
// A segmented prior body is not compared; the extraction's watermark finds nothing appended and calls no model.
if (!live || isSegmentedPage(live) || bodyUnread(page) || live.compiled_truth !== page.compiled_truth) return false;
if (!isFactsBackstopEligible(slug, live).ok) return false;
if (!(await extractionCompletedForPage(engine, live.id))) return false;
return !(await extractionPendingForPage(engine, live.id));
}
/**
* Provider availability belongs to the durable job's execution process.
* `before` is the page as this write found it (null for a new page).
*/
export async function prepareFactsBackstop(engine: BrainEngine, row: WriteRequest, page: ParsedPage, before: PageSnapshot | null = null): Promise<FactsBackstopStatus> {
const confined = derivedExtractionSkip(row.authority);
if (confined) return { skipped: confined };
if (skipsGuestNote('facts_backstop', await isGuestWrite(engine, row.source_id, row.intent))) return { skipped: 'guest_source' };
if (!(await isFactsExtractionEnabled(engine))) return { skipped: 'extraction_disabled' };
const eligible = isFactsBackstopEligible(row.slug, page);
if (!eligible.ok) return { skipped: eligible.reason };
if (await bodyAlreadyOffered(engine, row.slug, page, before)) return { skipped: 'body_unchanged' };
return { queued: true };
}
/** Optional fence on new durable jobs; old jobs retain their established input contract. */
export async function readFactsBackstopJobPage(engine: BrainEngine, data: Record<string, unknown>) {
const slug = typeof data.slug === 'string' ? data.slug : '';
const sourceId = typeof data.sourceId === 'string' ? data.sourceId : 'default';
if (await readManagedMode(engine) && data.persistence_request_id === undefined) return { skipped: 'missing_write_authority' } as const;
const snapshot = await engine.readPageSnapshot(slug, { sourceId });
if (!snapshot) return { skipped: 'page_missing' } as const;
if (data.persistence_request_id !== undefined) {
if (typeof data.persistence_request_id !== 'string' || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(data.persistence_request_id)) return { skipped: 'invalid_write_request' } as const;
const [row] = await engine.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE id=$1::uuid', [data.persistence_request_id]);
if (!row || row.state !== 'committed' || row.slug !== slug || row.source_id !== sourceId
|| row.source_incarnation !== snapshot.sourceIncarnation || snapshot.page.id !== data.page_id
|| snapshot.revision !== data.revision) return { skipped: 'superseded' } as const;
try { await authorizeFactsBackstop(engine, row); }
catch (error) {
if (error instanceof OperationError && ['permission_denied', 'source_changed', 'page_not_found'].includes(error.code)) return { skipped: error.code } as const;
throw error;
}
}
return { page: snapshot.page };
}
/** Job insertion and outbox completion commit together; losing their ACK cannot create another job. */
export async function dispatchFactsBackstopEffect(engine: BrainEngine, effect: PersistenceEffect, hostId: string): Promise<void> {
await engine.transaction(async tx => {
await tx.executeRaw("SELECT set_config('synchronous_commit','on',true)");
await guardEffectSource(tx, effect, hostId);
const [row] = await tx.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE id=$1::uuid', [effect.request_id]);
let skipped: string | undefined;
if (!row || row.state !== 'committed') skipped = 'invalid_write_request';
if (row && !skipped) {
try { await authorizeFactsBackstop(tx, row, true); }
catch (error) {
if (error instanceof OperationError && ['permission_denied', 'source_changed', 'page_not_found'].includes(error.code)) skipped = error.code;
else throw error;
}
}
if (effect.data.slug) await tx.lockPageKeys([{ sourceId: effect.source_id, slug: effect.data.slug }]);
const [current] = await tx.executeRaw<PersistenceEffect>('SELECT * FROM persistence_effects WHERE id=$1 FOR UPDATE', [effect.id]);
if (!current || current.state !== 'running' || current.execution_token !== effect.execution_token) return;
const snapshot = effect.data.slug ? await tx.readPageSnapshot(effect.data.slug, { sourceId: effect.source_id }) : null;
if (!snapshot || snapshot.page.id !== effect.data.page_id || snapshot.revision !== effect.revision) skipped ??= 'superseded';
if (!(await isFactsExtractionEnabled(tx))) skipped ??= 'extraction_disabled';
if (skipped) { await completeEffect(tx, effect, { facts: 'skipped', reason: skipped }); return; }
// #6231: the page-write filter in force when the effect dispatches; the job keeps it across retries.
const notabilityFilter = await resolvePageWriteNotabilityFilter(tx);
// #9552: a connector page keeps the connector path's session (its facts are retired with the item) and its high-only filter.
const connector = isConnectorIntentKind(row!.intent?.kind);
const job = await new MinionQueue(tx).add('facts-absorb', {
// #6333: a stable per-page session (mirrors sync's `sync:<slug>`) so a re-extraction feeds the same-page shadow counter.
slug: effect.data.slug, sourceId: effect.source_id, source: connector ? 'sync:import' : 'mcp:put_page',
sessionId: connector ? connectorFactsSession(effect.source_id, effect.data.slug!) : `put_page:${effect.data.slug}`,
notabilityFilter: connector ? 'high-only' : notabilityFilter,
visibility: effect.data.visibility === 'world' ? 'world' : 'private',
persistence_request_id: effect.request_id, page_id: effect.data.page_id, revision: effect.revision,
}, { queue: 'default', idempotency_key: factsAbsorbWriteKey(effect.request_id), max_attempts: 5, backoff_delay: 60_000 });
await completeEffect(tx, effect, { facts: 'queued', job_id: job.id });
});
}