Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.1 KB
Raw Blame
/**
 * 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();
  });
});