Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.6 KB
Raw Blame
#!/usr/bin/env bun
/**
 * #5575 owner-custody dry run (CEO-25 / ENG-17): what the write gate would
 * flag or quarantine in an existing brain, by projected trust tier and reason
 * family. Strictly read-only:
 *   - Postgres: every read runs inside one REPEATABLE READ READ ONLY
 *     transaction, so the server refuses any write; no migrations run.
 *   - PGLite: the data directory is copied to a temp dir first and only the
 *     copy is opened (opening a PGLite directory can write WAL files), then
 *     the copy is deleted.
 * No receipts, holds, markers or config are written. The report has counts
 * and pattern names only, never content, slugs or ids.
 *
 * Usage:
 *   bun scripts/trust-dry-run-scan.ts [--json] [--source <id>] [--limit <rows per table>]
 *     [--tables pages,facts,takes,timeline_entries] [--batch <n>] [--database-url <url>]
 */
import { cpSync, mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { loadConfig, toEngineConfig } from '../src/core/config.ts';
import { createEngine } from '../src/core/engine-factory.ts';
import type { EngineConfig } from '../src/core/types.ts';
import { scanWriteGateExposure, WRITE_GATE_SCAN_TABLES, type WriteGateScanReport, type WriteGateScanTable } from '../src/core/write-gate-scan.ts';

function flag(args: string[], name: string): string | undefined {
  const i = args.indexOf(name);
  return i >= 0 ? args[i + 1] : undefined;
}

function pct(n: number, d: number): string {
  return d ? `${((100 * n) / d).toFixed(2)}%` : '-';
}

export function renderReport(r: WriteGateScanReport): string {
  const lines = [`write-gate dry run (detector v${r.detector_version}, external_mode=${r.config.externalMode}, agent_mode=${r.config.agentMode}${r.source_id ? `, source ${r.source_id}` : ''}); nothing was written.`];
  for (const [table, t] of Object.entries(r.tables)) {
    if (!t) continue;
    lines.push('', `${table}: ${t.scanned} rows${t.truncated ? ' (limit reached)' : ''}`);
    lines.push('  tier                 rows      detector hits   flag      quarantine  families');
    for (const [tier, s] of Object.entries(t.by_tier)) {
      if (!s.rows) continue;
      const fam = Object.entries(s.families).filter(([, n]) => n).map(([f, n]) => `${f}=${n}`).join(' ');
      lines.push(`  ${tier.padEnd(20)} ${String(s.rows).padEnd(9)} ${`${s.detector_hits} (${pct(s.detector_hits, s.rows)})`.padEnd(15)} ${`${s.verdicts.flag}`.padEnd(9)} ${`${s.verdicts.quarantine}`.padEnd(11)} ${fam}`);
    }
    const top = Object.entries(t.patterns).sort((a, b) => b[1] - a[1]).slice(0, 8).map(([p, n]) => `${p}=${n}`).join(' ');
    if (top) lines.push(`  top patterns: ${top}`);
  }
  const tt = r.totals;
  lines.push('', `total: ${tt.rows} rows; would flag ${tt.flagged} (${pct(tt.flagged, tt.rows)}), quarantine ${tt.quarantined} (${pct(tt.quarantined, tt.rows)}); detector hit rate if every row were agent-written ${pct(tt.detector_hits, tt.rows)}.`);
  return lines.join('\n');
}

async function main(): Promise<number> {
  const args = process.argv.slice(2);
  if (args.includes('--help') || args.includes('-h')) {
    console.log('Usage: bun scripts/trust-dry-run-scan.ts [--json] [--source <id>] [--limit <rows per table>] [--tables pages,facts,takes,timeline_entries] [--batch <n>] [--database-url <url>]');
    return 0;
  }
  const tables = (flag(args, '--tables')?.split(',').map(t => t.trim()).filter(Boolean) ?? [...WRITE_GATE_SCAN_TABLES]) as WriteGateScanTable[];
  const unknown = tables.filter(t => !WRITE_GATE_SCAN_TABLES.includes(t));
  if (unknown.length) { console.error(`Unknown table(s): ${unknown.join(', ')}. Choose from ${WRITE_GATE_SCAN_TABLES.join(', ')}.`); return 2; }
  const limit = flag(args, '--limit');
  const batch = flag(args, '--batch');
  const url = flag(args, '--database-url');
  const config = loadConfig();
  let engineConfig: EngineConfig;
  if (url) engineConfig = { engine: 'postgres', database_url: url };
  else if (config) engineConfig = toEngineConfig(config);
  else { console.error('No GBrain config found. Pass --database-url, or run on the brain host.'); return 1; }
  let copyDir: string | null = null;
  if ((engineConfig.engine ?? (engineConfig.database_url ? 'postgres' : 'pglite')) === 'pglite') {
    if (!engineConfig.database_path) { console.error('PGLite brain has no database_path in its config.'); return 1; }
    copyDir = mkdtempSync(join(tmpdir(), 'gbrain-trust-dry-run-'));
    const target = join(copyDir, 'brain.pglite');
    cpSync(engineConfig.database_path, target, { recursive: true });
    rmSync(join(target, 'postmaster.pid'), { force: true });
    engineConfig = { ...engineConfig, database_path: target };
    process.stderr.write(`[trust-dry-run] PGLite: scanning a copy at ${target}; the original is not opened.\n`);
  }
  const engine = await createEngine(engineConfig);
  try {
    await engine.connect(engineConfig);
    const report = await engine.transaction(async tx => {
      await tx.executeRaw('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
      return scanWriteGateExposure(tx, {
        tables, ...(flag(args, '--source') ? { sourceId: flag(args, '--source') } : {}),
        ...(limit ? { limitPerTable: Number(limit) } : {}), ...(batch ? { batchSize: Number(batch) } : {}),
        onBatch: (table, n) => process.stderr.write(`[trust-dry-run] ${table}: ${n} rows\n`),
      });
    });
    console.log(args.includes('--json') ? JSON.stringify(report, null, 2) : renderReport(report));
    return 0;
  } finally {
    await engine.disconnect().catch(() => {});
    if (copyDir) rmSync(copyDir, { recursive: true, force: true });
  }
}

if (import.meta.main) process.exit(await main());