Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.6 KB
Raw Blame
/**
 * #6649: `gbrain backup create` on PGLite checks, before it takes the writer
 * lock or opens the database, that this recovery format can hold the brain:
 * the data dir must be the managed `<root>/.gbrain/brain.pglite` with no
 * symlink on the way (a flat or symlinked home is `unmanaged_database_path`),
 * and its estimated archive size must fit the 8 GiB cap (`backup_too_large`).
 * Both refusals name the same recovery: the quiesced physical-copy runbook.
 * Doctor's `pglite_data_dir` uses the same size estimate to warn early.
 */
import { lstatSync, readdirSync, type Stats } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import type { Action } from '../agent-output.ts';
import { opError, type OperationError } from '../ops/contract.ts';
import { BACKUP_ARCHIVE_MAX_BYTES } from './archive.ts';
import { UNREADABLE_CODES } from './runtime-artefacts.ts';

export const PHYSICAL_COPY_RUNBOOK = 'docs/guides/in-agent-setup.md#large-or-non-standard-brains-quiesced-physical-copy';
/** Doctor warns once the data dir's estimated archive size passes this share of the cap. */
export const BACKUP_SIZE_WARN_RATIO = 0.75;

const TAR_BLOCK = 512;

/**
 * Bytes `dumpDataDir` would write for `dir`: every regular file's apparent
 * size rounded up to a 512-byte tar block plus its header block, a header per
 * directory, and the two closing blocks. Symlinks are not followed. An entry
 * that vanished or that the runtime cannot lstat (a Windows AF_UNIX socket
 * reads as EACCES) adds nothing: it is not a regular file, and the runtime
 * artefact sweep decides what happens to it.
 */
export function estimatedTarBytes(dir: string): number {
  let total = 2 * TAR_BLOCK;
  const walk = (path: string): void => {
    let stat: Stats;
    try { stat = lstatSync(path); }
    catch (error) {
      const code = (error as NodeJS.ErrnoException).code;
      if (path !== dir && code && (code === 'ENOENT' || UNREADABLE_CODES.has(code))) return;
      throw error;
    }
    if (stat.isDirectory()) {
      total += TAR_BLOCK;
      for (const name of readdirSync(path)) walk(join(path, name));
    } else if (stat.isFile()) {
      total += TAR_BLOCK + Math.ceil(stat.size / TAR_BLOCK) * TAR_BLOCK;
    }
  };
  walk(dir);
  return total;
}

export type PgliteBackupLayout = 'managed' | 'flat' | 'symlinked';

/** Where the configured data dir sits relative to the managed `<root>/.gbrain/brain.pglite`. */
export function pgliteBackupLayout(root: string, dbPath: string): PgliteBackupLayout {
  const managed = join(root, '.gbrain', 'brain.pglite');
  if (resolve(dbPath) !== managed) return 'flat';
  for (let path = managed; path !== root && dirname(path) !== path; path = dirname(path)) {
    try { if (lstatSync(path).isSymbolicLink()) return 'symlinked'; } catch { /* missing: reported by the caller */ }
  }
  return 'managed';
}

const RUNBOOK_STEPS = 'Take a quiesced physical copy instead: stop every gbrain writer on this brain (gbrain serve, jobs and autopilot, agent sessions), ' +
  'copy the whole data directory and config.json into a new, isolated GBRAIN_HOME, point that config\'s database_path at the copy, ' +
  `then verify the copy with gbrain doctor --json run with GBRAIN_HOME set to it before relying on it (runbook: ${PHYSICAL_COPY_RUNBOOK}).`;

/** The runbook needs the user (writers stop, a copy is made); the agent then runs doctor read-only. */
export function physicalCopyFix(): Action {
  return {
    ask_user: true, argv: ['gbrain', 'doctor', '--json'], consent: [], actor: 'agent', requires_exclusive: false, docs: PHYSICAL_COPY_RUNBOOK,
    why: 'Read-only, after the user agrees to the physical copy: doctor opens the brain only when no other gbrain process holds it, so a clean run shows the writers are stopped.',
    user_message: RUNBOOK_STEPS, verify: { argv: ['gbrain', 'doctor', '--json'] },
  };
}

export const POSTGRES_BACKUP_DOCS = 'docs/guides/memory-boundaries.md#full-backup';

const POSTGRES_DUMP_STEPS = 'This brain lives in Postgres, so back it up with a database dump of its database: ' +
  '`pg_dump --format custom --file <DUMP_FILE> --dbname <DATABASE_URL>`, kept private (it holds every page, fact, member and token); `pg_restore --list <DUMP_FILE>` reads it back. ' +
  'Restore it into a new, empty database with `pg_restore --no-owner --dbname <NEW_DATABASE_URL> <DUMP_FILE>`, then run ' +
  '`gbrain init --url <NEW_DATABASE_URL>` under a separate GBRAIN_HOME, which opens the restored brain. ' +
  '`gbrain export` is not a backup: an import of it puts every page in one source and keeps no members, tokens or facts.';

/** The full backup of a Postgres brain: the host admin dumps its database; pg_restore --list reads the dump back. */
export function postgresDumpFix(): Action {
  return {
    argv: ['pg_dump', '--format', 'custom', '--file', '<DUMP_FILE>', '--dbname', '<DATABASE_URL>'],
    consent: ['credentials'], actor: 'host_admin', requires_exclusive: false, docs: POSTGRES_BACKUP_DOCS,
    why: 'A database dump keeps every source, page, fact, member, token and folder rule of a Postgres brain; a Markdown export keeps pages only.',
    user_message: POSTGRES_DUMP_STEPS,
    inputs: [
      { name: 'DUMP_FILE', how: 'A new file outside the brain, in a directory only the user can read.' },
      { name: 'DATABASE_URL', how: 'The brain\'s Postgres connection, preferably service=<name> from a pg_service file so no password lands in the command line.' },
    ],
  };
}

/** `gbrain backup create` on a Postgres brain: the same storage_error code, with the database dump as the fix. */
export function postgresBackupRefusal(): OperationError {
  return opError('storage_error',
    `gbrain backup create snapshots PGLite brains only. ${POSTGRES_DUMP_STEPS}`,
    'Tell the user to back up the Postgres database with pg_dump and restore it with pg_restore.',
    { reason: 'pglite_required', why: 'Full local snapshots copy a PGLite data directory; a Postgres brain\'s data is in its database server.', fix: postgresDumpFix() });
}

/**
 * The refusal for a brain this recovery format cannot hold, or null when it can.
 * Reads only file metadata; `managedFileBytes` runs only for a managed layout.
 */
export function pgliteBackupPreflight(root: string, dbPath: string, managedFileBytes: () => number): OperationError | null {
  const layout = pgliteBackupLayout(root, dbPath);
  if (layout !== 'managed') {
    return opError('unmanaged_database_path',
      layout === 'flat'
        ? `This recovery format requires the data directory at ${join(root, '.gbrain', 'brain.pglite')}; this brain's database_path is ${dbPath}. Nothing was written.`
        : `This recovery format requires a data directory with no symlink on its path; ${join(root, '.gbrain', 'brain.pglite')} reaches the data through a symlink. Nothing was written.`,
      RUNBOOK_STEPS,
      { why: 'The archive records the managed root it can restore and refuses to follow a symlink out of it.', fix: physicalCopyFix(), docs: PHYSICAL_COPY_RUNBOOK, detail: `layout=${layout}` });
  }
  const bytes = estimatedTarBytes(dbPath) + managedFileBytes();
  if (bytes <= BACKUP_ARCHIVE_MAX_BYTES) return null;
  return opError('backup_too_large',
    `This brain needs about ${formatGiB(bytes)} in a backup archive (${bytes} bytes), over the archive's ${formatGiB(BACKUP_ARCHIVE_MAX_BYTES)} cap. Nothing was written.`,
    RUNBOOK_STEPS,
    { why: 'The archive format holds at most 8 GiB of payload; refusing before the dump avoids hours of work and a partial archive.', fix: physicalCopyFix(), docs: PHYSICAL_COPY_RUNBOOK, detail: `bytes=${bytes} limit=${BACKUP_ARCHIVE_MAX_BYTES}` });
}

export function formatGiB(bytes: number): string {
  return `${(bytes / 1024 ** 3).toFixed(2)} GiB`;
}