Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* WP2/D3/D8 — the `_meta.retrieval` response channel and the model-visible
* second content block on empty retrievals, driven through the REAL dispatch
* path (dispatchToolCall → search op handler) with hybridSearchCached mocked.
*
* Pins the four load-bearing behaviors:
* 1. empty results → bare-array body + SECOND text block (D8);
* 2. `_meta.retrieval` present on empty AND non-empty responses (D3);
* 3. a metaHook failure never drops the retrieval key (per-key isolation);
* 4. metaHook keys merge ALONGSIDE retrieval, not over it.
*
* Serial: mock.module (isolation guard R2).
*/
import { describe, expect, mock, test } from 'bun:test';
import * as realHybrid from '../src/core/search/hybrid.ts';
import type { BrainEngine } from '../src/core/engine.ts';
let nextResults: unknown[] = [];
let nextMeta: Record<string, unknown> | null = null;
// Mock BEFORE importing dispatch (operations.ts binds hybridSearchCached at
// import time; the spread keeps every other export live).
mock.module('../src/core/search/hybrid.ts', () => ({
...realHybrid,
hybridSearchCached: async (
_engine: unknown,
_query: string,
opts: { onMeta?: (m: unknown) => void },
) => {
if (nextMeta) opts.onMeta?.(nextMeta);
return nextResults;
},
}));
const { dispatchToolCall } = await import('../src/mcp/dispatch.ts');
const engineStub = {
getConfig: async () => null,
// Cat 40 Hard F2: the strict keyword count every search reports (no matches here).
countKeywordPages: async () => 0,
executeRaw: async (sql: string) => sql.includes('AS pending') ? [{ pending: false }] : [],
} as unknown as BrainEngine;
const DEGRADED_META = {
vector_enabled: false,
expansion_applied: false,
detail_resolved: null,
retrieved_count: 3,
degraded: [{ stage: 'embed_unavailable' }],
};
function callSearch(metaHook?: () => Promise<Record<string, unknown> | undefined>) {
return dispatchToolCall(engineStub, 'search', { query: 'anything at all' }, {
remote: true,
transport: 'http',
sourceId: 'default',
...(metaHook ? { metaHook } : {}),
});
}
describe('dispatch response meta (WP2/D3/D8)', () => {
test('empty results → second content block + _meta.retrieval', async () => {
nextResults = [];
nextMeta = DEGRADED_META;
const out = await callSearch();
expect(out.isError).toBeUndefined();
// Body block 0 stays the bare array (deployed thin-clients parse only this).
expect(JSON.parse(out.content[0].text)).toEqual([]);
// D8: the model-visible diagnosis block, then F3's degraded_recall notice
// (agent contract v1: a recall-affecting stage always rides a notice).
// F2: the keyword count line rides right after the rows, before the notices.
// GBRA-200: the degraded stamp is the last block and `_meta.degraded`.
expect(out.content.length).toBe(5);
expect(out.content[1].text).toStartWith('[gbrain search] Rows are a ranked top-K');
expect(out.content[3].text).toStartWith('[gbrain notice degraded_recall kind=degraded]');
expect(out.content[4].text).toStartWith('[gbrain degraded: embed_unavailable]');
expect((out._meta as Record<string, any>).degraded).toEqual({ reasons: ['embed_unavailable'] });
expect(out.content[2].text).toContain('0 results');
expect(out.content[2].text).toContain('retrieved 3');
expect(out.content[2].text).toContain('degraded: embed_unavailable');
const retrieval = (out._meta as Record<string, any>).retrieval;
expect(retrieval.returned_count).toBe(0);
expect(retrieval.retrieved_count).toBe(3);
expect(retrieval.degraded).toEqual([{ stage: 'embed_unavailable' }]);
});
test('clean miss → second block says retrieval healthy, degraded absent', async () => {
nextResults = [];
nextMeta = { vector_enabled: true, expansion_applied: false, detail_resolved: null };
const out = await callSearch();
expect(out.content.length).toBe(3);
expect(out.content[1].text).toContain('Keyword matches: 0 pages');
expect(out.content[2].text).toContain('retrieval healthy');
const retrieval = (out._meta as Record<string, any>).retrieval;
expect(retrieval.degraded).toBeUndefined();
expect(retrieval.vector_enabled).toBe(true);
expect((out._meta as Record<string, any>).degraded).toBeUndefined();
});
test('non-empty results → body + degraded_recall notice only, _meta.retrieval still present (D3: on ALL responses)', async () => {
nextResults = [{ page_id: 1, source_id: 'default', slug: 'a', chunk_text: 'x' }];
nextMeta = DEGRADED_META;
const out = await callSearch();
// No empty-retrieval block; F3's degraded notice rides every affected HTTP call.
expect(out.content.length).toBe(4);
expect(out.content[1].text).toStartWith('[gbrain search] Rows are a ranked top-K');
expect(out.content[2].text).toStartWith('[gbrain notice degraded_recall kind=degraded]');
expect(out.content[3].text).toStartWith('[gbrain degraded: embed_unavailable]');
const retrieval = (out._meta as Record<string, any>).retrieval;
expect(retrieval.returned_count).toBe(1);
});
test('metaHook failure never drops the retrieval key (per-key isolation)', async () => {
nextResults = [];
nextMeta = DEGRADED_META;
const out = await callSearch(async () => { throw new Error('hot memory down'); });
expect((out._meta as Record<string, any>).retrieval).toBeDefined();
});
test('metaHook keys merge alongside retrieval, not over it', async () => {
nextResults = [];
nextMeta = DEGRADED_META;
const out = await callSearch(async () => ({ brain_hot_memory: { facts: [] } }));
const meta = out._meta as Record<string, any>;
expect(meta.retrieval).toBeDefined();
expect(meta.brain_hot_memory).toEqual({ facts: [] });
});
});
describe('buildEmptyRetrievalBlock (unit)', () => {
test('a ranking-only stage (reranker_skipped) never impairs recall → still a clean miss', async () => {
const { buildEmptyRetrievalBlock } = await import('../src/mcp/dispatch.ts');
const out = buildEmptyRetrievalBlock({ retrieved_count: 0, degraded: [{ stage: 'reranker_skipped', reason: 'no_key' }] });
expect(out).toContain('retrieval healthy');
expect(out).not.toContain('reranker_skipped');
const mixed = buildEmptyRetrievalBlock({ retrieved_count: 0, degraded: [{ stage: 'reranker_skipped' }, { stage: 'embed_unavailable', reason: 'no_provider' }] });
expect(mixed).toContain('degraded: embed_unavailable.');
});
test('hint passthrough + stage dedupe + garbage tolerance', async () => {
const { buildEmptyRetrievalBlock } = await import('../src/mcp/dispatch.ts');
const text = buildEmptyRetrievalBlock({
retrieved_count: 5,
degraded: [{ stage: 'embed_timeout' }, { stage: 'embed_timeout' }, { stage: 'budget_dropped_all' }],
hint: 'try the query tool.',
});
expect(text).toContain('retrieved 5');
expect(text).toContain('degraded: embed_timeout, budget_dropped_all');
expect(text).toContain('hint: try the query tool.');
expect((text!.match(/embed_timeout/g) ?? []).length).toBe(1);
expect(buildEmptyRetrievalBlock(null)).toBeNull();
expect(buildEmptyRetrievalBlock('nope')).toBeNull();
});
});