Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
18.0 KB
Raw Blame
/**
 * compile-context.ts — `gbrain compile-context` (cathedral-5, plan D3'/D4').
 *
 * Compiles a deterministic, sensitivity-scanned, token-budgeted context
 * file from the brain via src/core/context/compile-view.ts. Byte-stable:
 * an unchanged brain compiles to identical bytes (the header digest is the
 * freshness signal); check mode recompiles in memory and byte-compares.
 *
 * Targets (bootstrap spellings):
 *   claude-code  writes .claude/gbrain-context.md and prints the one-line
 *                CLAUDE.md import instruction (closed-harness: one line of
 *                user setup, no harness cooperation needed).
 *   codex        splices into AGENTS.md between the managed begin/end
 *                markers. Duplicate/orphan/out-of-order markers THROW
 *                (modeled on bootstrap/codex-toml.ts findBlock — hand-edits
 *                we must not guess through). Also serves opencode
 *                (AGENTS.md loads natively there).
 *   openclaw     writes <workspace>/.gbrain/compiled-context.md.
 *
 * Failure posture: read/config errors exit non-zero with NO partial
 * writes (atomicWriteTextFile is the only writer, and it only runs after
 * a full successful compile). Scan drops never abort — they are reported
 * on stderr (slug + family + fingerprint; never the matched text) and in
 * the json envelope.
 *
 * Exit codes: 0 ok / in-check identical; 1 check found a difference;
 * 2 error (usage, config, read failure, damaged markers).
 */

import { existsSync, readFileSync } from 'fs';
import { join, relative } from 'path';
import type { BrainEngine } from '../core/engine.ts';
import { atomicWriteTextFile } from '../core/bootstrap/atomic-write.ts';
import { compileView, type CompileViewMeta } from '../core/context/compile-view.ts';
import { formatSensitivityDrop, loadSensitivityConfig } from '../core/context/sensitivity-scan.ts';
import { resolveSourceId, ALL_SOURCES } from '../core/source-resolver.ts';
import { homedir } from 'os';
import { listCorePages, loadCoreBlock } from '../core/core-memory.ts';
import { ensureGitExcluded, gitRoot, isGitTracked, updateCompiledCoreRecord } from '../core/context/compiled-core.ts';

// ── Constants ───────────────────────────────────────────────────────────────

export const COMPILE_TARGETS = ['claude-code', 'codex', 'openclaw', 'codex-global', 'hermes'] as const;
export type CompileTarget = (typeof COMPILE_TARGETS)[number];

/** Managed-block markers for the codex (AGENTS.md) target. Exact-line match. */
export const COMPILED_BLOCK_BEGIN = '<!-- gbrain:compiled-context:begin -->';
export const COMPILED_BLOCK_END = '<!-- gbrain:compiled-context:end -->';

/** Default whole-file token budget when the budget flag is omitted. */
export const DEFAULT_COMPILE_BUDGET = 4000;

const EXIT_OK = 0;
const EXIT_DIFF = 1;
const EXIT_ERROR = 2;

// ── Flag parsing ────────────────────────────────────────────────────────────

interface CompileFlags {
  target: CompileTarget;
  budget: number;
  out?: string;
  stdout: boolean;
  source?: string;
  include?: string[];
  check: boolean;
  json: boolean;
  includeCore: boolean;
  removeCore: boolean;
}

class UsageError extends Error {}

function flagValue(args: string[], flag: string): string | undefined {
  const i = args.indexOf(flag);
  if (i >= 0) {
    const v = args[i + 1];
    if (v === undefined || v.startsWith('--')) {
      throw new UsageError(`${flag} requires a value`);
    }
    return v;
  }
  const prefix = `${flag}=`;
  const kv = args.find((a) => a.startsWith(prefix));
  return kv ? kv.slice(prefix.length) : undefined;
}

function parseCompileFlags(args: string[]): CompileFlags {
  const target = flagValue(args, '--target');
  if (!target) {
    throw new UsageError(`--target is required (${COMPILE_TARGETS.join(' | ')})`);
  }
  if (!(COMPILE_TARGETS as readonly string[]).includes(target)) {
    throw new UsageError(
      `unknown target "${target}" — expected one of: ${COMPILE_TARGETS.join(' | ')}`,
    );
  }
  const budgetRaw = flagValue(args, '--budget');
  let budget = DEFAULT_COMPILE_BUDGET;
  if (budgetRaw !== undefined) {
    budget = Number(budgetRaw);
    if (!Number.isFinite(budget) || !Number.isInteger(budget) || budget <= 0) {
      throw new UsageError(`--budget must be a positive integer (got "${budgetRaw}")`);
    }
  }
  const include = flagValue(args, '--include')
    ?.split(',')
    .map((p) => p.trim())
    .filter((p) => p.length > 0);
  return {
    target: target as CompileTarget,
    budget,
    out: flagValue(args, '--out'),
    stdout: args.includes('--stdout'),
    source: flagValue(args, '--source'),
    ...(include && include.length > 0 ? { include } : {}),
    check: args.includes('--check'),
    json: args.includes('--json'),
    // codex-global exists to carry core, so it includes core unless told to remove it.
    includeCore: !args.includes('--remove-core') && (args.includes('--include-core') || target === 'codex-global'),
    removeCore: args.includes('--remove-core'),
  };
}

/** Targets whose output is a managed block inside a file the user also edits. */
const SPLICE_TARGETS: ReadonlySet<CompileTarget> = new Set(['codex', 'codex-global']);

// ── Codex AGENTS.md splice ──────────────────────────────────────────────────

/**
 * Splice the compiled text into the managed block. No markers → append a
 * fresh block at EOF. Exactly one in-order pair → replace the interior.
 * Anything else (duplicates, an orphan, out of order) → THROW: those are
 * hand-edits we must not guess through (findBlock discipline).
 */
export function spliceCompiledBlock(existing: string, compiled: string): string {
  const lines = existing.length > 0 ? existing.split('\n') : [];
  const begins: number[] = [];
  const ends: number[] = [];
  lines.forEach((line, i) => {
    if (line === COMPILED_BLOCK_BEGIN) begins.push(i);
    if (line === COMPILED_BLOCK_END) ends.push(i);
  });
  // Neutralize marker-equal lines INSIDE the compiled body (adversarial
  // review): a page excerpt that is exactly a marker string would land as a
  // real marker line — the first splice succeeds, and every run after that
  // sees damaged markers (self-wedge until hand-edit). A leading space keeps
  // the text visible but fails the exact-line match. Deterministic, so the
  // check recompile compares like-for-like.
  const neutralized = compiled
    .split('\n')
    .map((l) => (l === COMPILED_BLOCK_BEGIN || l === COMPILED_BLOCK_END ? ` ${l}` : l))
    .join('\n');
  const body = neutralized.endsWith('\n') ? neutralized.slice(0, -1) : neutralized;
  if (begins.length === 0 && ends.length === 0) {
    const head =
      existing.length === 0 ? '' : existing.endsWith('\n') ? existing : `${existing}\n`;
    return `${head}${COMPILED_BLOCK_BEGIN}\n${body}\n${COMPILED_BLOCK_END}\n`;
  }
  if (begins.length !== 1 || ends.length !== 1 || begins[0] > ends[0]) {
    throw new Error(
      `the gbrain compiled-context markers in this file are damaged ` +
        `(${begins.length} begin / ${ends.length} end` +
        `${begins.length === 1 && ends.length === 1 ? ', out of order' : ''}) — ` +
        `the managed block was hand-edited. Fix the markers (or delete the whole block) and re-run.`,
    );
  }
  const out = [...lines.slice(0, begins[0] + 1), ...body.split('\n'), ...lines.slice(ends[0])];
  const joined = out.join('\n');
  return joined.endsWith('\n') ? joined : `${joined}\n`;
}

// ── Paths ───────────────────────────────────────────────────────────────────

// Semgrep path-join suppressions below: `cwd` is process.cwd() on a LOCAL,
// operator-invoked CLI command (CLI_ONLY, refused on thin clients) and every
// joined segment is a literal — there is no untrusted input in these paths.
export function defaultOutPath(target: CompileTarget, cwd: string): string {
  switch (target) {
    case 'claude-code':
      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
      return join(cwd, '.claude', 'gbrain-context.md');
    case 'codex':
      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
      return join(cwd, 'AGENTS.md');
    case 'openclaw':
      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
      return join(cwd, '.gbrain', 'compiled-context.md');
    case 'codex-global':
      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
      return join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'AGENTS.md');
    case 'hermes':
      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
      return join(gitRoot(cwd) ?? cwd, '.hermes.md');
  }
}

/** Removes the managed block from a splice target, leaving the user's own text. */
export function removeCompiledBlock(existing: string): string {
  const lines = existing.split('\n');
  const begin = lines.indexOf(COMPILED_BLOCK_BEGIN);
  const end = lines.indexOf(COMPILED_BLOCK_END);
  if (begin === -1 || end < begin) return existing;
  return [...lines.slice(0, begin), ...lines.slice(end + 1)].join('\n');
}

// ── Help ────────────────────────────────────────────────────────────────────

function printCompileContextHelp(): void {
  process.stdout.write(`Usage: gbrain compile-context --target <t> [flags]

Compile a deterministic, sensitivity-scanned, token-budgeted context file
from the brain. Unchanged brain => identical bytes; the header digest is
the freshness signal.

Flags:
  --target <t>       Required: claude-code | codex | openclaw.
  --budget <n>       Whole-file token budget (default ${DEFAULT_COMPILE_BUDGET}).
  --out <path>       Override the target's default output path.
  --stdout           Print the compiled text to stdout; write no files.
  --source <id>      Compile from this source (default: resolved source).
  --include <p,...>  Extra slug prefixes selected alongside the defaults.
  --check            Recompile in memory and byte-compare against the
                     existing output. Exit 0 same, 1 different, 2 error.
  --include-core     Render always-loaded core memory first, in full. Refused
                     when the output file is tracked by git.
  --remove-core      Recompile without core (codex-global: remove the block).
  --json             Machine-readable result envelope on stdout.
  --help             Show this help.

Targets:
  claude-code   .claude/gbrain-context.md + a one-line CLAUDE.md import.
  codex         AGENTS.md managed block (also loads natively in opencode).
  openclaw      .gbrain/compiled-context.md in the workspace.
  codex-global  $CODEX_HOME/AGENTS.md managed block: the default source's
                core memory, loaded in every Codex session.
  hermes        .hermes.md at the git root, kept out of git via
                .git/info/exclude.
`);
}

// ── Main ────────────────────────────────────────────────────────────────────

interface CompileEnvelope extends CompileViewMeta {
  target: CompileTarget;
  source_id: string;
  out: string | null;
  generated_at: string;
  check?: 'match' | 'diff';
}

/**
 * Signature matches the SELF_HELP_WITHOUT_ENGINE convention in cli.ts:
 * `(engine, args)` with `engine: BrainEngine | null` — the help guard runs
 * FIRST, before the engine is touched, so help answers with no brain.
 */
export async function runCompileContext(
  engine: BrainEngine | null,
  args: string[],
  opts: { cwd?: string } = {},
): Promise<number> {
  if (args.includes('--help') || args.includes('-h')) {
    printCompileContextHelp();
    return EXIT_OK;
  }
  if (!engine) {
    // Defensive: the dispatcher connects before calling with real work.
    process.stderr.write('compile-context: no brain configured (run `gbrain init` first).\n');
    return EXIT_ERROR;
  }

  let flags: CompileFlags;
  try {
    flags = parseCompileFlags(args);
  } catch (err) {
    process.stderr.write(`compile-context: ${(err as Error).message}\n`);
    process.stderr.write('Run `gbrain compile-context --help` for usage.\n');
    return EXIT_ERROR;
  }

  const cwd = opts.cwd ?? process.cwd();

  try {
    // Source resolution runs even when the source flag is omitted (6-tier
    // resolution: flag > env > dotfile > ... > 'default'). The user-global
    // codex file holds the default source's core only.
    const sourceId = flags.target === 'codex-global' ? 'default' : await resolveSourceId(engine, flags.source ?? null, cwd);
    if (sourceId === ALL_SOURCES) {
      process.stderr.write(
        'compile-context: compiles exactly ONE source — pass a concrete source id.\n',
      );
      return EXIT_ERROR;
    }

    // Config loads BEFORE any compile work: a loader failure (malformed
    // operator regex, unreadable allowlist) aborts here, before anything
    // could be written.
    const scanConfig = loadSensitivityConfig({ workspaceRoot: cwd });

    const outPath = flags.out ?? defaultOutPath(flags.target, cwd);
    // Core reaches every session that loads this file, so it never goes into a shared (git-tracked) file.
    if (flags.includeCore && !flags.stdout) {
      if (flags.target === 'hermes' && !isGitTracked(outPath)) ensureGitExcluded(outPath);
      if (isGitTracked(outPath)) {
        process.stderr.write(`compile-context: ${outPath} is tracked by git, so always-loaded core memory will not be written into it (it would be committed and shared). `
          + 'Use a local target (--target claude-code, hermes or codex-global) or --out <untracked path>, or drop --include-core.\n');
        return EXIT_ERROR;
      }
    }
    // Core pages leave the arms either way: with --include-core they render in full, without it they stay out.
    const excludeSlugs = new Set((await listCorePages(engine, { sourceIds: [sourceId] })).map(p => p.slug));
    let core: { text: string; revision: string; command: string } | undefined;
    if (flags.includeCore) {
      const block = await loadCoreBlock(engine, { sessionSourceId: sourceId, excludePrivate: true, notices: [] });
      const command = `gbrain compile-context --target ${flags.target}${flags.target === 'codex-global' ? '' : ' --include-core'}${flags.out ? ` --out ${flags.out}` : ''}`;
      core = { text: block.text, revision: block.revision, command };
    }

    const { text, meta } = await compileView({
      engine,
      sourceId,
      target: flags.target,
      budget: flags.budget,
      ...(flags.include ? { includePrefixes: flags.include } : {}),
      scanConfig,
      excludeSlugs,
      ...(core ? { core } : {}),
      ...(flags.target === 'codex-global' ? { coreOnly: true } : {}),
    });

    // Drops are always reported: slug + family + fingerprint, never the text.
    for (const d of meta.scan_drops) {
      process.stderr.write(`compile-context: ${formatSensitivityDrop(d, cwd)}\n`);
    }

    const existing = existsSync(outPath) ? readFileSync(outPath, 'utf-8') : null;

    const envelope = (extra: Partial<CompileEnvelope>): CompileEnvelope => ({
      target: flags.target,
      source_id: sourceId,
      out: flags.stdout ? null : outPath,
      generated_at: new Date().toISOString(),
      ...meta,
      ...extra,
    });

    if (flags.check) {
      let same: boolean;
      if (SPLICE_TARGETS.has(flags.target)) {
        // "Would a write change the file?" — includes missing/absent block.
        same = existing !== null && spliceCompiledBlock(existing, text) === existing;
      } else {
        same = existing === text;
      }
      const verdict: 'match' | 'diff' = same ? 'match' : 'diff';
      if (flags.json) {
        process.stdout.write(`${JSON.stringify(envelope({ check: verdict, out: outPath }))}\n`);
      } else {
        process.stdout.write(
          same
            ? `compile-context: up to date (${outPath})\n`
            : `compile-context: STALE — a recompile would change ${outPath}\n`,
        );
      }
      return same ? EXIT_OK : EXIT_DIFF;
    }

    if (flags.stdout) {
      if (flags.json) {
        process.stdout.write(`${JSON.stringify({ ...envelope({}), text })}\n`);
      } else {
        process.stdout.write(text);
      }
      return EXIT_OK;
    }

    if (flags.target === 'codex-global' && flags.removeCore) {
      if (existing !== null) atomicWriteTextFile(outPath, removeCompiledBlock(existing), { freshMode: 0o644 });
      updateCompiledCoreRecord(outPath, null);
      process.stdout.write(flags.json ? `${JSON.stringify(envelope({}))}\n` : `compile-context: removed core memory from ${outPath}\n`);
      return EXIT_OK;
    }
    const fileText =
      SPLICE_TARGETS.has(flags.target) ? spliceCompiledBlock(existing ?? '', text) : text;
    atomicWriteTextFile(outPath, fileText, { freshMode: 0o644 });
    updateCompiledCoreRecord(outPath, core ? { target: flags.target, source_id: sourceId, revision: core.revision, command: core.command } : null);

    if (flags.json) {
      process.stdout.write(`${JSON.stringify(envelope({}))}\n`);
    } else {
      process.stdout.write(
        `compile-context: wrote ${meta.entries_used} entr${meta.entries_used === 1 ? 'y' : 'ies'} ` +
          `(${meta.total_output_tokens} tokens, budget ${meta.requested_budget}) → ${outPath}\n`,
      );
      if (flags.target === 'claude-code') {
        const rel = relative(cwd, outPath);
        process.stdout.write(`Add this line to CLAUDE.md to load it: @${rel}\n`);
      }
    }
    return EXIT_OK;
  } catch (err) {
    process.stderr.write(`compile-context: ${(err as Error).message}\n`);
    return EXIT_ERROR;
  }
}