Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.2 KB
Raw Blame
/**
 * 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));
}