Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* The optional Rust engine shell (docs/designs/RUST_ENGINE.md, plan PR 8).
*
* `openRustEngine` is the one seam: the addon loader calls it after it has loaded and verified the native addon, and
* gets back the engine. It has every BrainEngine member; its `kind` is `'rust'`, which `BrainEngine.kind` admits once
* the `rust` config value lands with the addon loader. Selecting the engine, loading the addon and refusing a missing or mismatched addon live in
* the loader, not here. The shell reports an empty capability set, so every BrainEngine member except the lifecycle
* ones rejects with a typed `engine_capability_missing` naming the capability it needs (rust-engine/members.ts), before
* any work. Later Rust PRs replace those refusals with typed methods one capability at a time.
*/
import type { BrainEngine } from './engine.ts';
import type { Capability, EngineCapabilities } from './engine-capabilities.ts';
import type { EngineConfig } from './types.ts';
import { capabilityMissing } from './rust-engine/errors.ts';
import { RUST_ENGINE_MEMBERS } from './rust-engine/members.ts';
/** The loaded, verified addon exports. Opaque to the shell: the typed methods later PRs add call into it. */
export type RustEngineAddonHandle = object;
export interface OpenRustEngineOptions {
/** The addon exports, already loaded and checked (target, ABI, build) by the loader. */
addon: RustEngineAddonHandle;
/** Absolute path of the brain's store directory (the config's database_path). */
databasePath: string;
}
/** Builds the Rust engine around an addon the loader has already verified. Nothing is opened or written yet. */
export function openRustEngine(opts: OpenRustEngineOptions): RustEngine {
return new RustEngine(opts);
}
// The class implements the lifecycle members; the members it does not implement yet are installed on its prototype
// below from RUST_ENGINE_MEMBERS, so the interface half of this merge is honest about the full BrainEngine surface.
export interface RustEngine extends Omit<BrainEngine, 'kind'> {}
export class RustEngine {
readonly kind = 'rust' as const;
/** Empty until the Rust engine implements a capability with parity tests (plan PRs 9 onward). */
readonly capabilities: EngineCapabilities = new Set();
readonly addon: RustEngineAddonHandle;
readonly databasePath: string;
private _savedConfig: EngineConfig | null = null;
private _connected = false;
private readonly _beforeDisconnect = new Set<() => Promise<void>>();
constructor(opts: OpenRustEngineOptions) {
this.addon = opts.addon;
this.databasePath = opts.databasePath;
}
/** True between `connect()` and `disconnect()`. */
get connected(): boolean { return this._connected; }
async connect(config: EngineConfig): Promise<void> {
this._savedConfig = config;
this._connected = true;
}
async disconnect(): Promise<void> {
const stops = [...this._beforeDisconnect];
this._beforeDisconnect.clear();
for (const stop of stops) {
try { await stop(); } catch { /* a stop barrier never blocks shutdown */ }
}
this._connected = false;
}
async reconnect(_ctx?: { error?: unknown }): Promise<void> {
if (!this._savedConfig) return; // never connected; nothing to restore
const config = this._savedConfig;
await this.disconnect();
await this.connect(config);
}
registerBeforeDisconnect(stop: () => Promise<void>): () => void {
this._beforeDisconnect.add(stop);
return () => { this._beforeDisconnect.delete(stop); };
}
}
/** The capability a BrainEngine member needs on Rust, or null when the shell implements it. */
export function rustMemberCapability(member: string): Capability | null {
const cls = (RUST_ENGINE_MEMBERS as Record<string, string>)[member];
return cls === undefined || cls === 'implemented' ? null : (cls as Capability);
}
for (const [member, cls] of Object.entries(RUST_ENGINE_MEMBERS)) {
if (cls === 'implemented') continue;
const capability = cls as Capability;
Object.defineProperty(RustEngine.prototype, member, {
configurable: true,
writable: true,
enumerable: false,
value: function refuse(this: RustEngine): Promise<never> {
return Promise.reject(capabilityMissing(capability, member));
},
});
}