Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
tests: per-turn hook on every install path and its loud failure; print is not a failure
garrytanc978d17601d6
diff --git a/src/commands/setup.ts b/src/commands/setup.tsindex d4e10e08b6..46fd533d61 100644--- a/src/commands/setup.ts+++ b/src/commands/setup.ts@@ -27,7 +27,7 @@ import { dirname, join } from 'node:path';import { removeHermesTurnHook, syncHermesTurnHook } from '../core/setup/hermes-turn-hook.ts';import { removeOpenclawTurnPlugin, syncOpenclawTurnPlugin } from '../core/setup/openclaw-turn-plugin.ts';import { isTurnRuleHarness, removeTurnRuleHook, syncTurnRuleHook, type TurnHookOutcome, type TurnRuleHarness } from '../core/setup/turn-hook.ts';-import { inspectTurnHook, turnHookFix, verifyTurnHook, type TurnHookVerdict } from '../core/setup/turn-hook-check.ts';+import { inspectTurnHook, TURN_HOOK_NATIVE_INSPECT, turnHookFix, verifyTurnHook, type TurnHookVerdict } from '../core/setup/turn-hook-check.ts';import { opError, OperationError } from '../core/ops/contract.ts';import { cliRenderContext, renderCliError, renderNotice, type Action, type Notice } from '../core/agent-output.ts';import { writeCliNotices } from '../core/interop-notices.ts';@@ -792,7 +792,7 @@ function turnRuleHookFor(harness: TurnRuleHarness, off: boolean, flags: SetupFlafunction turnHookNotLoaded(harness: string, check: TurnHookVerdict, rerun: string[]): OperationError {const fix = turnHookFix(harness, rerun);- return opError('turn_hook_not_loaded', `The per-turn gbrain hook for ${harness} is not active: ${check.message}.`, fix.why, { reason: check.reason, docs: 'docs/guides/repair.md#turn-hook-not-loaded', fix });+ return opError('turn_hook_not_loaded', `The per-turn gbrain hook for ${harness} is not active: ${check.message}.${TURN_HOOK_NATIVE_INSPECT[harness] ? ` The harness's own check: ${TURN_HOOK_NATIVE_INSPECT[harness]}.` : ''}`, fix.why, { reason: check.reason, docs: 'docs/guides/repair.md#turn-hook-not-loaded', fix });}async function finish(out: Out, doc: {diff --git a/src/core/setup/turn-hook-check.ts b/src/core/setup/turn-hook-check.tsindex 52f4fd557e..9a82a0bf48 100644--- a/src/core/setup/turn-hook-check.ts+++ b/src/core/setup/turn-hook-check.ts@@ -137,7 +137,7 @@ export function verifyTurnHook(harness: string, opts: { projectDir?: string; runif (state.via === 'plugin') return { ok: true, state, reason: 'plugin_lane', message: `${state.detail}; check it with ${state.native_inspect}` };if ((harness === 'claude-code' || harness === 'codex') && state.command) {const r = run(['sh', '-c', state.command], JSON.stringify({ hook_event_name: 'UserPromptSubmit', prompt: '', session_id: 'gbrain-install-check' }));- if (!r.ok) return fail('hook_failed', `the UserPromptSubmit hook exited non-zero (${r.output.trim().split('\n').at(-1) ?? 'no output'})`);+ if (!r.ok) return fail('hook_failed', `the UserPromptSubmit hook exited non-zero (${r.output.trim().split('\n').at(-1) || 'no output'})`);if (!r.output.includes('GBrain: before answering')) return fail('no_rule', 'the UserPromptSubmit hook ran but did not add the brain-first rule (is the brain-first block installed for this harness?)');return { ok: true, state, reason: 'ran', message: `${state.detail}; it ran and added the rule` };}@@ -192,6 +192,7 @@ export function installerTurnHook(opts: { harness: string; accepted: boolean; gbconst outcome = carried && carried.state !== 'missing' && carried.via !== 'turn-rule'? { harness, action: 'skip' as const, path: '', detail: `per-turn rule already carried: ${carried.detail}` }: syncTurnRuleHook({ harness, gbrainBin: opts.gbrainBin, gbrainHome: opts.gbrainHome, paths: opts.paths, rerun: opts.rerun });- if (outcome.action === 'print') return { outcome, verdict: { ok: false, state: { harness, state: 'missing', detail: outcome.detail }, reason: 'missing', message: outcome.detail } };+ // Nothing was installed and the outcome names the step that does it: reported, never a failed install.+ if (outcome.action === 'print') return { outcome, verdict: null };return { outcome, verdict: opts.verify === false || opts.paths ? null : verifyTurnHook(harness) };}diff --git a/test/bootstrap-harness.serial.test.ts b/test/bootstrap-harness.serial.test.tsindex 6fc9bf9acf..941c69f9dd 100644--- a/test/bootstrap-harness.serial.test.ts+++ b/test/bootstrap-harness.serial.test.ts@@ -486,6 +486,18 @@ describe('full apply', () => {expect(readFileSync(join(dirname(g.codexConfig), 'hooks.json'), 'utf8')).toContain('hook session-end --harness codex');});+ test('codex lane wires the per-turn rule hook, trusted, beside the brain-first block; the consent block names it', async () => {+ const f = makeFake();+ expect(await applyHarness(flags(['--harness', 'codex']), f.deps)).toBe(0);+ expect(f.out.join('\n')).toContain('The per-turn brain-first rule hook (UserPromptSubmit');+ const hooks = readFileSync(join(dirname(f.codexConfig), 'hooks.json'), 'utf8');+ expect(hooks).toContain('GBRAIN_HOOK_LANE=turn-rule');+ expect(hooks).toContain('hook user-prompt');+ expect(readFileSync(f.codexConfig, 'utf8')).toContain('user_prompt_submit');+ expect(await removeHarness(flags(['--remove', '--harness', 'codex']), f.deps)).toBe(0);+ expect(existsSync(join(dirname(f.codexConfig), 'hooks.json')) ? readFileSync(join(dirname(f.codexConfig), 'hooks.json'), 'utf8') : '').not.toContain('GBRAIN_HOOK_LANE=turn-rule');+ });+test('--project must exist [F4]', async () => {const f = makeFake();const code = await applyHarness(flags(['--project', '/definitely/not/a/dir']), f.deps);diff --git a/test/connect.test.ts b/test/connect.test.tsindex 9a40ce5ed3..d32e2e5374 100644--- a/test/connect.test.ts+++ b/test/connect.test.ts@@ -538,6 +538,16 @@ describe('runConnect --install', () => {expect(all).toContain(REDACTED);});+ test('a per-turn hook that does not load fails the install loudly (turn_hook_not_loaded)', async () => {+ const r = await runWithExitCapture(+ ['https://brain.example.com/mcp', '--token', 'gbrain_tok', '--install', '--yes'],+ installDeps({ writeTurnHook: () => ({ lines: ['error turn_hook_not_loaded (hook_failed): the per-turn gbrain hook is not active'], ok: false }) }),+ );+ expect(r.exitCode).toBe(1);+ expect(r.err.join('\n')).toContain('turn_hook_not_loaded');+ expect(r.err.join('\n')).toMatch(/Verified/);+ });+test('missing claude binary fails fast', async () => {const r = await runWithExitCapture(['https://brain.example.com/mcp', '--token', 'tok', '--install', '--yes'],diff --git a/test/turn-hook-install-paths.test.ts b/test/turn-hook-install-paths.test.tsnew file mode 100644index 0000000000..cd8c93ea90--- /dev/null+++ b/test/turn-hook-install-paths.test.ts@@ -0,0 +1,193 @@+/**+ * The per-turn rule hook on every install path (src/core/setup/turn-hook.ts,+ * turn-hook-check.ts), and the loud failure when it cannot load:+ * - setup <claude-code|codex> --instructions-only (a plain `mcp add`) writes the+ * turn-rule hook, runs it once and exits 0; a hook that fails or adds no rule+ * exits 1 with turn_hook_not_loaded; with no absolute binary it prints the step;+ * - the installer lanes (connect --install, the hosted harness install,+ * bootstrap harness) share installerTurnHook;+ * - OpenClaw and Hermes verify through their own inspect commands.+ * Spawns `bun src/cli.ts setup` against a temp HOME / GBRAIN_HOME.+ */+import { afterAll, describe, expect, test } from 'bun:test';+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import { runCli } from './helpers/cli-spawn.ts';+import { withEnv } from './helpers/with-env.ts';+import { installerTurnHook, verifyTurnHook } from '../src/core/setup/turn-hook-check.ts';+import { TURN_RULE_LANE_TOKEN, TURN_RULE_MARKER } from '../src/core/setup/turn-hook.ts';+import { syncHermesTurnHook } from '../src/core/setup/hermes-turn-hook.ts';+import { openclawTurnPluginDir, openclawTurnPluginFiles } from '../src/core/setup/openclaw-turn-plugin.ts';++const CLI = resolve(import.meta.dir, '..', 'src', 'cli.ts');+const roots: string[] = [];+afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true }); });++function box() {+ const root = mkdtempSync(join(tmpdir(), 'gbrain-turn-hook-'));+ roots.push(root);+ const home = join(root, 'home');+ const project = join(root, 'project');+ mkdirSync(home, { recursive: true });+ mkdirSync(project, { recursive: true });+ mkdirSync(join(root, 'bin'));+ const script = (name: string, body: string) => { const p = join(root, 'bin', name); writeFileSync(p, `#!/bin/sh\n${body}\n`); chmodSync(p, 0o755); return p; };+ const bin = script('gbrain', `exec '${process.execPath}' --no-env-file '${CLI}' "$@"`);+ const env: Record<string, string | undefined> = {+ HOME: home, GBRAIN_HOME: home, PATH: '/usr/bin:/bin', CLAUDE_CONFIG_DIR: undefined, CODEX_HOME: undefined, XDG_CONFIG_HOME: undefined,+ OPENCLAW_STATE_DIR: undefined, OPENCLAW_WORKSPACE_DIR: undefined, OPENCLAW_PROFILE: undefined, OPENCLAW_CONFIG_PATH: undefined, HERMES_HOME: undefined,+ GBRAIN_AGENT_INSTRUCTIONS: undefined, GBRAIN_SURFACE: undefined, GBRAIN_SOURCE: undefined, GBRAIN_HOOKS: undefined, GBRAIN_HOOK_LANE: undefined,+ CLAUDECODE: undefined, CLAUDE_CODE_ENTRYPOINT: undefined, CODEX_SANDBOX: undefined, CODEX_CI: undefined,+ };+ return { root, home, project, bin, script, env };+}+type Box = ReturnType<typeof box>;++async function setup(b: Box, args: string[]) {+ const r = await runCli(['setup', ...args], { env: b.env, cwd: b.project });+ let doc: any = null;+ try { doc = JSON.parse(r.stdout); } catch { doc = null; }+ return { ...r, doc };+}+const readJson = (p: string) => JSON.parse(readFileSync(p, 'utf8'));+const claudePromptEntries = (b: Box) => (readJson(join(b.home, '.claude', 'settings.json')).hooks?.UserPromptSubmit ?? []).flatMap((g: any) => g.hooks);++describe('setup --instructions-only after a plain mcp add', () => {+ test('claude-code: writes the turn-rule hook, runs it and passes; a re-run keeps one entry', async () => {+ const b = box();+ const r = await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', b.bin, '--json']);+ expect(r.exitCode).toBe(0);+ expect(r.doc.turn_hook).toMatchObject({ harness: 'claude-code', action: 'write' });+ expect(r.doc.turn_hook_check).toMatchObject({ ok: true, reason: 'ran' });+ const entries = claudePromptEntries(b);+ expect(entries).toEqual([expect.objectContaining({ _gbrain: TURN_RULE_MARKER })]);+ expect(entries[0].command).toContain(TURN_RULE_LANE_TOKEN);+ expect(entries[0].command).toContain(`${b.bin} hook user-prompt`);+ expect((await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', b.bin, '--json'])).exitCode).toBe(0);+ expect(claudePromptEntries(b)).toHaveLength(1);+ });++ test('codex: writes the hooks.json group and its config.toml trust entry, runs it and passes', async () => {+ const b = box();+ const r = await setup(b, ['codex', '--instructions-only', '--gbrain-bin', b.bin, '--json']);+ expect(r.exitCode).toBe(0);+ expect(r.doc.turn_hook_check).toMatchObject({ ok: true, reason: 'ran' });+ expect(readFileSync(join(b.home, '.codex', 'hooks.json'), 'utf8')).toContain(TURN_RULE_LANE_TOKEN);+ expect(readFileSync(join(b.home, '.codex', 'config.toml'), 'utf8')).toContain('user_prompt_submit');+ });++ test('a hook that fails to run exits 1 with turn_hook_not_loaded and names the native check', async () => {+ const b = box();+ const broken = b.script('gbrain-broken', 'exit 3');+ const json = await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', broken, '--json']);+ expect(json.exitCode).toBe(1);+ expect(json.doc.turn_hook_check).toMatchObject({ ok: false, reason: 'hook_failed' });+ const text = await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', broken]);+ expect(text.exitCode).toBe(1);+ expect(text.stderr + text.stdout).toContain('turn_hook_not_loaded');+ expect(text.stderr + text.stdout).toContain("The harness's own check: /hooks (inside a Claude Code session).");+ expect(text.stderr + text.stdout).toContain('exited non-zero (no output)');+ });++ test('a hook that runs but adds no rule exits 1 (no_rule)', async () => {+ const b = box();+ const silent = b.script('gbrain-silent', 'exit 0');+ const r = await setup(b, ['codex', '--instructions-only', '--gbrain-bin', silent, '--json']);+ expect(r.exitCode).toBe(1);+ expect(r.doc.turn_hook_check).toMatchObject({ ok: false, reason: 'no_rule' });+ });++ test('no absolute gbrain binary: nothing is installed, the one-line next step is printed, exit 0', async () => {+ const b = box();+ const r = await setup(b, ['claude-code', '--instructions-only', '--json']);+ expect(r.exitCode).toBe(0);+ expect(r.doc.turn_hook).toMatchObject({ action: 'print', next: 'gbrain setup claude-code --instructions-only' });+ expect(r.doc.turn_hook_check).toBeUndefined();+ expect(existsSync(join(b.home, '.claude', 'settings.json'))).toBe(false);+ });++ test('--no-instructions removes the turn-rule hook with the block', async () => {+ const b = box();+ await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', b.bin, '--json']);+ expect(claudePromptEntries(b)).toHaveLength(1);+ expect((await setup(b, ['claude-code', '--instructions-only', '--no-instructions', '--json'])).exitCode).toBe(0);+ expect(claudePromptEntries(b)).toHaveLength(0);+ });+});++describe('installer lanes (connect --install, hosted harness install, bootstrap harness)', () => {+ test('installerTurnHook writes the hook beside a pointed-at config, removes it on decline, and never fails a print', async () => {+ const b = box();+ const paths = { claudeSettings: join(b.root, 'cfg', 'settings.json') };+ await withEnv(b.env, async () => {+ const wrote = installerTurnHook({ harness: 'claude-code', accepted: true, gbrainBin: b.bin, paths, rerun: 'gbrain setup claude-code --instructions-only' });+ expect(wrote.outcome.action).toBe('write');+ expect(readFileSync(paths.claudeSettings, 'utf8')).toContain(TURN_RULE_LANE_TOKEN);+ expect(installerTurnHook({ harness: 'claude-code', accepted: false, gbrainBin: b.bin, paths, rerun: '' }).outcome.action).toBe('remove');+ expect(readFileSync(paths.claudeSettings, 'utf8')).not.toContain(TURN_RULE_LANE_TOKEN);+ const printed = installerTurnHook({ harness: 'codex', accepted: true, gbrainBin: null, rerun: 'gbrain setup codex --instructions-only' });+ expect(printed.outcome).toMatchObject({ action: 'print', next: 'gbrain setup codex --instructions-only' });+ expect(printed.verdict).toBeNull();+ expect(installerTurnHook({ harness: 'opencode', accepted: true, gbrainBin: b.bin, rerun: '' }).outcome.action).toBe('skip');+ });+ });++ test('a written hook that does not load fails the install with a verdict (default paths)', async () => {+ const b = box();+ const broken = b.script('gbrain-broken', 'exit 3');+ await withEnv(b.env, async () => {+ const r = installerTurnHook({ harness: 'claude-code', accepted: true, gbrainBin: broken, rerun: 'gbrain setup claude-code --instructions-only' });+ expect(r.outcome.action).toBe('write');+ expect(r.verdict).toMatchObject({ ok: false, reason: 'hook_failed' });+ });+ });+});++describe('OpenClaw and Hermes verify with their own inspect commands', () => {+ const access = { kind: 'mcp', server: 'gbrain' } as const;++ function openclaw(b: Box, entry: Record<string, unknown>) {+ const state = join(b.root, 'openclaw');+ const env = { ...b.env, OPENCLAW_STATE_DIR: state };+ return withEnv(env, async () => {+ const dir = openclawTurnPluginDir();+ mkdirSync(dir, { recursive: true });+ for (const [name, body] of Object.entries(openclawTurnPluginFiles(access))) writeFileSync(join(dir, name), body);+ writeFileSync(join(state, 'openclaw.json'), JSON.stringify({ plugins: { entries: { 'gbrain-turn-rule': entry } } }));+ }).then(() => env);+ }++ test('openclaw: loaded with before_prompt_build passes; an error status fails not_loaded; no allowConversationAccess is untrusted', async () => {+ const b = box();+ const env = await openclaw(b, { enabled: true, hooks: { allowConversationAccess: true } });+ const which = () => '/usr/local/bin/openclaw';+ await withEnv(env, async () => {+ const seen: string[][] = [];+ const loaded = verifyTurnHook('openclaw', { which, run: (argv) => { seen.push(argv); return { ok: true, output: '{"id":"gbrain-turn-rule","status":"loaded","imported":true,"hooks":["before_prompt_build"]}' }; } });+ expect(loaded).toMatchObject({ ok: true, reason: 'ran' });+ expect(seen[0]).toEqual(['/usr/local/bin/openclaw', 'plugins', 'inspect', 'gbrain-turn-rule', '--runtime', '--json']);+ expect(verifyTurnHook('openclaw', { which, run: () => ({ ok: true, output: '{"id":"gbrain-turn-rule","status":"error","hooks":["before_prompt_build"]}' }) })).toMatchObject({ ok: false, reason: 'not_loaded' });+ });+ const untrusted = await openclaw(box(), { enabled: true });+ await withEnv(untrusted, async () => {+ expect(verifyTurnHook('openclaw', { which, run: () => ({ ok: true, output: '' }) })).toMatchObject({ ok: false, reason: 'untrusted' });+ });+ });++ test('hermes: a healthy hooks doctor block passes; a ✗ line fails not_loaded', async () => {+ const b = box();+ const hermesHome = join(b.root, 'hermes');+ mkdirSync(hermesHome, { recursive: true });+ writeFileSync(join(hermesHome, 'SOUL.md'), 'You are a careful assistant.\n');+ const env = { ...b.env, HERMES_HOME: hermesHome };+ await withEnv(env, async () => {+ expect(syncHermesTurnHook({ hermesHome, access, dryRun: false }).action).toBe('write');+ const which = () => '/usr/local/bin/hermes';+ const doctor = (mark: string) => () => ({ ok: true, output: `Shell hooks\n [pre_llm_call] /bin/echo '{"context":"GBrain: before answering this turn"}'\n ${mark}\n [post_tool_call] /bin/true\n ✓ allowlisted\n` });+ expect(verifyTurnHook('hermes', { which, run: doctor('✓ allowlisted, script present') })).toMatchObject({ ok: true, reason: 'ran' });+ expect(verifyTurnHook('hermes', { which, run: doctor('✗ not allowlisted') })).toMatchObject({ ok: false, reason: 'not_loaded' });+ expect(verifyTurnHook('hermes', { which: () => null })).toMatchObject({ ok: true, reason: 'native_unavailable' });+ });+ });+});