Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Interview engine for `gbrain bootstrap interview` (library module — no CLI
* parsing; the dispatcher in src/commands/bootstrap/ calls these functions).
*
* State lives at `<workspace>/state/interview.json` (COMMITTED — identity
* source of truth, same sensitivity as the rendered USER.md; makes
* re-render-on-new-machine work). All writes are atomic (tmp + rename).
*
* Hardening carried from the plan (docs/designs/AGENT_BOOTSTRAP_PLAN.md):
* - [G12] Reads detect git conflict markers and return a typed,
* agent-readable error — never a thrown SyntaxError.
* - [G10] `setAnswer` enforces per-key maxLength / rejectValues / allowed
* lists, strips control characters, and escapes `{{` / `}}` at set time.
* THE ESCAPE (documented contract, relied on by render.ts and the
* unresolved-token sweep): every `{{` becomes `{ {` and every `}}` becomes
* `} }`, applied repeatedly until no adjacent brace pair remains. The
* renderer's token regex (`/\{\{([A-Z0-9_]+)\}\}/`) can never match the
* escaped form, the renderer never re-interprets it, and the post-render
* token sweep cannot trip on it.
* - [A8] Per-answer `set_at` provenance. `confirm` requires the hash of the
* exact answer set that was read back (`readBackHash`); any later
* setAnswer/skipAnswer invalidates a prior confirm (the `confirmed` block
* is cleared), so a single-batch set+confirm-without-readback cannot pass.
* - [CX2-13] Keys marked `persist: false` + `sink: 'config'` (PROVIDER_KEY)
* NEVER touch interview.json, never appear in hashes/provenance/logs or in
* error messages; `setAnswer` returns `{ sink: 'config', key }` and the
* caller routes the value through `routeProviderKeyToConfig` (the existing
* 0600 config-file API in src/core/config.ts).
*/
import { createHash } from 'node:crypto';
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { loadQuestionBank, type QuestionBank, type QuestionSpec } from './assets.ts';
import { configPath, loadConfigFileOnly, saveConfig, type GBrainConfig } from '../config.ts';
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
export interface InterviewAnswer {
value: string;
/** ISO timestamp of when this answer was set [A8]. */
set_at: string;
skipped?: boolean;
}
export interface InterviewState {
version: 1;
answers: Record<string, InterviewAnswer>;
/** Set by `confirm` after a successful read-back hash match [A8]. */
confirmed?: { hash: string; at: string };
}
export type InterviewErrorCode =
| 'conflict_markers'
| 'invalid_json'
| 'invalid_shape'
| 'newer_version'
| 'unknown_key'
| 'empty_value'
| 'too_long'
| 'rejected_value'
| 'not_allowed'
| 'required_key'
| 'incomplete'
| 'hash_mismatch'
| 'config_missing'
| 'unrecognized_key_shape'
| 'io_error';
/** Typed, agent-readable failure. `message` is safe to relay verbatim to the
* human — it never contains an answer value (secret-hygiene for sink keys). */
export interface InterviewError {
ok: false;
code: InterviewErrorCode;
message: string;
}
export interface InterviewStatus {
ok: true;
/** Required bank keys with no non-skipped answer. */
missingRequired: string[];
/** Keys with a non-skipped persisted answer, sorted. */
answered: string[];
/** Keys explicitly skipped, sorted. */
skipped: string[];
/** True when every required key is answered. */
complete: boolean;
/** True when a `confirmed` block exists AND its hash still matches the
* current answer set (a later setAnswer clears it, so this can only be
* true for the exact set that was read back). */
confirmed: boolean;
}
export interface ShowEntry {
key: string;
question?: string;
required: boolean;
answered: boolean;
skipped: boolean;
value?: string;
set_at?: string;
default?: string;
}
// ---------------------------------------------------------------------------
// State file plumbing
// ---------------------------------------------------------------------------
export function interviewStatePath(workspaceDir: string): string {
return join(workspaceDir, 'state', 'interview.json');
}
function freshState(): InterviewState {
return { version: 1, answers: {} };
}
/**
* Read + validate the state file. Never throws for expected failure modes:
* conflict markers [G12], invalid JSON, wrong shape, newer version — each
* returns a typed error whose message the agent can relay.
*/
export function readInterviewState(
workspaceDir: string
): { ok: true; state: InterviewState; exists: boolean } | InterviewError {
const path = interviewStatePath(workspaceDir);
if (!existsSync(path)) return { ok: true, state: freshState(), exists: false };
let raw: string;
try {
raw = readFileSync(path, 'utf8');
} catch (e) {
return { ok: false, code: 'io_error', message: `could not read ${path}: ${(e as Error).message}` };
}
if (raw.includes('<<<<<<<') || raw.includes('>>>>>>>')) {
return {
ok: false,
code: 'conflict_markers',
message:
`${path} contains git conflict markers — resolve the merge in state/interview.json ` +
`(keep the answer set the principal actually confirmed), then retry.`,
};
}
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch (e) {
return {
ok: false,
code: 'invalid_json',
message:
`${path} is not valid JSON (${(e as Error).message}). ` +
`Fix or delete the file, then re-run the interview (answers may need re-entry).`,
};
}
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
return { ok: false, code: 'invalid_shape', message: `${path} must contain a JSON object.` };
}
const s = parsed as Record<string, unknown>;
if (typeof s.version !== 'number') {
return { ok: false, code: 'invalid_shape', message: `${path} is missing a numeric "version" field.` };
}
if (s.version > 1) {
return {
ok: false,
code: 'newer_version',
message: `${path} has version ${s.version}, written by a newer gbrain — upgrade this binary before continuing.`,
};
}
if (typeof s.answers !== 'object' || s.answers === null || Array.isArray(s.answers)) {
return { ok: false, code: 'invalid_shape', message: `${path} is missing an "answers" object.` };
}
return { ok: true, state: s as unknown as InterviewState, exists: true };
}
/** Atomic write (tmp + rename) — a killed interview never leaves a torn file. */
function writeInterviewState(workspaceDir: string, state: InterviewState): void {
const path = interviewStatePath(workspaceDir);
mkdirSync(dirname(path), { recursive: true });
const tmp = `${path}.tmp-${process.pid}`;
writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
renameSync(tmp, path);
}
/** Create `<ws>/state/interview.json` if absent. Idempotent; refuses to
* clobber an existing-but-broken file (returns its typed read error). */
export function initState(
workspaceDir: string
): { ok: true; created: boolean; path: string } | InterviewError {
const read = readInterviewState(workspaceDir);
if (!read.ok) return read;
if (read.exists) return { ok: true, created: false, path: interviewStatePath(workspaceDir) };
try {
writeInterviewState(workspaceDir, freshState());
} catch (e) {
return { ok: false, code: 'io_error', message: `could not create interview state: ${(e as Error).message}` };
}
return { ok: true, created: true, path: interviewStatePath(workspaceDir) };
}
// ---------------------------------------------------------------------------
// Value sanitization [G10]
// ---------------------------------------------------------------------------
/**
* Set-time sanitization, in order:
* 1. Normalize CRLF/CR to LF.
* 2. Strip control characters except newline and tab.
* 3. Escape template braces: `{{` → `{ {` and `}}` → `} }`, repeated until
* stable (single-pass replace can leave adjacent pairs in runs like
* `{{{{`). See the module doc for why this escape is the contract.
* 4. Trim leading/trailing whitespace.
* Exported for direct unit testing.
*/
export function sanitizeAnswerValue(raw: string): string {
let v = raw.replace(/\r\n?/g, '\n');
// eslint-disable-next-line no-control-regex
v = v.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
while (v.includes('{{')) v = v.replaceAll('{{', '{ {');
while (v.includes('}}')) v = v.replaceAll('}}', '} }');
return v.trim();
}
function bankSpec(bank: QuestionBank, key: string): QuestionSpec | undefined {
return bank.questions[key];
}
function isConfigSink(spec: QuestionSpec): boolean {
return spec.persist === false && spec.sink === 'config';
}
function requiredKeys(bank: QuestionBank): string[] {
return bank.interviewKeys.filter((k) => bank.questions[k]?.required === true);
}
// ---------------------------------------------------------------------------
// setAnswer / skipAnswer
// ---------------------------------------------------------------------------
export type SetAnswerResult =
| { ok: true; sink: 'state'; key: string; value: string; invalidatedConfirmation?: boolean }
/** Config-sink keys [CX2-13]: nothing persisted here; the caller routes the
* value via `routeProviderKeyToConfig`. The value is deliberately NOT
* echoed back in this result. */
| { ok: true; sink: 'config'; key: string }
| InterviewError;
export function setAnswer(workspaceDir: string, key: string, rawValue: string): SetAnswerResult {
const bank = loadQuestionBank();
const spec = bankSpec(bank, key);
if (!spec) {
return {
ok: false,
code: 'unknown_key',
message: `"${key}" is not in the question bank. Known keys: ${Object.keys(bank.questions).sort().join(', ')}.`,
};
}
const value = sanitizeAnswerValue(rawValue);
if (value === '') {
return {
ok: false,
code: 'empty_value',
message: `"${key}" got an empty answer. To decline an optional question use skip; required questions need a real answer.`,
};
}
if (value.length > spec.maxLength) {
return {
ok: false,
code: 'too_long',
message:
`answer for "${key}" is ${value.length} characters after sanitization; the limit is ${spec.maxLength}. ` +
`Truncate it to the essential part (or split the overflow into a follow-up note) and set it again.`,
};
}
// Config-sink keys bypass everything below: no persistence, no hash
// membership, no value in the return or in any message [CX2-13].
if (isConfigSink(spec)) {
return { ok: true, sink: 'config', key };
}
if (spec.rejectValues && spec.rejectValues.includes(value.toLowerCase())) {
return {
ok: false,
code: 'rejected_value',
message: `"${value}" is a placeholder, not an answer for ${key}. Ask again for a real one (rejected: ${spec.rejectValues.filter((r) => r !== '').join(', ')}).`,
};
}
let stored = value;
if (spec.allowed) {
const match = spec.allowed.find((a) => a.toLowerCase() === value.toLowerCase());
if (!match) {
return {
ok: false,
code: 'not_allowed',
message: `"${key}" must be one of: ${spec.allowed.join(', ')}.`,
};
}
stored = match; // store the canonical spelling
}
const read = readInterviewState(workspaceDir);
if (!read.ok) return read;
const state = read.state;
state.answers[key] = { value: stored, set_at: new Date().toISOString() };
// Any change invalidates a prior read-back confirmation [A8]. Surfaced to
// the caller so the CLI can WARN — silently voiding the confirmation used
// to fail much later, at render, with no pointer back to this --set.
const invalidatedConfirmation = state.confirmed !== undefined;
delete state.confirmed;
try {
writeInterviewState(workspaceDir, state);
} catch (e) {
return { ok: false, code: 'io_error', message: `could not write interview state: ${(e as Error).message}` };
}
return { ok: true, sink: 'state', key, value: stored, invalidatedConfirmation };
}
export function skipAnswer(
workspaceDir: string,
key: string
): { ok: true; sink: 'state' | 'config'; key: string; skipped: true; invalidatedConfirmation?: boolean } | InterviewError {
const bank = loadQuestionBank();
const spec = bankSpec(bank, key);
if (!spec) {
return { ok: false, code: 'unknown_key', message: `"${key}" is not in the question bank.` };
}
if (spec.required === true) {
return {
ok: false,
code: 'required_key',
message: `"${key}" is required and cannot be skipped — the interview gate stays closed until it has a real answer.`,
};
}
// Config-sink keys persist nothing, including the skip [CX2-13].
if (isConfigSink(spec)) {
return { ok: true, sink: 'config', key, skipped: true };
}
const read = readInterviewState(workspaceDir);
if (!read.ok) return read;
const state = read.state;
state.answers[key] = { value: '', set_at: new Date().toISOString(), skipped: true };
// Same [A8] invalidation-surfacing as setAnswer.
const invalidatedConfirmation = state.confirmed !== undefined;
delete state.confirmed;
try {
writeInterviewState(workspaceDir, state);
} catch (e) {
return { ok: false, code: 'io_error', message: `could not write interview state: ${(e as Error).message}` };
}
return { ok: true, sink: 'state', key, skipped: true, invalidatedConfirmation };
}
// ---------------------------------------------------------------------------
// status / readBackHash / confirm / show
// ---------------------------------------------------------------------------
function answeredKeys(state: InterviewState): string[] {
return Object.keys(state.answers)
.filter((k) => state.answers[k] && state.answers[k]!.skipped !== true)
.sort();
}
export function status(workspaceDir: string): InterviewStatus | InterviewError {
const bank = loadQuestionBank();
const read = readInterviewState(workspaceDir);
if (!read.ok) return read;
const state = read.state;
const answered = answeredKeys(state);
const skipped = Object.keys(state.answers)
.filter((k) => state.answers[k]?.skipped === true)
.sort();
const missingRequired = requiredKeys(bank).filter((k) => !answered.includes(k));
const complete = missingRequired.length === 0;
let confirmed = false;
if (state.confirmed && complete) {
confirmed = state.confirmed.hash === computeHash(state);
}
return { ok: true, missingRequired, answered, skipped, complete, confirmed };
}
/** Stable hash over the sorted (key, value) pairs of every non-skipped
* persisted answer. Config-sink values can never appear here [CX2-13]. */
function computeHash(state: InterviewState): string {
const pairs = answeredKeys(state).map((k) => [k, state.answers[k]!.value]);
return createHash('sha256').update(JSON.stringify(pairs), 'utf8').digest('hex');
}
/**
* The hash of the exact answer set to read back to the human [A8]. Errors
* until every required key is answered — an incomplete set has nothing worth
* confirming. `confirm` only accepts this value, computed AFTER the final
* answer landed; setting any answer afterwards changes the hash.
*/
export function readBackHash(
workspaceDir: string
): { ok: true; hash: string; keys: string[] } | InterviewError {
const bank = loadQuestionBank();
const read = readInterviewState(workspaceDir);
if (!read.ok) return read;
const state = read.state;
const answered = answeredKeys(state);
const missing = requiredKeys(bank).filter((k) => !answered.includes(k));
if (missing.length > 0) {
return {
ok: false,
code: 'incomplete',
message: `cannot read back an incomplete interview — still missing required: ${missing.join(', ')}.`,
};
}
return { ok: true, hash: computeHash(state), keys: answered };
}
/**
* Record the principal's confirmation of the read-back [A8]. `providedHash`
* must equal the CURRENT `readBackHash` — confirming a set the human never
* saw (stale hash, guessed hash, answers changed since read-back) fails.
*/
export function confirm(
workspaceDir: string,
providedHash: string
): { ok: true; hash: string; at: string } | InterviewError {
const current = readBackHash(workspaceDir);
if (!current.ok) return current;
if (providedHash !== current.hash) {
return {
ok: false,
code: 'hash_mismatch',
message:
`confirmation hash does not match the current answer set. The answers changed since they were ` +
`read back (or were never read back). Read the full set back to the principal, then confirm ` +
`with the hash from that read-back.`,
};
}
const read = readInterviewState(workspaceDir);
if (!read.ok) return read;
const state = read.state;
const at = new Date().toISOString();
state.confirmed = { hash: current.hash, at };
try {
writeInterviewState(workspaceDir, state);
} catch (e) {
return { ok: false, code: 'io_error', message: `could not write interview state: ${(e as Error).message}` };
}
return { ok: true, hash: current.hash, at };
}
/**
* The read-back payload: one entry per interview key (question text, current
* answer/skip/default), plus any persisted consent answers, plus the
* confirmation hash when the required set is complete. The dispatcher renders
* this to the human and quotes `hash` for `confirm`.
*/
export function show(workspaceDir: string):
| { ok: true; entries: ShowEntry[]; extras: ShowEntry[]; hash?: string; confirmed: boolean }
| InterviewError {
const bank = loadQuestionBank();
const read = readInterviewState(workspaceDir);
if (!read.ok) return read;
const state = read.state;
const toEntry = (key: string): ShowEntry => {
const spec = bank.questions[key];
const a = state.answers[key];
return {
key,
question: spec?.question,
required: spec?.required === true,
answered: !!a && a.skipped !== true,
skipped: a?.skipped === true,
...(a && a.skipped !== true ? { value: a.value } : {}),
...(a ? { set_at: a.set_at } : {}),
...(spec?.default !== undefined ? { default: spec.default } : {}),
};
};
const entries = bank.interviewKeys.map(toEntry);
const extras = Object.keys(state.answers)
.filter((k) => !bank.interviewKeys.includes(k))
.sort()
.map(toEntry);
const st = status(workspaceDir);
if (!st.ok) return st;
const result: { ok: true; entries: ShowEntry[]; extras: ShowEntry[]; hash?: string; confirmed: boolean } = {
ok: true,
entries,
extras,
confirmed: st.confirmed,
};
if (st.complete) {
const h = readBackHash(workspaceDir);
if (h.ok) result.hash = h.hash;
}
return result;
}
// ---------------------------------------------------------------------------
// Config sink routing [CX2-13]
// ---------------------------------------------------------------------------
/** Provider detection by key shape. Order matters: `sk-ant-` and `sk-or-v1-` before `sk-`. */
const PROVIDER_KEY_SHAPES: Array<{ prefix: string; configKey: ProviderConfigKey; label: string }> = [
{ prefix: 'sk-ant-', configKey: 'anthropic_api_key', label: 'Anthropic (sk-ant-…)' },
{ prefix: 'sk-or-v1-', configKey: 'openrouter_api_key', label: 'OpenRouter (sk-or-v1-…)' },
{ prefix: 'sk-', configKey: 'openai_api_key', label: 'OpenAI (sk-…)' },
{ prefix: 'pa-', configKey: 'voyage_api_key', label: 'Voyage (pa-…)' },
];
export type ProviderConfigKey = 'anthropic_api_key' | 'openrouter_api_key' | 'openai_api_key' | 'voyage_api_key';
/**
* Route an interview-provided provider key to the 0600 config file — the ONLY
* legal destination for a `sink: 'config'` answer [CX2-13]. Reads the file
* plane only (`loadConfigFileOnly`) so env-merged values are never baked into
* the file, and writes through `saveConfig` (0600 + chmod + per-home
* .gitignore). Error messages NEVER contain the key material.
*/
export function routeProviderKeyToConfig(
rawValue: string
): { ok: true; configKey: ProviderConfigKey } | InterviewError {
const bank = loadQuestionBank();
const spec = bank.questions['PROVIDER_KEY'];
const maxLength = spec?.maxLength ?? 256;
const value = rawValue.trim();
if (value === '') {
return { ok: false, code: 'empty_value', message: 'no key provided — use skip to decline the provider-key question.' };
}
if (value.length > maxLength) {
return { ok: false, code: 'too_long', message: `provider key is ${value.length} characters; the limit is ${maxLength}. Check the paste.` };
}
if (/[\x00-\x1f\x7f\s]/.test(value)) {
return { ok: false, code: 'unrecognized_key_shape', message: 'provider key contains whitespace or control characters — check the paste.' };
}
const shape = PROVIDER_KEY_SHAPES.find((s) => value.startsWith(s.prefix));
if (!shape) {
return {
ok: false,
code: 'unrecognized_key_shape',
message: `key shape not recognized. Supported: ${PROVIDER_KEY_SHAPES.map((s) => s.label).join(', ')}.`,
};
}
const config = loadConfigFileOnly();
if (!config) {
return {
ok: false,
code: 'config_missing',
message: `no gbrain config found at ${configPath()} — run \`gbrain init\` first, then set the provider key again.`,
};
}
const next: GBrainConfig = { ...config, [shape.configKey]: value };
try {
saveConfig(next);
} catch (e) {
return { ok: false, code: 'io_error', message: `could not write config: ${(e as Error).message}` };
}
return { ok: true, configKey: shape.configKey };
}