Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Render engine for `gbrain bootstrap render` (library module — the dispatcher
* in src/commands/bootstrap/ calls `renderWorkspace`).
*
* One rendering code path, two consumers [D4]: the normal bootstrap render
* (interview answers) and the release-time template-repo generator
* (`minimal: true`, placeholder answers, byte-deterministic [CX2-14]).
*
* Contracts carried from docs/designs/AGENT_BOOTSTRAP_PLAN.md:
* - Token resolution: interview answers > bank defaults. DERIVED_TOKENS
* (assets.ts) resolve from `opts.derived` with canonical fallbacks.
* - [S3#3] Interview-sourced values are DATA, not structure: before
* insertion, any line of an answer that begins (allowing up to 3 leading
* spaces, the markdown heading tolerance) with `#`, `<!--`, a ``` code
* fence, or a ~~~ tilde fence is prefixed with a backslash — THE
* DOCUMENTED ESCAPE. A
* backslash-prefixed `#` is not a heading, `\<!--` is not a comment
* open, and `\``` does not open a fence. The first line of a value is
* escaped too even when the token sits mid-line — deliberate
* over-escaping; a cosmetic backslash beats a structural injection.
* Values already carry set-time `{{`/`}}` escaping (interview.ts), so
* substitution can never introduce new tokens.
* - HARD-FAIL on any unresolved {{TOKEN}} — every unresolved token across
* every selected file is listed, and NOTHING is written (all files render
* in memory first).
* - Render never clobbers: an existing dest without `force` is skipped;
* with `force` the old content is backed up to
* `<ws>/.gbrain-bootstrap-backups/<ts>/<dest>` before the write.
* - Minimal mode [D4/CX2-14]: ignores interview state AND `opts.derived`
* entirely; keys with bank defaults render their defaults; the six
* required keys (no defaults) stay as literal `{{TOKEN}}` placeholders
* (they are the template repo's visible fill-me markers); the manifest is
* the canonical TEMPLATE_PLACEHOLDER_MANIFEST (frozen timestamp). Two
* independent minimal renders are byte-identical.
* - [ENG-10] The renderer only ever writes BOOTSTRAP_TEMPLATES dests —
* never skillpack scaffold paths, so intentional literals like
* `{{output-from-skill}}` in skills/ survive untouched. Guarded by
* `isBootstrapRenderDest` at write time.
*/
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { BOOTSTRAP_TEMPLATES, DERIVED_TOKENS, GITHUB_URL_PLACEHOLDER, loadQuestionBank, readTemplate } from './assets.ts';
import {
readManifest,
writeManifest,
FORMAT_VERSION,
TEMPLATE_PLACEHOLDER_MANIFEST,
type AgentManifest,
} from './format.ts';
import { readInterviewState, type InterviewState } from './interview.ts';
import { OPENCLAW_RENDER_NOTE, resolveRenderHost } from './render-host.ts';
// ---------------------------------------------------------------------------
// Errors
// ---------------------------------------------------------------------------
export class BootstrapRenderError extends Error {
code: string;
constructor(code: string, message: string) {
super(message);
this.name = 'BootstrapRenderError';
this.code = code;
}
}
export class UnresolvedTokenError extends BootstrapRenderError {
tokens: string[];
constructor(tokens: string[]) {
super(
'unresolved_tokens',
`render refused — unresolved template tokens (nothing was written): ${tokens.join(', ')}. ` +
`Answer the missing interview questions (gbrain bootstrap interview --status) and re-run.`
);
this.name = 'UnresolvedTokenError';
this.tokens = tokens;
}
}
// ---------------------------------------------------------------------------
// Public option/result types
// ---------------------------------------------------------------------------
export interface RenderOptions {
/** Overwrite existing dests (each overwritten file is backed up first). */
force?: boolean;
/** Render only these dests (exact BOOTSTRAP_TEMPLATES dest names, e.g.
* ['SOUL.md']). Unknown names throw. Partial renders never touch the
* manifest (a `render --only` on a template clone must not flip it to
* initialized). */
only?: string[];
/** Template-repo generator mode [D4]: all defaults, byte-deterministic. */
minimal?: boolean;
/** Values for DERIVED_TOKENS (GITHUB_REPO_URL, CORPUS_RETENTION_DAYS).
* Ignored in minimal mode (determinism). Missing entries use canonical
* fallbacks. */
derived?: Record<string, string>;
/** Recorded as agent.json `created_by` (the dispatcher passes the gbrain
* version). */
createdBy?: string;
/** Recorded as agent.json `source_id`. When unset, an existing initialized
* manifest's source_id is preserved; otherwise defaults to 'workspace'. */
sourceId?: string;
/** The harness the workspace belongs to (render-host.ts): 'openclaw' writes
* each template's `openclawDest` instead of its dest (HEARTBEAT.md →
* SCHEDULES.md, #7470), 'generic' never does, 'auto' (the default) detects.
* Ignored in minimal mode (determinism). An unknown value throws. */
host?: string;
}
export interface RenderResult {
/** Why the render used host-specific names, when it did. */
note?: string;
written: string[];
skipped: string[];
backups: string[];
}
/** Canonical fallbacks for DERIVED_TOKENS — also the exact values minimal
* mode always uses [CX2-14]. */
export const DERIVED_DEFAULTS: Record<(typeof DERIVED_TOKENS)[number], string> = {
GITHUB_REPO_URL: GITHUB_URL_PLACEHOLDER,
CORPUS_RETENTION_DAYS: '30',
SCHEDULES_FILE: 'HEARTBEAT.md',
};
const TOKEN_RE = /\{\{([A-Z0-9_]+)\}\}/g;
// ---------------------------------------------------------------------------
// Building blocks (exported for direct unit tests)
// ---------------------------------------------------------------------------
/** [ENG-10] The only paths the renderer may ever write, relative to the
* workspace root. Skillpack scaffolds, skills/, and anything else are out. */
export function isBootstrapRenderDest(relPath: string): boolean {
return BOOTSTRAP_TEMPLATES.some((t) => t.dest === relPath || t.openclawDest === relPath);
}
/**
* [S3#3] Structural-marker escape for interview-sourced values (see module
* doc). Applied at render time, per line, to answer values only — bank
* defaults are our own trusted copy.
*/
export function escapeStructuralMarkers(value: string): string {
return value
.split('\n')
.map((line) => line.replace(/^(\s{0,3})(#|<!--|```|~~~)/, '$1\\$2'))
.join('\n');
}
/** Collapse runs of 3+ blank lines to exactly 2 (4+ consecutive newlines →
* 3). Applied to final rendered content, so empty optional answers don't
* leave gaping holes. */
export function collapseBlankLines(content: string): string {
return content.replace(/\n{4,}/g, '\n\n\n');
}
/**
* Byte floors for `bootstrap verify`, scaled to how many interview questions
* were actually answered. Floors catch SKIPPED INTERVIEWS, never pressure
* invention: an all-defaults render passes the base floor; every answered
* question raises the bar toward the full-interview floor (D8: SOUL.md
* ≥3000B, USER.md ≥1000B at all 12 answered).
*
* Formula (documented contract):
* SOUL.md floor = 1500 + 125 × min(answeredCount, 12)
* USER.md floor = 400 + 50 × min(answeredCount, 12)
*/
export function byteFloors(answeredCount: number): { 'SOUL.md': number; 'USER.md': number } {
const n = Math.max(0, Math.min(Math.floor(answeredCount), 12));
return {
'SOUL.md': 1500 + 125 * n,
'USER.md': 400 + 50 * n,
};
}
// ---------------------------------------------------------------------------
// Token resolution
// ---------------------------------------------------------------------------
type Resolution =
| { kind: 'value'; value: string }
/** Minimal mode, key with no default: the literal token stays in the file
* on purpose (template-repo fill-me marker) and is NOT an error. */
| { kind: 'placeholder' }
| { kind: 'unresolved' };
function buildResolver(opts: RenderOptions, state: InterviewState | null, host: 'openclaw' | undefined): (token: string) => Resolution {
const bank = loadQuestionBank();
const minimal = opts.minimal === true;
const derivedSet = new Set<string>(DERIVED_TOKENS);
return (token: string): Resolution => {
if (derivedSet.has(token)) {
const canonical = DERIVED_DEFAULTS[token as (typeof DERIVED_TOKENS)[number]];
if (minimal) return { kind: 'value', value: canonical };
const supplied = opts.derived?.[token];
if (supplied !== undefined) return { kind: 'value', value: supplied };
if (token === 'SCHEDULES_FILE' && host === 'openclaw') {
return { kind: 'value', value: BOOTSTRAP_TEMPLATES.find((t) => t.dest === canonical)!.openclawDest! };
}
return { kind: 'value', value: canonical };
}
const spec = bank.questions[token];
if (!spec) return { kind: 'unresolved' };
if (!minimal && state) {
const a = state.answers[token];
if (a && a.skipped !== true) {
return { kind: 'value', value: escapeStructuralMarkers(a.value) };
}
}
if (spec.default !== undefined) return { kind: 'value', value: spec.default };
if (minimal) return { kind: 'placeholder' };
return { kind: 'unresolved' };
};
}
// ---------------------------------------------------------------------------
// renderWorkspace
// ---------------------------------------------------------------------------
export function renderWorkspace(workspaceDir: string, opts: RenderOptions = {}): RenderResult {
const minimal = opts.minimal === true;
// Minimal mode is the template-repo generator path: it lays placeholder
// content AND resets the manifest to `initialized: false`. On a LIVE
// (initialized) workspace that would demote a real install to a template
// clone — refuse unless the caller forces it (typed error, agent-readable).
if (minimal && !opts.force) {
const existing = readManifest(workspaceDir);
if (existing.state === 'initialized') {
throw new BootstrapRenderError(
'minimal_on_initialized',
'render --minimal refused: this workspace is already initialized (agent.json says initialized: true). ' +
'Minimal mode writes template placeholders and resets the manifest to an uninitialized template. ' +
'If you really mean to, re-run with --force (existing files are backed up first).'
);
}
}
const host = resolveRenderHost(workspaceDir, opts.host ?? 'auto', minimal);
if (host === null) {
throw new BootstrapRenderError('unknown_host', `unknown render host '${opts.host}': pass --host openclaw, generic or auto.`);
}
// Validate --only against the known dest list (typo protection).
const destFor = (t: (typeof BOOTSTRAP_TEMPLATES)[number]): string =>
!minimal && host === 'openclaw' && t.openclawDest ? t.openclawDest : t.dest;
const selected = BOOTSTRAP_TEMPLATES.filter(
(t) => !opts.only || opts.only.includes(t.dest) || (t.openclawDest !== undefined && opts.only.includes(t.openclawDest)),
);
if (opts.only) {
const known = new Set(BOOTSTRAP_TEMPLATES.flatMap((t) => (t.openclawDest ? [t.dest, t.openclawDest] : [t.dest])));
const unknown = opts.only.filter((o) => !known.has(o));
if (unknown.length > 0) {
throw new BootstrapRenderError(
'unknown_only',
`unknown render target(s): ${unknown.join(', ')}. Valid targets: ${[...known].join(', ')}.`
);
}
}
// Interview state feeds tokens only in non-minimal mode. A broken state
// file (conflict markers, invalid JSON) surfaces as an agent-readable
// error, never a SyntaxError [G12].
let state: InterviewState | null = null;
if (!minimal) {
const read = readInterviewState(workspaceDir);
if (!read.ok) throw new BootstrapRenderError(read.code, read.message);
state = read.state;
}
const resolve = buildResolver(opts, state, minimal ? undefined : host);
// Phase 1 — render everything in memory. Nothing is written until every
// selected file resolves cleanly (hard-fail lists ALL unresolved tokens).
const unresolved = new Set<string>();
const placeholders = new Set<string>();
const rendered: Array<{ dest: string; content: string }> = [];
for (const t of selected) {
const template = readTemplate(t);
// Function-form replace: replacement values are inserted verbatim —
// `$&`-style patterns in an answer are never re-interpreted, and
// set-time escaping guarantees a value cannot introduce a new token.
const out = template.replace(TOKEN_RE, (match, token: string) => {
const r = resolve(token);
if (r.kind === 'value') return r.value;
if (r.kind === 'placeholder') {
placeholders.add(token);
return match;
}
unresolved.add(token);
return match;
});
// Defensive final sweep: any surviving token that is not a deliberate
// minimal-mode placeholder is unresolved.
for (const m of out.matchAll(TOKEN_RE)) {
const token = m[1]!;
if (!placeholders.has(token)) unresolved.add(token);
}
rendered.push({ dest: destFor(t), content: collapseBlankLines(out) });
}
if (unresolved.size > 0) {
throw new UnresolvedTokenError([...unresolved].sort());
}
// Phase 2 — write, never clobbering without force [plan: render never
// clobbers]. Backups for a forced overwrite land under one per-run
// timestamp dir. The stamp has MILLISECOND granularity, so two forced
// renders of the same workspace within the same millisecond (a fast CI
// runner re-rendering back-to-back) would collide on the exclusive `wx`
// backup write with EEXIST. Claim the stamp dir ATOMICALLY (non-recursive
// mkdir; EEXIST → bump a numeric suffix) lazily on the first backup, so
// every render call owns a distinct backup dir.
const result: RenderResult = { ...(host && !minimal ? { note: OPENCLAW_RENDER_NOTE } : {}), written: [], skipped: [], backups: [] };
let backupStamp: string | null = null;
const claimBackupStamp = (): string => {
if (backupStamp) return backupStamp;
const root = join(workspaceDir, '.gbrain-bootstrap-backups');
mkdirSync(root, { recursive: true });
const base = new Date().toISOString().replace(/[:.]/g, '-');
for (let n = 0; ; n++) {
const candidate = n === 0 ? base : `${base}-${n}`;
try {
mkdirSync(join(root, candidate)); // non-recursive: EEXIST = taken
backupStamp = candidate;
return candidate;
} catch (e) {
if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e;
}
}
};
for (const { dest, content } of rendered) {
if (!isBootstrapRenderDest(dest)) {
// [ENG-10] Unreachable by construction (dests come from
// BOOTSTRAP_TEMPLATES), kept as the write-time guard so a future
// refactor can never point the renderer at scaffold paths.
throw new BootstrapRenderError('forbidden_dest', `refusing to render non-bootstrap path: ${dest}`);
}
const abs = join(workspaceDir, dest);
if (existsSync(abs)) {
if (!opts.force) {
result.skipped.push(dest);
continue;
}
const stamp = claimBackupStamp();
const backupAbs = join(workspaceDir, '.gbrain-bootstrap-backups', stamp, dest);
mkdirSync(dirname(backupAbs), { recursive: true });
writeFileSync(backupAbs, readFileSync(abs), { flag: 'wx' });
result.backups.push(join('.gbrain-bootstrap-backups', stamp, dest));
}
mkdirSync(dirname(abs), { recursive: true });
const tmp = `${abs}.tmp-${process.pid}`;
writeFileSync(tmp, content, 'utf8');
renameSync(tmp, abs);
result.written.push(dest);
}
// Phase 3 — manifest. Full renders only: a partial `--only` render must
// not flip a template clone to initialized (and must not invent a
// manifest). Minimal mode writes the canonical placeholder manifest
// (initialized: false, frozen timestamp) for byte determinism [CX2-14].
if (!opts.only) {
if (minimal) {
writeManifest(workspaceDir, TEMPLATE_PLACEHOLDER_MANIFEST);
} else {
const existing = readManifest(workspaceDir);
const priorCreatedAt =
existing.state === 'initialized' && typeof existing.manifest.created_at === 'string'
? existing.manifest.created_at
: null;
// Preserve a prior source_id (verify's collision resolution may have
// derived e.g. 'workspace-<hash>' and persisted it — a re-render must
// not silently reset it to the default).
const priorSourceId =
existing.state === 'initialized' &&
typeof existing.manifest.source_id === 'string' &&
existing.manifest.source_id.length > 0
? existing.manifest.source_id
: null;
const agentName = state?.answers['AGENT_NAME']?.value ?? '{{AGENT_NAME}}';
const manifest: AgentManifest = {
format_version: FORMAT_VERSION,
initialized: true,
agent_name: agentName,
created_by: opts.createdBy ?? 'gbrain',
created_at: priorCreatedAt ?? new Date().toISOString(),
source_id: opts.sourceId ?? priorSourceId ?? 'workspace',
};
writeManifest(workspaceDir, manifest);
}
}
return result;
}