Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.4 KB
Raw Blame
/**
 * #6089: the schema-version half of the `gbrain apply-migrations` exit
 * contract. The runner never exits 0 while it leaves the schema behind.
 *
 * - One helper connects the configured brain and reads `config.version`; the
 *   Postgres pre-flight, `--force-schema` and the check after orchestrators
 *   all go through it.
 * - After the orchestrators ran, the version is read again. On Postgres only
 *   when the pre-flight connected (an unreachable database stays non-fatal,
 *   with the GBRAIN_DB_ACCESS marker). On PGLite this check replaces the
 *   pre-flight, which stays skipped (#1100 lock race): it runs in-process once
 *   the orchestrators released the datastore, never in a child process, and an
 *   authorized run applies the schema migrations here.
 * - A schema still behind, or a version that cannot be read back, is
 *   `migrations_pending` (exit 1) with a reason and the schema migrations
 *   still pending. After an authorized run the fix is a report (doctor, then
 *   tell the user), never another `--yes` that would repeat the failure.
 */
import { existsSync } from 'node:fs';
import type { GBrainConfig } from '../core/config.ts';
import type { BrainEngine } from '../core/engine.ts';
import type { Action } from '../core/agent-output.ts';
import { opError, type OperationError } from '../core/ops/contract.ts';
import { PgliteBusyError } from '../core/pglite-lock.ts';
import { connectMigrationEngine } from './migrations/run-engine.ts';
import { DB_ACCESS_MARKER_PREFIX, shouldEmitDbAccessMarker } from '../core/pg-access-classify.ts';
import { readMigrationTimeout, type MigrationTimeoutRecord } from '../core/migration-timeout.ts';
import { migrationTimeoutAdvice } from '../core/migration-timeout-advice.ts';

export type SchemaPendingReason = 'not_applied' | 'still_behind' | 'schema_unreadable';

export interface SchemaPending {
  reason: SchemaPendingReason;
  /** The version read back, or null when it could not be read. */
  current: number | null;
  latest: number;
  /** Schema migration versions above the last version this run read. */
  pending: number[];
  /** Redacted read error (`schema_unreadable` only). */
  read_error?: string;
  /** #7108: the pending migration that last ran out of its statement budget (`still_behind` only). */
  timeout?: MigrationTimeoutRecord;
}

/** Connect the configured brain and read its schema version. The caller disconnects; a failed read disconnects here. */
export async function connectAtSchemaVersion(cfg: GBrainConfig): Promise<{ engine: BrainEngine; version: number }> {
  const { toEngineConfig } = await import('../core/config.ts');
  const { createEngine } = await import('../core/engine-factory.ts');
  const engine = await createEngine(toEngineConfig(cfg));
  try {
    await engine.connect(toEngineConfig(cfg));
    return { engine, version: parseInt(await engine.getConfig('version') || '1', 10) };
  } catch (err) {
    await engine.disconnect().catch(() => {});
    throw err;
  }
}

/** A connection error with URLs and connection details redacted: safe for stderr, issues and CI logs. */
export async function redactDbError(err: unknown): Promise<string> {
  const { redactUrlsInText } = await import('../core/url-redact.ts');
  const { redactConnectionInfo } = await import('../core/audit/redact-connection-info.ts');
  return redactConnectionInfo(redactUrlsInText(err instanceof Error ? err.message : String(err)));
}

async function pendingAbove(version: number | null): Promise<{ latest: number; pending: number[] }> {
  const { MIGRATIONS, LATEST_VERSION } = await import('../core/migrate.ts');
  const pending = version === null ? [] : MIGRATIONS.map(m => m.version).filter(v => v > version).sort((a, b) => a - b);
  return { latest: LATEST_VERSION, pending };
}

/**
 * #7776: `client_behind` when the brain's schema is newer than this binary, so an older binary runs no orchestrator (or
 * its schema replay) there. Postgres reuses the pre-flight's version; PGLite is read here, before any orchestrator opens
 * the datastore. An unreadable PGLite datastore is left to the orchestrators, as before.
 */
export async function schemaAheadRefusal(cfg: GBrainConfig, preflightVersion: number | null): Promise<OperationError | null> {
  let version = preflightVersion;
  if (version === null && cfg.engine === 'pglite' && cfg.database_path && existsSync(cfg.database_path)) {
    try {
      const { engine, close } = await connectMigrationEngine(cfg);
      try { version = parseInt(await engine.getConfig('version') || '0', 10); } finally { await close(); }
    } catch { return null; }
  }
  const { clientBehindError } = await import('../core/schema-client-behind.ts');
  const { latest } = await pendingAbove(null);
  return version !== null && version > latest ? clientBehindError(version) : null;
}

/**
 * #7776: the connection for `--force-schema` / `--force-all`, whose runMigrations pass (under the lease) runs drift
 * repairs that would rewrite a newer schema's objects. `behind` is client_behind, with the engine already closed, when
 * the schema is newer than this binary, so the forced run refuses as the pre-flight does.
 */
export async function connectForForcedSchema(cfg: GBrainConfig): Promise<{ engine: BrainEngine; version: number; behind: OperationError | null }> {
  const conn = await connectAtSchemaVersion(cfg);
  const behind = await schemaAheadRefusal(cfg, conn.version);
  if (behind) await conn.engine.disconnect();
  return { ...conn, behind };
}

/** The pre-flight's finding when it saw the schema behind and did not bring it to head. */
export async function schemaBehindAtPreflight(version: number, authorized: boolean, timeout?: MigrationTimeoutRecord): Promise<SchemaPending> {
  return { reason: authorized ? 'still_behind' : 'not_applied', current: version, ...(await pendingAbove(version)), ...(authorized && timeout ? { timeout } : {}) };
}

/**
 * Read the schema version after the orchestrators ran; null when it is at
 * head or there is nothing to check (no PGLite datastore yet, or Postgres was
 * unreachable at the pre-flight, or a PGLite datastore that was never
 * initialized). `apply` brings a PGLite schema to head on an authorized run.
 * A busy PGLite datastore is rethrown like an orchestrator's.
 */
export async function checkSchemaAfterOrchestrators(opts: {
  cfg: GBrainConfig;
  authorized: boolean;
  preflightVersion: number | null;
  apply: (engine: BrainEngine, from: number) => Promise<unknown>;
}): Promise<SchemaPending | null> {
  const { cfg, authorized } = opts;
  const pglite = cfg.engine === 'pglite';
  if (pglite ? !cfg.database_path || !existsSync(cfg.database_path) : opts.preflightVersion === null) return null;
  let lastRead = opts.preflightVersion;
  try {
    const { engine, close } = await connectMigrationEngine(cfg);
    let current: number;
    let timeout: MigrationTimeoutRecord | null = null;
    try {
      current = parseInt(await engine.getConfig('version') || '1', 10);
      const { latest } = await pendingAbove(current);
      if (pglite && authorized && current < latest) {
        console.error(`Schema v${current} is behind v${latest}; applying schema migrations in-process...`);
        try { await opts.apply(engine, current); } catch (err) { console.error(`Schema migration failed: ${await redactDbError(err)}`); }
        current = parseInt(await engine.getConfig('version') || '1', 10);
      }
      if (authorized && current < latest) timeout = await readMigrationTimeout(engine, current);
    } finally {
      await close();
    }
    lastRead = current;
    const { latest, pending } = await pendingAbove(current);
    if (current >= latest) return null;
    return { reason: authorized ? 'still_behind' : 'not_applied', current, latest, pending, ...(timeout ? { timeout } : {}) };
  } catch (err) {
    if (err instanceof PgliteBusyError) throw err;
    // A PGLite datastore without the config table was never initialized: `gbrain init` creates a brain, not this run.
    if (pglite && /relation "config" does not exist/i.test(err instanceof Error ? err.message : String(err))) {
      console.error('The PGLite datastore has no gbrain schema yet, so there is no schema version to check; `gbrain init` creates it.');
      return null;
    }
    return { reason: 'schema_unreadable', current: null, ...(await pendingAbove(lastRead)), read_error: await redactDbError(err) };
  }
}

/** Tell the user, then show doctor's view: the same run again would fail the same way. */
function reportFix(why: string): Action {
  return { consent: [], actor: 'agent', requires_exclusive: false, why, verify: { argv: ['gbrain', 'doctor', '--json'] } };
}

const REPORT_SUGGESTION = 'Run `gbrain doctor --json` and tell the user what it reports, with the schema error from stderr. '
  + 'If the gbrain install itself is broken, the deterministic clone install in README.md recovers it (issue #218).';

/** `migrations_pending` for a run that leaves the schema behind. `rerunWithYes` is the fix when the run was not authorized. */
export function schemaPendingError(p: SchemaPending, rerunWithYes: Action): OperationError {
  const ids = p.pending.length ? p.pending.map(v => `v${v}`).join(', ') : 'unknown';
  const where = `schema v${p.current}, latest v${p.latest}; pending: ${ids}`;
  if (p.reason === 'not_applied') {
    return opError('migrations_pending', `Schema migrations are behind (${where}); this run did not apply them.`,
      'Apply them with `gbrain apply-migrations --yes` (or `--force-schema`).',
      { reason: p.reason, fix: rerunWithYes });
  }
  if (p.reason === 'still_behind' && p.timeout) {
    const advice = migrationTimeoutAdvice(p.timeout, { argv: ['gbrain', 'doctor', '--only', 'schema_version', '--json'] });
    return opError('migrations_pending', `Schema migrations are still behind after an authorized run (${where}). ${advice.message}`,
      advice.fix.user_message ?? advice.fix.why,
      { reason: p.reason, why: 'A schema migration ran out of its statement budget, so the run stopped below it; what helps depends on the release that ran it and on whether a session was blocking it.',
        fix: advice.fix });
  }
  if (p.reason === 'still_behind') {
    return opError('migrations_pending', `Schema migrations are still behind after an authorized run (${where}); the schema migration did not apply, and running --yes again repeats that.`,
      REPORT_SUGGESTION,
      { reason: p.reason, why: 'apply-migrations --yes tried the schema migrations and they did not apply; stderr names the failing migration.',
        fix: reportFix('Tell the user the schema migrations did not apply and what doctor reports; another --yes run repeats the failure.') });
  }
  return opError('migrations_pending', `The schema version could not be read after the orchestrators ran (${p.read_error ?? 'unknown error'}); latest v${p.latest}, pending since the last version read: ${ids}.`,
    REPORT_SUGGESTION,
    { reason: p.reason, why: 'The run cannot confirm the schema reached head, so it does not report success.',
      fix: reportFix('Tell the user the schema version could not be confirmed and what doctor reports.') });
}

/** Postgres unreachable without --require-db: still non-fatal, but never silent. */
export function reportDatabaseUnreachable(probe: { reason: string; access?: string }): void {
  if (shouldEmitDbAccessMarker()) process.stderr.write(`${DB_ACCESS_MARKER_PREFIX} ${probe.access ?? 'unknown'}\n`);
  console.error(`Database unreachable (${probe.reason}): the schema version was not checked; orchestrators run their filesystem-only phases. `
    + 'Diagnose it with `gbrain db-repair`; pass --require-db to fail instead.');
}