Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* The per-turn brain-first rule (src/core/setup/brain-first.ts): one line a
* harness's per-turn hook puts beside every user turn. Pins who gets it and
* when it is off: Claude Code / Codex UserPromptSubmit (only while a block is
* installed for that harness), the self-contained Hermes pre_llm_call hook
* setup writes into config.yaml, the hook-only OpenClaw plugin setup installs
* with OpenClaw's CLI, and the opt-out.
*/
import { afterAll, describe, expect, test } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { load } from 'js-yaml';
import { withEnv } from './helpers/with-env.ts';
import { brainFirstTurnRule, renderBrainFirstTurnRule, type BrainFirstAccess } from '../src/core/setup/brain-first.ts';
import { runHook } from '../src/commands/hook.ts';
import { hermesTurnHookCommand, removeHermesTurnHook, syncHermesTurnHook } from '../src/core/setup/hermes-turn-hook.ts';
import { inspectTurnHook } from '../src/core/setup/turn-hook-check.ts';
import { OPENCLAW_TURN_PLUGIN_ID, openclawTurnPluginDir, removeOpenclawTurnPlugin, syncOpenclawTurnPlugin } from '../src/core/setup/openclaw-turn-plugin.ts';
const roots: string[] = [];
afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true }); });
function home(entries: Array<{ harness: string; status: 'installed' | 'declined'; access?: BrainFirstAccess }> | null): string {
const root = mkdtempSync(join(tmpdir(), 'gbrain-turn-rule-'));
roots.push(root);
if (entries) {
mkdirSync(join(root, '.gbrain'), { recursive: true });
writeFileSync(join(root, '.gbrain', 'agent-instructions.json'), JSON.stringify({ version: 1, entries: entries.map((e, i) => ({
path: join(root, `file-${i}.md`), block_version: 2, access: { kind: 'mcp', server: 'gbrain' }, writer: 'test', created_file: false,
updated_at: new Date(Date.UTC(2026, 9, 25, 0, i)).toISOString(), ...e,
})) }));
}
return root;
}
const env = (root: string, extra: Record<string, string | undefined> = {}) => ({ GBRAIN_HOME: root, GBRAIN_AGENT_INSTRUCTIONS: undefined, GBRAIN_HOOKS: undefined, ...extra });
async function userPrompt(root: string, harness?: string, extra: Record<string, string | undefined> = {}): Promise<string> {
let out = '';
await withEnv(env(root, extra), async () => {
const code = await runHook(['user-prompt', ...(harness ? ['--harness', harness] : [])], {
stdin: JSON.stringify({ prompt: 'what did alice-example decide about the launch?', session_id: 's1' }),
write: (s) => { out += s; }, cwd: root, configOverride: null, disablePushBanner: true, disableTelemetry: true,
});
expect(code).toBe(0);
});
return out;
}
describe('per-turn rule: text and decision', () => {
test('names the tools of the recorded access', () => {
expect(renderBrainFirstTurnRule({ kind: 'mcp', server: 'gbrain' })).toContain('before answering this turn, check GBrain first (`search` or `query` on the `gbrain` MCP server)');
expect(renderBrainFirstTurnRule({ kind: 'mcp', server: 'brain', surface: 'verbs' })).toContain('`recall` or `entity` on the `brain` MCP server');
expect(renderBrainFirstTurnRule({ kind: 'cli', launcher: '/opt/gbrain' })).toContain('`/opt/gbrain search "<names>"`');
});
test('a recorded install turns it on with its access; no record, a decline or the opt-out turns it off', async () => {
await withEnv(env(home(null)), async () => {
expect(brainFirstTurnRule('claude-code')).toBeNull();
});
await withEnv(env(home([{ harness: 'claude-code', status: 'installed', access: { kind: 'mcp', server: 'brain', surface: 'verbs' } }])), async () => {
expect(brainFirstTurnRule('claude-code')).toBe(renderBrainFirstTurnRule({ kind: 'mcp', server: 'brain', surface: 'verbs' }));
expect(brainFirstTurnRule('codex')).toBeNull();
});
await withEnv(env(home([{ harness: 'openclaw', status: 'declined' }])), async () => {
expect(brainFirstTurnRule('openclaw')).toBeNull();
});
await withEnv(env(home([{ harness: 'claude-code', status: 'installed' }]), { GBRAIN_AGENT_INSTRUCTIONS: '0' }), async () => {
expect(brainFirstTurnRule('claude-code')).toBeNull();
});
});
});
describe('per-turn rule: Claude Code and Codex user-prompt hook', () => {
test('with a block installed, every turn carries the rule even when serve has no context to add', async () => {
const out = await userPrompt(home([{ harness: 'claude-code', status: 'installed' }]));
const doc = JSON.parse(out.trim());
expect(doc.hookSpecificOutput).toEqual({ hookEventName: 'UserPromptSubmit', additionalContext: renderBrainFirstTurnRule({ kind: 'mcp', server: 'gbrain' }) });
expect(doc.systemMessage).toBeUndefined();
});
test('codex reads its own ledger entry', async () => {
const root = home([{ harness: 'codex', status: 'installed' }]);
expect(await userPrompt(root, 'codex')).toContain('check GBrain first');
expect(await userPrompt(root)).toBe('');
});
test('no block, a declined block, GBRAIN_AGENT_INSTRUCTIONS=0 or the null seam: stdout stays empty', async () => {
expect(await userPrompt(home(null))).toBe('');
expect(await userPrompt(home([{ harness: 'claude-code', status: 'declined' }]))).toBe('');
expect(await userPrompt(home([{ harness: 'claude-code', status: 'installed' }]), undefined, { GBRAIN_AGENT_INSTRUCTIONS: '0' })).toBe('');
let out = '';
await withEnv(env(home([{ harness: 'claude-code', status: 'installed' }])), async () => {
await runHook(['user-prompt'], { stdin: JSON.stringify({ prompt: 'hi' }), write: (s) => { out += s; }, configOverride: null, disablePushBanner: true, disableTelemetry: true, turnRule: null });
});
expect(out).toBe('');
});
});
describe('per-turn rule: turns no person typed (#9163)', () => {
async function prompt(text: string, extra: Record<string, string | undefined> = {}): Promise<string> {
let out = '';
await withEnv(env(home([{ harness: 'claude-code', status: 'installed' }]), extra), async () => {
await runHook(['user-prompt'], { stdin: JSON.stringify({ prompt: text, session_id: 's1' }), write: (s) => { out += s; },
configOverride: null, disablePushBanner: true, disableTelemetry: true });
});
return out;
}
const NOTIFICATION = '<task-notification>\n<task-id>t1</task-id>\n<status>completed</status>\n</task-notification>';
const TEAMMATE = '<teammate-message teammate_id="lead">rebase on main</teammate-message>';
test('a task notification or teammate message gets no rule; a typed turn keeps it', async () => {
expect(await prompt(NOTIFICATION)).toBe('');
expect(await prompt(TEAMMATE)).toBe('');
expect(await prompt('what did alice-example decide about the launch?')).toContain('check GBrain first');
});
test('the turn-rule lane skips them too', async () => {
const lane = { GBRAIN_HOOK_LANE: 'turn-rule' };
expect(await prompt(NOTIFICATION, lane)).toBe('');
expect(await prompt('what did alice-example decide about the launch?', lane)).toContain('check GBrain first');
});
});
describe('per-turn rule names the tools where tool_search hides them', () => {
test('OpenClaw: names the gbrain tools and the tool_search / tool_call route; Hermes: names mcp__<server>__<tool>', () => {
const starter = { kind: 'mcp', server: 'gbrain', surface: 'starter' } as const;
const openclaw = renderBrainFirstTurnRule(starter, 'openclaw');
expect(openclaw).toContain('find them with `tool_search` (search "gbrain recall") and run them with `tool_call`');
expect(openclaw).toContain('`recall`, `entity`, `search`, `query` on the `gbrain` MCP server');
expect(openclaw).toContain('tool_search shows them as external data');
const hermes = renderBrainFirstTurnRule({ kind: 'mcp', server: 'brain', surface: 'verbs' }, 'hermes');
// #8068: Hermes registers MCP tools as mcp__<server>__<tool> (hermes-agent#52750), with the server name sanitized to [A-Za-z0-9_].
expect(hermes).toContain('find them with `tool_search` (they register as `mcp__brain__recall`, `mcp__brain__entity`, `mcp__brain__remember`)');
expect(renderBrainFirstTurnRule({ kind: 'mcp', server: 'team-brain', surface: 'verbs' }, 'hermes')).toContain('`mcp__team_brain__recall`');
// Claude Code and Codex list MCP tools directly; a CLI launcher needs no discovery.
expect(renderBrainFirstTurnRule(starter, 'claude-code')).not.toContain('tool_search');
expect(renderBrainFirstTurnRule(starter)).not.toContain('tool_search');
expect(renderBrainFirstTurnRule({ kind: 'cli', launcher: '/opt/gbrain' }, 'openclaw')).not.toContain('tool_search');
});
});
describe('per-turn rule: Hermes pre_llm_call hook in config.yaml', () => {
const access: BrainFirstAccess = { kind: 'mcp', server: 'gbrain' };
const cmd = hermesTurnHookCommand(access);
function hermes(config?: string, approvals: unknown[] = []): string {
const dir = mkdtempSync(join(tmpdir(), 'gbrain-hermes-home-'));
roots.push(dir);
if (config !== undefined) writeFileSync(join(dir, 'config.yaml'), config);
if (approvals.length) writeFileSync(join(dir, 'shell-hooks-allowlist.json'), JSON.stringify({ approvals }));
return dir;
}
const cfg = (d: string) => readFileSync(join(d, 'config.yaml'), 'utf8');
const approvals = (d: string) => JSON.parse(readFileSync(join(d, 'shell-hooks-allowlist.json'), 'utf8')).approvals as Array<Record<string, unknown>>;
test('the command echoes Hermes\'s {"context": ...} wire shape on its own: no shell, no gbrain process', () => {
const quoted: BrainFirstAccess = { kind: 'cli', launcher: "/opt/it's/gbrain" };
const c = hermesTurnHookCommand(quoted);
expect(c.startsWith("/bin/echo '")).toBe(true);
expect(c.endsWith("'")).toBe(true);
const inner = c.slice("/bin/echo '".length, -1);
expect(inner).not.toContain("'");
expect(JSON.parse(inner)).toEqual({ context: renderBrainFirstTurnRule(quoted, 'hermes') });
expect(JSON.parse(cmd.slice("/bin/echo '".length, -1))).toEqual({ context: renderBrainFirstTurnRule(access, 'hermes') });
});
test('a flow-style config.yaml, or an allowlist gbrain cannot read, gets the entry printed and both files left as they are', () => {
const flow = '{model: alice-example-model, agent: {max_turns: 4}}\n';
const d = hermes(flow);
expect(syncHermesTurnHook({ hermesHome: d, access, dryRun: false }).action).toBe('print');
expect(cfg(d)).toBe(flow);
const unreadable = hermes('model: x\n');
writeFileSync(join(unreadable, 'shell-hooks-allowlist.json'), '{"approvals": [{"event": "post_tool_call", "command": "/opt/x"}],}');
expect(syncHermesTurnHook({ hermesHome: unreadable, access, dryRun: false }).action).toBe('print');
expect(cfg(unreadable)).toBe('model: x\n');
expect(readFileSync(join(unreadable, 'shell-hooks-allowlist.json'), 'utf8')).toContain('post_tool_call');
const bom = hermes('model: x\n');
writeFileSync(join(bom, 'shell-hooks-allowlist.json'), '\uFEFF' + JSON.stringify({ approvals: [{ event: 'post_tool_call', command: '/opt/x' }] }));
expect(syncHermesTurnHook({ hermesHome: bom, access, dryRun: false }).action).toBe('write');
expect(approvals(bom).map((e) => e.event)).toEqual(['post_tool_call', 'pre_llm_call']);
});
test('appends a marked hook after the user\'s text, approves exactly that command, keeps on a re-run, and removal undoes both', () => {
const mine = '# my config\nmodel:\n default: alice-example-model\n';
const other = { event: 'pre_tool_call', command: '/usr/bin/true', approved_at: 'x', script_mtime_at_approval: null };
const d = hermes(mine, [other]);
expect(syncHermesTurnHook({ hermesHome: d, access, dryRun: false }).action).toBe('write');
const text = cfg(d);
expect(text.startsWith(mine)).toBe(true);
expect(load(text)).toEqual({ model: { default: 'alice-example-model' }, hooks: { pre_llm_call: [{ command: cmd, timeout: 10 }] } });
expect(approvals(d)).toEqual([other, expect.objectContaining({ event: 'pre_llm_call', command: cmd, script_mtime_at_approval: null })]);
expect(syncHermesTurnHook({ hermesHome: d, access, dryRun: false }).action).toBe('keep');
expect(cfg(d)).toBe(text);
expect(approvals(d)).toHaveLength(2);
expect(removeHermesTurnHook({ hermesHome: d, dryRun: false }).action).toBe('remove');
expect(cfg(d)).toBe(mine);
expect(approvals(d)).toEqual([other]);
});
// Hermes's own writer (agent/shell_hooks.py _locked_update_approvals): an
// exclusive fcntl.flock on the sibling .lock around read-modify-write.
const HERMES_WRITER = [
'import fcntl, json, os, sys, time',
'home, hold = sys.argv[1], float(sys.argv[2])',
'path = os.path.join(home, "shell-hooks-allowlist.json")',
'with open(path + ".lock", "a+") as lock:',
' fcntl.flock(lock.fileno(), fcntl.LOCK_EX)',
' print("locked", flush=True)',
' data = json.load(open(path, encoding="utf-8-sig")) if os.path.exists(path) else {"approvals": []}',
' time.sleep(hold)',
' data["approvals"].append({"event": "post_tool_call", "command": "/opt/hermes-side", "approved_at": "x", "script_mtime_at_approval": None})',
' open(path + ".tmp", "w").write(json.dumps(data))',
' os.replace(path + ".tmp", path)',
' fcntl.flock(lock.fileno(), fcntl.LOCK_UN)',
].join('\n');
async function hermesHoldsLock(d: string, holdSecs: number) {
const proc = Bun.spawn(['python3', '-c', HERMES_WRITER, d, String(holdSecs)], { stdout: 'pipe', stderr: 'inherit' });
const reader = proc.stdout.getReader();
const first = await reader.read();
expect(new TextDecoder().decode(first.value)).toContain('locked');
reader.releaseLock();
return proc;
}
test.skipIf(!Bun.which('python3'))('the approval waits for Hermes\'s allowlist flock, so an approval Hermes records at the same moment survives', async () => {
const d = hermes('model: x\n');
const proc = await hermesHoldsLock(d, 0.8);
expect(syncHermesTurnHook({ hermesHome: d, access, dryRun: false }).action).toBe('write');
expect(await proc.exited).toBe(0);
expect(approvals(d).map((a) => a.command)).toEqual(['/opt/hermes-side', cmd]);
});
test.skipIf(!Bun.which('python3'))('a flock Hermes holds past the wait refuses loudly and leaves the allowlist untouched', async () => {
const d = hermes('model: x\n', [{ event: 'pre_tool_call', command: '/usr/bin/true' }]);
const before = readFileSync(join(d, 'shell-hooks-allowlist.json'), 'utf8');
const proc = await hermesHoldsLock(d, 8);
try {
const o = syncHermesTurnHook({ hermesHome: d, access, dryRun: false });
expect(o.action).toBe('print');
expect(o.detail).toContain('shell-hooks-allowlist.json.lock');
expect(readFileSync(join(d, 'shell-hooks-allowlist.json'), 'utf8')).toBe(before);
} finally {
proc.kill();
await proc.exited;
}
});
test('new rule text rewrites the block in place and moves the approval to the new command', () => {
const d = hermes('');
syncHermesTurnHook({ hermesHome: d, access, dryRun: false });
const next: BrainFirstAccess = { kind: 'mcp', server: 'brain', surface: 'verbs' };
expect(syncHermesTurnHook({ hermesHome: d, access: next, dryRun: false }).action).toBe('write');
expect(load(cfg(d))).toEqual({ hooks: { pre_llm_call: [{ command: hermesTurnHookCommand(next), timeout: 10 }] } });
expect(approvals(d).map((a) => a.command)).toEqual([hermesTurnHookCommand(next)]);
});
test('prints the entry instead of editing: a hooks: section of the user\'s, no Hermes home, damaged markers', () => {
const theirs = 'hooks:\n pre_tool_call:\n - command: /usr/bin/true\n';
const d = hermes(theirs);
const o = syncHermesTurnHook({ hermesHome: d, access, dryRun: false });
expect(o.action).toBe('print');
expect(o.snippet).toContain(`- command: ${JSON.stringify(cmd)}`);
expect(cfg(d)).toBe(theirs);
expect(existsSync(join(d, 'shell-hooks-allowlist.json'))).toBe(false);
expect(syncHermesTurnHook({ hermesHome: join(tmpdir(), 'gbrain-no-such-hermes-home'), access, dryRun: false }).action).toBe('print');
const damaged = hermes('# gbrain:turn-rule:begin\nmodel: x\n');
expect(syncHermesTurnHook({ hermesHome: damaged, access, dryRun: false }).action).toBe('print');
expect(cfg(damaged)).toBe('# gbrain:turn-rule:begin\nmodel: x\n');
});
test('doctor sees the printed entry once it is pasted into the user\'s hooks: section, and only that exact command', async () => {
const theirs = 'hooks:\n pre_tool_call:\n - command: /usr/bin/true\n';
const d = hermes(theirs);
const snippet = syncHermesTurnHook({ hermesHome: d, access, dryRun: false }).snippet!;
const pasted = `${theirs} pre_llm_call:\n${snippet.split('\n').slice(2).join('\n')}`;
expect(load(pasted)).toEqual({ hooks: { pre_tool_call: [{ command: '/usr/bin/true' }], pre_llm_call: [{ command: cmd, timeout: 10 }] } });
writeFileSync(join(d, 'config.yaml'), pasted);
const root = home([{ harness: 'hermes', status: 'installed', access }]);
const ledger = join(root, '.gbrain', 'agent-instructions.json');
const entries = JSON.parse(readFileSync(ledger, 'utf8')).entries;
writeFileSync(ledger, JSON.stringify({ version: 1, entries: entries.map((e: Record<string, unknown>) => ({ ...e, path: join(d, 'SOUL.md') })) }));
await withEnv({ GBRAIN_HOME: root, HERMES_HOME: d }, async () => {
expect(inspectTurnHook('hermes')).toMatchObject({ state: 'untrusted', via: 'native' });
writeFileSync(join(d, 'shell-hooks-allowlist.json'), JSON.stringify({ approvals: [{ event: 'pre_llm_call', command: cmd }] }));
expect(inspectTurnHook('hermes')).toMatchObject({ state: 'wired', via: 'native' });
writeFileSync(join(d, 'config.yaml'), pasted.replace(JSON.stringify(cmd), JSON.stringify('/bin/echo hi')));
expect(inspectTurnHook('hermes').state).toBe('missing');
});
});
test('dry-run writes nothing', () => {
const d = hermes('model: x\n');
expect(syncHermesTurnHook({ hermesHome: d, access, dryRun: true }).action).toBe('write');
expect(cfg(d)).toBe('model: x\n');
expect(existsSync(join(d, 'shell-hooks-allowlist.json'))).toBe(false);
});
});
describe('per-turn rule: OpenClaw before_prompt_build plugin', () => {
const access: BrainFirstAccess = { kind: 'mcp', server: 'gbrain' };
function state(): string {
const dir = mkdtempSync(join(tmpdir(), 'gbrain-openclaw-state-'));
roots.push(dir);
return dir;
}
function recorder(fail?: string) {
const calls: string[][] = [];
return { calls, run: (argv: string[]) => { calls.push(argv); return argv.includes(fail ?? '\0') ? { ok: false, output: 'boom' } : { ok: true, output: '' }; } };
}
test('writes a self-contained hook-only plugin and installs it with the openclaw CLI; a re-run keeps it', async () => {
const st = state();
await withEnv({ OPENCLAW_STATE_DIR: st, OPENCLAW_PROFILE: undefined }, async () => {
const dir = openclawTurnPluginDir();
expect(dir).toBe(join(st, 'gbrain', OPENCLAW_TURN_PLUGIN_ID));
const rec = recorder();
const o = syncOpenclawTurnPlugin({ access, dryRun: false, openclawBin: '/bin/openclaw', run: rec.run });
expect(o.action).toBe('write');
expect(rec.calls).toEqual([
['/bin/openclaw', 'plugins', 'install', '--link', dir, '--force', '--accept-capabilities'],
['/bin/openclaw', 'plugins', 'enable', OPENCLAW_TURN_PLUGIN_ID],
['/bin/openclaw', 'config', 'set', `plugins.entries.${OPENCLAW_TURN_PLUGIN_ID}.hooks.allowConversationAccess`, 'true'],
]);
expect(JSON.parse(readFileSync(join(dir, 'openclaw.plugin.json'), 'utf8'))).toMatchObject({ id: OPENCLAW_TURN_PLUGIN_ID, configSchema: { type: 'object' } });
expect(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).openclaw).toEqual({ extensions: ['./index.js'] });
const mod = await import(join(dir, 'index.js'));
const handlers: Record<string, () => unknown> = {};
mod.default.register({ on: (event: string, fn: () => unknown) => { handlers[event] = fn; } });
expect(Object.keys(handlers)).toEqual(['before_prompt_build']);
expect(handlers.before_prompt_build()).toEqual({ prependContext: renderBrainFirstTurnRule(access, 'openclaw') });
expect(syncOpenclawTurnPlugin({ access, dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run }).action).toBe('keep');
});
});
test('internal turns (heartbeat, cron, exec completion) get the rule without the reply sentence; every other turn keeps it', async () => {
await withEnv({ OPENCLAW_STATE_DIR: state(), OPENCLAW_PROFILE: undefined }, async () => {
syncOpenclawTurnPlugin({ access, dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run });
const mod = await import(join(openclawTurnPluginDir(), 'index.js'));
const handlers: Record<string, (event?: unknown, ctx?: unknown) => unknown> = {};
mod.default.register({ on: (event: string, fn: (event?: unknown, ctx?: unknown) => unknown) => { handlers[event] = fn; } });
const full = renderBrainFirstTurnRule(access, 'openclaw');
expect(full).toEndWith(' Then answer and finish the task.');
const internal = renderBrainFirstTurnRule(access, 'openclaw', { reply: false });
expect(internal).toBe(full.slice(0, -' Then answer and finish the task.'.length));
expect(handlers.before_prompt_build({}, { inputProvenance: { kind: 'internal_system' } })).toEqual({ prependContext: internal });
expect(handlers.before_prompt_build({}, { inputProvenance: { kind: 'external_user' } })).toEqual({ prependContext: full });
expect(handlers.before_prompt_build({}, {})).toEqual({ prependContext: full });
});
});
test('no openclaw on PATH or a failed command: the plugin is written and the remaining commands are printed', async () => {
await withEnv({ OPENCLAW_STATE_DIR: state(), OPENCLAW_PROFILE: undefined }, async () => {
const o = syncOpenclawTurnPlugin({ access, dryRun: false, openclawBin: null });
expect(o.action).toBe('print');
expect(o.commands?.[0]).toBe(`openclaw plugins install --link ${openclawTurnPluginDir()} --force --accept-capabilities`);
expect(o.commands).toHaveLength(3);
expect(existsSync(join(openclawTurnPluginDir(), 'index.js'))).toBe(true);
const failed = syncOpenclawTurnPlugin({ access, dryRun: false, openclawBin: '/bin/openclaw', run: recorder('enable').run });
expect(failed.action).toBe('print');
expect(failed.commands).toEqual([`/bin/openclaw plugins enable ${OPENCLAW_TURN_PLUGIN_ID}`, `/bin/openclaw config set plugins.entries.${OPENCLAW_TURN_PLUGIN_ID}.hooks.allowConversationAccess true`]);
});
});
test('dry-run writes and runs nothing; removal uninstalls and deletes the directory and its empty parent', async () => {
const st = state();
await withEnv({ OPENCLAW_STATE_DIR: st, OPENCLAW_PROFILE: undefined }, async () => {
const rec = recorder();
expect(syncOpenclawTurnPlugin({ access, dryRun: true, openclawBin: '/bin/openclaw', run: rec.run }).action).toBe('write');
expect(rec.calls).toEqual([]);
expect(existsSync(openclawTurnPluginDir())).toBe(false);
expect(removeOpenclawTurnPlugin({ dryRun: false, openclawBin: '/bin/openclaw', run: rec.run }).action).toBe('skip');
syncOpenclawTurnPlugin({ access, dryRun: false, openclawBin: '/bin/openclaw', run: rec.run });
const gone = recorder();
expect(removeOpenclawTurnPlugin({ dryRun: false, openclawBin: '/bin/openclaw', run: gone.run }).action).toBe('remove');
expect(gone.calls).toEqual([['/bin/openclaw', 'plugins', 'uninstall', OPENCLAW_TURN_PLUGIN_ID, '--force']]);
expect(existsSync(join(st, 'gbrain'))).toBe(false);
});
});
test('a --workspace run leaves the gateway-shared plugin when it names another server, and never removes it', async () => {
await withEnv({ OPENCLAW_STATE_DIR: state(), OPENCLAW_PROFILE: undefined }, async () => {
syncOpenclawTurnPlugin({ access, dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run });
const index = readFileSync(join(openclawTurnPluginDir(), 'index.js'), 'utf8');
const rec = recorder();
const other = syncOpenclawTurnPlugin({ access: { kind: 'mcp', server: 'gbrain-a' }, workspace: '/ws/a', dryRun: false, openclawBin: '/bin/openclaw', run: rec.run });
expect(other.action).toBe('print');
expect(other.detail).toContain('names the `gbrain` MCP server');
expect(other.commands).toEqual(['gbrain setup openclaw --remove --workspace /ws/a']);
expect(readFileSync(join(openclawTurnPluginDir(), 'index.js'), 'utf8')).toBe(index);
expect(rec.calls).toEqual([]);
expect(syncOpenclawTurnPlugin({ access, workspace: '/ws/a', dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run }).action).toBe('keep');
const kept = removeOpenclawTurnPlugin({ workspace: '/ws/a', dryRun: false, openclawBin: '/bin/openclaw', run: rec.run });
expect(kept.action).toBe('skip');
expect(rec.calls).toEqual([]);
expect(readFileSync(join(openclawTurnPluginDir(), 'index.js'), 'utf8')).toBe(index);
});
});
test('a plugin an older gbrain wrote (no recorded access): a same-server --workspace run rewrites it; another server or an unreadable rule is left', async () => {
const legacy = (rule: string) => {
const dir = openclawTurnPluginDir();
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, 'package.json'), `${JSON.stringify({ name: OPENCLAW_TURN_PLUGIN_ID, version: '1.0.0', private: true, type: 'module', openclaw: { extensions: ['./index.js'] } }, null, 2)}\n`);
writeFileSync(join(dir, 'index.js'), [`const RULE = ${JSON.stringify(rule)};`, 'export default {', ` id: '${OPENCLAW_TURN_PLUGIN_ID}',`, ' register(api) {', " api.on('before_prompt_build', () => ({ prependContext: RULE }));", ' },', '};', ''].join('\n'));
return dir;
};
await withEnv({ OPENCLAW_STATE_DIR: state(), OPENCLAW_PROFILE: undefined }, async () => {
const dir = legacy(renderBrainFirstTurnRule(access, 'openclaw'));
expect(syncOpenclawTurnPlugin({ access, workspace: '/ws/a', dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run }).action).toBe('write');
expect(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).gbrain).toEqual({ access });
const mod = await import(join(dir, 'index.js'));
const handlers: Record<string, (event?: unknown, ctx?: unknown) => unknown> = {};
mod.default.register({ on: (event: string, fn: (event?: unknown, ctx?: unknown) => unknown) => { handlers[event] = fn; } });
expect(handlers.before_prompt_build({}, { inputProvenance: { kind: 'internal_system' } })).toEqual({ prependContext: renderBrainFirstTurnRule(access, 'openclaw', { reply: false }) });
});
await withEnv({ OPENCLAW_STATE_DIR: state(), OPENCLAW_PROFILE: undefined }, async () => {
const dir = legacy(renderBrainFirstTurnRule({ kind: 'mcp', server: 'gbrain-b' }, 'openclaw'));
const index = readFileSync(join(dir, 'index.js'), 'utf8');
const other = syncOpenclawTurnPlugin({ access, workspace: '/ws/a', dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run });
expect(other.action).toBe('print');
expect(other.detail).toContain('names the `gbrain-b` MCP server');
expect(readFileSync(join(dir, 'index.js'), 'utf8')).toBe(index);
});
await withEnv({ OPENCLAW_STATE_DIR: state(), OPENCLAW_PROFILE: undefined }, async () => {
const dir = legacy('not a gbrain rule');
const unreadable = syncOpenclawTurnPlugin({ access, workspace: '/ws/a', dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run });
expect(unreadable.action).toBe('print');
expect(unreadable.detail).toContain('gbrain cannot read');
expect(readFileSync(join(dir, 'index.js'), 'utf8')).toContain('not a gbrain rule');
});
});
test('removal keeps the directory OpenClaw still loads when the uninstall fails or openclaw is not on PATH', async () => {
await withEnv({ OPENCLAW_STATE_DIR: state(), OPENCLAW_PROFILE: undefined }, async () => {
syncOpenclawTurnPlugin({ access, dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run });
const failed = removeOpenclawTurnPlugin({ dryRun: false, openclawBin: '/bin/openclaw', run: recorder('uninstall').run });
expect(failed.action).toBe('print');
expect(failed.commands).toEqual([`/bin/openclaw plugins uninstall ${OPENCLAW_TURN_PLUGIN_ID} --force`]);
expect(existsSync(join(openclawTurnPluginDir(), 'index.js'))).toBe(true);
const noBin = removeOpenclawTurnPlugin({ dryRun: false, openclawBin: null });
expect(noBin.action).toBe('print');
expect(noBin.commands).toEqual([`openclaw plugins uninstall ${OPENCLAW_TURN_PLUGIN_ID} --force`]);
expect(existsSync(join(openclawTurnPluginDir(), 'index.js'))).toBe(true);
});
});
});