Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
19.6 KB
Raw Blame
/**
 * `gbrain init --prefer-postgres` — the Postgres-first install ladder for
 * agent-harness installs (db-availability loop, 5a). The zero-config
 * `gbrain init` default stays PGLite; THIS flag is how the Codex/Claude Code
 * plugin lane prefers Postgres "if at all possible".
 *
 * Ladder (first usable rung wins; every reachable-but-unusable rung prints a
 * one-line note and falls through — only the final PGLite rung is terminal):
 *   1. env URL          (GBRAIN_DATABASE_URL / #427-guarded DATABASE_URL)
 *   2. Supabase token   (SUPABASE_ACCESS_TOKEN [+ SUPABASE_PROJECT_REF]
 *                        + SUPABASE_DB_PASSWORD — Management API DISCOVERY
 *                        only; the candidate URL is connect-probed before
 *                        anything persists)
 *   3. local Postgres   (opportunistic: only when PG* env vars are set or
 *                        --local-postgres — a blind localhost probe on
 *                        peer-auth dev installs just burns a timeout.
 *                        Detection-only: CREATE DATABASE needs
 *                        --allow-create-db)
 *   4. docker           (--allow-docker only; gbrain's own pgvector
 *                        container — idempotent reuse recovers the REAL
 *                        credentials via docker inspect)
 *   5. PGLite           (zero-config floor, with the upgrade-later note)
 *
 * Consent bars: headless mutation of a server gbrain doesn't own is never
 * implicit (rung 3's CREATE DATABASE and rung 4's container are both behind
 * explicit flags). Token hygiene: SUPABASE_ACCESS_TOKEN is never persisted,
 * logged, or echoed.
 */

import { randomBytes } from 'node:crypto';

import { effectiveEnvDatabaseUrl, isThinClient, loadConfigFileOnly } from '../core/config.ts';
import { InitPostgresFailure, initPGLite, initPostgresCore } from './init.ts';
import { defaultDeps as dbRepairDeps } from './db-repair.ts';
import { discoverPoolerUrl, listProjects } from '../core/supabase-admin.ts';
import {
  GBRAIN_PG_HOST_PORT,
  containerState,
  dockerAvailable,
  inspectCredentials,
  runNewContainer,
  startContainer,
} from '../core/docker-postgres.ts';
import { redactPgUrl, redactUrlsInText } from '../core/url-redact.ts';
import { classifyPgAccessError } from '../core/pg-access-classify.ts';

export interface PreferPostgresOpts {
  jsonOutput: boolean;
  apiKey: string | null;
  customPath: string | null;
  aiOpts: Parameters<typeof initPostgresCore>[0]['aiOpts'];
  schemaPack: string;
  skipEmbedCheck: boolean;
  allowDocker: boolean;
  allowCreateDb: boolean;
  localPostgres: boolean;
  content?: Parameters<typeof initPostgresCore>[0]['content'];
}

type LadderRung = 'env_url' | 'supabase_token' | 'local_postgres' | 'docker' | 'pglite';

function note(line: string): void {
  console.error(`[prefer-postgres] ${line}`);
}

/** Rung-note copy for a caught error: message redacted (a driver error can
 *  embed the full DSN, credentials included) and truncated. */
function noteErr(e: unknown): string {
  return redactUrlsInText(e instanceof Error ? e.message : String(e)).slice(0, 200);
}

/**
 * In --json mode the ladder's final envelope must be the ONLY stdout content
 * — but the inner init cores (called with jsonOutput:false) print their
 * human progress to stdout. Reroute stdout to stderr for the duration so
 * `gbrain init --prefer-postgres --json | jq` always parses.
 *
 * BOTH seams are patched: Bun's console.log writes to fd 1 directly and
 * bypasses a process.stdout.write override (verified by repro), so
 * console.log is rerouted to console.error and the write patch catches the
 * remaining bare process.stdout.write callers.
 */
async function withStdoutToStderr<T>(active: boolean, fn: () => Promise<T>): Promise<T> {
  if (!active) return fn();
  const realWrite = process.stdout.write.bind(process.stdout);
  const realLog = console.log;
  console.log = (...args: unknown[]) => console.error(...args);
  (process.stdout as { write: typeof process.stdout.write }).write = ((
    chunk: Parameters<typeof process.stdout.write>[0],
    ...rest: unknown[]
  ) => (process.stderr.write as (...a: unknown[]) => boolean)(chunk, ...rest)) as typeof process.stdout.write;
  try {
    return await fn();
  } finally {
    (process.stdout as { write: typeof process.stdout.write }).write = realWrite;
    console.log = realLog;
  }
}

/** Single bounded connect probe (shared with db-repair — one prober, one contract). */
async function probeUrl(url: string): Promise<string | null> {
  const diag = await dbRepairDeps.probeAccess({ engine: 'postgres', database_url: url });
  return diag === null ? null : `${diag.reason}: ${diag.remediation}`;
}

/**
 * What already lives in a reachable candidate database?
 *   'gbrain'  — an existing gbrain brain (pages table present): safe to adopt.
 *   'empty'   — no user tables in public: safe to initialize.
 *   'foreign' — someone else's tables: NEVER mutate implicitly.
 *   'unknown' — the check itself failed: treat as foreign (fail-closed).
 */
async function classifyDbContent(url: string): Promise<'gbrain' | 'empty' | 'foreign' | 'unknown'> {
  try {
    return await dbRepairDeps.withEngine({ engine: 'postgres', database_url: url }, async (engine) => {
      const pages = await engine.executeRaw<{ n: string | number }>(
        "SELECT count(*)::int AS n FROM pg_catalog.pg_tables WHERE schemaname = 'public' AND tablename = 'pages'",
      );
      if (Number(pages[0]?.n) > 0) return 'gbrain' as const;
      const tables = await engine.executeRaw<{ n: string | number }>(
        "SELECT count(*)::int AS n FROM pg_catalog.pg_tables WHERE schemaname = 'public'",
      );
      return Number(tables[0]?.n) === 0 ? ('empty' as const) : ('foreign' as const);
    });
  } catch {
    return 'unknown';
  }
}

async function initPostgresRung(
  o: PreferPostgresOpts,
  databaseUrl: string,
  rung: LadderRung,
): Promise<LadderRung | null> {
  try {
    await withStdoutToStderr(o.jsonOutput, () => initPostgresCore({
      databaseUrl,
      // Inner JSON stays off in --json mode: the ladder emits ONE final
      // envelope (two JSON objects on stdout would break every parser),
      // and withStdoutToStderr keeps the core's human lines off stdout too.
      jsonOutput: false,
      apiKey: o.apiKey ?? undefined,
      aiOpts: o.aiOpts,
      schemaPack: o.schemaPack,
      skipEmbedCheck: o.skipEmbedCheck,
      content: o.content,
    } as Parameters<typeof initPostgresCore>[0]));
    return rung;
  } catch (e) {
    if (e instanceof InitPostgresFailure) {
      note(`${rung}: init failed (${e.reason}) — falling through`);
      return null;
    }
    const d = classifyPgAccessError(e, { url: databaseUrl });
    note(`${rung}: ${d.reason} — ${d.remediation} Falling through.`);
    return null;
  }
}

export async function runPreferPostgresLadder(o: PreferPostgresOpts): Promise<void> {
  // A brain is already configured → REFUSE. The ladder's rung choice is
  // environment-dependent (env URL today, docker tomorrow), so a re-run
  // would repoint the brain non-deterministically — worst case, a configured
  // Postgres brain whose server is temporarily down falls through every rung
  // and the PGLite floor overwrites config.json, orphaning the whole brain
  // because of an OUTAGE. Outages are db-repair's lane, not init's.
  const existing = loadConfigFileOnly();
  if (existing && (existing.engine || existing.database_url || existing.database_path || isThinClient(existing))) {
    console.error(
      '[prefer-postgres] a brain is already configured — refusing to re-run the ladder over it.\n' +
      '  Inspect:            gbrain engine status --probe\n' +
      '  Access broken?      gbrain db-repair\n' +
      '  Move PGLite → PG:   gbrain migrate --to postgres --url-env GBRAIN_TARGET_URL --plan  (the postgres-adopt skill walks it)\n' +
      '  Really start over:  gbrain init --url <conn>  (explicit target, no ladder)',
    );
    process.exit(1);
  }

  // Rung-entry criterion — the preference is informed, not silent.
  note('Postgres wins on concurrency, multi-machine access, and 1000+ pages; PGLite keeps the per-turn bootstrap hook lane. Trying Postgres first.');

  let rung: LadderRung | null = null;
  let urlSource: string | null = null;

  // Rung 1 — env URL. GBRAIN_DATABASE_URL is gbrain-specific and adopted as
  // stated intent. A bare DATABASE_URL is NOT (deploy platforms export it
  // pointing at the APP's database) — initSchema would mutate a server
  // gbrain doesn't own, so it is adopted only when the target is already a
  // gbrain brain or holds no tables at all (fail-closed on 'foreign').
  const envUrl = effectiveEnvDatabaseUrl();
  if (envUrl) {
    const bare = !process.env.GBRAIN_DATABASE_URL;
    let adoptable = true;
    if (bare) {
      const content = await classifyDbContent(envUrl);
      if (content === 'foreign' || content === 'unknown') {
        adoptable = false;
        note(
          `rung 1 (env URL): DATABASE_URL points at a database with existing non-gbrain tables (${content}) — ` +
          'refusing to adopt it implicitly. Export GBRAIN_DATABASE_URL to use it deliberately. Next.',
        );
      }
    }
    if (adoptable) {
      note(`rung 1 (env URL): trying ${redactPgUrl(envUrl)}`);
      rung = await initPostgresRung(o, envUrl, 'env_url');
      if (rung) urlSource = 'env';
    }
  } else {
    note('rung 1 (env URL): no GBRAIN_DATABASE_URL/DATABASE_URL — next');
  }

  // Rung 2 — Supabase Management API discovery.
  if (!rung && process.env.SUPABASE_ACCESS_TOKEN) {
    const token = process.env.SUPABASE_ACCESS_TOKEN;
    try {
      let ref = process.env.SUPABASE_PROJECT_REF ?? null;
      if (!ref) {
        const projects = await listProjects(token);
        if (projects.length === 1) {
          ref = projects[0].id;
        } else if (projects.length === 0) {
          note('rung 2 (supabase): the account has no projects — create one in the dashboard, then re-run. Next.');
        } else {
          note(`rung 2 (supabase): ${projects.length} projects on the account — set SUPABASE_PROJECT_REF to pick one (guessing a brain's home is never OK). Next.`);
        }
      }
      if (ref) {
        const password = process.env.SUPABASE_DB_PASSWORD;
        if (!password) {
          note('rung 2 (supabase): the Management API cannot return the DB password — set SUPABASE_DB_PASSWORD (dashboard > Project Settings > Database). Next.');
        } else {
          let candidate = await discoverPoolerUrl(token, ref);
          candidate = candidate.replace('[YOUR-PASSWORD]', encodeURIComponent(password));
          const probeFail = await probeUrl(candidate);
          if (probeFail) {
            note(`rung 2 (supabase): discovered URL failed its probe (${probeFail}) — not persisting an unverified URL. Next.`);
          } else {
            note(`rung 2 (supabase): discovered + probed ${redactPgUrl(candidate)}`);
            rung = await initPostgresRung(o, candidate, 'supabase_token');
            if (rung) urlSource = 'supabase_discovery';
          }
        }
      }
    } catch (e) {
      note(`rung 2 (supabase): ${noteErr(e)} — next`);
    }
  } else if (!rung) {
    note('rung 2 (supabase): no SUPABASE_ACCESS_TOKEN — next');
  }

  // Rung 3 — local Postgres (opportunistic + detection-only by default).
  const pgEnvPresent = Boolean(process.env.PGHOST || process.env.PGPORT || process.env.PGUSER || process.env.PGPASSWORD);
  if (!rung && (pgEnvPresent || o.localPostgres)) {
    const host = process.env.PGHOST || 'localhost';
    const port = process.env.PGPORT || '5432';
    const user = process.env.PGUSER || 'postgres';
    const pass = process.env.PGPASSWORD ? `:${encodeURIComponent(process.env.PGPASSWORD)}` : '';
    const base = `postgresql://${user}${pass}@${host}:${port}`; /* allow-pg-url-literal */ // constructed target, only ever printed via redactPgUrl
    try {
      const maint = `${base}/postgres`;
      const probeFail = await probeUrl(maint);
      if (probeFail) {
        note(`rung 3 (local postgres): ${host}:${port} not usable (${probeFail}) — next`);
      } else {
        const checks = await dbRepairDeps.withEngine({ engine: 'postgres', database_url: maint }, async (engine) => {
          const vector = await engine.executeRaw<{ one: number }>(
            "SELECT 1 AS one FROM pg_available_extensions WHERE name = 'vector'",
          );
          const db = await engine.executeRaw<{ one: number }>(
            "SELECT 1 AS one FROM pg_database WHERE datname = 'gbrain'",
          );
          return { hasVector: vector.length > 0, hasDb: db.length > 0 };
        });
        if (!checks.hasVector) {
          note('rung 3 (local postgres): reachable but pgvector is not installed — install it (or use another rung). Next.');
        } else if (!checks.hasDb && !o.allowCreateDb) {
          note('rung 3 (local postgres): reachable with pgvector, but no `gbrain` database. CREATE DATABASE on a server not owned by this brain needs explicit consent: re-run with --allow-create-db. Next.');
        } else {
          if (!checks.hasDb) {
            await dbRepairDeps.withEngine({ engine: 'postgres', database_url: maint }, async (engine) => {
              await engine.executeRaw('CREATE DATABASE gbrain');
            });
            note('rung 3 (local postgres): created database `gbrain` (--allow-create-db)');
          }
          rung = await initPostgresRung(o, `${base}/gbrain`, 'local_postgres');
          if (rung) urlSource = 'local_probe';
        }
      }
    } catch (e) {
      note(`rung 3 (local postgres): ${noteErr(e)} — next`);
    }
  } else if (!rung) {
    note('rung 3 (local postgres): no PG* env vars and no --local-postgres — skipped (a blind localhost probe just burns a timeout)');
  }

  // Rung 4 — gbrain's own docker container (explicit opt-in only).
  if (!rung && o.allowDocker) {
    if (!dockerAvailable()) {
      note('rung 4 (docker): docker is not available — next');
    } else {
      try {
        const state = containerState();
        let url: string | null = null;
        if (state === 'absent') {
          const password = randomBytes(16).toString('hex');
          const run = runNewContainer(password);
          if (!run.ok) {
            note(`rung 4 (docker): container create failed (${run.stderr.slice(0, 120)}) — next`);
          } else {
            url = `postgresql://postgres:${password}@localhost:${GBRAIN_PG_HOST_PORT}/postgres`; /* allow-pg-url-literal */ // constructed target, only ever printed via redactPgUrl
          }
        } else {
          // Idempotent reuse: a freshly generated password can never match a
          // surviving container, and `docker start` reuses the ORIGINAL port
          // mapping — recover both from docker inspect.
          const creds = inspectCredentials();
          if (!creds) {
            note('rung 4 (docker): the gbrain-postgres container exists but its credentials are unrecoverable via docker inspect — gbrain never destroys a container it cannot prove it owns. Remove it yourself (docker rm -f gbrain-postgres) and re-run, or use another rung. Next.');
          } else {
            if (state === 'stopped' && !startContainer()) {
              note('rung 4 (docker): docker start failed — next');
            } else {
              // encodeURIComponent: gbrain-generated passwords are hex, but a
              // user-created container's password can carry URL metacharacters.
              url = `postgresql://postgres:${encodeURIComponent(creds.password)}@localhost:${creds.hostPort}/postgres`; /* allow-pg-url-literal */ // constructed target, only ever printed via redactPgUrl
            }
          }
        }
        if (url) {
          // Readiness poll: postgres in a fresh container takes a few seconds.
          let ready = false;
          let authMismatch = false;
          for (let i = 0; i < 20; i++) {
            const diag = await dbRepairDeps.probeAccess({ engine: 'postgres', database_url: url });
            if (diag === null) { ready = true; break; }
            // A FRESH container rejecting the password we JUST generated means
            // a surviving gbrain-pgdata volume: the postgres image ignores
            // POSTGRES_PASSWORD when a cluster already exists in the volume.
            // Reachable-with-wrong-auth is terminal — polling won't fix it,
            // and "never became reachable" would misdiagnose it.
            if (state === 'absent' && diag.reason === 'auth_failed') { authMismatch = true; break; }
            await new Promise((r) => setTimeout(r, 1000));
          }
          if (authMismatch) {
            note(
              'rung 4 (docker): a gbrain-pgdata volume survives from an earlier container, so the fresh password was ' +
              'ignored (postgres keeps the volume\'s original credentials) — the old brain is still in that volume. ' +
              'Adopt it by exporting GBRAIN_DATABASE_URL with the ORIGINAL password, or start clean with ' +
              'docker rm -f gbrain-postgres && docker volume rm gbrain-pgdata (destroys that brain). Next.',
            );
          } else if (!ready) {
            note('rung 4 (docker): the container never became reachable — next');
          } else {
            // Content guard on BOTH paths (reuse AND fresh-create — a fresh
            // container can attach a SURVIVING gbrain-pgdata volume). With
            // the existing-config refusal above, reaching this rung means
            // THIS home has no brain, so any content here is either another
            // home/user's brain (the container is machine-global) or foreign
            // tables. Fail-closed on 'unknown' — same predicate as rung 1.
            const content = await classifyDbContent(url);
            if (content === 'gbrain') {
              note(
                'rung 4 (docker): the gbrain-postgres container already holds a brain not recorded in this ' +
                'home\'s config — refusing to share it implicitly. To adopt it deliberately, export GBRAIN_DATABASE_URL ' +
                'with its connection string and re-run. Next.',
              );
            } else if (content !== 'empty') {
              note(
                `rung 4 (docker): the container's database holds non-gbrain tables (${content}) — refusing to ` +
                'initialize over them. Next.',
              );
            } else {
              note('rung 4 (docker): container ready. gbrain starts/reuses this container but never stops or removes it.');
              rung = await initPostgresRung(o, url, 'docker');
              if (rung) urlSource = 'docker';
            }
          }
        }
      } catch (e) {
        note(`rung 4 (docker): ${noteErr(e)} — next`);
      }
    }
  } else if (!rung && !o.allowDocker) {
    note('rung 4 (docker): not opted in (--allow-docker) — next');
  }

  // Rung 5 — PGLite, the zero-config floor. Terminal; no silent anything.
  if (!rung) {
    note('falling back to PGLite. Upgrade later: gbrain migrate --to postgres --plan (docs/guides/move-to-postgres.md; the postgres-adopt skill walks it).');
    await withStdoutToStderr(o.jsonOutput, () => initPGLite({
      jsonOutput: false,
      apiKey: o.apiKey ?? undefined,
      customPath: o.customPath ?? undefined,
      aiOpts: o.aiOpts,
      schemaPack: o.schemaPack,
      skipEmbedCheck: o.skipEmbedCheck,
      content: o.content,
    } as Parameters<typeof initPGLite>[0]));
    rung = 'pglite';
    urlSource = null;
  }

  if (o.jsonOutput) {
    // D2: the ladder's envelope replaces the inner init's document (written once by runInit).
    const { setInitJsonResult } = await import('./init-json.ts');
    setInitJsonResult({
      status: 'ok',
      engine: rung === 'pglite' ? 'pglite' : 'postgres',
      ladder_rung: rung,
      url_source: urlSource,
    }, { replace: true });
  }
}