Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Finds, checks and loads the Rust engine addon. Only the `rust` engine's open path may import it, lazily,
* so a PGLite or Postgres brain never loads it and never creates `<gbrain home>/engines/`. The engine shell calls
* {@link loadRustEngineAddon}.
*
* Order:
* 1. GBRAIN_RUST_ENGINE_ADDON (an absolute path to a build you made with `bun run rust:build`) is the development
* override. It skips only the release checksum pin; engine_abi and target are still checked.
* 2. An addon at `<home>/engines/rust/<engine_build>/<target>.node` whose SHA-256 equals the cached manifest of this
* gbrain version (`<home>/engines/rust/manifest-<version>.json`) loads. Nothing in gbrain writes that cache yet:
* fetching the release addon into it comes later, with content-addressed paths.
* 3. Otherwise it refuses with rust_engine_addon_missing (not_installed). It never reaches the network.
*
* Every failure is `rust_engine_addon_missing` or `rust_engine_addon_mismatch`, raised before the brain is touched.
* The addon is loaded with process.dlopen from a computed path: a literal `require('x.node')` would be bundled
* into compiled executables, and the addon must not be inside them.
*/
import { existsSync, readFileSync } from 'node:fs';
import { isAbsolute, join } from 'node:path';
import { gbrainPath } from '../config.ts';
import { VERSION } from '../../version.ts';
import { defaultComputeDigest } from '../binary-self-update.ts';
import { OperationError } from '../ops/contract.ts';
import { addonMismatch, addonMissing } from './addon-errors.ts';
import { parseRustAddonManifest, RELEASE_ADDON_TARGETS, RUST_ENGINE_ABI, type RustAddonManifest } from './addon-manifest.ts';
import { detectAddonTarget } from './addon-target.ts';
/** What the loader reads from the addon; the crate's exports (rust/crates/gbrain-napi) beyond these are for the engine. */
export interface RustAddon {
target: string;
engineAbi: number;
engineBuild: string;
catalogVersion: number;
formatVersions: unknown[];
[name: string]: unknown;
}
export interface RustAddonLoaderDeps {
env: Record<string, string | undefined>;
/** gbrain home's `engines/rust` directory. */
rustDir: string;
/** The running gbrain version; the cached manifest must name it. */
version: string;
/** This platform's addon target name, or null when it cannot be identified. */
target: string | null;
/** SHA-256 of a file, lowercase hex. */
computeDigest(path: string): string;
dlopen(path: string): unknown;
}
export function defaultRustAddonLoaderDeps(): RustAddonLoaderDeps {
return {
env: process.env,
rustDir: gbrainPath('engines', 'rust'),
version: VERSION,
target: detectAddonTarget(),
computeDigest: defaultComputeDigest,
dlopen(path) {
const module = { exports: {} as unknown };
process.dlopen(module as NodeJS.Module, path);
return module.exports;
},
};
}
/** `<home>/engines/rust/manifest-<version>.json`: the release manifest that names the cached addon. */
function cachedManifestPath(rustDir: string, version: string): string {
return join(rustDir, `manifest-${version}.json`);
}
/** `<home>/engines/rust/<engine_build>/<target>.node` */
function addonPath(rustDir: string, engineBuild: string, target: string): string {
return join(rustDir, engineBuild, `${target}.node`);
}
/** Reads the cached manifest, or null when it is absent, unreadable or for another version. */
function readCachedManifest(rustDir: string, version: string): RustAddonManifest | null {
try {
const manifest = parseRustAddonManifest(readFileSync(cachedManifestPath(rustDir, version), 'utf8'));
return manifest && manifest.gbrain_version === version ? manifest : null;
} catch {
return null;
}
}
interface Expected {
target: string;
/** Unset under the development override, which names no build to pin. */
manifest?: RustAddonManifest;
}
function load(path: string, expected: Expected, deps: RustAddonLoaderDeps): RustAddon {
let addon: RustAddon;
try {
addon = deps.dlopen(path) as RustAddon;
} catch (err) {
throw addonMismatch('load_failed', `The Rust engine addon at ${path} could not be loaded: ${err instanceof Error ? err.message : String(err)}.`);
}
if (addon?.engineAbi !== RUST_ENGINE_ABI) {
throw addonMismatch('engine_abi', `The Rust engine addon at ${path} reports engine_abi ${String(addon?.engineAbi)}; this gbrain loads engine_abi ${RUST_ENGINE_ABI}.`);
}
if (addon.target !== expected.target) {
throw addonMismatch('target', `The Rust engine addon at ${path} was built for ${String(addon.target)}; this machine is ${expected.target}.`);
}
if (expected.manifest && addon.engineBuild !== expected.manifest.engine_build) {
throw addonMismatch('engine_build', `The Rust engine addon at ${path} is engine_build ${String(addon.engineBuild)}; the gbrain v${expected.manifest.gbrain_version} release names ${expected.manifest.engine_build}.`);
}
return addon;
}
/**
* Loads the addon: the development override, else the cached addon whose SHA-256 matches the cached manifest.
* It is async because the release fetch that comes later is; today it never waits on anything.
*/
export async function loadRustAddon(overrides: Partial<RustAddonLoaderDeps> = {}): Promise<RustAddon> {
const deps: RustAddonLoaderDeps = { ...defaultRustAddonLoaderDeps(), ...overrides };
const override = deps.env.GBRAIN_RUST_ENGINE_ADDON?.trim();
if (override) {
if (!isAbsolute(override) || !existsSync(override)) {
throw addonMissing('override_not_found', `GBRAIN_RUST_ENGINE_ADDON is ${override}, which is not an existing absolute path to an addon file.`);
}
const target = deps.target;
if (!target) throw addonMissing('unsupported_target', 'This machine\'s platform could not be identified, so no Rust engine addon can be chosen for it.');
return load(override, { target }, deps);
}
const target = deps.target;
if (!target || !RELEASE_ADDON_TARGETS.includes(target)) {
throw addonMissing('unsupported_target', `No Rust engine addon is published for ${target ?? 'this platform'}; releases carry ${RELEASE_ADDON_TARGETS.join(' and ')}.`);
}
const cached = readCachedManifest(deps.rustDir, deps.version);
const entry = cached?.targets[target];
const path = cached && entry ? addonPath(deps.rustDir, cached.engine_build, target) : null;
if (!cached || !entry || !path || !existsSync(path)) {
throw addonMissing('not_installed', `No Rust engine addon for gbrain v${deps.version} on ${target} is installed in ${deps.rustDir}. Set GBRAIN_RUST_ENGINE_ADDON to a build from bun run rust:build.`);
}
let digest: string;
try {
digest = deps.computeDigest(path);
} catch (err) {
throw addonMismatch('digest', `The Rust engine addon at ${path} could not be read to check its SHA-256: ${err instanceof Error ? err.message : String(err)}.`);
}
if (digest !== entry.sha256) {
throw addonMismatch('digest', `The Rust engine addon at ${path} has SHA-256 ${digest}; the gbrain v${deps.version} manifest names ${entry.sha256}.`);
}
return load(path, { target, manifest: cached }, deps);
}
/** The two refusal codes {@link loadRustEngineAddon} reports; nothing else is ever caught. */
export type RustEngineAddonRefusalCode = 'rust_engine_addon_missing' | 'rust_engine_addon_mismatch';
/** What {@link loadRustEngineAddon} returns: the loaded addon, or the refusal it raised before touching the brain. */
export type RustEngineAddonLoad =
| { ok: true; addon: RustAddon }
| { ok: false; code: RustEngineAddonRefusalCode; reason: string; message: string };
/**
* The engine shell's entry point to the addon: {@link loadRustAddon} as a result, never a throw, for the two refusal
* codes. Any other error (a bug, not a refusal) is re-thrown unchanged.
*/
export async function loadRustEngineAddon(overrides: Partial<RustAddonLoaderDeps> = {}): Promise<RustEngineAddonLoad> {
try {
return { ok: true, addon: await loadRustAddon(overrides) };
} catch (err) {
if (err instanceof OperationError) {
const code = err.code as string;
if (code === 'rust_engine_addon_missing' || code === 'rust_engine_addon_mismatch') {
return { ok: false, code, reason: err.reason ?? 'unknown', message: err.message };
}
}
throw err;
}
}