Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.1 KB
Raw Blame
/**
 * Shared types for the migration registry + orchestrators.
 *
 * Each migration is a module that exports a `Migration` object; the registry
 * at `./index.ts` lists them in version order. Compiled binaries ship the
 * registry directly — no filesystem walk of `skills/migrations/*.md` is
 * needed at runtime.
 */

import type { Effect } from '../../core/agent-output.ts';

export interface FeaturePitch {
  /** One-line headline printed post-upgrade. */
  headline: string;
  /** Optional multi-line description. */
  description?: string;
  /** Optional integration recipe name printed as a follow-up. */
  recipe?: string;
}

/**
 * Options passed to every orchestrator. The orchestrator must be idempotent:
 * re-running after a partial run must complete missed phases without
 * duplicating side-effects.
 */
export interface OrchestratorOpts {
  /** Non-interactive: skip prompts, use defaults with explicit print. */
  yes: boolean;
  /** Explicit minion_mode override (bypasses the Phase C prompt). */
  mode?: 'always' | 'pain_triggered' | 'off';
  /** Dry-run: print intended actions, take no side effects. */
  dryRun: boolean;
  /** Include $PWD in host-file walk (default: $HOME/.claude + $HOME/.openclaw). */
  hostDir?: string;
  /** Skip autopilot install (Phase F). */
  noAutopilotInstall: boolean;
  dbOnlyExport?: {
    root: string;
    sourceId: string;
    confirmQuiesced: boolean;
    backup?: 'operator_verified' | 'acknowledged_unprotected';
    /** The runner's own orchestration lease, which the quiescence check ignores. */
    ownLeaseToken?: string;
  };
  /** #5476: `--accept-reviewed-inventory <source>=<digest>`: the reviewed shared-skills inventory change to accept, per source. */
  acceptReviewedInventory?: Record<string, string>;
}

export interface OrchestratorPhaseResult {
  name: string;
  status: 'complete' | 'skipped' | 'failed';
  detail?: string;
  /** A stable code for why the phase ended this way (kept in the ledger), for readers that must not parse `detail`. */
  reason?: string;
  /** The exact command that resolves or inspects what this phase left open; printed by the runner and kept in the ledger. */
  argv?: string[];
}

export interface OrchestratorResult {
  version: string;
  status: 'complete' | 'partial' | 'failed';
  phases: OrchestratorPhaseResult[];
  files_rewritten?: number;
  autopilot_installed?: boolean;
  install_target?: string;
  pending_host_work?: number;
}

export interface Migration {
  /** Semver string, e.g. "0.11.0". */
  version: string;
  /** Agent-readable feature pitch printed by runPostUpgrade. */
  featurePitch: FeaturePitch;
  /** Run the migration. Must be idempotent. */
  orchestrator: (opts: OrchestratorOpts) => Promise<OrchestratorResult>;
  preview?: (opts: OrchestratorOpts) => Promise<unknown>;
  reconcile?: boolean;
  /**
   * #6466: brain-level DB config key whose explicit off value declines this
   * migration (`./opt-out.ts`): the runner skips it, reconcile included,
   * lists it `declined`, and refuses an explicit `--migration <v>`.
   */
  optOut?: { key: string };
  /**
   * Consent effects the orchestrator performs (agent operator contract A4);
   * apply-migrations asks for them before running it. `persistent_install`
   * is skipped (and not asked) under --no-autopilot-install or on PGLite.
   */
  effects?: readonly Effect[];
  /**
   * True only when the orchestrator changes nothing on a brain `gbrain init`
   * just created: schema already current, no data to backfill, no files,
   * preferences or services to write. Init records these as complete
   * (`fresh_install: true` ledger entries, `./fresh-install.ts`); every other
   * migration lists as `pending_fresh_install` until it runs. Each flagged
   * migration is proven by test/migrations-fresh-install-audit.serial.test.ts.
   */
  fresh_install_noop?: true;
  /**
   * The orchestrator opens the brain only through `connectMigrationEngine`
   * (`./run-engine.ts`) and calls `releaseRunEngine` before any `gbrain` child
   * that needs the brain, so consecutive flagged migrations of one run share
   * one PGLite open.
   */
  sharesRunEngine?: true;
}