Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/** Filesystem-only contracts shared by the in-agent installer and recovery. */
import { createHash, randomUUID } from 'node:crypto';
import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
import type { GBrainConfig } from '../config.ts';
import { flushDirectory } from '../fs-durable.ts';
import { shouldDropAgentEnv } from './environment.ts';
import { shellQuote } from '../mcp-registration.ts';
import type { LocalSharedSkillsResult } from './shared-skills.ts';
import { INSTALL_REF } from '../install-ref.ts';
export class AgentInstallError extends Error {
constructor(public code: string, message: string) { super(message); this.name = 'AgentInstallError'; }
}
export type AgentHarness = 'grok-bot' | 'muse';
export interface InstallArtifact {
source_ref: string;
version: string;
bun_version: string;
bun_sha256: string;
package_sha256: string;
/** Relative paths, confined to the installation root. */
directory: string;
cli: string;
setup_entry: string;
}
export interface AgentInstallReceipt {
format_version: 1;
installation_id: string;
root: string;
harness: AgentHarness;
source_id: string;
database_path: string;
state: 'installing' | 'ready';
created_at: string;
updated_at: string;
artifact?: InstallArtifact;
/** Kept until the installed runtime has successfully migrated existing memory. */
pending_runtime_migration?: boolean;
initialized: boolean;
schema_version?: number;
adopted: boolean;
/** Only these trees belong to this installer. External sources are inventoried separately. */
managed_paths: string[];
owned_files: Record<string, string>;
pending_files?: Record<string, { before: string | null; after: string }>;
native: { skill_id: string; routine_id: string; verification: 'unverified' };
capabilities?: { transport: 'local-cli'; engine: 'pglite'; finite_database_probe: 'passed'; native_runtime: 'unverified' };
search_mode_confirmation_required: boolean;
skills_policy?: 'follow' | 'memory-only';
shared_skills?: LocalSharedSkillsResult;
/** Non-secret, durable recovery and enablement state. Older receipts derive it on repair. */
pending_steps?: string[];
recovery?: { command: string; action: string };
last_failure?: { code: string; at: string };
}
export function sha256(bytes: Uint8Array | string): string {
return createHash('sha256').update(bytes).digest('hex');
}
/** Reject ambiguous roots and every existing symlink component before any write. */
export function checkedRoot(input: string): string {
if (!isAbsolute(input) || input.split(/[\\/]/).includes('..') || input.includes('\0') || /[\r\n]/.test(input)) {
throw new AgentInstallError('invalid_root', 'Storage root must be an absolute path without traversal or control characters.');
}
const root = resolve(input);
if (dirname(root) === root) throw new AgentInstallError('invalid_root', 'The filesystem root cannot be an installation root.');
assertNoSymlinks(root);
return root;
}
export function assertNoSymlinks(path: string): void {
let current = resolve(path);
for (;;) {
try {
const stat = lstatSync(current);
if (stat.isSymbolicLink()) throw new AgentInstallError('symlink_path', `Refusing a symlink in managed path: ${current}`);
if (current !== path && !stat.isDirectory()) throw new AgentInstallError('invalid_path', `Parent is not a directory: ${current}`);
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
}
const parent = dirname(current);
if (parent === current) break;
current = parent;
}
}
export function checkedRelativePath(relative: string): string {
if (!relative || /[\\<>:"|?*\x00-\x1f\x7f]/.test(relative)
|| relative.split('/').some(p => !p || p === '.' || p === '..' || /[. ]$/.test(p)
|| /^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?: *\.| *$)/i.test(p))) {
throw new AgentInstallError('invalid_relative_path', `Invalid managed relative path: ${JSON.stringify(relative)}`);
}
return relative;
}
export function confinedPath(root: string, relative: string): string {
checkedRelativePath(relative);
const base = checkedRoot(root);
const target = resolve(base, relative);
if (!target.startsWith(base.endsWith(sep) ? base : base + sep)) throw new AgentInstallError('path_escape', 'Managed path escapes storage root.');
assertNoSymlinks(target);
return target;
}
export { flushDirectory as syncDirectory } from '../fs-durable.ts';
export function privateWrite(path: string, contents: string | Uint8Array, mode = 0o600): void {
assertNoSymlinks(path);
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
const tmp = `${path}.tmp-${randomUUID()}`;
let fd: number | undefined;
try {
fd = openSync(tmp, 'wx', mode);
writeFileSync(fd, contents);
fsyncSync(fd);
closeSync(fd); fd = undefined;
renameSync(tmp, path);
flushDirectory(dirname(path));
} catch (error) {
if (fd !== undefined) closeSync(fd);
try { unlinkSync(tmp); } catch { /* no temporary file after a failed write */ }
throw error;
}
}
export function installReceiptPath(root: string): string { return join(root, '.gbrain', 'agent-install', 'receipt.json'); }
/** A data inventory cannot include installer internals, credentials or another inventory root. */
export function checkedManagedPaths(root: string | null, input: unknown): string[] {
if (!Array.isArray(input) || input.some(path => typeof path !== 'string')) throw new AgentInstallError('invalid_managed_paths', 'Invalid managed path inventory.');
const paths = input as string[];
for (const path of paths) {
if (root === null) checkedRelativePath(path);
else confinedPath(root, path);
const first = path.split('/')[0].toLowerCase();
if (['.gbrain', 'runtime', 'bin', 'restore-receipt.json'].includes(first) || first.startsWith('.restore-') || first.startsWith('.gbrain-')) throw new AgentInstallError('invalid_managed_paths', 'Managed data cannot include installer, credential or restore state.');
}
const keys = paths.map(path => path.normalize('NFC').toLowerCase());
if (keys.some((path, i) => keys.some((other, j) => i !== j && (path === other || path.startsWith(other + '/'))))) throw new AgentInstallError('invalid_managed_paths', 'Managed inventory paths overlap.');
return paths;
}
export function readInstallReceipt(root: string): AgentInstallReceipt | null {
const path = installReceiptPath(root);
assertNoSymlinks(path);
if (!existsSync(path)) return null;
let value: AgentInstallReceipt;
try { value = JSON.parse(readFileSync(path, 'utf8')); }
catch { throw new AgentInstallError('invalid_receipt', `Unreadable install receipt: ${path}. Preserve it and recover before setup.`); }
if (!value || value.format_version !== 1 || !value.installation_id || !['grok-bot', 'muse'].includes(value.harness) || typeof value.source_id !== 'string' || !value.native || !value.owned_files || typeof value.owned_files !== 'object' || !['installing', 'ready'].includes(value.state)) {
throw new AgentInstallError('invalid_receipt', `Unsupported or invalid install receipt: ${path}`);
}
if (value.skills_policy !== undefined && !['follow', 'memory-only'].includes(value.skills_policy)) throw new AgentInstallError('invalid_receipt', 'Invalid recorded shared-skills choice; preserve the receipt before recovery.');
if (value.root !== root || value.database_path !== join(root, '.gbrain', 'brain.pglite')) {
throw new AgentInstallError('receipt_mismatch', 'Install receipt belongs to a different root/database; use backup restore to relocate it.');
}
checkedManagedPaths(root, value.managed_paths);
for (const relative of [...Object.keys(value.owned_files), ...Object.keys(value.pending_files ?? {})]) confinedPath(root, relative);
if (value.artifact) {
for (const relative of [value.artifact.directory, value.artifact.cli, value.artifact.setup_entry]) confinedPath(root, relative);
}
return value;
}
export function writeInstallReceipt(receipt: AgentInstallReceipt): void {
receipt.updated_at = new Date().toISOString();
receipt.pending_steps = [
...(!receipt.artifact ? ['install_runtime'] : []),
...(!receipt.initialized ? ['initialize_database'] : []),
...(receipt.pending_runtime_migration ? ['migrate_database'] : []),
...(receipt.state !== 'ready' ? ['verify_local_installation'] : []),
...(receipt.search_mode_confirmation_required ? ['confirm_search_mode'] : []),
...(receipt.skills_policy === undefined ? ['approve_shared_skills_follow'] : []),
'enable_native_skill', 'enable_native_maintenance', 'verify_new_conversation',
];
const helper = join(receipt.root, 'bin', 'gbrain-setup');
let helperOwned = false;
try {
assertNoSymlinks(helper);
helperOwned = sha256(readFileSync(helper)) === receipt.owned_files['bin/gbrain-setup'];
} catch { /* A missing or changed helper is repaired from the recorded package. */ }
const ref = /^[a-f0-9]{40}$/.test(receipt.artifact?.source_ref ?? '') ? receipt.artifact!.source_ref : INSTALL_REF;
const command = helperOwned ? `bash ${shellQuote(helper)} --json`
: `curl -fsSL https://raw.githubusercontent.com/garrytan/gbrain/${ref}/scripts/setup-in-agent.sh | bash -s -- --root ${shellQuote(receipt.root)} --harness ${shellQuote(receipt.harness)} --json`;
receipt.recovery = { command, action: receipt.last_failure
? 'Preserve memory and owned files. Resolve the reported failure, then run the recorded repair command; never remove a live lock.'
: 'Run the recorded command to repair software without reinitializing memory. Complete pending native and search-mode steps separately.' };
privateWrite(installReceiptPath(receipt.root), JSON.stringify(receipt, null, 2) + '\n');
}
export type ConfigState = { kind: 'absent' } | { kind: 'invalid' } | { kind: 'present'; config: GBrainConfig };
export function readFileConfigState(path: string): ConfigState {
if (!existsSync(path)) return { kind: 'absent' };
try {
const value = JSON.parse(readFileSync(path, 'utf8'));
if (!value || typeof value !== 'object' || Array.isArray(value)) return { kind: 'invalid' };
return { kind: 'present', config: value };
} catch { return { kind: 'invalid' }; }
}
/** A child receives only its selected installation's GBrain environment. */
export function isolatedAgentEnv(root: string, inherited: NodeJS.ProcessEnv = process.env): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(inherited)) {
if (value !== undefined && !shouldDropAgentEnv(key)) env[key] = value;
}
return { ...env, GBRAIN_HOME: root, GBRAIN_BRAIN_ID: 'host', GBRAIN_SOURCE: 'default', GBRAIN_SKIP_STARTUP_HOOKS: '1' };
}