Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Tests for src/core/bootstrap/interview.ts — the bootstrap interview engine.
*
* Pins the plan's interview hardening (docs/designs/AGENT_BOOTSTRAP_PLAN.md):
* - required-key gate data (status → missingRequired/complete)
* - skip refuses required keys
* - [G10] maxLength / rejectValues / allowed enforcement, control-char
* stripping, `{{`/`}}` set-time escaping
* - [G12] conflict-marker + invalid-JSON detection returns typed errors,
* never throws
* - [A8] confirm requires the hash of the exact set that was read back;
* single-batch set+confirm-without-readback fails; set_at provenance
* - [CX2-13] PROVIDER_KEY (persist:false, sink:'config') never lands in
* interview.json and never leaks through results or error messages
*/
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, existsSync, statSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import {
initState,
interviewStatePath,
readInterviewState,
setAnswer,
skipAnswer,
status,
readBackHash,
confirm,
show,
sanitizeAnswerValue,
routeProviderKeyToConfig,
} from '../src/core/bootstrap/interview.ts';
import { configPath } from '../src/core/config.ts';
const REQUIRED = [
'AGENT_NAME',
'PRINCIPAL_NAME',
'AGENT_PURPOSE',
'AGENT_TOP_JOBS',
'PRINCIPAL_CONTEXT',
'VOICE_REGISTER',
] as const;
const ANSWERS: Record<(typeof REQUIRED)[number], string> = {
AGENT_NAME: 'Trenton',
PRINCIPAL_NAME: 'Alice Example',
AGENT_PURPOSE: 'Maintain the research corpus and draft the weekly memo.',
AGENT_TOP_JOBS: '- corpus upkeep\n- weekly memo\n- meeting prep',
PRINCIPAL_CONTEXT: 'Runs a small research lab; ships a memo every Friday.',
VOICE_REGISTER: 'Direct. Three options, the second one wins.',
};
function makeWs(): string {
return mkdtempSync(join(tmpdir(), 'gbrain-interview-test-'));
}
function answerAllRequired(ws: string): void {
for (const key of REQUIRED) {
const r = setAnswer(ws, key, ANSWERS[key]);
expect(r.ok).toBe(true);
}
}
function expectErr(r: { ok: boolean }, code: string): asserts r is { ok: false; code: string; message: string } {
expect(r.ok).toBe(false);
expect((r as unknown as { code: string }).code).toBe(code);
}
describe('initState + readInterviewState', () => {
test('creates state/interview.json once, idempotently', () => {
const ws = makeWs();
const first = initState(ws);
expect(first.ok).toBe(true);
if (first.ok) expect(first.created).toBe(true);
const second = initState(ws);
expect(second.ok).toBe(true);
if (second.ok) expect(second.created).toBe(false);
const parsed = JSON.parse(readFileSync(interviewStatePath(ws), 'utf8'));
expect(parsed).toEqual({ version: 1, answers: {} });
});
test('missing file reads as a fresh empty state (exists: false)', () => {
const ws = makeWs();
const read = readInterviewState(ws);
expect(read.ok).toBe(true);
if (read.ok) {
expect(read.exists).toBe(false);
expect(read.state.answers).toEqual({});
}
});
test('[G12] git conflict markers → typed error with agent-readable message, no throw', () => {
const ws = makeWs();
mkdirSync(join(ws, 'state'), { recursive: true });
writeFileSync(
interviewStatePath(ws),
'<<<<<<< HEAD\n{"version":1,"answers":{}}\n=======\n{"version":1}\n>>>>>>> other\n'
);
const read = readInterviewState(ws);
expectErr(read, 'conflict_markers');
expect(read.message).toContain('resolve');
// status and setAnswer surface the same typed error and never clobber.
expectErr(status(ws), 'conflict_markers');
expectErr(setAnswer(ws, 'AGENT_NAME', 'Trenton'), 'conflict_markers');
expect(readFileSync(interviewStatePath(ws), 'utf8')).toContain('<<<<<<<');
});
test('[G12] invalid JSON → typed error, never a thrown SyntaxError', () => {
const ws = makeWs();
mkdirSync(join(ws, 'state'), { recursive: true });
writeFileSync(interviewStatePath(ws), 'this is not json');
const read = readInterviewState(ws);
expectErr(read, 'invalid_json');
expect(read.message).toContain('not valid JSON');
});
test('newer state version → typed error naming the upgrade path', () => {
const ws = makeWs();
mkdirSync(join(ws, 'state'), { recursive: true });
writeFileSync(interviewStatePath(ws), JSON.stringify({ version: 9, answers: {} }));
expectErr(readInterviewState(ws), 'newer_version');
});
});
describe('gate data (status)', () => {
test('fresh state: all 6 required missing, complete false', () => {
const ws = makeWs();
initState(ws);
const st = status(ws);
expect(st.ok).toBe(true);
if (st.ok) {
expect(st.missingRequired.sort()).toEqual([...REQUIRED].sort());
expect(st.answered).toEqual([]);
expect(st.complete).toBe(false);
expect(st.confirmed).toBe(false);
}
});
test('answering all required flips complete', () => {
const ws = makeWs();
answerAllRequired(ws);
const st = status(ws);
if (!st.ok) throw new Error(st.message);
expect(st.missingRequired).toEqual([]);
expect(st.complete).toBe(true);
expect(st.answered.sort()).toEqual([...REQUIRED].sort());
});
test('a skipped optional key counts as skipped, not answered', () => {
const ws = makeWs();
const r = skipAnswer(ws, 'SOUL_WINCE');
expect(r.ok).toBe(true);
const st = status(ws);
if (!st.ok) throw new Error(st.message);
expect(st.skipped).toEqual(['SOUL_WINCE']);
expect(st.answered).toEqual([]);
});
});
describe('skipAnswer', () => {
test('refuses required keys', () => {
const ws = makeWs();
for (const key of REQUIRED) {
const r = skipAnswer(ws, key);
expectErr(r, 'required_key');
expect(r.message).toContain(key);
}
});
test('optional skip persists skipped:true with provenance', () => {
const ws = makeWs();
const r = skipAnswer(ws, 'SOUL_WORLDVIEW');
expect(r.ok).toBe(true);
const parsed = JSON.parse(readFileSync(interviewStatePath(ws), 'utf8'));
expect(parsed.answers.SOUL_WORLDVIEW.skipped).toBe(true);
expect(Number.isNaN(Date.parse(parsed.answers.SOUL_WORLDVIEW.set_at))).toBe(false);
});
});
describe('[G10] setAnswer enforcement', () => {
test('unknown key → typed error', () => {
const ws = makeWs();
expectErr(setAnswer(ws, 'NOT_A_KEY', 'x'), 'unknown_key');
});
test('empty value → typed error suggesting skip', () => {
const ws = makeWs();
const r = setAnswer(ws, 'SOUL_WINCE', ' ');
expectErr(r, 'empty_value');
expect(r.message).toContain('skip');
});
test('maxLength rejected with a clear truncation message', () => {
const ws = makeWs();
const r = setAnswer(ws, 'AGENT_NAME', 'a'.repeat(65));
expectErr(r, 'too_long');
expect(r.message).toContain('64');
expect(r.message.toLowerCase()).toContain('truncate');
});
test('rejectValues blocks placeholder names, case-insensitively', () => {
const ws = makeWs();
for (const bad of ['agent', 'Agent', ' AI ', 'tbd']) {
expectErr(setAnswer(ws, 'AGENT_NAME', bad), 'rejected_value');
}
expect(setAnswer(ws, 'AGENT_NAME', 'Trenton').ok).toBe(true);
});
test('allowed list enforced for consent keys; canonical spelling stored', () => {
const ws = makeWs();
expectErr(setAnswer(ws, 'SEARCH_MODE', 'warp-speed'), 'not_allowed');
const r = setAnswer(ws, 'SEARCH_MODE', 'BALANCED');
expect(r.ok).toBe(true);
const parsed = JSON.parse(readFileSync(interviewStatePath(ws), 'utf8'));
expect(parsed.answers.SEARCH_MODE.value).toBe('balanced');
});
test('control characters stripped; CRLF normalized to LF', () => {
expect(sanitizeAnswerValue('hello\x07world\r\nnext\tkeep')).toBe('helloworld\nnext\tkeep');
});
test('{{ and }} escaped at set time — token regex can never match the stored value', () => {
const ws = makeWs();
const r = setAnswer(ws, 'VOICE_REGISTER', 'I use {{handlebars}} and {{{RUNS}}} daily');
expect(r.ok).toBe(true);
if (r.ok && r.sink === 'state') {
expect(r.value).not.toContain('{{');
expect(r.value).not.toContain('}}');
expect(r.value).toContain('{ {');
}
const raw = readFileSync(interviewStatePath(ws), 'utf8');
const stored = JSON.parse(raw).answers.VOICE_REGISTER.value as string;
expect(/\{\{/.test(stored)).toBe(false);
expect(/\}\}/.test(stored)).toBe(false);
});
test('brace runs converge (no adjacent pair survives repeated escaping)', () => {
const v = sanitizeAnswerValue('{{{{X}}}}');
expect(v).not.toContain('{{');
expect(v).not.toContain('}}');
});
});
describe('[A8] provenance + read-back confirm', () => {
test('every answer records a parseable set_at ISO timestamp', () => {
const ws = makeWs();
answerAllRequired(ws);
const parsed = JSON.parse(readFileSync(interviewStatePath(ws), 'utf8'));
for (const key of REQUIRED) {
const setAt = parsed.answers[key].set_at as string;
expect(Number.isNaN(Date.parse(setAt))).toBe(false);
expect(new Date(setAt).toISOString()).toBe(setAt);
}
});
test('readBackHash refuses an incomplete required set', () => {
const ws = makeWs();
setAnswer(ws, 'AGENT_NAME', 'Trenton');
const r = readBackHash(ws);
expectErr(r, 'incomplete');
expect(r.message).toContain('PRINCIPAL_NAME');
});
test('confirm with a wrong hash fails; with the current hash succeeds', () => {
const ws = makeWs();
answerAllRequired(ws);
expectErr(confirm(ws, 'deadbeef'), 'hash_mismatch');
const h = readBackHash(ws);
if (!h.ok) throw new Error(h.message);
const c = confirm(ws, h.hash);
expect(c.ok).toBe(true);
const st = status(ws);
if (!st.ok) throw new Error(st.message);
expect(st.confirmed).toBe(true);
});
test('HOSTILE: single-batch set+confirm without a fresh read-back fails', () => {
const ws = makeWs();
// The agent sets five answers, grabs a hash mid-stream, then sets the
// sixth and confirms with the stale hash — the human never saw the final
// set. Must fail.
for (const key of REQUIRED.slice(0, 5)) setAnswer(ws, key, ANSWERS[key]);
setAnswer(ws, 'SOUL_WINCE', 'Filler openers.');
// Not even computable pre-completion for the required set — but simulate
// the closest attack: complete the set, hash, then change an answer.
setAnswer(ws, REQUIRED[5], ANSWERS[REQUIRED[5]]);
const stale = readBackHash(ws);
if (!stale.ok) throw new Error(stale.message);
setAnswer(ws, 'SOUL_WINCE', 'Actually: hedging.'); // set AFTER the read-back
expectErr(confirm(ws, stale.hash), 'hash_mismatch');
// Only the hash of the exact current set — computed AFTER all answers —
// is accepted.
const fresh = readBackHash(ws);
if (!fresh.ok) throw new Error(fresh.message);
expect(confirm(ws, fresh.hash).ok).toBe(true);
});
test('any later setAnswer or skipAnswer invalidates a prior confirm', () => {
const ws = makeWs();
answerAllRequired(ws);
const h = readBackHash(ws);
if (!h.ok) throw new Error(h.message);
confirm(ws, h.hash);
setAnswer(ws, 'SOUL_GOOD_OUTPUT', 'A finished artifact.');
const st = status(ws);
if (!st.ok) throw new Error(st.message);
expect(st.confirmed).toBe(false);
const parsed = JSON.parse(readFileSync(interviewStatePath(ws), 'utf8'));
expect(parsed.confirmed).toBeUndefined();
});
test('setAnswer surfaces invalidatedConfirmation ONLY when a confirm existed', () => {
const ws = makeWs();
answerAllRequired(ws);
// No prior confirmation → nothing was invalidated (falsy flag).
const r0 = setAnswer(ws, 'SOUL_WINCE', 'Filler openers.');
expect(r0.ok).toBe(true);
if (!r0.ok || r0.sink !== 'state') throw new Error('expected a state-sink result');
expect(r0.invalidatedConfirmation).toBeFalsy();
// Full confirm, then a later set → the result SAYS it voided the confirm
// (the CLI warns at --set time instead of failing much later at render).
const h = readBackHash(ws);
if (!h.ok) throw new Error(h.message);
expect(confirm(ws, h.hash).ok).toBe(true);
const r1 = setAnswer(ws, 'SOUL_GOOD_OUTPUT', 'A finished artifact.');
expect(r1.ok).toBe(true);
if (!r1.ok || r1.sink !== 'state') throw new Error('expected a state-sink result');
expect(r1.invalidatedConfirmation).toBe(true);
const st = status(ws);
if (!st.ok) throw new Error(st.message);
expect(st.confirmed).toBe(false);
});
test('skipAnswer surfaces invalidatedConfirmation ONLY when a confirm existed (optional key — required keys refuse skip)', () => {
const ws = makeWs();
answerAllRequired(ws);
// No prior confirmation → falsy flag on an optional-key skip.
const r0 = skipAnswer(ws, 'SOUL_WINCE');
expect(r0.ok).toBe(true);
if (!r0.ok) throw new Error('unreachable');
expect(r0.invalidatedConfirmation).toBeFalsy();
// Full confirm, then a later optional-key skip → invalidation surfaced.
const h = readBackHash(ws);
if (!h.ok) throw new Error(h.message);
expect(confirm(ws, h.hash).ok).toBe(true);
const r1 = skipAnswer(ws, 'SOUL_WORLDVIEW');
expect(r1.ok).toBe(true);
if (!r1.ok) throw new Error('unreachable');
expect(r1.invalidatedConfirmation).toBe(true);
const st = status(ws);
if (!st.ok) throw new Error(st.message);
expect(st.confirmed).toBe(false);
});
test('show returns the read-back payload with the hash once complete', () => {
const ws = makeWs();
answerAllRequired(ws);
setAnswer(ws, 'SEARCH_MODE', 'balanced');
const s = show(ws);
if (!s.ok) throw new Error(s.message);
expect(s.entries.length).toBe(12); // the 12 interview keys
const name = s.entries.find((e) => e.key === 'AGENT_NAME');
expect(name?.value).toBe('Trenton');
expect(name?.required).toBe(true);
expect(s.extras.map((e) => e.key)).toEqual(['SEARCH_MODE']);
const h = readBackHash(ws);
if (!h.ok) throw new Error(h.message);
expect(s.hash).toBe(h.hash);
});
});
describe('[CX2-13] PROVIDER_KEY never lands in interview.json', () => {
test('setAnswer returns the config sink and persists NOTHING', () => {
const ws = makeWs();
setAnswer(ws, 'AGENT_NAME', 'Trenton'); // ensure the state file exists
const before = readFileSync(interviewStatePath(ws), 'utf8');
const r = setAnswer(ws, 'PROVIDER_KEY', 'sk-ant-supersecret-123456');
expect(r.ok).toBe(true);
if (r.ok) {
expect(r.sink).toBe('config');
expect(r.key).toBe('PROVIDER_KEY');
}
// The value appears NOWHERE in the result object.
expect(JSON.stringify(r)).not.toContain('supersecret');
// The state file is byte-identical: no PROVIDER_KEY entry, no secret.
const after = readFileSync(interviewStatePath(ws), 'utf8');
expect(after).toBe(before);
expect(after).not.toContain('PROVIDER_KEY');
expect(after).not.toContain('supersecret');
});
test('skip on PROVIDER_KEY persists nothing either', () => {
const ws = makeWs();
setAnswer(ws, 'AGENT_NAME', 'Trenton');
const before = readFileSync(interviewStatePath(ws), 'utf8');
const r = skipAnswer(ws, 'PROVIDER_KEY');
expect(r.ok).toBe(true);
expect(readFileSync(interviewStatePath(ws), 'utf8')).toBe(before);
});
test('too-long provider key error never echoes the value', () => {
const ws = makeWs();
const secret = `sk-${'a'.repeat(300)}`;
const r = setAnswer(ws, 'PROVIDER_KEY', secret);
expectErr(r, 'too_long');
expect(r.message).not.toContain(secret);
expect(r.message).not.toContain('aaaa');
});
test('PROVIDER_KEY does not participate in the read-back hash', () => {
const ws = makeWs();
answerAllRequired(ws);
const h1 = readBackHash(ws);
if (!h1.ok) throw new Error(h1.message);
confirm(ws, h1.hash);
setAnswer(ws, 'PROVIDER_KEY', 'sk-ant-supersecret-123456');
const h2 = readBackHash(ws);
if (!h2.ok) throw new Error(h2.message);
expect(h2.hash).toBe(h1.hash); // sink answers are hash-invisible
const st = status(ws);
if (!st.ok) throw new Error(st.message);
expect(st.confirmed).toBe(true); // and don't invalidate the confirm
});
});
describe('routeProviderKeyToConfig (0600 config sink)', () => {
let home: string;
let prevHome: string | undefined;
beforeEach(() => {
home = mkdtempSync(join(tmpdir(), 'gbrain-interview-home-'));
prevHome = process.env.GBRAIN_HOME;
process.env.GBRAIN_HOME = home;
});
afterEach(() => {
if (prevHome === undefined) delete process.env.GBRAIN_HOME;
else process.env.GBRAIN_HOME = prevHome;
rmSync(home, { recursive: true, force: true });
});
function seedConfig(): void {
mkdirSync(join(home, '.gbrain'), { recursive: true });
writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite' }));
}
test('routes each provider prefix to its config key, mode 0600', () => {
seedConfig();
const cases: Array<[string, string]> = [
['sk-ant-abc123', 'anthropic_api_key'],
['sk-plainopenai456', 'openai_api_key'],
['pa-voyage789', 'voyage_api_key'],
];
for (const [key, configKey] of cases) {
const r = routeProviderKeyToConfig(key);
expect(r.ok).toBe(true);
if (r.ok) expect(r.configKey).toBe(configKey as typeof r.configKey);
const cfg = JSON.parse(readFileSync(configPath(), 'utf8'));
expect(cfg[configKey]).toBe(key);
}
expect(statSync(configPath()).mode & 0o777).toBe(0o600);
});
test('an OpenRouter key (sk-or-v1-) is saved as openrouter_api_key, never openai_api_key (#7977)', () => {
seedConfig();
const key = `sk-or-v1-${'a1'.repeat(32)}`;
const r = routeProviderKeyToConfig(key);
expect(r.ok).toBe(true);
if (r.ok) expect(r.configKey).toBe('openrouter_api_key');
const cfg = JSON.parse(readFileSync(configPath(), 'utf8'));
expect(cfg.openrouter_api_key).toBe(key);
expect(cfg.openai_api_key).toBeUndefined();
});
test('unrecognized key shape → error that never echoes the value', () => {
seedConfig();
const r = routeProviderKeyToConfig('xoxb-not-a-supported-provider');
expectErr(r, 'unrecognized_key_shape');
expect(r.message).not.toContain('xoxb');
});
test('missing config → agent-readable "run gbrain init first" error', () => {
const r = routeProviderKeyToConfig('sk-ant-abc123');
expectErr(r, 'config_missing');
expect(r.message).toContain('gbrain init');
expect(existsSync(configPath())).toBe(false);
});
});