Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.3 KB
Raw Blame
/**
 * 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;
}