Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
19.2 KB
Raw Blame
/**
 * gbrain friction — friction reporter CLI.
 *
 * Five subcommands (remaining analytical ones — trend, migration-stub — stay v1.1):
 *   gbrain friction log     Append a friction or delight entry
 *   gbrain friction render  Render a run as markdown or JSON
 *   gbrain friction list    List recent runs with counts
 *   gbrain friction summary Side-by-side friction + delight summary
 *   gbrain friction diff    Compare two runs (or agents): unique-to-each + shared-but-changed
 *
 * Subcommands stay thin (≤ ~30 LOC each). Reader/writer/redaction logic lives
 * in src/core/friction.ts; the diff computation lives here (it is CLI-only).
 *
 * The CLI is dispatched from src/cli.ts. See `gbrain friction --help`.
 */

import { existsSync } from 'fs';
import {
  logFriction, readFriction, listRuns, renderReport, renderSummary,
  activeRunId, frictionFile, frictionDir, redactEntry,
  type FrictionKind, type FrictionSeverity, type FrictionEntry, type ReadResult,
} from '../core/friction.ts';

const VALID_KINDS = new Set<FrictionKind>(['friction', 'delight', 'phase-marker', 'interrupted']);
const VALID_SEVERITIES = new Set<FrictionSeverity>(['confused', 'error', 'blocker', 'nit']);

export function runFriction(args: string[]): number {
  const [sub, ...rest] = args;
  switch (sub) {
    case 'log':     return cmdLog(rest);
    case 'render':  return cmdRender(rest);
    case 'list':    return cmdList(rest);
    case 'summary': return cmdSummary(rest);
    case 'diff':    return cmdDiff(rest);
    case undefined:
    case '--help':
    case '-h':
      printHelp();
      return 0;
    default:
      console.error(`unknown subcommand: ${sub}`);
      printHelp();
      return 2;
  }
}

// ---------------------------------------------------------------------------
// log
// ---------------------------------------------------------------------------

function cmdLog(args: string[]): number {
  const flags = parseFlags(args);
  const phase = flags.string('--phase');
  const message = flags.string('--message');
  if (!phase || !message) {
    console.error('usage: gbrain friction log --phase <name> --message <text> [--severity ...] [--hint ...] [--kind ...] [--run-id ...]');
    return 2;
  }
  const kind = (flags.string('--kind') ?? 'friction') as FrictionKind;
  if (!VALID_KINDS.has(kind)) {
    console.error(`invalid --kind ${kind}; must be one of: ${[...VALID_KINDS].join(', ')}`);
    return 2;
  }
  const severityRaw = flags.string('--severity');
  const severity = severityRaw as FrictionSeverity | undefined;
  if (severity && !VALID_SEVERITIES.has(severity)) {
    console.error(`invalid --severity ${severity}; must be one of: ${[...VALID_SEVERITIES].join(', ')}`);
    return 2;
  }
  try {
    logFriction({
      phase,
      message,
      kind,
      severity,
      hint: flags.string('--hint'),
      runId: flags.string('--run-id'),
      agent: flags.string('--agent'),
      source: 'claw',
    });
  } catch (e) {
    console.error(`friction log failed: ${e instanceof Error ? e.message : String(e)}`);
    return 1;
  }
  return 0;
}

// ---------------------------------------------------------------------------
// render
// ---------------------------------------------------------------------------

function cmdRender(args: string[]): number {
  const flags = parseFlags(args);
  const runId = flags.string('--run-id') ?? activeRunId();
  const json = flags.bool('--json');
  const format = json ? 'json' : 'md';
  const transcripts = flags.bool('--transcripts');
  const noRedact = flags.bool('--no-redact');
  // --redact is the default for md output; --no-redact disables.
  const redact = noRedact ? false : (format === 'md');
  try {
    const out = renderReport(runId, {
      format,
      redact,
      transcriptPath: transcripts ? flags.string('--transcript-path') ?? undefined : undefined,
    });
    process.stdout.write(out + '\n');
    return 0;
  } catch (e) {
    console.error(`friction render failed: ${e instanceof Error ? e.message : String(e)}`);
    return 1;
  }
}

// ---------------------------------------------------------------------------
// list
// ---------------------------------------------------------------------------

function cmdList(args: string[]): number {
  const flags = parseFlags(args);
  const json = flags.bool('--json');
  const runs = listRuns();
  if (json) {
    console.log(JSON.stringify(runs, null, 2));
    return 0;
  }
  if (runs.length === 0) {
    console.log('no runs yet');
    return 0;
  }
  for (const r of runs) {
    const interrupted = r.counts.interrupted ? ' (interrupted)' : '';
    const sev = Object.entries(r.counts.bySeverity).map(([k, v]) => `${k}=${v}`).join(' ');
    console.log(`${r.runId}${interrupted}  friction=${r.counts.friction}  delight=${r.counts.delight}  ${sev}`);
  }
  return 0;
}

// ---------------------------------------------------------------------------
// summary
// ---------------------------------------------------------------------------

function cmdSummary(args: string[]): number {
  const flags = parseFlags(args);
  const runId = flags.string('--run-id') ?? activeRunId();
  const json = flags.bool('--json');
  try {
    const out = renderSummary(runId, { format: json ? 'json' : 'md' });
    process.stdout.write(out + '\n');
    return 0;
  } catch (e) {
    console.error(`friction summary failed: ${e instanceof Error ? e.message : String(e)}`);
    return 1;
  }
}

// ---------------------------------------------------------------------------
// diff
// ---------------------------------------------------------------------------

/**
 * Entry identity for diffing: (kind, phase, normalized message prefix) —
 * lowercase, whitespace-collapsed, digit runs collapsed (durations, counts,
 * and tempdir suffixes would otherwise make the same friction land in
 * "unique to each" across runs), first 80 chars, with redaction applied
 * FIRST (the caller redacts via redactEntry). Kind IS identity: a delight
 * and a friction with the same text are different findings, and a
 * delight→friction flip must surface, never compare equal. Severity is
 * deliberately EXCLUDED from identity — it is the compared attribute, as a
 * PER-SEVERITY MULTISET (two errors + one nit vs one error + two nits is a
 * reported difference even though the severity sets and totals match).
 */
const IDENTITY_PREFIX_CHARS = 80;

interface DiffIdentityRecord {
  kind: string;
  phase: string;
  /** Redacted message of the first occurrence (display sample). */
  message: string;
  count: number;
  /** Unique severities, sorted (display); counts live in severity_counts. */
  severities: string[];
  severity_counts: Record<string, number>;
}

interface DiffChangedRecord {
  kind: string;
  phase: string;
  message: string;
  base_count: number;
  compare_count: number;
  base_severities: string[];
  compare_severities: string[];
  base_severity_counts: Record<string, number>;
  compare_severity_counts: Record<string, number>;
  count_changed: boolean;
  severity_changed: boolean;
}

interface DiffRunBanner {
  run_id: string;
  agent?: string;
  scenario?: string;
  gbrain_version?: string;
  interrupted: boolean;
  /** Malformed JSONL lines skipped by the reader (surfaced, never hidden). */
  malformed: number;
}

export interface FrictionDiffResult {
  base: string;
  compare: string;
  banner: { base: DiffRunBanner; compare: DiffRunBanner; warnings: string[] };
  unique_to_base: DiffIdentityRecord[];
  unique_to_compare: DiffIdentityRecord[];
  changed: DiffChangedRecord[];
}

/**
 * Resolve a run spec: an exact run-id wins; otherwise treat the spec as an
 * agent name and pick the LATEST run (listRuns is mtime-sorted, newest first)
 * whose entries carry that agent — the run-start marker stamps agent on clean
 * runs, and any agent-stamped entry also counts. Returns undefined if nothing
 * matches.
 */
export function resolveRunSpec(spec: string): string | undefined {
  try {
    if (existsSync(frictionFile(spec))) return spec;
  } catch { /* spec has characters a run-id can't; fall through to agent-name resolution */ }
  for (const run of listRuns()) {
    try {
      const { entries } = readFriction(run.runId);
      if (entries.some(e => e.agent === spec)) return run.runId;
    } catch { /* unreadable file; skip */ }
  }
  return undefined;
}

function normalizeForIdentity(message: string): string {
  return message.toLowerCase().replace(/\d+/g, '#').replace(/\s+/g, ' ').trim().slice(0, IDENTITY_PREFIX_CHARS);
}

interface IdentityAccum { kind: string; phase: string; message: string; count: number; severities: Map<string, number> }

/** Sorted-key plain object from a severity count map (deterministic JSON). */
function severityCounts(m: Map<string, number>): Record<string, number> {
  return Object.fromEntries([...m.entries()].sort(([a], [b]) => a.localeCompare(b)));
}

/** Diff operates ONLY on kind friction|delight; markers/interruptions feed the banner. */
function collectIdentities(entries: FrictionEntry[]): Map<string, IdentityAccum> {
  const map = new Map<string, IdentityAccum>();
  for (const raw of entries) {
    // Entries from older writers may omit kind; they are friction by contract.
    const kind = raw.kind ?? 'friction';
    if (kind !== 'friction' && kind !== 'delight') continue;
    const e = redactEntry(raw);
    const key = `${kind}\u0000${e.phase}\u0000${normalizeForIdentity(e.message)}`;
    let acc = map.get(key);
    if (!acc) {
      acc = { kind, phase: e.phase, message: e.message, count: 0, severities: new Map() };
      map.set(key, acc);
    }
    acc.count++;
    if (e.severity) acc.severities.set(e.severity, (acc.severities.get(e.severity) ?? 0) + 1);
  }
  return map;
}

function toIdentityRecord(acc: IdentityAccum): DiffIdentityRecord {
  return {
    kind: acc.kind,
    phase: acc.phase,
    message: acc.message,
    count: acc.count,
    severities: [...acc.severities.keys()].sort(),
    severity_counts: severityCounts(acc.severities),
  };
}

function bannerFor(runId: string, read: ReadResult): DiffRunBanner {
  const start = read.entries.find(e => e.kind === 'phase-marker' && e.marker === 'start');
  const agent = start?.agent ?? read.entries.find(e => e.agent)?.agent;
  return {
    run_id: runId,
    agent,
    scenario: start?.scenario,
    gbrain_version: start?.gbrain_version ?? read.entries[0]?.gbrain_version,
    interrupted: read.entries.some(e => e.kind === 'interrupted'),
    malformed: read.malformed,
  };
}

/** Compute the diff between two resolved run-ids. Throws on read errors. */
export function computeFrictionDiff(baseRunId: string, compareRunId: string): FrictionDiffResult {
  const baseRead = readFriction(baseRunId);
  const compareRead = readFriction(compareRunId);
  const baseBanner = bannerFor(baseRunId, baseRead);
  const compareBanner = bannerFor(compareRunId, compareRead);

  const warnings: string[] = [];
  if ((baseBanner.scenario ?? '') !== (compareBanner.scenario ?? '')) {
    warnings.push(`scenario differs: ${baseRunId} ran ${baseBanner.scenario ?? '(unknown)'}, ${compareRunId} ran ${compareBanner.scenario ?? '(unknown)'} — entries may not be comparable`);
  }
  if ((baseBanner.gbrain_version ?? '') !== (compareBanner.gbrain_version ?? '')) {
    warnings.push(`gbrain version differs: ${baseRunId} ran ${baseBanner.gbrain_version ?? '(unknown)'}, ${compareRunId} ran ${compareBanner.gbrain_version ?? '(unknown)'}`);
  }

  const baseIds = collectIdentities(baseRead.entries);
  const compareIds = collectIdentities(compareRead.entries);
  const uniqueToBase: DiffIdentityRecord[] = [];
  const uniqueToCompare: DiffIdentityRecord[] = [];
  const changed: DiffChangedRecord[] = [];
  for (const [key, b] of baseIds) {
    const c = compareIds.get(key);
    if (!c) { uniqueToBase.push(toIdentityRecord(b)); continue; }
    const bCounts = severityCounts(b.severities);
    const cCounts = severityCounts(c.severities);
    const countChanged = b.count !== c.count;
    // severity_changed = the per-severity DISTRIBUTION SHAPE changed — a new
    // severity appeared/disappeared or the mix redistributed (2×error+1×nit →
    // 1×error+2×nit, which the unique-severity set hides). Uniform scaling
    // (1×error → 10×error) is purely a count change and count_changed already
    // reports it. Integer cross-multiplication keeps the proportion test
    // exact.
    const bTotal = Object.values(bCounts).reduce((a, n) => a + n, 0);
    const cTotal = Object.values(cCounts).reduce((a, n) => a + n, 0);
    let severityChanged = (bTotal === 0) !== (cTotal === 0);
    if (!severityChanged) {
      for (const s of new Set([...Object.keys(bCounts), ...Object.keys(cCounts)])) {
        if ((bCounts[s] ?? 0) * cTotal !== (cCounts[s] ?? 0) * bTotal) { severityChanged = true; break; }
      }
    }
    if (countChanged || severityChanged) {
      changed.push({
        kind: b.kind, phase: b.phase, message: b.message,
        base_count: b.count, compare_count: c.count,
        base_severities: Object.keys(bCounts), compare_severities: Object.keys(cCounts),
        base_severity_counts: bCounts, compare_severity_counts: cCounts,
        count_changed: countChanged, severity_changed: severityChanged,
      });
    }
  }
  for (const [key, c] of compareIds) {
    if (!baseIds.has(key)) uniqueToCompare.push(toIdentityRecord(c));
  }
  const byPhaseThenMessage = (a: { phase: string; message: string }, b: { phase: string; message: string }) =>
    a.phase.localeCompare(b.phase) || a.message.localeCompare(b.message);
  uniqueToBase.sort(byPhaseThenMessage);
  uniqueToCompare.sort(byPhaseThenMessage);
  changed.sort(byPhaseThenMessage);

  return {
    base: baseRunId,
    compare: compareRunId,
    banner: { base: baseBanner, compare: compareBanner, warnings },
    unique_to_base: uniqueToBase,
    unique_to_compare: uniqueToCompare,
    changed,
  };
}

function groupByPhase<T extends { phase: string }>(records: T[]): Map<string, T[]> {
  const map = new Map<string, T[]>();
  for (const r of records) {
    if (!map.has(r.phase)) map.set(r.phase, []);
    map.get(r.phase)!.push(r);
  }
  return map;
}

function fmtSeverityCounts(counts: Record<string, number>): string {
  const parts = Object.entries(counts).map(([s, n]) => (n > 1 ? `${s}×${n}` : s));
  return parts.length > 0 ? parts.join('/') : '(none)';
}

/** Render the diff as markdown. Sections are labeled by run-id — the diff is
 *  an instrument, not a judge; it never attributes blame to either side. */
function renderDiff(diff: FrictionDiffResult): string {
  const lines: string[] = [];
  lines.push(`# Friction diff — base \`${diff.base}\` vs compare \`${diff.compare}\``);
  lines.push('');
  for (const side of [diff.banner.base, diff.banner.compare]) {
    const bits = [
      `agent=${side.agent ?? '(unknown)'}`,
      `scenario=${side.scenario ?? '(unknown)'}`,
      `gbrain=${side.gbrain_version ?? '(unknown)'}`,
    ];
    if (side.interrupted) bits.push('interrupted');
    if (side.malformed > 0) bits.push(`${side.malformed} malformed line(s) skipped`);
    lines.push(`- \`${side.run_id}\`: ${bits.join(' · ')}`);
  }
  lines.push('');
  for (const w of diff.banner.warnings) lines.push(`> ⚠ WARN: ${w}`);
  if (diff.banner.warnings.length > 0) lines.push('');

  if (diff.unique_to_base.length === 0 && diff.unique_to_compare.length === 0 && diff.changed.length === 0) {
    lines.push('No differences.');
    lines.push('');
  }

  const renderIdentitySection = (title: string, records: DiffIdentityRecord[]) => {
    lines.push(`## ${title} (${records.length})`);
    lines.push('');
    if (records.length === 0) { lines.push('(none)'); lines.push(''); return; }
    for (const [phase, rs] of groupByPhase(records)) {
      lines.push(`### \`${phase}\``);
      lines.push('');
      for (const r of rs) {
        const sev = r.severities.length > 0 ? `[${r.severities.join('/')}] ` : '';
        const kind = r.kind === 'delight' ? '[delight] ' : '';
        const count = r.count > 1 ? ` ×${r.count}` : '';
        lines.push(`- ${kind}${sev}${r.message}${count}`);
      }
      lines.push('');
    }
  };
  renderIdentitySection(`Unique to \`${diff.compare}\``, diff.unique_to_compare);
  renderIdentitySection(`Unique to \`${diff.base}\``, diff.unique_to_base);

  lines.push(`## Shared but changed (${diff.changed.length})`);
  lines.push('');
  if (diff.changed.length === 0) { lines.push('(none)'); lines.push(''); }
  for (const [phase, rs] of groupByPhase(diff.changed)) {
    lines.push(`### \`${phase}\``);
    lines.push('');
    for (const r of rs) {
      const deltas: string[] = [];
      if (r.severity_changed) deltas.push(`severity ${fmtSeverityCounts(r.base_severity_counts)} → ${fmtSeverityCounts(r.compare_severity_counts)}`);
      if (r.count_changed) deltas.push(`count ${r.base_count} → ${r.compare_count}`);
      const kind = r.kind === 'delight' ? '[delight] ' : '';
      lines.push(`- ${kind}${r.message} — ${deltas.join('; ')}`);
    }
    lines.push('');
  }
  return lines.join('\n');
}

function cmdDiff(args: string[]): number {
  const flags = parseFlags(args);
  const baseSpec = flags.string('--base');
  const compareSpec = flags.string('--compare');
  if (!baseSpec || !compareSpec) {
    console.error('usage: gbrain friction diff --base <run-or-agent> --compare <run-or-agent> [--json]');
    return 2;
  }
  const baseRun = resolveRunSpec(baseSpec);
  const compareRun = resolveRunSpec(compareSpec);
  if (!baseRun || !compareRun) {
    const unresolved = [!baseRun ? baseSpec : undefined, !compareRun ? compareSpec : undefined]
      .filter((s): s is string => s !== undefined)
      .map(s => JSON.stringify(s)).join(', ');
    const runs = listRuns();
    const available = runs.length > 0 ? runs.map(r => `  ${r.runId}`).join('\n') : '  (none)';
    console.error(`friction diff failed: ${unresolved} matched no run-id or agent\navailable runs under ${frictionDir()}:\n${available}`);
    return 1;
  }
  try {
    const diff = computeFrictionDiff(baseRun, compareRun);
    process.stdout.write((flags.bool('--json') ? JSON.stringify(diff, null, 2) : renderDiff(diff)) + '\n');
    return 0;
  } catch (e) {
    console.error(`friction diff failed: ${e instanceof Error ? e.message : String(e)}`);
    return 1;
  }
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

function parseFlags(args: string[]) {
  return {
    string(flag: string): string | undefined {
      const idx = args.indexOf(flag);
      return idx === -1 ? undefined : args[idx + 1];
    },
    bool(flag: string): boolean {
      return args.includes(flag);
    },
  };
}

function printHelp() {
  console.log(`gbrain friction — friction reporter

Subcommands:
  log     Append a friction or delight entry to the active run
  render  Render a run's entries as markdown (default) or JSON
  list    List recent runs with friction/delight counts
  summary Two-column summary of friction + delight for a run
  diff    Compare two runs: unique-to-each + shared-but-changed entries

Examples:
  gbrain friction log --severity confused --phase install --message "init didn't say which engine"
  gbrain friction render --run-id claw-test-20260428-... --transcripts
  gbrain friction list --json
  gbrain friction summary
  gbrain friction diff --base openclaw --compare hermes --json

Run-id resolution: --run-id > $GBRAIN_FRICTION_RUN_ID > 'standalone'.
Diff run resolution: an exact run-id wins; otherwise the value is treated as
an agent name and resolves to that agent's latest run.`);
}