Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { spawnSync } from '../spawn.ts';
import { gbrainPath, isThinClient } from '../config.ts';
import { opError, type OperationContext } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { claimWorktree, getWorktreeBinding, readPersistenceBrain } from '../persistence/ownership.ts';
import { unboundBindCommand } from '../persistence/unbound-source.ts';
import { activateSharedSkillPersistence } from '../persistence/skill-activation.ts';
import { checkedContentRoot } from './setup-files.ts';
import { DEFAULT_SHARED_PACK_ID, packagedSharedSkillPolicy, packagedSharedSkills } from './setup-bundle.ts';
import { publicationEnabled, setSharedSkillPolicy } from './policy.ts';
import type { BrainEngine } from '../engine.ts';
import { assertPackagedSkillSource, sharedSkillSourcePolicy } from './setup-source-policy.ts';
import { gitChildEnv } from '../git-env.ts';
import { initializeLocalPersistence, requestPrincipalForContext } from '../persistence/page-mutations.ts';
import { waitForWrite } from '../persistence/service.ts';
import { isTerminal, type WriteRequest } from '../persistence/model.ts';
export async function isNewContentDatabase(engine: BrainEngine): Promise<boolean> {
const [row] = await engine.executeRaw<{ fresh: boolean }>("SELECT to_regclass('public.pages') IS NULL AND to_regclass('public.config') IS NULL AND to_regclass('public.persistence_brain') IS NULL AS fresh");
return row?.fresh === true;
}
export interface SharedContentOptions {
sourceId?: string;
root?: string;
dbOnly?: boolean;
git?: 'init' | 'none';
dryRun?: boolean;
fresh?: boolean;
}
export interface SharedContentReceipt {
version: 1;
brain_id: string | null;
source_id: string;
source_incarnation: string | null;
root: string | null;
repository_kind: 'git' | 'content_directory' | 'db_only' | 'remote';
backup: 'not_verified';
status: 'ready' | 'action_required' | 'planned';
stage: 'root' | 'owner' | 'pack' | 'complete';
pending_actions: string[];
owned_root: boolean;
root_identity?: { device: number; inode: number };
fresh_root_activation?: boolean;
}
export function contentSetupKey(sourceId: string, incarnation: string): string {
return `shared_skills.content.v1.${sourceId}.${incarnation}`;
}
export async function saveContentReceipt(ctx: OperationContext, receipt: SharedContentReceipt): Promise<void> {
if (receipt.source_incarnation) await ctx.engine.setConfig(contentSetupKey(receipt.source_id, receipt.source_incarnation), JSON.stringify(receipt));
}
export async function setupSharedBrainContent(ctx: OperationContext, options: SharedContentOptions = {}): Promise<SharedContentReceipt> {
if (ctx.remote !== false) {
throw opError('permission_denied', 'Content-root setup requires the trusted local host.',
'Content-root setup runs only from gbrain init on the brain host; a remote connection cannot create or choose content directories.');
}
const receipt: SharedContentReceipt = {
version: 1, brain_id: null, source_id: options.sourceId ?? ctx.sourceId ?? 'default', source_incarnation: null,
root: null, repository_kind: 'remote', backup: 'not_verified', status: 'action_required', stage: 'root', pending_actions: [], owned_root: false,
};
if (isThinClient(ctx.config)) {
receipt.pending_actions = ['Manage canonical content on the host brain; this thin client creates no content repository.'];
return receipt;
}
const sourceId = options.sourceId ?? ctx.sourceId;
const brain = await readPersistenceBrain(ctx.engine);
const [source] = await ctx.engine.executeRaw<{ id: string; incarnation: string; local_path: string | null }>(
'SELECT id,incarnation,local_path FROM sources WHERE id=$1 AND NOT archived', [sourceId]);
if (!source) {
throw opError('source_changed', 'Content setup requires an active selected source.',
`Source ${sourceId} is archived or not registered. Check the registered sources, then run gbrain init again for an active one.`,
{ fix: readFix('Lists the registered sources and whether each is archived.', { argv: ['gbrain', 'sources', 'list', '--json'] }) });
}
receipt.brain_id = brain.brain_id;
receipt.source_id = sourceId;
receipt.source_incarnation = source.incarnation;
const sourcePolicy = await sharedSkillSourcePolicy(ctx.engine, sourceId);
if (sourcePolicy.mode !== 'content') {
receipt.root = source.local_path;
receipt.repository_kind = source.local_path ? 'content_directory' : 'db_only';
if (source.local_path) {
const git = spawnSync('git', ['-C', source.local_path, 'rev-parse', '--show-toplevel'], { env: gitChildEnv(), encoding: 'utf8', timeout: 15_000 });
if (git.status === 0 && resolve(git.stdout.trim()) === resolve(source.local_path)) receipt.repository_kind = 'git';
}
receipt.pending_actions = [sourcePolicy.reason];
if (!options.dryRun) await saveContentReceipt(ctx, receipt);
return receipt;
}
const key = contentSetupKey(sourceId, source.incarnation);
const saved = await ctx.engine.getConfig(key);
let prior: SharedContentReceipt | null = null;
if (saved) {
const checkpointFix = { fix: readFix('Prints the saved content setup checkpoint.', { argv: ['gbrain', 'config', 'get', key] }) };
try { prior = JSON.parse(saved); } catch {
throw opError('local_conflict', 'The content setup checkpoint is malformed.',
`The saved content setup checkpoint for source ${sourceId} (config key ${key}) is not valid JSON. Show it to the user and ask how to proceed before changing it.`, checkpointFix);
}
if (prior?.version !== 1 || prior.brain_id !== brain.brain_id || prior.source_incarnation !== source.incarnation) {
throw opError('local_conflict', 'The content setup checkpoint does not match this brain.',
`The content setup checkpoint for source ${sourceId} (config key ${key}) belongs to another brain or source incarnation. Show it to the user and ask how to proceed before changing it.`, checkpointFix);
}
}
const existingRoot = source.local_path || (sourceId === 'default' ? await ctx.engine.getConfig('sync.repo_path') : null);
if (options.root && existingRoot && resolve(options.root) !== resolve(existingRoot)) {
throw opError('local_conflict', 'The selected source already has a different content root; use an explicit source rebind.',
`Source ${sourceId} already uses ${existingRoot}. Run gbrain init without --content-root to keep it; moving it is a deliberate rebind the user must approve.`);
}
if (options.dbOnly && existingRoot) {
throw opError('local_conflict', 'DB-only setup cannot detach an existing canonical source root. Preserve it or use an explicit topology migration.',
`Source ${sourceId} already has the canonical root ${existingRoot}; run gbrain init without --db-only to keep it.`);
}
if (options.dbOnly || !options.root && !existingRoot && prior?.repository_kind === 'db_only') {
receipt.repository_kind = 'db_only';
receipt.pending_actions = ['Memory remains available. Select a host canonical root and validate a full export/import round trip before shared publication.'];
if (!options.dryRun) await saveContentReceipt(ctx, receipt);
return receipt;
}
const [pages] = await ctx.engine.executeRaw<{ present: boolean }>('SELECT EXISTS(SELECT 1 FROM pages WHERE source_id=$1) AS present', [sourceId]);
if (!existingRoot && pages.present) {
receipt.repository_kind = 'db_only';
receipt.pending_actions = ['Existing database pages have no canonical root. Export and verify a round trip on the host before adopting a root; no empty replacement was created.'];
if (!options.dryRun) await saveContentReceipt(ctx, receipt);
return receipt;
}
const root = checkedContentRoot(existingRoot || options.root || prior?.root || gbrainPath('content', brain.brain_id, sourceId));
receipt.root = root;
receipt.owned_root = prior?.owned_root ?? (!existingRoot && (!!options.fresh || !!options.root));
receipt.fresh_root_activation = prior?.fresh_root_activation ?? (!existingRoot && !!options.fresh);
const gitProbe = existsSync(join(root, '.git')) ? spawnSync('git', ['-C', root, 'rev-parse', '--show-toplevel'], { env: gitChildEnv(), encoding: 'utf8', timeout: 15_000 }) : null;
receipt.repository_kind = gitProbe?.status === 0 && resolve(gitProbe.stdout.trim()) === root ? 'git' : 'content_directory';
const existed = existsSync(root);
if (prior?.root && prior.root !== root) {
const bound = existingRoot ? await getWorktreeBinding(ctx.engine, sourceId) !== null : true;
if (existingRoot && (!bound || !brain.enabled)) {
const claim = ['gbrain', 'sources', 'writer', 'claim', sourceId, '--path', root, '--dry-run', '--json'];
const activate = ['gbrain', 'sources', 'writer', 'activate', '--confirm-quiesced', '--shared-skills', '--dry-run', '--json'];
const activateStep = `activate writer persistence (preview with ${activate.join(' ')}, then run it without --dry-run with --admin-intent writer_activate --expected-state <admin_state>)`;
throw opError('local_conflict', 'The canonical root changed after setup began.',
`Content setup for source ${sourceId} began at ${prior.root}, but the source is now registered at ${root} (a host move, transfer or relocation). gbrain repair content-receipt-root lists only sources claimed under activated writer persistence, and this source ${bound ? 'is claimed but persistence is not activated' : 'has no canonical owner'}, so the repair has nothing to list yet. Ask the user, then ${bound ? activateStep : `claim it on this host (preview with ${claim.join(' ')}, then ${unboundBindCommand(sourceId, root)})${brain.enabled ? '' : ` and ${activateStep}`}`}. Then preview gbrain repair content-receipt-root --source ${sourceId}, which lists the step that rebinds the checkpoint, and run the migration again.`,
{ fix: readFix(bound ? 'Previews activating writer persistence with shared skills, read-only.' : `Previews claiming source ${sourceId}'s registered root on this host, read-only.`, { argv: bound ? activate : claim }) });
}
if (existingRoot) {
throw opError('local_conflict', 'The canonical root changed after setup began.',
`Content setup for source ${sourceId} began at ${prior.root}, but the source is now registered at ${root} (a host move, transfer or relocation). Preview gbrain repair content-receipt-root --source ${sourceId}: it lists what proves the new root and the step that rebinds the checkpoint; then run the migration again.`,
{ fix: readFix(`Lists source ${sourceId}'s content checkpoint that names another root, with the step that rebinds it, read-only.`, { argv: ['gbrain', 'repair', 'content-receipt-root', '--source', sourceId] }) });
}
throw opError('local_conflict', 'The canonical root changed after setup began.',
`Content setup for source ${sourceId} began at ${prior.root}; resume it with --content-root ${prior.root}, or ask the user before abandoning that setup.`);
}
if (existingRoot && !existed) {
throw opError('local_conflict', 'The registered content root is missing; restore it rather than creating a replacement.',
`Source ${sourceId}'s registered root ${root} does not exist. Restore it (for example from its Git remote or backup), then run gbrain init again.`);
}
if (!existingRoot && existed && !prior && readdirSync(root).length > 0) {
throw opError('local_conflict', 'The requested root contains unowned files; register an existing source explicitly instead.',
`${root} already has files. Pass --content-root a new or empty directory, or register that directory as a source with gbrain sources add.`);
}
if (prior?.owned_root && existed) {
const stat = statSync(root);
if (prior.root_identity ? prior.root_identity.device !== stat.dev || prior.root_identity.inode !== stat.ino : readdirSync(root).length > 0) {
throw opError('local_conflict', 'The owned root changed or gained unverified files after setup was interrupted.',
`${root} was replaced or gained files after content setup was interrupted, so setup stopped. Ask the user whether those files belong there before resuming gbrain init.`);
}
receipt.root_identity = { device: stat.dev, inode: stat.ino };
}
if (options.dryRun) {
receipt.status = 'planned';
receipt.pending_actions = [existingRoot ? 'Preserve the selected existing root and review source-local skill adoption.' : `Create the combined content directory at ${root}.`, options.git === 'init' ? 'Initialize Git only if this root is newly owned and empty.' : 'Git and off-host backup remain unconfigured.'];
return receipt;
}
if (prior?.stage === 'complete') return prior;
await saveContentReceipt(ctx, receipt);
if (!existed) {
if (!receipt.owned_root) {
receipt.pending_actions = ['Authorize a new owned content root or register an existing source before setup.'];
await saveContentReceipt(ctx, receipt);
return receipt;
}
mkdirSync(dirname(root), { recursive: true, mode: 0o700 });
mkdirSync(root, { mode: 0o700 });
}
if (receipt.owned_root) {
const stat = statSync(root);
receipt.root_identity = { device: stat.dev, inode: stat.ino };
await saveContentReceipt(ctx, receipt);
}
if (options.git === 'init' && receipt.repository_kind !== 'git') {
if (!receipt.owned_root || readdirSync(root).length !== 0) {
throw opError('local_conflict', 'Git initialization is allowed only in a newly owned empty content directory.',
`${root} is not a new empty directory gbrain created; run gbrain init without --git and initialize Git there yourself if the user wants it.`);
}
const git = spawnSync('git', ['init', '--quiet', root], { env: gitChildEnv(), encoding: 'utf8', timeout: 15_000 });
if (!git.error && git.status === 0) receipt.repository_kind = 'git';
else receipt.pending_actions.push('Git initialization was unavailable; install Git and explicitly initialize this content directory later.');
}
if (receipt.repository_kind === 'content_directory' && !receipt.pending_actions.length) receipt.pending_actions.push('Optional: initialize Git explicitly; configure an off-host backup separately.');
if (receipt.owned_root && receipt.repository_kind === 'content_directory') {
const enclosing = spawnSync('git', ['-C', root, 'rev-parse', '--show-toplevel'], { env: gitChildEnv(), encoding: 'utf8', timeout: 15_000 });
if (enclosing.status === 0 && resolve(enclosing.stdout.trim()) !== root) {
throw opError('local_conflict', 'The new content directory is inside another Git worktree. Choose a separate root or explicitly initialize Git here; setup will not claim its parent repository.',
`${root} is inside the Git worktree ${enclosing.stdout.trim()}. Pass --content-root a path outside any repository, or add --git so the content directory gets its own repository.`);
}
}
if (!existingRoot) await ctx.engine.executeRaw('UPDATE sources SET local_path=$1 WHERE id=$2 AND incarnation=$3::uuid AND local_path IS NULL', [root, sourceId, source.incarnation]);
receipt.stage = 'owner';
await saveContentReceipt(ctx, receipt);
if (!receipt.owned_root) {
receipt.pending_actions.push('Preserve existing files. Run the staged shared-skills migration to review ownership, publication policy and source-local skills.');
await saveContentReceipt(ctx, receipt);
return receipt;
}
if (!receipt.fresh_root_activation && !brain.skill_bundles_enabled) {
receipt.pending_actions.push('writer_not_quiesced: this is an existing brain. Stop/exclude older writers, claim this root and explicitly activate shared-skill persistence before publication.');
await saveContentReceipt(ctx, receipt);
return receipt;
}
let binding = await getWorktreeBinding(ctx.engine, sourceId);
if (!binding) binding = await claimWorktree(ctx.engine, sourceId, root);
if (binding.state !== 'active' || !binding.owner_host_id) {
throw opError('owner_unavailable', 'The canonical content owner is not active.',
`Source ${sourceId}'s canonical owner is ${binding.state}, so the packaged skills were not installed. Inspect the binding; activating or moving ownership is the user's decision.`,
{ fix: readFix(`Shows source ${sourceId}'s owner binding and any pending recovery.`, { argv: ['gbrain', 'sources', 'writer', 'status', '--source', sourceId, '--json'] }) });
}
if (!brain.skill_bundles_enabled) await activateSharedSkillPersistence(ctx.engine, { confirmQuiesced: true });
receipt.stage = 'pack';
await saveContentReceipt(ctx, receipt);
if (receipt.fresh_root_activation && await publicationEnabled(ctx)) {
const existingPolicy = await ctx.engine.executeRaw('SELECT epoch FROM shared_skill_policies WHERE source_id=$1 AND source_incarnation=$2::uuid', [sourceId, source.incarnation]);
if (!existingPolicy.length) {
ctx.logger.info('Fresh brain setup approves following the packaged memory skills: prose only, existing memory/discovery tools, no scripts, paid services, capture or editor grants.');
await setSharedSkillPolicy(ctx, sourceId, packagedSharedSkillPolicy(), null);
}
}
await installPackagedSharedSkills(ctx, sourceId);
receipt.stage = 'complete';
receipt.status = 'ready';
await saveContentReceipt(ctx, receipt);
return receipt;
}
export async function installPackagedSharedSkills(ctx: OperationContext, sourceId: string, preservePaths: string[] = []): Promise<void> {
await assertPackagedSkillSource(ctx.engine, sourceId);
// #8453: the adoption key binds the release-stamped payload, so an install begun on an earlier release left its adoption
// under another key. Resume (or keep) that request instead of admitting a second publication of the pack.
await initializeLocalPersistence(ctx);
const principal = await requestPrincipalForContext(ctx);
const [open] = await ctx.engine.executeRaw<WriteRequest>(`SELECT r.* FROM persistence_requests r JOIN sources s ON s.id=r.source_id AND s.incarnation=r.source_incarnation
WHERE r.operation='put_skill' AND r.source_id=$1 AND r.principal_kind=$2 AND r.principal_id=$3 AND r.intent->>'pack_id'=$4
AND r.authority ? 'skillAdoptionPreconditions' AND r.state IN ('queued','deferred','running','recovering','committed') ORDER BY r.sequence DESC LIMIT 1`,
[sourceId, principal.kind, principal.id, DEFAULT_SHARED_PACK_ID]);
const resumed = open ? await waitForWrite(ctx.engine, open, ctx.config, ctx.writeWaitMs) : null;
if (resumed?.state === 'committed') return;
if (resumed && !isTerminal(resumed)) throw packagedPublicationPending(resumed.request_id);
const files = packagedSharedSkills();
for (const path of preservePaths) if (['README.md', 'LICENSE'].includes(path)) delete files[path];
const { adoptSharedSkillpack } = await import('./catalog.ts');
const result = await adoptSharedSkillpack(ctx, sourceId, {
request_id: 'gbrain-default-content-v1', pack_id: DEFAULT_SHARED_PACK_ID,
initial_files: files,
skills: JSON.parse(files['skillpack.json']).skills.map((path: string) => ({
pack_id: DEFAULT_SHARED_PACK_ID, name: path.slice('skills/'.length), expected_revision: null,
files: [{ path: `${path}/SKILL.md`, content: files[`${path}/SKILL.md`], file_class: 'prose' }],
})),
});
const pending = result.receipts.map(receipt => receipt.write_request as { state?: string; request_id?: string } | undefined).find(request => request?.state !== 'committed');
if (pending) throw packagedPublicationPending(pending.request_id);
}
function packagedPublicationPending(requestId: string | undefined) {
return opError('publication_pending', 'The default pack was accepted but is not fully committed; rerun init to resume its durable requests.',
`Inspect the accepted request${requestId ? ` ${requestId}` : ''} first; gbrain init resumes the same durable request (same request_id), so it never publishes the pack twice.`,
requestId ? { fix: readFix('Shows whether the default pack publication committed, is still pending, or failed.', { argv: ['gbrain', 'write-request', '--', requestId] }) } : {});
}