Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Engine capabilities: what a storage engine can do, by name.
*
* `BrainEngine.capabilities` is the read-only set an engine reports. PGLite and
* Postgres report everything they have today; a new engine (the optional Rust
* engine, docs/designs/RUST_ENGINE.md "Capability gating") reports only what it
* implements, and callers ask for a capability instead of branching on
* `engine.kind`.
*
* `REQUIRED_CAPABILITIES` records what each operation, CLI command, cycle phase
* and minion handler needs. Anything not listed needs `raw_sql`, so an engine
* without raw SQL refuses it until its row says otherwise. On PGLite and
* Postgres every lookup passes: both report every capability a row can name,
* except the engine-specific `single_owner` and `postgres_admin`.
*/
export const ENGINE_CAPABILITIES = [
// Raw SQL entry points: executeRaw, executeRawDirect, withReservedConnection.
// The Rust engine never reports it (D18: no SQL dialect).
'raw_sql',
// Subsystems that still reach the database through raw SQL.
'persistence_journal',
'minion_queue',
'access_control',
'belief_ledger',
/** One owner process hosts the brain and other processes are its clients. */
'single_owner',
/** Postgres server administration: pooler, roles, server settings and statistics. */
'postgres_admin',
// Typed BrainEngine storage domains.
'schema',
'transactions',
'sources',
'config',
'pages',
'page_versions',
'page_body',
'tags',
'chunks',
'embeddings',
'keyword_search',
'vector_search',
'links',
'timeline',
'graph',
'facts',
'takes',
'files',
'code_edges',
'salience',
'health',
'raw_data',
'eval_capture',
'ingest_log',
'dream_verdicts',
'contradictions',
'ontology',
] as const;
export type Capability = (typeof ENGINE_CAPABILITIES)[number];
/** The read-only capability set an engine reports. */
export type EngineCapabilities = ReadonlySet<Capability>;
/** Engine kinds whose capability set is known without opening the engine. */
export type SqlEngineKind = 'pglite' | 'postgres';
const ENGINE_ONLY: Readonly<Record<SqlEngineKind, readonly Capability[]>> = {
pglite: ['single_owner'],
postgres: ['postgres_admin'],
};
const ENGINE_SPECIFIC = new Set<Capability>(Object.values(ENGINE_ONLY).flat());
/**
* The full capability set PGLite or Postgres reports: every shared capability
* plus its own engine-specific ones. Returns a fresh set, so one engine can
* never change another engine's answer.
*/
export function capabilitiesForEngineKind(kind: SqlEngineKind): EngineCapabilities {
const caps = new Set<Capability>(ENGINE_CAPABILITIES.filter(c => !ENGINE_SPECIFIC.has(c)));
for (const c of ENGINE_ONLY[kind]) caps.add(c);
return caps;
}
export function hasCapability(engine: { readonly capabilities: EngineCapabilities }, capability: Capability): boolean {
return engine.capabilities.has(capability);
}
/** The surfaces that dispatch work onto an engine. */
export type CapabilityConsumer = 'operation' | 'command' | 'phase' | 'handler';
/**
* What each operation (`src/core/operations.ts` name), CLI command record
* (`src/cli/command-table.ts` name), cycle phase and minion handler needs.
* An entry is added only once its whole path is proven to run without raw SQL;
* until then it is absent and needs `raw_sql`.
*/
export const REQUIRED_CAPABILITIES: Readonly<Record<CapabilityConsumer, Readonly<Record<string, readonly Capability[]>>>> = {
operation: {},
command: {},
phase: {},
handler: {},
};
const RAW_SQL_ONLY: readonly Capability[] = Object.freeze(['raw_sql'] as Capability[]);
/** The capabilities `name` needs. An unlisted name needs `raw_sql`. */
export function requiredCapabilities(consumer: CapabilityConsumer, name: string): readonly Capability[] {
const table = REQUIRED_CAPABILITIES[consumer];
return Object.prototype.hasOwnProperty.call(table, name) ? table[name]! : RAW_SQL_ONLY;
}
/** The capabilities `name` needs that `engine` does not report, in table order. Empty means it can run. */
export function missingCapabilities(
engine: { readonly capabilities: EngineCapabilities },
consumer: CapabilityConsumer,
name: string,
): Capability[] {
return requiredCapabilities(consumer, name).filter(c => !engine.capabilities.has(c));
}