Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { createHash } from 'node:crypto';
import { execFileSync } from 'node:child_process';
import { existsSync, readFileSync, mkdirSync, lstatSync, unlinkSync, readdirSync } from 'node:fs';
import { dirname, join, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import { atomicWriteTextFile } from '../bootstrap/atomic-write.ts';
import { acquireBootstrapLock } from '../bootstrap/lock.ts';
import { claudeUserMcpConfigPath, codexConfigPath, opencodeGlobalConfigPath, opencodeGlobalSiblingPath, CODEX_TOML_BLOCK_BEGIN } from '../bootstrap/host-specs.ts';
import { writeCodexHttpServerBlock, removeCodexHttpServerBlock, codexToolPolicy, codexToolsOutsideBlock } from '../bootstrap/codex-toml.ts';
import { writeOpencodeMcpEntry, removeOpencodeMcpEntry, parseOpencodeConfig } from '../bootstrap/opencode-json.ts';
import { renderAgentLauncher } from '../agent-install/launcher.ts';
import { isValidName, shellQuote } from '../mcp-registration.ts';
import { GBRAIN_MCP_INSTRUCTIONS } from '../../mcp/instructions.ts';
import { harnessAdapter } from './registry.ts';
import { GIT_ENV } from '../git-remote.ts';
import { credentialAccessToken, credentialReceipt, type HarnessCredentials } from './credentials.ts';
import { assertNoSymlinks, checkedRoot, confinedPath, sha256, privateWrite } from '../agent-install/state.ts';
import { installSharedSkillsConnection } from './shared-skills.ts';
import type { SharedSkillsToolCaller } from '../shared-skills/adapter.ts';
import { harnessSharedSkillsRoot } from './status.ts';
import { gitChildEnv } from '../git-env.ts';
import { installerTurnHook, turnHookFix } from '../setup/turn-hook-check.ts';
import type { TurnHookPaths } from '../setup/turn-hook.ts';
import { resolveGbrainBin } from '../gbrain-bin.ts';
import { brainFirstTargetAt, codexInstructionFile, installerBrainFirst, readBrainFirstLedger, renderBrainFirstSnippet, resolveBrainFirstDecision, type BrainFirstHarness } from '../setup/brain-first.ts';
import { indexLauncher, inspectSkillsBlock, installerSkillsBlock, isSkillLoading, renderSkillsSnippet, resolveSkillLoading, skillsOutcomeFailed, type SkillLoading, type SkillsBlockOutcome } from '../setup/skills-block.ts';
export interface InstallOptions { harness: string; name?: string; root?: string; configPath?: string; remove?: boolean;
sharedSkills?: HarnessCredentials['shared_skills']; toolCaller?: SharedSkillsToolCaller; nativeSkillsDir?: string; credentialsFile?: string; freshToken?: boolean;
/** false: opt out of the brain-first instruction block (removes an existing one); true: opt back in. */
instructions?: boolean;
/** The spring-loaded skills index beside the brain-first block (off by default; GBRAIN_SKILL_LOADING and the recorded choice apply). */
skillLoading?: SkillLoading;
/** The absolute gbrain the native-config index names (default: this gbrain, else the one on PATH). */
gbrainBin?: string }
const hash = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
const readJson = (path: string): Record<string, any> => {
assertNoSymlinks(path);
if (!existsSync(path)) return {};
if (lstatSync(path).isSymbolicLink()) throw new Error('configuration_conflict: refusing a symbolic-link configuration');
try {
const value = JSON.parse(readFileSync(path, 'utf8'));
if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error();
return value;
} catch { throw new Error('configuration_conflict: existing configuration is not a JSON object'); }
};
function nativeEntry(path: string, format: string, name: string): unknown {
assertNoSymlinks(path);
if (!existsSync(path)) return undefined;
const text = readFileSync(path, 'utf8');
const parsed = (format === 'codex-toml' ? Bun.TOML.parse(text) : format === 'opencode-json' ? parseOpencodeConfig(text, path) : readJson(path)) as Record<string, unknown>;
const entries = parsed[format === 'codex-toml' ? 'mcp_servers' : format === 'opencode-json' ? 'mcp' : 'mcpServers'] as Record<string, unknown> | undefined;
if (format === 'codex-toml' && text.includes(CODEX_TOML_BLOCK_BEGIN) && entries?.[name] === undefined) throw new Error('configuration_conflict: managed Codex block belongs to another connection');
return entries?.[name];
}
/** The Git working tree whose next commit would include `path`, or null when it is ignored or outside every tree. */
function committingGitTree(path: string): string | null {
const git = (args: string[]) => execFileSync('git', ['-C', dirname(path), ...args],
{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000, env: gitChildEnv({ ...GIT_ENV }) }).trim();
let tree: string;
try { tree = git(['rev-parse', '--show-toplevel']); } catch { return null; }
try { git(['check-ignore', '-q', '--', path]); return null; } catch { return tree; }
}
/** Where an installed bearer token lives and how to replace it, never the token itself (#5775). */
export function inlineTokenReceipt(c: HarnessCredentials, harness: string, name: string, configPath: string, reload: string, credentialsFile?: string) {
const renew = ['gbrain connect', shellQuote(c.mcp_url), '--harness', shellQuote(harness), '--credentials-file',
credentialsFile ? shellQuote(credentialsFile) : '<private-handoff-file>', ...(name === 'gbrain' ? [] : ['--name', shellQuote(name)]), '--install', ...(c.client_secret ? ['--fresh-token'] : [])].join(' ');
const invalidate = (apply: string) => `gbrain mcp admin invalidate-tokens ${shellQuote(c.client_id)}${apply} --url ${shellQuote(c.mcp_url)} --admin-token-file <owner-admin-token-file> --json`;
const tree = committingGitTree(configPath);
// A cached unexpired handoff token may be the invalidated one, so renewal always exchanges a new token.
const replace = c.client_secret ? `Write a freshly exchanged token here: ${renew}`
: `This handoff cannot exchange a new token; get a new private handoff from the brain owner (gbrain mcp grant on the brain host), then run: ${renew}`;
return {
token_storage: 'inline' as const, config_path: configPath, renew_command: renew,
if_exposed: {
steps: [`On the brain host, preview: ${invalidate('')}`, `Apply with the previewed revision: ${invalidate(' --yes --if-version <revision>')}`,
replace, reload],
docs_url: 'docs/mcp/ADMIN.md#invalidate-tokens-revoke-or-delete',
},
...(tree ? { token_warning: `${configPath} is inside the Git working tree ${tree}, so committing there would publish this bearer token. `
+ `Add ${relative(tree, configPath).split('\\').join('/')} to that repository's .gitignore or move the configuration; if it was already committed, follow if_exposed.` } : {}),
};
}
/**
* #6799: the hash gbrain owns a native entry by. A Codex entry's `tools` table
* holds Codex's own per-tool settings ("always allow"), so it is left out;
* every other key, including any unexpected one, stays covered.
*/
function ownedEntryHash(entry: unknown, connection: string): string {
if (connection !== 'codex-toml' || !entry || typeof entry !== 'object' || codexToolPolicy((entry as Record<string, unknown>).tools) === null) return hash(entry);
const { tools: _tools, ...owned } = entry as Record<string, unknown>;
return hash(owned);
}
/** Owned when the receipt recorded either hash: the current one or the whole-entry hash older installs wrote. */
function assertEntryOwned(entry: unknown, prior: Record<string, any>, connection: string) {
if (entry === undefined) return;
const recorded = [prior.entry_hash, prior.pending_entry_hash];
if (!prior.client_id || ![hash(entry), ownedEntryHash(entry, connection)].some(h => recorded.includes(h))) throw new Error('configuration_conflict: refusing to replace an unowned or edited MCP entry');
}
/** The harness's own instruction file, next to the config this install writes. */
function instructionFileBeside(connection: string, configPath: string): { harness: BrainFirstHarness; path: string } {
const dir = dirname(configPath);
if (connection === 'codex-toml') return { harness: 'codex', path: codexInstructionFile(join(dir, 'AGENTS.override.md'), join(dir, 'AGENTS.md')) };
if (connection === 'opencode-json') return { harness: 'opencode', path: join(dir, 'AGENTS.md') };
return { harness: 'claude-code', path: process.env.CLAUDE_CONFIG_DIR?.trim() === dir ? join(dir, 'CLAUDE.md') : join(dir, '.claude', 'CLAUDE.md') };
}
/** The per-turn hook files next to a config this install was pointed at (tests, a non-default config). */
function turnHookPathsBeside(connection: string, configPath: string): TurnHookPaths {
const dir = dirname(configPath);
if (connection === 'codex-toml') return { codexHooks: join(dir, 'hooks.json'), codexConfig: configPath };
return { claudeSettings: process.env.CLAUDE_CONFIG_DIR?.trim() === dir ? join(dir, 'settings.json') : join(dir, '.claude', 'settings.json') };
}
/** Install only in the current environment. Foreign entries are never adopted. */
export async function installHarnessConnection(c: HarnessCredentials, opts: InstallOptions) {
// A cached unexpired token may be the invalidated one; every later step (config and shared skills) uses the new token.
if (opts.freshToken && !opts.remove) c = { ...c, access_token: await credentialAccessToken({ ...c, access_token: undefined }), expires_at: undefined };
const adapter = harnessAdapter(opts.harness);
const name = opts.name ?? 'gbrain';
if (!isValidName(name)) throw new Error('Invalid connection name');
const common = { ...credentialReceipt(c), harness: adapter.id, native_harness_verified: false, next_action: adapter.reload };
let deactivated: Awaited<ReturnType<typeof installSharedSkillsConnection>> | undefined;
if (opts.remove || (opts.sharedSkills ?? c.shared_skills)?.follow === false) {
const root = harnessSharedSkillsRoot(opts);
if (root) {
const prior = readJson(adapter.connection === 'thin-cli' ? join(root, 'harness-connection.json')
: join(dirname(root), `.gbrain-connection-${adapter.id}-${name}.json`));
if (prior.client_id && (prior.client_id !== c.client_id || prior.mcp_url !== c.mcp_url)) throw new Error('configuration_conflict: connection name belongs to another client');
deactivated = await installSharedSkillsConnection(c, { ...opts, root });
}
}
if (adapter.connection === 'manual') return { ...common, status: 'pending', reason: 'manual_configuration_required', documentation: adapter.guide,
shared_skills: { status: 'pending', reason: 'native_installation_authority_unverified', native: 'unverified' } };
if (adapter.connection === 'thin-cli') {
const installed = await installThinClient(c, opts, common);
const shared_skills = deactivated ?? await installSharedSkillsConnection(c, { ...opts, root: join(opts.root!, '.gbrain'), launcher: join(opts.root!, 'bin', 'gbrain') });
return { ...installed, native_harness_verified: false, shared_skills,
remote_membership_pending: 'remote_membership_pending' in shared_skills && shared_skills.remote_membership_pending === true };
}
const configPath = opts.configPath ?? (adapter.connection === 'codex-toml' ? codexConfigPath()
: adapter.connection === 'claude-json' ? claudeUserMcpConfigPath() : opencodeGlobalConfigPath());
assertNoSymlinks(configPath);
mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
const lock = await acquireBootstrapLock(dirname(configPath));
try {
const receiptPath = join(dirname(configPath), `.gbrain-connection-${adapter.id}-${name}.json`);
const prior = readJson(receiptPath);
if (prior.client_id && (prior.client_id !== c.client_id || prior.mcp_url !== c.mcp_url)) throw new Error('configuration_conflict: connection name belongs to another client');
const before = nativeEntry(configPath, adapter.connection, name);
assertEntryOwned(before, prior, adapter.connection);
if (opts.remove && adapter.connection === 'codex-toml' && existsSync(configPath)) {
const orphaned = codexToolsOutsideBlock(readFileSync(configPath, 'utf8'), name);
if (orphaned.length) throw new Error(`configuration_conflict: Codex tool settings for ${orphaned.join(', ')} ([mcp_servers.${name}.tools.*]) sit outside the gbrain-managed block; removing the server would leave them without one. Delete those tables in ${configPath}, then re-run.`);
}
if (adapter.connection === 'opencode-json') {
const sibling = opencodeGlobalSiblingPath(configPath);
if (sibling && nativeEntry(sibling, adapter.connection, name) !== undefined) throw new Error('configuration_conflict: same-name entry in sibling opencode config; preserve it and choose one explicit configuration before installing');
}
const token = opts.remove ? '' : await credentialAccessToken(c);
const entry = adapter.connection === 'codex-toml' ? { url: c.mcp_url, http_headers: { Authorization: `Bearer ${token}` } }
: adapter.connection === 'opencode-json' ? { type: 'remote', url: c.mcp_url, headers: { Authorization: `Bearer ${token}` }, enabled: true }
: { type: 'http', url: c.mcp_url, headers: { Authorization: `Bearer ${token}` } };
if (!opts.remove) atomicWriteTextFile(receiptPath, `${JSON.stringify({ ...prior, ...common, status: 'prepared', entry_hash: before === undefined ? null : ownedEntryHash(before, adapter.connection), pending_entry_hash: hash(entry), config_path: configPath })}\n`, { forceMode: 0o600 });
if (adapter.connection === 'codex-toml') {
if (opts.remove) removeCodexHttpServerBlock(configPath, name);
else writeCodexHttpServerBlock(configPath, { name, url: c.mcp_url, bearerToken: token });
} else if (adapter.connection === 'opencode-json') {
if (opts.remove) removeOpencodeMcpEntry(configPath, name, { url: c.mcp_url });
else {
writeOpencodeMcpEntry(configPath, { kind: 'remote', name, url: c.mcp_url, tokenMode: 'inline', bearerToken: token }, { expect: { url: c.mcp_url } });
}
} else {
const config = readJson(configPath);
if (config.mcpServers !== undefined && (!config.mcpServers || typeof config.mcpServers !== 'object' || Array.isArray(config.mcpServers))) throw new Error('configuration_conflict: mcpServers is not an object');
const servers = config.mcpServers ?? {};
if (opts.remove) delete servers[name];
else {
servers[name] = entry;
}
config.mcpServers = servers;
atomicWriteTextFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { forceMode: 0o600 });
}
const beside = instructionFileBeside(adapter.connection, configPath);
const instructions = installerBrainFirst({ target: brainFirstTargetAt(beside.harness, beside.path), access: { kind: 'mcp', server: name },
writer: `gbrain connect --harness ${adapter.id} --install`, instructions: opts.instructions, remove: opts.remove });
const keptForOther = opts.remove && readBrainFirstLedger().some((b) => b.harness === beside.harness && b.path === beside.path && b.status === 'installed' && b.access.kind === 'mcp' && b.access.server !== name);
const skills = keptForOther
? { harness: beside.harness, path: beside.path, decision: { value: 'off', source: 'flag' }, action: 'skip', state_before: inspectSkillsBlock(beside.path).state, detail: `the skills index in ${beside.path} sits beside another connection's brain-first block, so removing \`${name}\` leaves it` } satisfies SkillsBlockOutcome
: installerSkillsBlock({ target: brainFirstTargetAt(beside.harness, beside.path), launcher: opts.gbrainBin ?? indexLauncher() ?? 'gbrain',
writer: `gbrain connect --harness ${adapter.id} --install`, brainFirstDeclined: instructions.decision.value === 'declined', skillLoading: opts.skillLoading, audience: 'downstream', remove: opts.remove });
const skillsFailed = skillsOutcomeFailed(skills) ? { skills_failed: true } : {};
const turn = installerTurnHook({ harness: beside.harness, accepted: !opts.remove && instructions.decision.value === 'accepted' && instructions.action !== 'preserve',
gbrainBin: resolveGbrainBin(), gbrainHome: process.env.GBRAIN_HOME?.trim() || undefined, paths: opts.configPath ? turnHookPathsBeside(adapter.connection, configPath) : undefined,
rerun: `gbrain setup ${beside.harness} --instructions-only` });
const turn_hook = { ...turn.outcome, ...(turn.verdict ? { check: turn.verdict } : {}),
...(turn.verdict && !turn.verdict.ok ? { error: { code: 'turn_hook_not_loaded', reason: turn.verdict.reason, message: turn.verdict.message, fix: turnHookFix(beside.harness, ['gbrain', 'setup', beside.harness, '--instructions-only']) } } : {}) };
if (opts.remove) {
if (existsSync(receiptPath)) unlinkSync(receiptPath);
const shared_skills = deactivated ?? await installSharedSkillsConnection(c, { ...opts, root: join(dirname(configPath), `.gbrain-${adapter.id}-${name}`) });
const pending = 'remote_membership_pending' in shared_skills && shared_skills.remote_membership_pending === true;
return { ...common, status: 'removed', config_path: configPath, shared_skills, remote_membership_pending: pending, instructions, skills, turn_hook, ...skillsFailed,
next_action: pending ? 'Local configuration and unchanged owned skills were removed. Remote membership deactivation remains pending; retry when host authority is available.'
: 'The client configuration was removed. Revoke the grant on the brain host if access should end.' };
}
const nextReceipt = { ...common, entry_hash: ownedEntryHash(nativeEntry(configPath, adapter.connection, name), adapter.connection), status: 'installed',
...inlineTokenReceipt(c, adapter.id, name, configPath, adapter.reload, opts.credentialsFile) };
atomicWriteTextFile(receiptPath, `${JSON.stringify(nextReceipt, null, 2)}\n`, { forceMode: 0o600 });
const shared_skills = deactivated ?? await installSharedSkillsConnection(c, { ...opts, root: join(dirname(configPath), `.gbrain-${adapter.id}-${name}`) });
return { ...nextReceipt, shared_skills, instructions, skills, turn_hook, remote_membership_pending: 'remote_membership_pending' in shared_skills && shared_skills.remote_membership_pending === true, ...skillsFailed };
} finally { lock.release(); }
}
async function installThinClient(c: HarnessCredentials, opts: InstallOptions, common: Record<string, unknown>) {
if (!opts.root) throw new Error('storage_root_unverified: pass --root with a verified absolute persistent directory');
const root = checkedRoot(opts.root);
if (!opts.remove && !c.client_secret) throw new Error('Thin CLI installation requires a renewable client credential');
if (!existsSync(root)) mkdirSync(root, { mode: 0o700 });
const lock = await acquireBootstrapLock(root);
try {
const state = join(root, '.gbrain');
const configPath = join(state, 'config.json');
const receiptPath = join(state, 'harness-connection.json');
const existing = readJson(configPath);
const prior = readJson(receiptPath);
if (!prior.client_id && readdirSync(root).some(p => p !== '.gbrain-bootstrap.lock')) {
throw new Error('configuration_conflict: existing state has no connection receipt; choose a fresh root');
}
if (prior.client_id && (prior.client_id !== c.client_id || prior.mcp_url !== c.mcp_url || prior.root !== root)) throw new Error('configuration_conflict: receipt belongs to another connection or root');
if (Object.keys(existing).length && (!prior.client_id || prior.client_id !== c.client_id || existing.remote_mcp?.oauth_client_id !== c.client_id || existing.remote_mcp?.mcp_url !== c.mcp_url)) {
throw new Error('configuration_conflict: choose a fresh root; this command never converts an existing brain');
}
const config = { engine: 'postgres', remote_mcp: { issuer_url: c.issuer_url, mcp_url: c.mcp_url,
oauth_client_id: c.client_id, oauth_client_secret: c.client_secret } };
const sourceCli = fileURLToPath(new URL('../../cli.ts', import.meta.url));
const launcher = join(root, 'bin', 'gbrain');
const brainFirst = resolveBrainFirstDecision(opts.instructions, prior.brain_first_instructions === 'declined' ? { status: 'declined' } : undefined).value;
const skillLoading = opts.remove || brainFirst === 'declined' ? 'off' : resolveSkillLoading(opts.skillLoading, isSkillLoading(prior.skill_loading) ? { mode: prior.skill_loading } : undefined).value;
const rerun = `gbrain connect ${shellQuote(c.mcp_url)} --harness ${shellQuote(opts.harness)} --credentials-file <private-handoff-file> --root ${shellQuote(root)} --install`;
const skillsIndex = skillLoading === 'spring' ? renderSkillsSnippet(opts.harness, launcher, 'downstream', { refresh: rerun, optOut: `${rerun} --skill-loading off` }) : '';
const instructionsHead = `${brainFirst === 'declined' ? '' : renderBrainFirstSnippet(opts.harness, { kind: 'cli', launcher }, 're-run gbrain connect with --no-instructions')}${skillsIndex}`;
const files = [
{ path: '.gbrain/config.json', text: `${JSON.stringify(config, null, 2)}\n`, mode: 0o600 },
{ path: 'bin/gbrain', text: renderAgentLauncher({ root, bunPath: process.execPath, cliPath: sourceCli.includes('$bunfs') ? undefined : sourceCli, mode: 'thin-client',
repairHint: `Reinstall GBrain in this environment, then repeat: gbrain connect ${shellQuote(c.mcp_url)} --harness ${shellQuote(opts.harness)} --credentials-file <private-handoff-file> --root ${shellQuote(root)} --install` }), mode: 0o700 },
{ path: 'GBRAIN-INSTRUCTIONS.md', text: `${instructionsHead ? `${instructionsHead}\n` : ''}${GBRAIN_MCP_INSTRUCTIONS}\n\nRun commands with the absolute launcher: ${launcher}\nThis is a hosted connection. The host grant controls sources and permissions.\n`, mode: 0o600 },
];
const owned: Record<string, string> = prior.owned_files ?? {};
const pending: Record<string, { before: string | null; after: string }> = prior.pending_files ?? {};
// Preflight EVERY file before making any change, including removal.
for (const file of files) {
const target = confinedPath(root, file.path);
if (existsSync(target) && ![owned[file.path], pending[file.path]?.before, pending[file.path]?.after].includes(sha256(readFileSync(target)))) throw new Error('configuration_conflict: refusing to replace or remove an unowned or edited thin-client file');
}
if (opts.remove) {
for (const file of files) { const path = confinedPath(root, file.path); if (existsSync(path)) unlinkSync(path); }
privateWrite(receiptPath, `${JSON.stringify({ ...common, root, status: 'removed', owned_files: {} }, null, 2)}\n`);
return { ...common, status: 'removed', root, next_action: 'Disable the native skill and routine. Revoke the client on the host to end access; separately protect or remove retained handoff files.' };
}
const receipt = { ...common, root, launcher, config_path: configPath, status: 'prepared', native_instructions: 'pending', brain_first_instructions: brainFirst, skill_loading: skillLoading, owned_files: owned, pending_files: pending };
const save = () => privateWrite(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
save();
for (const file of files) {
const target = confinedPath(root, file.path);
pending[file.path] = { before: existsSync(target) ? sha256(readFileSync(target)) : null, after: sha256(file.text) }; save();
privateWrite(target, file.text, file.mode);
owned[file.path] = pending[file.path].after; delete pending[file.path]; save();
}
receipt.status = 'installed'; save();
return receipt;
} finally { lock.release(); }
}