Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Migration-ledger summary — the read-only "what host migrations are
* outstanding" view, shared by the get_health op (TODOS:4063: remote agents
* detect wedged migrations without SSH-ing to run the doctor) and the
* apply-migrations orchestrator (which imports statusForVersion +
* compareVersions from here).
*
* OV4/EV4 (CLI→MCP gap-closure wave): an op must never import
* src/commands/apply-migrations.ts — that module statically pulls the whole
* migration registry (17 migration modules plus orchestrator machinery). This
* module works on VERSION STRINGS ONLY: MIGRATION_VERSIONS below is a plain
* string list, pinned against the real registry by
* test/migration-ledger.test.ts so it cannot drift silently.
*/
import type { Action } from './agent-output.ts';
import type { BrainEngine } from './engine.ts';
import { loadCompletedMigrations, preferencesPaths, type CompletedMigrationEntry } from './preferences.ts';
import { schemaVersionAtConnect } from './migrate-pending.ts';
import { LATEST_SCHEMA_VERSION } from './schema-migrations/latest.generated.ts';
/**
* Version strings of every registered host migration, in registry order.
* APPEND HERE when adding a migration module to src/commands/migrations/
* (the sync test fails the suite otherwise).
*/
export const MIGRATION_VERSIONS: readonly string[] = [
'0.11.0', '0.12.0', '0.12.2', '0.13.0', '0.13.1', '0.14.0', '0.16.0',
'0.18.0', '0.18.1', '0.21.0', '0.22.4', '0.28.0', '0.29.1', '0.31.0',
'0.32.2', '0.43.0', '0.46.3', '0.53.0', '0.60.31',
];
/**
* #6466: migrations a brain owner can decline, by version → the brain-level
* DB config key whose explicit off value declines it. Registry-free (version
* strings and keys only, like MIGRATION_VERSIONS); pinned against each
* module's `optOut` by test/migration-ledger.test.ts.
*/
export const MIGRATION_OPT_OUT_KEYS: Readonly<Record<string, string>> = {
'0.53.0': 'shared_skills.migration.enabled',
};
/** True for an explicit off value; absent, empty or anything else keeps the migration enabled. */
export function isMigrationDeclinedValue(raw: string | null | undefined): boolean {
return typeof raw === 'string' && ['false', '0', 'off', 'no'].includes(raw.trim().toLowerCase());
}
/** Versions MIGRATION_OPT_OUT_KEYS declines on this brain, in version order; an unreadable key counts as enabled. */
export async function declinedMigrations(engine: Pick<BrainEngine, 'getConfig'>): Promise<Set<string>> {
const declined = new Set<string>();
for (const [version, key] of Object.entries(MIGRATION_OPT_OUT_KEYS)) {
if (isMigrationDeclinedValue(await engine.getConfig(key).catch(() => null))) declined.add(version);
}
return declined;
}
/**
* Whether this host's upgrade-migration ledger speaks for the brain. The ledger lives under GBRAIN_HOME, so an empty one
* is a fresh brain only when the brain's schema is new too: an existing brain an older release last opened (its schema
* version above 1 and behind this release when this process connected) still has its upgrade migrations to run. A brain
* whose schema is already current was opened by this release before, so a new or rebuilt GBRAIN_HOME stays quiet there.
*/
export function upgradeLedgerApplies(engine: object): boolean {
const atConnect = schemaVersionAtConnect(engine) ?? 0;
return loadCompletedMigrations().length > 0 || (atConnect > 1 && atConnect < LATEST_SCHEMA_VERSION);
}
/** Bug 3 attempt cap — consecutive partials before a version counts wedged. */
export const MAX_CONSECUTIVE_PARTIALS = 3;
/** Where a wedged migration's failure reasons are recorded: its partial rows in this brain's completion ledger (not every partial row carries phases). */
export function wedgedLedgerHint(): string {
return `the migration's partial rows in ${preferencesPaths.completedJsonl()} (phases[].detail, if present)`;
}
/**
* Compare two semver strings (MAJOR.MINOR.PATCH). Returns -1 / 0 / 1.
* Canonical home (moved from src/commands/migrations/index.ts, which
* re-exports it); originally extracted from upgrade.ts#isNewerThan.
*/
export function compareVersions(a: string, b: string): -1 | 0 | 1 {
const va = a.split('.').map(n => parseInt(n, 10) || 0);
const vb = b.split('.').map(n => parseInt(n, 10) || 0);
for (let i = 0; i < 3; i++) {
const da = va[i] ?? 0;
const db = vb[i] ?? 0;
if (da > db) return 1;
if (da < db) return -1;
}
return 0;
}
export type MigrationLedgerStatus = 'complete' | 'partial' | 'pending' | 'wedged';
/**
* Resolved status for a migration version given its ledger entries.
*
* Semantics (Bug 3 — keep "complete wins" safety):
* - If the latest entry is `retry`, the version is pending. This is the
* explicit escape hatch written by a forced retry, and it overrides an
* earlier `complete` entry without hand-editing the ledger.
* - Otherwise, if any entry is `complete`, the version is complete.
* - Otherwise, MAX_CONSECUTIVE_PARTIALS trailing partials → wedged.
* - Otherwise, any `partial` entry → partial; else pending.
*
* `complete` never regresses accidentally. A later `partial` append cannot
* undo a completed migration; only a trailing, explicit `retry` marker can.
*/
export function statusForVersion(
version: string,
byVersion: Map<string, CompletedMigrationEntry[]>,
): MigrationLedgerStatus {
const entries = byVersion.get(version) ?? [];
if (entries.length === 0) return 'pending';
const latest = entries[entries.length - 1];
if (latest.status === 'retry') return 'pending';
if (entries.some(e => e.status === 'complete')) return 'complete';
if (trailingPartialCount(entries) >= MAX_CONSECUTIVE_PARTIALS) return 'wedged';
if (entries.some(e => e.status === 'partial')) return 'partial';
return 'pending';
}
/** Consecutive `partial` entries at the end of one version's ledger history: the wedge counter. A `retry` or `complete` entry resets it. */
/**
* #6796: the latest ledger row for the version is `complete` but recorded
* `apply_migrations_pending`: the mechanical checkpoint landed and host work
* (publication, client activation) is still outstanding.
*/
export function hostWorkPendingForVersion(version: string, byVersion: Map<string, CompletedMigrationEntry[]>): boolean {
const latest = byVersion.get(version)?.at(-1);
return latest?.status === 'complete' && latest.apply_migrations_pending === true;
}
/** Read-only next step for host work a migration left pending: its per-source inventory. */
export function hostWorkInspectArgv(version: string): string[] {
return ['gbrain', 'apply-migrations', '--migration', version, '--dry-run', '--json'];
}
/**
* Upgrade migrations whose orchestrator declares `reconcile: true` (a per-source recheck that records host work, today the
* shared-skills content migration). Registry-free mirror of that flag, pinned against the registry by
* test/migration-ledger.test.ts like MIGRATION_OPT_OUT_KEYS.
*/
export const RECONCILE_MIGRATION_VERSIONS: readonly string[] = ['0.53.0'];
/**
* A reconcile migration wedged with its latest row recording `apply_migrations_pending`: its per-source recheck stopped on
* a conflict in one or more sources that a person has to settle. Other migrations (v0.11.0, v0.14.0) set the same flag on
* ordinary partial runs, so their wedges keep the forward-progress rule.
*/
export function hostWorkOwedForVersion(version: string, byVersion: Map<string, CompletedMigrationEntry[]>): boolean {
return RECONCILE_MIGRATION_VERSIONS.includes(version) && statusForVersion(version, byVersion) === 'wedged' && byVersion.get(version)?.at(-1)?.apply_migrations_pending === true;
}
/** One source in conflict, read from the migration's read-only preview: the stage's code and reason. */
export interface OwedConflict { source_id: string; code: string; reason: string }
/** The step a person takes for one source's conflict. */
export function owedConflictNextStep(conflict: OwedConflict): string {
if (conflict.code === 'shared_skills_unmanifested') {
return 'review the skills in its skills/ folder with the user, then either declare the ones to share in a skillpack.json at the source\'s root, or keep the source out of '
+ 'shared-skills adoption with ' + ['gbrain', 'sources', 'shared-skills', conflict.source_id, 'off'].join(' ');
}
return 'settle what its reason names with the user';
}
/**
* The one description of a wedged migration with host work owed, shared by every surface that reports it. `conflicts` is
* the live list from the read-only preview, or null where the surface cannot read it (no database, a remote caller).
*/
export function hostWorkOwedMessage(versions: readonly string[], conflicts: readonly OwedConflict[] | null = null): string {
const first = versions[0]!;
const named = versions.map(v => `v${v}`).join(', ');
if (conflicts === null) {
return `Migration ${named} stopped ${MAX_CONSECUTIVE_PARTIALS}+ runs in a row on a conflict in one or more sources that a person has to settle. `
+ `See each source's conflict and its next step (read-only): ${hostWorkInspectArgv(first).join(' ')}.`;
}
if (conflicts.length === 0) {
return `Migration ${named} stopped ${MAX_CONSECUTIVE_PARTIALS}+ runs in a row on a source conflict, and its preview finds no source in conflict now, so nothing waits on a person. `
+ `See each source's state (read-only): ${hostWorkInspectArgv(first).join(' ')}.`;
}
return `Migration ${named} is stopped on a conflict in ${conflicts.length} source(s) that a person has to settle: `
+ conflicts.map(c => `${c.source_id} (${c.code}): ${c.reason} Next: ${owedConflictNextStep(c)}.`).join(' ')
+ ` Preview every source (read-only): ${hostWorkInspectArgv(first).join(' ')}.`;
}
/** The fix for a wedged migration with host work owed: the read-only per-source inspect, then the user's decision for each source in conflict now. */
export function hostWorkOwedFix(versions: readonly string[], conflicts: readonly OwedConflict[] | null = null): Action {
const first = versions[0]!;
const inspect: Action = { argv: hostWorkInspectArgv(first), consent: [], actor: 'agent', requires_exclusive: false,
verify: { argv: ['gbrain', 'apply-migrations', '--list', '--json'] },
why: `Lists each source's state and any conflict for v${first}, with the step that settles it; changes nothing.` };
if (conflicts === null || conflicts.length === 0) return inspect;
const unmanifested = conflicts.find(c => c.code === 'shared_skills_unmanifested');
return { ...inspect, then: { ask_user: true, consent: [], actor: 'agent', requires_exclusive: false,
...(unmanifested ? { argv: ['gbrain', 'sources', 'shared-skills', unmanifested.source_id, 'off'] } : {}),
verify: { argv: hostWorkInspectArgv(first) },
why: 'Each conflict needs the user\'s decision; nothing changes until they make it.',
user_message: `gbrain migration v${first} is stopped on a conflict in ${conflicts.map(c => c.source_id).join(', ')}. `
+ conflicts.map(c => `For ${c.source_id}: ${owedConflictNextStep(c)}.`).join(' ') + ' Which do you want for each?' } };
}
export function trailingPartialCount(entries: readonly CompletedMigrationEntry[]): number {
let consecutive = 0;
for (let i = entries.length - 1; i >= 0 && entries[i].status === 'partial'; i--) consecutive++;
return consecutive;
}
/**
* Doctor's forward-progress rule (`minions_migration`): a partial or wedged version is history, not outstanding work, once a
* newer migration really ran (a `complete` entry that is not an init fresh-install stamp). Returns that newer version, or null.
*/
export function forwardProgressPast(version: string, entries: readonly CompletedMigrationEntry[]): string | null {
return entries.find(e => e.status === 'complete' && !isFreshInstallStamp(e) && compareVersions(e.version, version) > 0)?.version ?? null;
}
/** A ledger entry `gbrain init` wrote for a `fresh_install_noop` migration (src/commands/migrations/fresh-install.ts). */
export function isFreshInstallStamp(entry: CompletedMigrationEntry): boolean {
return entry.fresh_install === true;
}
/**
* The gbrain version that created this brain, read from init's fresh-install
* stamps; null for a brain created before stamping existed. A pending
* migration at or below it is `pending_fresh_install`: setup work the new
* brain has not run yet, never an interrupted upgrade.
*/
export function freshInstallVersion(entries: CompletedMigrationEntry[]): string | null {
let latest: string | null = null;
for (const entry of entries) {
if (!isFreshInstallStamp(entry) || typeof entry.installed_version !== 'string') continue;
if (latest === null || compareVersions(entry.installed_version, latest) > 0) latest = entry.installed_version;
}
return latest;
}
export function isPendingFreshInstall(version: string, freshVersion: string | null): boolean {
return freshVersion !== null && compareVersions(version, freshVersion) <= 0;
}
export function indexCompletedEntries(
entries: CompletedMigrationEntry[],
): Map<string, CompletedMigrationEntry[]> {
const byVersion = new Map<string, CompletedMigrationEntry[]>();
for (const e of entries) {
const list = byVersion.get(e.version) ?? [];
list.push(e);
byVersion.set(e.version, list);
}
return byVersion;
}
export interface MigrationLedgerSummary {
/** Registered migrations ≤ installed version with no ledger completion (upgrade work). */
pending: string[];
/**
* Not yet run on a brain `gbrain init` created at or after their version:
* expected setup work (`gbrain apply-migrations --yes`), not a broken upgrade.
*/
pending_fresh_install: string[];
/** Started but unfinished (some phases recorded partial). */
partial: string[];
/** Hit the consecutive-partial cap — needs an explicit forced retry. */
wedged: string[];
/** #6466: declined by the brain's config (a migration's `optOut` key is off); never pending, partial or wedged. */
declined: string[];
/**
* Migrations newer than the installed binary (count only). Future-versioned
* migrations are excluded from ALL status buckets regardless of ledger
* state (matches the apply-migrations list view); after a binary downgrade
* a wedged future migration appears only in this count.
*/
skipped_future: number;
}
/**
* Summarize the host migration ledger for the given installed version.
* Filesystem read (the completed-migrations JSONL) — engine-agnostic, which
* is why get_health composes this at the op layer rather than growing
* BrainEngine.getHealth() in both engines. Version strings only; never
* migration internals.
*/
export function migrationLedgerSummary(installedVersion: string, declined: ReadonlySet<string> = new Set()): MigrationLedgerSummary {
const entries = loadCompletedMigrations();
const byVersion = indexCompletedEntries(entries);
const freshVersion = freshInstallVersion(entries);
const summary: MigrationLedgerSummary = { pending: [], pending_fresh_install: [], partial: [], wedged: [], declined: [], skipped_future: 0 };
for (const version of MIGRATION_VERSIONS) {
if (compareVersions(version, installedVersion) > 0) {
summary.skipped_future += 1;
continue;
}
if (declined.has(version)) { summary.declined.push(version); continue; }
const status = statusForVersion(version, byVersion);
if (status === 'pending') (isPendingFreshInstall(version, freshVersion) ? summary.pending_fresh_install : summary.pending).push(version);
else if (status === 'partial') summary.partial.push(version);
else if (status === 'wedged') summary.wedged.push(version);
}
return summary;
}