Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import type { BrainEngine } from '../engine.ts';
import { configDir, type GBrainConfig } from '../config.ts';
import { checkedRoot, confinedPath, sha256, privateWrite, readFileConfigState } from '../agent-install/state.ts';
import { findBridgeEntry, loadBridgeState } from './bridge-state.ts';
import { ownedBridgeSlugs, SHARED_DEP_LEDGER_KEY } from './harness-bridge.ts';
import { isMissingSchemaObject } from '../utils.ts';
import { createSharedSkillsAdapter, type SharedSkillsToolCaller } from '../shared-skills/adapter.ts';
import { verifyLocalWriter, withVerifiedLocalRegistration, type LocalRegistration } from '../persistence/identity.ts';
import { renderAgentLauncher } from '../agent-install/launcher.ts';
import { resolveSourceWithTier, ALL_SOURCES } from '../source-resolver.ts';
import { resolveBrainId } from '../brain-resolver.ts';
import { acquireBootstrapLock } from '../bootstrap/lock.ts';
import { assertLegacySkillFilesystemWrite } from './writer-guard.ts';
import { readPrivateText } from '../harness/credentials.ts';
import { harnessAdapter } from '../harness/registry.ts';
import { opError, OperationError } from '../ops/contract.ts';
async function bindBridgeTarget(engine: BrainEngine, brainId: string, adapter: string, root: string, follow: boolean): Promise<LocalRegistration> {
const registration = JSON.parse(readPrivateText(confinedPath(configDir(), `persistence/${brainId}.cli.json`), 65536)) as LocalRegistration;
if (registration.lane !== 'cli' || typeof registration.credential !== 'string' || !/^[a-f0-9-]{36}$/i.test(registration.id)) {
throw opError('bridge_ownership_conflict', 'The private local CLI registration is invalid.',
`The private CLI registration for brain ${brainId} is malformed, so no bridge was bound. Inspect the local writer registrations; re-registering is the user's decision.`,
{ fix: { argv: ['gbrain', 'auth', 'local-writer', 'list', '--json'], consent: [], actor: 'agent', why: 'Shows the local writer registrations and whether the CLI one is active.', requires_exclusive: false } });
}
let verified = false;
try { await verifyLocalWriter(engine, registration); verified = true; }
catch (error) { if (follow) throw error; }
const claimKey = `shared_skills.bridge_owner.v1.${registration.id}.${adapter}`;
const target = sha256(JSON.stringify([brainId, root]));
const refuseIndependent = () => opError('independent_principal_required',
'This local CLI principal already owns another source/destination for this harness. Reuse that bridge target; independent installations need separate private-handoff principals. Leaving does not release this binding.',
`Install the ${adapter} bridge to the destination this CLI principal already owns, or give the second installation its own private-handoff principal; nothing was changed.`);
const existing = await engine.getConfig(claimKey);
if (existing !== null && existing !== undefined) {
if (existing !== target) throw refuseIndependent();
return registration;
}
if (!verified) {
throw opError('bridge_ownership_conflict', 'Restore writer access to verify legacy bridge ownership before attempting cleanup.',
'The CLI writer registration could not be verified, so legacy bridge ownership cannot be checked; nothing was changed. Inspect the local writer registrations before trying again.',
{ fix: { argv: ['gbrain', 'auth', 'local-writer', 'list', '--json'], consent: [], actor: 'agent', why: 'Shows whether the CLI writer registration is active.', requires_exclusive: false } });
}
const [member] = await engine.executeRaw<{ installation_id: string }>(
"SELECT installation_id FROM shared_skill_members WHERE principal_kind='local_cli' AND principal_id=$1 AND adapter=$2", [registration.id, adapter]);
const readReceipt = (path: string) => {
const receipt = JSON.parse(readPrivateText(path, 4 * 1024 * 1024)) as { format_version: number; adapter: string; brain_id: string; installation_id: string };
if (receipt.format_version !== 1 || typeof receipt.adapter !== 'string' || typeof receipt.brain_id !== 'string' || typeof receipt.installation_id !== 'string') {
throw opError('bridge_ownership_conflict', 'Preserve the invalid legacy enrollment receipt before retrying.',
`${path} is not a valid legacy enrollment receipt. Keep it, show it to the user, and resolve which installation it belongs to before installing again; nothing was changed.`);
}
return receipt;
};
if (member) {
const parent = dirname(root);
const directories = existsSync(parent) ? readdirSync(parent).filter(name => /^[a-f0-9]{32}$/.test(name)) : [];
if (directories.length > 4096) {
throw opError('bridge_ownership_conflict', 'The legacy bridge inventory exceeds the ownership inspection limit.',
`${parent} holds more than 4096 legacy bridge directories, beyond what gbrain inspects. Ask the user to archive old copies there before installing again; nothing was changed.`);
}
const matching: string[] = [];
for (const directory of directories) {
const candidate = confinedPath(parent, `${directory}/shared-skills/receipt.json`);
if (!existsSync(candidate)) continue;
const receipt = readReceipt(candidate);
if (receipt.brain_id === brainId && receipt.adapter === adapter && receipt.installation_id === member.installation_id) matching.push(join(parent, directory));
}
if (matching.length !== 1) {
throw opError('bridge_ownership_conflict',
'Existing membership has missing or multiple bridge receipts. No enrollment or native files were changed. Preserve and resolve all old copies before using separate private-handoff principals.',
`Found ${matching.length} bridge receipts for installation ${member.installation_id} under ${parent}. Show the user the copies and keep exactly one before installing again.`);
}
if (matching[0] !== root) throw refuseIndependent();
} else if (existsSync(confinedPath(root, 'shared-skills/receipt.json'))) {
throw opError('bridge_ownership_conflict', 'The existing bridge receipt does not belong to the current authenticated principal.',
`${root} already holds another principal's bridge receipt. Install to a different destination, or ask the user which installation should own this one; nothing was changed.`);
}
await engine.executeRaw('INSERT INTO config(key,value) VALUES($1,$2) ON CONFLICT(key) DO NOTHING', [claimKey, target]);
if (await engine.getConfig(claimKey) !== target) throw refuseIndependent();
return registration;
}
export async function sharedBrainBridgePlan(options: {
engine: BrainEngine | null;
config: GBrainConfig | null;
harness: string;
dest?: string;
statePath?: string;
}) {
let active = !!options.config?.remote_mcp;
let unavailable = false;
if (!active && options.engine) {
try {
const [brain] = await options.engine.executeRaw<{ skill_bundles_enabled: boolean }>('SELECT skill_bundles_enabled FROM persistence_brain WHERE singleton=1');
active = brain?.skill_bundles_enabled === true;
} catch (error) {
if (!isMissingSchemaObject(error, 'table', 'persistence_brain')) unavailable = true;
}
} else if (!active && (options.config?.database_url || options.config?.database_path || options.config?.engine === 'pglite')) unavailable = true;
if (!active && !unavailable) return null;
const migration = { owned_unchanged: [] as string[], modified: [] as string[], missing: [] as string[], ownership: 'unverified' };
if (options.dest) {
const entry = findBridgeEntry(loadBridgeState({ statePath: options.statePath }), { harness: options.harness, dest: options.dest });
if (entry) {
migration.ownership = 'ledger';
// #6922: remove --harness keeps the shared deps (_shared), so once no owned slug is left they are not a legacy copy to migrate.
const owned = ownedBridgeSlugs(entry).length > 0;
const files = new Map(Object.entries(entry.written).filter(([slug]) => owned || slug !== SHARED_DEP_LEDGER_KEY).flatMap(([, record]) => Object.entries(record.files)));
if (files.size > 2048) migration.modified.push('(inventory limit exceeded)');
else for (const [relative, expected] of files) {
try {
const path = confinedPath(checkedRoot(options.dest), relative);
if (!existsSync(path)) { migration.missing.push(relative); continue; }
const stat = lstatSync(path);
if (!stat.isFile() || stat.size > 8 * 1024 * 1024 || sha256(readFileSync(path)) !== expected) migration.modified.push(relative);
else migration.owned_unchanged.push(relative);
} catch { migration.modified.push(relative); }
}
}
}
const reason = migration.modified.length ? 'legacy_skill_conflict' : migration.owned_unchanged.length
? 'legacy_skill_migration_required' : unavailable ? 'shared_brain_unavailable' : 'follow_approval_required';
return {
status: 'pending', reason, native: 'unverified', legacy_copy_written: false, migration,
next_action: migration.modified.length
? 'Preserve the modified legacy skills and resolve their native shadow copies before enrolling. No copied bodies, pointers, or unrelated native skills were changed.'
: migration.owned_unchanged.length
? 'Review and explicitly remove the unchanged bridge-owned copies with skillpack remove for this harness and destination, then use the shared-skills connection installer with an approved follow policy. No legacy copy was removed automatically.'
: unavailable
? 'Reconnect the selected brain and verify its shared catalog before installing skills. Memory and existing native files are unchanged; unavailable is not a legacy-copy fallback.'
: options.config?.remote_mcp
? 'Use the existing remote private-handoff connection installer with explicit follow approval and a skills_member_self grant for join_brain, sync_brain_skills, leave_brain and catalog reads. Do not mint against a local brain or install bundled copies.'
: 'Use bootstrap harness with explicit shared-skills follow approval, or the installation-bound setup for a personal agent. Confirm the intended source and self-member grant; skillpack scaffold does not invent an enrollment credential or install stale bundled copies.',
};
}
export async function installSharedBrainBridge(options: {
engine: BrainEngine | null;
config: GBrainConfig | null;
harness: string;
dest?: string;
policy?: 'follow' | 'memory-only';
dryRun?: boolean;
statePath?: string;
}) {
const plan = await sharedBrainBridgePlan(options);
if (!plan) return options.policy ? {
status: 'pending', reason: options.policy === 'follow' ? 'shared_content_migration_required' : 'memory_only', native: 'unverified', legacy_copy_written: false,
migration: { owned_unchanged: [] as string[], modified: [] as string[], missing: [] as string[], ownership: 'unverified' },
next_action: options.policy === 'follow' ? 'Activate the selected brain’s shared content through the reviewed host migration before following. No legacy body or stub was installed as a substitute.'
: 'Memory-only was selected. No bundled skill copies or shared routers were installed.',
} : null;
if (options.config?.remote_mcp || !options.engine || !options.config || options.dryRun ||
plan.migration.modified.length || plan.migration.owned_unchanged.length) return plan;
if (!options.dest) return { ...plan, reason: 'native_destination_required', next_action: 'Specify a supported native skill destination before approving shared following. No native installation is inferred.' };
const engine = options.engine, config = options.config;
const pending = (reason: string, next_action: string) => ({ ...plan, reason, next_action });
const home = dirname(configDir());
const stored = readFileConfigState(join(configDir(), 'config.json'));
if (resolveBrainId(null) !== 'host' || stored.kind !== 'present' || stored.config.engine !== config.engine ||
stored.config.database_url !== config.database_url || stored.config.database_path !== config.database_path) {
return pending('bound_connection_required', 'The selected brain depends on ambient routing. Use an installation-bound connection instead of creating a launcher that could select another brain.');
}
const source = await resolveSourceWithTier(engine, null);
if (source.source_id === ALL_SOURCES) return pending('source_approval_required', 'Select one explicit source for the native shared router before approving following.');
const dest = checkedRoot(options.dest);
try { assertLegacySkillFilesystemWrite(dest); }
catch { return pending('canonical_destination_refused', 'Native router installation cannot write into a managed canonical source. Choose the harness’s separate native skills directory; publish canonical skill changes through the catalog.'); }
const [brain] = await engine.executeRaw<{ brain_id: string }>('SELECT brain_id FROM persistence_brain WHERE singleton=1');
const adapterId = harnessAdapter(options.harness).id;
const key = sha256(JSON.stringify([brain.brain_id, source.source_id, adapterId, dest])).slice(0, 32);
const root = join(configDir(), 'skillpack-shared', key);
const receiptPath = confinedPath(root, 'installation.json');
const priorText = existsSync(receiptPath) ? readFileSync(receiptPath, 'utf8') : null;
let prior: { policy?: string; launcher_hash?: string; pending_hash?: string } = {};
if (priorText !== null) {
try {
prior = JSON.parse(priorText);
if (!prior || typeof prior !== 'object' || Array.isArray(prior)) throw new Error('invalid receipt');
}
catch { return pending('local_conflict', 'Preserve the unreadable shared bridge receipt before retrying.'); }
}
const policy = options.policy ?? prior.policy;
if (policy !== 'follow' && policy !== 'memory-only') return plan;
if (policy === 'memory-only' && !existsSync(join(root, 'shared-skills', 'receipt.json'))) return {
...plan, reason: 'memory_only', next_action: 'Shared following is disabled. Memory and unrelated native skills are unchanged.',
};
const launcher = confinedPath(root, 'gbrain');
const sourceCli = fileURLToPath(new URL('../../cli.ts', import.meta.url));
const content = renderAgentLauncher({ root: home, sourceId: source.source_id, bunPath: process.execPath,
cliPath: sourceCli.includes('$bunfs') ? undefined : sourceCli });
const actual = existsSync(launcher) ? sha256(readFileSync(launcher)) : null;
if (actual !== null && ![prior.launcher_hash, prior.pending_hash].includes(actual)) return pending('local_conflict', 'The installation-bound launcher was edited or is unowned. Preserve it before retrying.');
let registration: LocalRegistration;
try { registration = await bindBridgeTarget(engine, brain.brain_id, adapterId, root, policy === 'follow'); }
catch (error) {
if (error instanceof OperationError && ['independent_principal_required', 'bridge_ownership_conflict'].includes(error.code)) {
if (policy !== 'memory-only') return pending(error.code, error.message);
try {
const cleanupLock = await acquireBootstrapLock(root);
try {
if ((existsSync(receiptPath) ? readFileSync(receiptPath, 'utf8') : null) !== priorText) throw new Error('changed ownership receipt');
const state = confinedPath(root, 'shared-skills');
const cached = JSON.parse(readPrivateText(join(state, 'receipt.json'), 4 * 1024 * 1024));
if (cached.brain_id !== brain.brain_id || cached.adapter !== adapterId || typeof cached.installation_id !== 'string') throw new Error('unbound local receipt');
const nativePath = confinedPath(state, 'native-router.json');
if (existsSync(nativePath)) {
const native = JSON.parse(readPrivateText(nativePath, 65536));
const name = `gbrain-shared-${sha256(JSON.stringify([brain.brain_id, cached.installation_id, adapterId, `bridge-${key}`])).slice(0, 24)}`;
if (native.version !== 1 || native.name !== name || native.skills_dir !== dest || native.brain_id !== brain.brain_id ||
native.installation_id !== cached.installation_id || native.adapter !== adapterId) throw new Error('foreign native router ownership');
} else if (cached.native_router_path) throw new Error('missing native router ownership');
const local = createSharedSkillsAdapter({ root: state, adapter: adapterId, call: async () => { throw error; } });
const result = await local.leave();
privateWrite(receiptPath, `${JSON.stringify({ ...prior, policy: 'memory-only' })}\n`);
return { ...plan, ...result, status: 'pending', reason: error.code, remote_membership_pending: true,
next_action: `${error.message} Only unchanged owned local files were cleaned up; edited files are retained. Shared server leave was withheld to protect the other enrollment. Native disablement remains unverified.` };
} finally { cleanupLock.release(); }
} catch {
return pending('bridge_local_cleanup_conflict', 'The existing native ownership cannot be confined to this target. Preserve the files for manual cleanup; no server leave was sent and native disablement is unverified.');
}
}
return pending('bridge_ownership_unavailable', 'Verify the installation’s existing private local CLI registration and bridge receipts before retrying. No target artifacts or enrollment were changed.');
}
mkdirSync(root, { recursive: true, mode: 0o700 });
const lock = await acquireBootstrapLock(root);
try {
if ((existsSync(receiptPath) ? readFileSync(receiptPath, 'utf8') : null) !== priorText) return pending('local_conflict', 'Another installer changed the shared bridge receipt. Retry without overwriting it.');
const current = existsSync(launcher) ? sha256(readFileSync(launcher)) : null;
if (current !== actual) return pending('local_conflict', 'The installation-bound launcher changed while installing. Preserve it and retry.');
privateWrite(receiptPath, `${JSON.stringify({ ...prior, policy, pending_hash: sha256(content) })}\n`);
if (current !== sha256(content)) privateWrite(launcher, content, 0o700);
privateWrite(receiptPath, `${JSON.stringify({ policy, launcher_hash: sha256(content) })}\n`);
const { operationsByName } = await import('../operations.ts');
const ctx = { engine, config, sourceId: source.source_id, remote: false, dryRun: false,
logger: { info() {}, warn() {}, error() {} } };
const allowed = new Set(['join_brain', 'sync_brain_skills', 'leave_brain', 'get_skill', 'get_skill_asset']);
const call: SharedSkillsToolCaller = async <T>(name: string, params: Record<string, unknown>): Promise<T> => {
if (!allowed.has(name) || !operationsByName[name]) throw new Error('unsupported shared-skills operation');
return await withVerifiedLocalRegistration(engine, registration, async () => await operationsByName[name].handler(ctx, params) as T);
};
const adapter = createSharedSkillsAdapter({ call, root: join(root, 'shared-skills'), adapter: adapterId,
launcher, nativeSkillsDir: dest, connectionName: `bridge-${key}` });
const result = policy === 'follow' ? await adapter.join({ approved: true, source_ids: [source.source_id] }) : await adapter.leave();
if ('remote_membership_pending' in result && result.remote_membership_pending) return { ...plan, ...result, status: 'pending', reason: 'remote_membership_pending',
next_action: 'Owned local router cleanup completed, but enrollment closure remains pending. Repair the existing local writer and retry memory-only cleanup; no new authority was created.' };
return { ...plan, ...result, source_id: source.source_id, launcher, reason: policy === 'follow' ? 'native_activation_unverified' : 'memory_only' };
} catch {
return pending('shared_enrollment_unavailable', 'Memory and unrelated files are preserved. Verify local writer authority, follow policy and the owned router/cache, then retry; native activation is unverified.');
} finally { lock.release(); }
}