Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Lane F notice producers on the MCP channel (agent operator contract v1,
* F3 / F8 / F9): degraded recall, a source binding that narrowed an empty
* read, and the keyless explanations. Pins the closed DEGRADED_STAGE_GUIDANCE
* map, the wire shape (content[0] byte-identical, notices as prefixed extra
* blocks + `_meta.gbrain_notices`), stdio once-per-session vs HTTP
* every-call delivery, and the "never coach on a keyless-by-choice brain" rule.
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { dispatchToolCall, __resetBackupNoticeForTests } from '../src/mcp/dispatch.ts';
import { DEGRADED_STAGES, RANKING_ONLY_DEGRADED_STAGES } from '../src/core/types.ts';
import { NOTICE_CODES } from '../src/core/error-registry.ts';
import {
DEGRADED_STAGE_GUIDANCE, degradedRecallNotice, sourceBindingNarrowedNotice, recallStagesFor,
chatKeyFix, keylessThinkNotice, thinkNotSavedNotice, degradedDedupNotice,
} from '../src/core/interop-notices.ts';
import { withEnv } from './helpers/with-env.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { serializeMarkdown } from '../src/core/markdown.ts';
import type { GBrainConfig } from '../src/core/config.ts';
let engine: PGLiteEngine;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
});
afterAll(async () => { await engine.disconnect(); });
beforeEach(async () => {
await resetPgliteState(engine);
__resetBackupNoticeForTests();
});
const NO_KEYS = { OPENAI_API_KEY: undefined, ANTHROPIC_API_KEY: undefined, VOYAGE_API_KEY: undefined, GBRAIN_EMBEDDING_MODEL: undefined };
const keylessByChoice = { engine: 'pglite', embedding_disabled: true } as unknown as GBrainConfig;
const keylessUnchosen = { engine: 'pglite' } as unknown as GBrainConfig;
describe('DEGRADED_STAGE_GUIDANCE', () => {
test('covers every recall-affecting stage and no ranking-only one', () => {
for (const stage of DEGRADED_STAGES) {
if (RANKING_ONLY_DEGRADED_STAGES.has(stage)) expect(stage in DEGRADED_STAGE_GUIDANCE).toBe(false);
else expect(DEGRADED_STAGE_GUIDANCE[stage as keyof typeof DEGRADED_STAGE_GUIDANCE]).toBeDefined();
}
});
test('every Lane F notice code is registered with its kind', () => {
expect(NOTICE_CODES.degraded_recall.kind).toBe('degraded');
for (const c of ['source_binding_narrowed', 'degraded_dedup', 'synthesis_keyless', 'think_not_saved', 'model_override_ignored', 'listing_truncated'] as const) {
expect(NOTICE_CODES[c].kind).toBe('info');
}
});
test('ranking-only degradation is no notice; recall-affecting stages are named and say "not absence"', () => {
expect(degradedRecallNotice([{ stage: 'reranker_skipped' }], { config: keylessUnchosen, transport: 'stdio' })).toBeNull();
const n = degradedRecallNotice([{ stage: 'expansion_failed', reason: 'timeout' }], { config: keylessUnchosen, transport: 'stdio' })!;
expect(n.code).toBe('degraded_recall');
expect(n.kind).toBe('degraded');
expect(n.why).toContain('expansion_failed');
expect(n.why).toContain('never as "the brain has nothing on this"');
expect(n.fix?.argv).toEqual(['gbrain', 'doctor', '--json']);
});
test('keyword-only on a brain without a key: the enablement fix asks (credentials + paid)', async () => {
await withEnv(NO_KEYS, async () => {
const n = degradedRecallNotice([{ stage: 'embed_unavailable', reason: 'no_provider' }], { config: keylessUnchosen, transport: 'stdio' })!;
expect(n.fix?.consent).toEqual(['credentials', 'paid']);
expect(n.user_message).toBeTruthy();
});
});
test('keyless by the user\'s choice: the notice states the limit but never coaches', async () => {
await withEnv(NO_KEYS, async () => {
const n = degradedRecallNotice(['keyword_only_no_embedding_provider'], { config: keylessByChoice, transport: 'stdio' })!;
expect(n.fix).toBeUndefined();
expect(n.user_message).toBeUndefined();
expect(n.why).toContain("keyword-only by the user's choice");
expect(degradedDedupNotice(keylessByChoice).fix).toBeUndefined();
});
});
test('recallStagesFor reads each op\'s own degradation marker', () => {
expect(recallStagesFor('search', [], { retrieval: { degraded: [{ stage: 'reranker_skipped' }, { stage: 'embed_unavailable' }] } })).toEqual(['embed_unavailable']);
expect(recallStagesFor('recall', { facts: [], search_degraded: 'keyword_only_no_embedding_provider' }, {})).toEqual(['keyword_only_no_embedding_provider']);
expect(recallStagesFor('context_pack', { degraded_reason: 'deadline' }, {})).toEqual(['deadline']);
expect(recallStagesFor('think', { warnings: ['QUESTION_EMBED_FAILED'] }, {})).toEqual(['embed_unavailable']);
expect(recallStagesFor('get_page', {}, {})).toEqual([]);
});
});
describe('degraded recall over MCP dispatch (keyless PGLite)', () => {
async function seedPage() {
await engine.putPage('notes/alpha', { type: 'note', title: 'Alpha', compiled_truth: 'Alpha body about widgets.', timeline: '', frontmatter: {} }, { sourceId: 'default' });
}
/** A page that is indexed and safety-checked, so a keyless search's only degradation is the configuration-persistent embed_unavailable. */
async function importPage() {
await importFromContent(engine, 'notes/alpha', serializeMarkdown({}, 'Alpha body about widgets.', '', { type: 'note', title: 'Alpha', tags: [] }), { noEmbed: true, forceRechunk: true });
}
const noticeBlocks = (res: { content: Array<{ text: string }> }) => res.content.filter(c => c.text.startsWith('[gbrain notice degraded_recall'));
test('stdio: two keyless searches show one degraded_recall notice; a transient stage on the same search rides every call', async () => {
await withEnv(NO_KEYS, async () => {
await importPage();
const opts = { remote: true, transport: 'stdio' as const, sourceId: 'default', config: keylessUnchosen, noticeLedger: new (await import('../src/core/notice-ledger.ts')).NoticeLedger() };
const first = await dispatchToolCall(engine as any, 'search', { query: 'widgets' }, opts);
const degraded = (first._meta?.retrieval as { degraded?: Array<{ stage: string; reason?: string }> }).degraded;
expect(degraded).toEqual([{ stage: 'embed_unavailable', reason: 'no_provider' }]);
expect(JSON.parse(first.content[0].text).length).toBeGreaterThan(0);
expect(noticeBlocks(first)).toHaveLength(1);
const second = await dispatchToolCall(engine as any, 'search', { query: 'widgets' }, opts);
expect(noticeBlocks(second)).toHaveLength(0);
// keyword_zero (no match for these terms) is this call's own state: the notice rides each such call.
for (let i = 0; i < 2; i++) {
const miss = await dispatchToolCall(engine as any, 'search', { query: 'zeppelin' }, opts);
expect(noticeBlocks(miss)[0]?.text).toContain('keyword_zero');
}
});
}, 60_000);
test('stdio: content[0] unchanged, a prefixed degraded block + _meta.gbrain_notices, once per session', async () => {
await withEnv(NO_KEYS, async () => {
await importPage();
const opts = { remote: true, transport: 'stdio' as const, sourceId: 'default', config: keylessUnchosen };
const first = await dispatchToolCall(engine as any, 'search', { query: 'widgets' }, opts);
expect(first.isError).toBeUndefined();
expect(Array.isArray(JSON.parse(first.content[0].text))).toBe(true);
const block = first.content.find(c => c.text.startsWith('[gbrain notice degraded_recall kind=degraded]'));
expect(block).toBeDefined();
expect(block!.text).toContain('embed_unavailable');
const meta = first._meta?.gbrain_notices as Array<{ code: string; contract_version: number }>;
expect(meta.some(n => n.code === 'degraded_recall' && n.contract_version === 1)).toBe(true);
// Process ledger: the stdio session saw it already.
const second = await dispatchToolCall(engine as any, 'search', { query: 'widgets' }, opts);
expect(second.content.some(c => c.text.startsWith('[gbrain notice degraded_recall'))).toBe(false);
});
}, 60_000);
test('HTTP: degraded notices ride every affected call', async () => {
await withEnv(NO_KEYS, async () => {
await seedPage();
const { NoticeLedger } = await import('../src/core/notice-ledger.ts');
const opts = {
remote: true, transport: 'http' as const, sourceId: 'default', config: keylessUnchosen, noticeLedger: new NoticeLedger(),
auth: { token: 't', clientId: 'client-a', clientName: 'a', scopes: ['read'], expiresAt: Date.now() / 1000 + 3600 } as any,
};
for (let i = 0; i < 2; i++) {
const res = await dispatchToolCall(engine as any, 'search', { query: 'widgets' }, opts);
expect(res.content.some(c => c.text.startsWith('[gbrain notice degraded_recall kind=degraded]'))).toBe(true);
}
});
}, 60_000);
});
describe('source_binding_narrowed', () => {
const binding = { sourceId: 'work', via: 'GBRAIN_SOURCE' as const, sourceIds: ['work', 'personal'], optedOut: [] };
test('an empty unqualified bound read names the binding and the explicit read', () => {
const n = sourceBindingNarrowedNotice('search', { query: 'x' }, [], binding)!;
expect(n.code).toBe('source_binding_narrowed');
expect(n.why).toContain("bound to source 'work' by GBRAIN_SOURCE");
expect(n.fix?.mcp).toEqual({ tool: 'search', arguments: { query: 'x', source_id: 'personal' } });
});
test('silent when the read named a source, found something, or nothing else is readable', () => {
expect(sourceBindingNarrowedNotice('search', { query: 'x', source_id: 'work' }, [], binding)).toBeNull();
expect(sourceBindingNarrowedNotice('search', { query: 'x' }, [{ slug: 'a' }], binding)).toBeNull();
expect(sourceBindingNarrowedNotice('search', { query: 'x' }, [], { ...binding, sourceIds: ['work'] })).toBeNull();
expect(sourceBindingNarrowedNotice('get_page', { slug: 'x' }, [], binding)).toBeNull();
});
test('opted-out sources are named without a fix', () => {
const n = sourceBindingNarrowedNotice('recall', {}, { facts: [] }, { ...binding, sourceIds: ['work'], optedOut: ['private'] })!;
expect(n.why).toContain('opted out of federated reads): private');
expect(n.fix).toBeUndefined();
});
test('dispatch attaches it to an empty bound stdio read every time (per-call notice)', async () => {
await withEnv(NO_KEYS, async () => {
await engine.executeRaw(`INSERT INTO sources (id, name, config) VALUES ('work', 'work', '{}'::jsonb), ('personal', 'personal', '{}'::jsonb) ON CONFLICT DO NOTHING`);
const opts = { remote: true, transport: 'stdio' as const, sourceId: 'work', explicitReadBinding: binding, config: keylessUnchosen };
for (let i = 0; i < 2; i++) {
const res = await dispatchToolCall(engine as any, 'list_pages', {}, opts);
expect(JSON.parse(res.content[0].text)).toEqual([]);
expect(res.content.some(c => c.text.startsWith('[gbrain notice source_binding_narrowed kind=info]'))).toBe(true);
}
});
}, 60_000);
});
describe('keyless answers ask before spending (F8/F9)', () => {
test('the chat-key fix names both providers, asks, and never puts a key on a command line', () => {
const fix = chatKeyFix();
expect(fix.consent).toEqual(['credentials', 'paid']);
expect(fix.actor).toBe('user');
expect(fix.why).toContain('ANTHROPIC_API_KEY');
expect(fix.why).toContain('OPENAI_API_KEY');
expect(fix.why).toContain('Free fallback');
expect(fix.argv?.join(' ')).not.toMatch(/sk-|api_key/);
});
test('think keyless + not-saved notices are info and carry their reason', () => {
expect(keylessThinkNotice().kind).toBe('info');
expect(keylessThinkNotice().fix?.consent).toEqual(['credentials', 'paid']);
expect(thinkNotSavedNotice().why).toContain('saved_slug: null');
});
});
describe('F6 hidden-tool hint (owner stdio only)', () => {
test('a tool outside the stdio surface names itself, the request_tools widen, its CLI equivalent and GBRAIN_SURFACE=full', async () => {
// A1: the CLI fix names the served brain explicitly.
const { STARTER_OPS } = await import('../src/mcp/surface.ts');
const allowedOps = new Set(STARTER_OPS);
const stdio = await dispatchToolCall(engine as any, 'get_health', {}, { remote: true, transport: 'stdio', sourceId: 'default', allowedOps, surface: 'starter' });
const env = JSON.parse(stdio.content[0].text);
expect(env.code).toBe('unknown_tool');
expect(env.suggestion).toContain('get_health exists, but this session serves the starter tool surface');
expect(env.suggestion).toContain('GBRAIN_SURFACE=full');
expect(env.fix.mcp).toEqual({ tool: 'request_tools', arguments: { surface: 'full' } });
expect(env.fix.command).toBe('gbrain doctor --json --brain host');
expect(env.fix.next).toBe('run');
// HTTP keeps the opaque envelope (no existence oracle).
const http = await dispatchToolCall(engine as any, 'get_health', {}, { remote: true, transport: 'http', sourceId: 'default', allowedOps, surface: 'starter' });
const opaque = JSON.parse(http.content[0].text);
expect(opaque.code).toBe('unknown_tool');
expect(opaque.suggestion).not.toContain('exists');
expect(opaque.fix?.command).not.toBe('gbrain doctor --json --brain host');
});
});
describe('F7 coaching reaches agents', () => {
test('the advisor is published on stdio by default; HTTP stays opt-in; explicit false and read failures hide it', async () => {
const { readPublishGate } = await import('../src/mcp/publish-gates.ts');
const unset = { getConfig: async () => null } as any;
expect(await readPublishGate(unset, {} as any, 'mcp.publish_advisor', 'stdio')).toBe(true);
expect(await readPublishGate(unset, {} as any, 'mcp.publish_advisor', 'http')).toBe(false);
expect(await readPublishGate(unset, {} as any, 'mcp.publish_skills', 'stdio')).toBe(false);
expect(await readPublishGate({ getConfig: async () => 'false' } as any, {} as any, 'mcp.publish_advisor', 'stdio')).toBe(false);
expect(await readPublishGate(unset, { mcp: { publish_advisor: false } } as any, 'mcp.publish_advisor', 'stdio')).toBe(false);
expect(await readPublishGate({ getConfig: async () => { throw new Error('down'); } } as any, {} as any, 'mcp.publish_advisor', 'stdio')).toBe(false);
});
test('post-upgrade: one safety notice per upgraded version on stdio, with contract_version and the behavior-table URL', async () => {
const { mkdtempSync, mkdirSync, writeFileSync, rmSync } = await import('node:fs');
const { join } = await import('node:path');
const { tmpdir } = await import('node:os');
const { VERSION } = await import('../src/version.ts');
const { takePostUpgradeMcpNotice, __resetPostUpgradeNoticeForTests } = await import('../src/core/post-upgrade-notice.ts');
const { renderNotice, cliRenderContext } = await import('../src/core/agent-output.ts');
const home = mkdtempSync(join(tmpdir(), 'gbrain-postup-'));
try {
mkdirSync(join(home, '.gbrain'), { recursive: true });
writeFileSync(join(home, '.gbrain', 'upgrade-state.json'), JSON.stringify({ last_upgrade: { from: '0.0.1.0', to: VERSION } }));
await withEnv({ HOME: home, GBRAIN_HOME: home, GBRAIN_NO_ONBOARD_NUDGE: undefined }, async () => {
__resetPostUpgradeNoticeForTests();
const n = takePostUpgradeMcpNotice()!;
expect(n.code).toBe('post_upgrade');
expect(n.kind).toBe('safety');
const r = renderNotice(n, cliRenderContext());
expect(r.contract_version).toBe(1);
expect(r.fix?.docs).toMatch(/^https:\/\/.*CHANGELOG\.md#behavior-changes-for-scripts-and-agents$/);
__resetPostUpgradeNoticeForTests();
expect(takePostUpgradeMcpNotice()).toBeNull();
});
} finally {
rmSync(home, { recursive: true, force: true });
__resetPostUpgradeNoticeForTests();
}
});
test('#8621: a partly failed remember batch (an MCP error) leaves the one-shot post-upgrade notice for the next call', async () => {
const { mkdtempSync, mkdirSync, writeFileSync, rmSync } = await import('node:fs');
const { join } = await import('node:path');
const { tmpdir } = await import('node:os');
const { VERSION } = await import('../src/version.ts');
const { takePostUpgradeMcpNotice, __resetPostUpgradeNoticeForTests } = await import('../src/core/post-upgrade-notice.ts');
const { operations } = await import('../src/core/operations.ts');
const op = operations.find(o => o.name === 'remember')! as { handler: unknown };
const original = op.handler;
const home = mkdtempSync(join(tmpdir(), 'gbrain-postup-batch-'));
try {
mkdirSync(join(home, '.gbrain'), { recursive: true });
writeFileSync(join(home, '.gbrain', 'upgrade-state.json'), JSON.stringify({ last_upgrade: { from: '0.0.1.0', to: VERSION } }));
const { __resetBehaviorNoticeForTests, BEHAVIOR_NOTICE_CODE, takeLocalBehaviorNotice } = await import('../src/core/behavior-change-notice.ts');
// A brain older than this release has pending behavior changes, so the stdio behavior notice is due.
await engine.executeRaw("UPDATE sources SET created_at = now() - interval '30 days'");
await withEnv({ HOME: home, GBRAIN_HOME: home, GBRAIN_NO_ONBOARD_NUDGE: undefined }, async () => {
__resetPostUpgradeNoticeForTests();
__resetBehaviorNoticeForTests();
op.handler = async () => ({ status: 'error', error: 'invalid_params', code: 'invalid_params', message: '1 of 2 item(s) failed.',
items: [{ index: 0, request_id: 'r0', status: 'failed', error: { code: 'invalid_params', message: 'refused' } }, { index: 1, request_id: 'r1', status: 'inserted', id: 7 }],
saved: 1, failed: 1, partial: true });
const res = await dispatchToolCall(engine as any, 'remember', { items: ['alice-example likes tea', 'alice-example likes jazz'], provenance: 'test' }, { remote: true, transport: 'stdio', sourceId: 'default' });
expect(res.isError).toBe(true);
expect(takePostUpgradeMcpNotice()?.code).toBe('post_upgrade');
expect((await takeLocalBehaviorNotice(engine as any, 'stdio', { cfg: null }))?.code).toBe(BEHAVIOR_NOTICE_CODE);
});
} finally {
op.handler = original;
rmSync(home, { recursive: true, force: true });
__resetPostUpgradeNoticeForTests();
}
});
});
describe('onboarding notices on the stdio channel', () => {
test('an onboard_* notice renders as a prefixed block and in _meta.gbrain_notices; first_run_decisions carries its decisions', async () => {
const { mkdtempSync, rmSync } = await import('node:fs');
const { tmpdir } = await import('node:os');
const { join } = await import('node:path');
const { __resetMcpOnboardingForTests, __warmOnboardingCacheForTests } = await import('../src/core/onboard/mcp-onboarding.ts');
const home = mkdtempSync(join(tmpdir(), 'gb-notice-onboard-'));
try {
await withEnv({ GBRAIN_HOME: home, GBRAIN_NO_ONBOARD_NUDGE: undefined }, async () => {
__resetMcpOnboardingForTests();
__resetBackupNoticeForTests();
for (const p of ['alice-example', 'bob-example', 'charlie-example']) {
await engine.putPage(`people/${p}`, { type: 'person', title: p, compiled_truth: `${p} notes.` });
}
await __warmOnboardingCacheForTests(engine as never);
const opts = { remote: true, transport: 'stdio' as const, sourceId: 'default' };
const first = await dispatchToolCall(engine as never, 'get_backlinks', { slug: 'people/alice-example' }, opts);
const block = first.content.map(c => c.text).find(t => t.startsWith('[gbrain notice onboard_link_coverage kind=coaching]'));
expect(block).toBeDefined();
expect(block).toContain('fix: get_health {}');
expect(block).toContain('user_message: ');
const meta = (first._meta?.gbrain_notices as Array<{ code: string; contract_version: number }>).find(n => n.code === 'onboard_link_coverage');
expect(meta?.contract_version).toBe(1);
const second = await dispatchToolCall(engine as never, 'list_pages', {}, opts);
const ask = (second._meta?.gbrain_notices as Array<{ code: string; decisions?: Array<{ id: string; options: Array<{ argv?: string[] }> }> }>).find(n => n.code === 'first_run_decisions');
const writeback = ask?.decisions?.find(d => d.id === 'writeback');
expect(writeback?.options.map(o => o.argv)).toContainEqual(['gbrain', 'config', 'set', 'memory.auto_writeback', 'salient']);
expect(second.content.some(c => c.text.startsWith('[gbrain notice first_run_decisions kind=ask]'))).toBe(true);
});
} finally {
rmSync(home, { recursive: true, force: true });
__resetMcpOnboardingForTests();
}
});
});