Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/** One resumable, non-root local setup path. It never creates a personal identity or server. */
import { randomUUID } from 'node:crypto';
import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { PGLiteEngine } from '../pglite-engine.ts';
import { PgliteBusyError } from '../pglite-lock.ts';
import { acquireBootstrapLock } from '../bootstrap/lock.ts';
import { harnessAdapter } from '../harness/registry.ts';
import { renderAgentLauncher } from './launcher.ts';
import { shellQuote } from '../mcp-registration.ts';
import { SHARED_CONTENT_MIGRATION_VERSION } from '../../commands/migrations/shared-content.ts';
import { installLocalSharedSkills, type LocalSharedSkillsResult } from './shared-skills.ts';
import {
AgentInstallError, checkedRoot, confinedPath, installReceiptPath, isolatedAgentEnv, privateWrite,
readFileConfigState, readInstallReceipt, sha256, writeInstallReceipt,
type AgentHarness, type AgentInstallReceipt, type InstallArtifact,
} from './state.ts';
import { bunSpawn, bunSpawnSync } from '../spawn.ts';
import { MINIMUM_BUN_VERSION, bunVersionMeets } from '../runtime-version.ts';
import { INSTALL_RAW_BASE } from '../install-ref.ts';
const SETUP_HELPER_URL = `${INSTALL_RAW_BASE}/scripts/setup-in-agent.sh`;
export interface AgentSetupOptions {
root: string;
harness: AgentHarness;
/** Private bundle prepared by setup-in-agent.sh: bun + app/node_modules/gbrain. */
bundle: string;
sourceRef: string;
adopt?: boolean;
upgrade?: boolean;
skills?: 'follow' | 'memory-only';
/** The caller reads JSON output; a refusal's rerun command keeps `--json`. */
json?: boolean;
}
export interface AgentSetupResult {
status: 'installed' | 'repaired' | 'unchanged';
root: string;
launcher: string;
repair: string;
receipt: string;
instructions: string;
maintenance: string;
native_verification: 'unverified';
search_mode_confirmation_required: boolean;
shared_skills: LocalSharedSkillsResult;
}
async function cli(root: string, artifact: InstallArtifact, args: string[]): Promise<void> {
const commandArgs = args.includes('--migrate-only') || args[0] === 'apply-migrations' ? [...args, '--json'] : args;
const child = bunSpawn([join(root, artifact.directory, 'bun'), '--no-env-file', join(root, artifact.cli), '--brain', 'host', ...commandArgs], {
cwd: root, env: { ...isolatedAgentEnv(root), DATABASE_URL: '', GBRAIN_DATABASE_URL: '', ...(args[0] === 'init' ? { GBRAIN_IN_AGENT_SETUP: '1' } : {}) },
stdin: 'ignore', stdout: 'pipe', stderr: 'pipe',
});
const timer = setTimeout(() => child.kill('SIGTERM'), 120_000);
const killTimer = setTimeout(() => child.kill('SIGKILL'), 125_000);
try {
const [output, errors, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
// Preserve the real init [AGENT] search-mode cost matrix for the operator.
if (output) process.stderr.write(output);
if (errors) process.stderr.write(errors);
if (code !== 0) {
let failure: { error?: string; reason?: string; next_action?: string } | undefined;
try { failure = JSON.parse(output.trim().split(/\r?\n/).at(-1) ?? ''); } catch { /* ordinary command error remains below */ }
if (failure?.error === 'pglite_busy') throw new PgliteBusyError(
failure.next_action ?? 'The database is busy. Wait for its owner to finish and rerun setup; do not remove its lock.',
failure.reason === 'live_serve' ? 'live_serve' : 'timeout',
);
throw new AgentInstallError('setup_command_failed', `GBrain ${args[0]} failed (exit ${code}); rerun setup to resume. Existing data is preserved.`);
}
} finally { clearTimeout(timer); clearTimeout(killTimer); }
}
function verifyLocalState(root: string): void {
const state = readFileConfigState(join(root, '.gbrain', 'config.json'));
if (state.kind !== 'present' || state.config.remote_mcp || state.config.engine !== 'pglite' || state.config.database_url || state.config.database_path !== join(root, '.gbrain', 'brain.pglite')) {
throw new AgentInstallError('incompatible_installation', 'This root is not the expected local PGLite installation. Use a different root or an explicit migration.');
}
}
function artifactFromBundle(bundle: string, sourceRef: string): Omit<InstallArtifact, 'directory' | 'cli' | 'setup_entry'> {
const root = checkedRoot(bundle);
const bun = join(root, 'bun');
const packageDir = join(root, 'app', 'node_modules', 'gbrain');
const pkg = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
if (pkg.name !== 'gbrain' || typeof pkg.version !== 'string' || !existsSync(join(packageDir, 'src', 'cli.ts')) || !existsSync(join(packageDir, 'scripts', 'setup-in-agent.sh'))) {
throw new AgentInstallError('invalid_artifact', 'Setup bundle does not contain the GBrain package and setup helper.');
}
if (!/^[a-f0-9]{40}$/.test(sourceRef)) throw new AgentInstallError('invalid_artifact_ref', 'A resolved 40-character source commit is required.');
const version = bunSpawnSync([bun, '--version'], { stdout: 'pipe', stderr: 'pipe' });
if (version.exitCode !== 0) throw new AgentInstallError('runtime_unusable', 'The staged Bun runtime is not executable on this machine.');
return { source_ref: sourceRef, version: pkg.version, bun_version: version.stdout.toString().trim(), bun_sha256: sha256(readFileSync(bun)), package_sha256: sha256(readFileSync(join(packageDir, 'package.json'))) };
}
function installArtifact(root: string, options: AgentSetupOptions, identity: ReturnType<typeof artifactFromBundle>): InstallArtifact {
const directory = `runtime/${identity.version.replace(/[^a-zA-Z0-9.-]/g, '_')}-${randomUUID()}`;
const target = confinedPath(root, directory);
mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
const stage = `${target}.partial`;
try {
// Dereference package-manager links so the installed runtime is independent
// of the temporary bundle and package cache. Validate the copied entrypoints.
cpSync(options.bundle, stage, { recursive: true, dereference: true, errorOnExist: true, force: false });
chmodSync(stage, 0o700); chmodSync(join(stage, 'bun'), 0o700);
if (sha256(readFileSync(join(stage, 'bun'))) !== identity.bun_sha256) throw new AgentInstallError('artifact_checksum', 'Runtime copy did not match the staged checksum.');
const cliPath = join(stage, 'app', 'node_modules', 'gbrain', 'src', 'cli.ts');
if (!realpathSync(cliPath).startsWith(realpathSync(stage) + '/')) throw new AgentInstallError('artifact_escape', 'Package entrypoint escapes the installed artifact.');
renameSync(stage, target);
} catch (error) {
rmSync(stage, { recursive: true, force: true });
throw error;
}
return { ...identity, directory, cli: `${directory}/app/node_modules/gbrain/src/cli.ts`, setup_entry: `${directory}/app/node_modules/gbrain/src/core/agent-install/entry.ts` };
}
function artifactUsable(root: string, artifact: InstallArtifact): boolean {
try {
if (!existsSync(confinedPath(root, artifact.cli)) || sha256(readFileSync(confinedPath(root, `${artifact.directory}/bun`))) !== artifact.bun_sha256) return false;
const probe = bunSpawnSync([join(root, artifact.directory, 'bun'), '--no-env-file', join(root, artifact.cli), '--version'], {
cwd: root, env: { ...isolatedAgentEnv(root), DATABASE_URL: '', GBRAIN_DATABASE_URL: '' }, stdout: 'pipe', stderr: 'pipe', timeout: 15_000,
});
return probe.exitCode === 0;
} catch { return false; }
}
/** Never overwrite an unowned or user-modified generated file. */
function ownFile(receipt: AgentInstallReceipt, path: string, text: string, mode = 0o600): boolean {
const target = confinedPath(receipt.root, path);
const desired = sha256(text);
const actual = ownedFileHash(receipt, path);
if (actual !== null) {
if (actual === desired) {
receipt.owned_files[path] = desired;
if (receipt.pending_files) delete receipt.pending_files[path];
writeInstallReceipt(receipt);
return false;
}
}
receipt.pending_files ??= {};
receipt.pending_files[path] = { before: actual, after: desired };
writeInstallReceipt(receipt);
privateWrite(target, text, mode);
receipt.owned_files[path] = desired;
delete receipt.pending_files[path];
writeInstallReceipt(receipt);
return true;
}
function ownedFileHash(receipt: AgentInstallReceipt, path: string): string | null {
const target = confinedPath(receipt.root, path);
const pending = receipt.pending_files?.[path];
if (existsSync(target)) {
const actual = sha256(readFileSync(target));
if (actual !== receipt.owned_files[path] && actual !== pending?.before && actual !== pending?.after) {
throw new AgentInstallError('modified_owned_file', `Preserve your changes at ${target} before rerunning setup; it will not be overwritten.`);
}
return actual;
}
return null;
}
export function renderLocalInstructions(root: string, sourceId: string, sharedRouter = ''): string {
const launcher = join(root, 'bin', 'gbrain');
return `# GBrain memory
Use the executable \`${launcher}\` for this installation. It selects the host brain and source \`${sourceId}\`; use this same absolute path from every conversation and native routine.
Recall relevant memory before answering personal or continuing-work questions. Use \`gbrain recall --help\` through this launcher for the installed command schema. Explicitly remember user-requested durable facts, with their source and date. Preserve uncertainty and distinguish what the user said from an inference. Correct or forget outdated facts when asked; verify the change through a fresh recall. Forgetting withdraws active memory; history, source material, and private backups may remain. Never promise physical erasure. Never import connected-service history or enable automatic capture without the user's instruction.
Do not replace the agent's identity. This is one shared local installation, not a boundary between Bots. Memory calls are finite CLI processes. A busy database means another command is running: retry after it finishes; never remove its lock.
Load these instructions as a native saved skill/standing instruction. Confirm that a NEW conversation invokes this executable and recalls a randomized saved fact; platform-native memory alone is not verification. Native installation remains unverified until that test succeeds.
${sharedRouter ? `\n${sharedRouter}\n` : ''}`;
}
export function renderLocalMaintenance(root: string, routineId: string): string {
return `# GBrain maintenance (${routineId})
Create at most one native scheduled routine with this identifier for the shared installation. Use \`${join(root, 'bin', 'gbrain')}\` with absolute paths. First run \`doctor --fast --json\`; report failures. Run only configured maintenance that does not require missing provider credentials. Paid embedding/extraction is a separate user choice. Do not start serve, cron, or a daemon.
For a complete local backup, pause other memory/file writers and run \`backup create --output /absolute/private/path/unique.gbrain-backup\`. The parent directory must exist. Archives contain sensitive full database state, potentially including credentials; protect any explicitly chosen off-VM copy. Coverage checks and markdown exports are not full database backups.
Restore with \`backup restore /absolute/path/archive.gbrain-backup --into /absolute/new-root\`. Restoration never replaces an existing root and quarantines unfinished jobs. Reinstall the runtime using the setup helper, reconnect excluded credentials/services, and reattach this routine only after verifying the restored brain. No automation starts on restore.
`;
}
function refuseBelowFloor(identity: ReturnType<typeof artifactFromBundle>, options: AgentSetupOptions, root: string, outcome: string): void {
if (bunVersionMeets(identity.bun_version, MINIMUM_BUN_VERSION)) return;
const rerunArgs = ['--root', root, '--harness', options.harness, ...(options.adopt ? ['--adopt'] : []), ...(options.upgrade ? ['--upgrade'] : []),
...(options.skills ? ['--skills', options.skills] : []), ...(options.json ? ['--json'] : [])];
const rerun = `curl --fail --silent --show-error --location ${SETUP_HELPER_URL} --output /tmp/gbrain-setup.sh && bash /tmp/gbrain-setup.sh ${rerunArgs.map(shellQuote).join(' ')}`;
const next = options.upgrade ? 'Make a verified backup first (docs/guides/in-agent-setup.md), then fetch' : 'Fetch';
throw new AgentInstallError('runtime_below_floor', `This GBrain release needs Bun ${MINIMUM_BUN_VERSION} or newer, but the setup bundle carries Bun ${identity.bun_version || 'of unknown version'}, so the helper that staged it is out of date. ${outcome} ${next} the current helper and rerun setup: ${rerun}`);
}
export async function setupInAgent(options: AgentSetupOptions): Promise<AgentSetupResult> {
if (options.skills !== undefined && !['follow', 'memory-only'].includes(options.skills)) throw new AgentInstallError('usage', 'The skills policy must be follow or memory-only.');
const root = checkedRoot(options.root);
const adapter = harnessAdapter(options.harness);
if (!['grok-bot', 'muse'].includes(adapter.id) || !adapter.modes.includes('local-cli')) throw new AgentInstallError('unsupported_harness', 'This local setup supports Grok Bot and Muse personal agents.');
// A bundle that cannot be read is reported inside the install below, where the receipt journals it.
let identity: ReturnType<typeof artifactFromBundle> | undefined;
try { identity = artifactFromBundle(options.bundle, options.sourceRef); } catch { identity = undefined; }
if (identity) refuseBelowFloor(identity, options, root, 'Nothing was changed.');
if (!existsSync(dirname(root))) throw new AgentInstallError('parent_missing', 'Create and verify the persistent parent directory first.');
const existed = existsSync(root);
if (!existed) mkdirSync(root, { mode: 0o700 });
if (!lstatSync(root).isDirectory()) throw new AgentInstallError('invalid_root', 'Storage root is not a directory.');
const lock = await acquireBootstrapLock(root);
let receipt: AgentInstallReceipt | null = null;
try {
const restoreReceiptPath = confinedPath(root, 'restore-receipt.json');
if (existsSync(restoreReceiptPath)) {
let state: unknown;
try { state = JSON.parse(readFileSync(restoreReceiptPath, 'utf8')).state; } catch { /* malformed restore state stays blocked */ }
if (state !== 'ready') throw new AgentInstallError('restore_incomplete', 'This destination has an incomplete restore. Preserve it for inspection and restore into a new absent root before setup.');
}
receipt = readInstallReceipt(root);
const configPath = join(root, '.gbrain', 'config.json');
const config = readFileConfigState(configPath);
const hasDb = existsSync(join(root, '.gbrain', 'brain.pglite'));
if (!receipt) {
const entries = readdirSync(root).filter(name => name !== '.gbrain-bootstrap.lock');
if (config.kind === 'invalid') throw new AgentInstallError('invalid_config', 'Existing config is malformed; it will not be replaced.');
if ((config.kind === 'present' || hasDb || entries.length) && !options.adopt) throw new AgentInstallError('adoption_required', 'This root contains unowned state. Choose an empty root or explicitly --adopt a compatible local brain.');
if (options.adopt) {
verifyLocalState(root);
if (!hasDb) throw new AgentInstallError('missing_database', 'Adoption requires the existing database; setup will not replace it with an empty brain.');
}
receipt = {
format_version: 1, installation_id: randomUUID(), root, harness: options.harness,
source_id: 'default', database_path: join(root, '.gbrain', 'brain.pglite'), state: 'installing',
initialized: !!options.adopt, adopted: !!options.adopt, created_at: new Date().toISOString(), updated_at: new Date().toISOString(),
managed_paths: options.adopt ? ['instructions'] : ['memory', 'instructions'], owned_files: {},
native: { skill_id: '', routine_id: '', verification: 'unverified' }, search_mode_confirmation_required: !options.adopt,
...(options.skills ? { skills_policy: options.skills } : !options.adopt ? { skills_policy: 'follow' as const } : {}),
};
process.stderr.write(receipt.skills_policy === 'follow'
? 'Shared skills: this setup follows the source-scoped brain catalog through an owned router. No identity replacement, automatic capture, scripts, paid calls, or editor grant. Native loading remains manual and unverified. Opt out with --skills memory-only.\n'
: 'Shared skills: memory remains available; existing/adopted roots require explicit --skills follow approval before enrollment.\n');
receipt.native.skill_id = `gbrain-${receipt.installation_id}`;
receipt.native.routine_id = `gbrain-maintenance-${receipt.installation_id}`;
writeInstallReceipt(receipt);
} else {
if (receipt.harness !== options.harness) throw new AgentInstallError('harness_mismatch', `This installation belongs to ${receipt.harness}; reuse its existing launcher.`);
if (receipt.initialized && (!hasDb || config.kind !== 'present')) throw new AgentInstallError('memory_missing', 'Previously initialized memory/config is missing. Restore a backup; setup will not create a replacement brain.');
if (config.kind === 'invalid') throw new AgentInstallError('invalid_config', 'Existing config is malformed; recover it before setup.');
if (config.kind === 'present') verifyLocalState(root);
// A killed init can leave DB/config before all migrations or its journal
// update. Their presence proves identity, not schema completion.
if (!receipt.initialized && config.kind === 'present' && hasDb) {
receipt.initialized = true; receipt.pending_runtime_migration = true; writeInstallReceipt(receipt);
}
if (!receipt.initialized && hasDb && config.kind === 'absent') throw new AgentInstallError('partial_database', 'Initialization left a database without configuration. Preserve it and recover its configuration before continuing.');
}
if (options.skills) receipt.skills_policy = options.skills;
if (receipt.skills_policy === 'follow') ownedFileHash(receipt, 'instructions/gbrain-skill.md');
writeInstallReceipt(receipt);
delete receipt.last_failure;
let changed = false;
identity ??= artifactFromBundle(options.bundle, options.sourceRef);
refuseBelowFloor(identity, options, root, 'No runtime was installed.');
if (receipt.artifact && !options.upgrade && identity.source_ref !== receipt.artifact.source_ref) throw new AgentInstallError('artifact_version_mismatch', 'Repair must use the recorded source commit; use --upgrade to explicitly change versions.');
const upgrade = !!options.upgrade && receipt.artifact?.source_ref !== identity.source_ref;
if (!receipt.artifact || upgrade || !artifactUsable(root, receipt.artifact)) {
receipt.artifact = installArtifact(root, options, identity);
// The artifact pointer commits before migration. Keep the migration stage
// independently durable so a failed/killed upgrade resumes even though
// the next invocation now sees the same source ref as the receipt.
receipt.pending_runtime_migration = receipt.initialized;
receipt.state = 'installing'; writeInstallReceipt(receipt); changed = true;
}
const artifact = receipt.artifact;
if (!receipt.initialized) {
for (const path of receipt.managed_paths) mkdirSync(confinedPath(root, path), { recursive: true, mode: 0o700 });
await cli(root, artifact, ['init', '--pglite', '--no-embedding', '--non-interactive']);
verifyLocalState(root);
receipt.initialized = true; writeInstallReceipt(receipt); changed = true;
}
if (receipt.pending_runtime_migration) {
// apply-migrations also runs host harness/automation orchestrators. This
// isolated installation only owns its configured database schema.
await cli(root, artifact, ['init', '--migrate-only', '--non-interactive']);
receipt.pending_runtime_migration = false; writeInstallReceipt(receipt); changed = true;
}
await cli(root, artifact, ['apply-migrations', '--migration', SHARED_CONTENT_MIGRATION_VERSION, '--yes', '--non-interactive']);
// A finite database probe also makes a ready receipt prove the installed
// memory can actually be opened, rather than only that files exist.
const engine = new PGLiteEngine();
let sharedSkills: LocalSharedSkillsResult;
try {
await engine.connect({ engine: 'pglite', database_path: receipt.database_path });
if (!receipt.adopted) await engine.executeRaw(`UPDATE sources SET local_path = $1 WHERE id = $2 AND local_path IS NULL`, [join(root, 'memory'), receipt.source_id]);
const sources = await engine.executeRaw<{ id: string }>('SELECT id FROM sources WHERE id = $1 AND COALESCE(archived, FALSE) = FALSE', [receipt.source_id]);
if (!sources.length) throw new AgentInstallError('source_missing', 'Configured source is missing or archived; repair source routing before setup.');
receipt.schema_version = Number(await engine.getConfig('version'));
receipt.capabilities = { transport: 'local-cli', engine: 'pglite', finite_database_probe: 'passed', native_runtime: 'unverified' };
const localConfig = readFileConfigState(configPath);
if (localConfig.kind !== 'present') throw new AgentInstallError('invalid_config', 'The installation config must remain readable.');
sharedSkills = await installLocalSharedSkills({ engine, config: localConfig.config, sourceId: receipt.source_id, remote: false,
dryRun: false, logger: { info() {}, warn() {}, error() {} } }, {
root, harness: receipt.harness, sourceId: receipt.source_id, follow: receipt.skills_policy === 'follow',
});
if (receipt.skills_policy === undefined) sharedSkills = { ...sharedSkills, status: 'pending', reason: 'follow_approval_required' };
receipt.shared_skills = sharedSkills;
writeInstallReceipt(receipt);
} finally { await engine.disconnect(); }
for (const path of ['bin', 'instructions']) {
const target = confinedPath(root, path);
if (!existsSync(target)) mkdirSync(target, { mode: 0o700 });
}
const launcher = renderAgentLauncher({ root, bunPath: join(root, artifact.directory, 'bun'), cliPath: join(root, artifact.cli), sourceId: receipt.source_id, repairHint: `Run: bash ${shellQuote(join(root, 'bin', 'gbrain-setup'))}` });
changed = ownFile(receipt, 'bin/gbrain', launcher, 0o700) || changed;
const setupScript = readFileSync(join(root, artifact.directory, 'app', 'node_modules', 'gbrain', 'scripts', 'setup-in-agent.sh'), 'utf8');
changed = ownFile(receipt, 'bin/gbrain-setup', setupScript, 0o700) || changed;
changed = ownFile(receipt, 'instructions/gbrain-skill.md', renderLocalInstructions(root, receipt.source_id,
sharedSkills.router_path ? readFileSync(sharedSkills.router_path, 'utf8') : '')) || changed;
changed = ownFile(receipt, 'instructions/maintenance.md', renderLocalMaintenance(root, receipt.native.routine_id)) || changed;
receipt.state = 'ready'; writeInstallReceipt(receipt);
return {
status: !existed ? 'installed' : changed ? 'repaired' : 'unchanged', root,
launcher: join(root, 'bin', 'gbrain'), repair: join(root, 'bin', 'gbrain-setup'), receipt: installReceiptPath(root),
instructions: join(root, 'instructions', 'gbrain-skill.md'), maintenance: join(root, 'instructions', 'maintenance.md'),
native_verification: 'unverified', search_mode_confirmation_required: receipt.search_mode_confirmation_required,
shared_skills: sharedSkills,
};
} catch (error) {
// Only the lock owner journals a recognized installation; preflight
// conflicts must never create or adopt somebody else's receipt.
if (receipt?.harness === options.harness) {
receipt.state = 'installing';
receipt.last_failure = { code: error instanceof AgentInstallError || error instanceof PgliteBusyError ? error.code : 'setup_failed', at: new Date().toISOString() };
try { writeInstallReceipt(receipt); } catch { /* Preserve the original failure if storage itself is unavailable. */ }
}
throw error;
} finally { lock.release(); }
}