Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Unit tests for src/core/onboard/init-nudge.ts (runInitNudge).
*
* runInitNudge fires 6 parallel COUNT probes (stale chunks, entities, linked
* entities, timeline entities, takes, total pages) and prints a one-line
* nudge to stderr. These tests pin the DX-wave behavior:
* - EMPTY brain (pages count 0) → the whole nudge is suppressed, even
* when takes === 0 (no "0 takes" jargon-noise on first init)
* - pages probe REJECTS → fail-open sentinel treats the brain as
* non-empty, so the takes nudge still fires
* - non-empty + healthy + one rejected arm → partial-checks notice
* - non-empty + takes 0 → "0 takes" opportunity nudge
*
* The gate is process.stderr.isTTY (NOT process.env), so monkeypatching it
* here does not trip the serial-isolation rules for env-mutating tests.
* Both isTTY and stderr.write are restored in finally.
*/
import { withEnv } from './helpers/with-env.ts';
import { describe, test, expect } from 'bun:test';
import { runInitNudge } from '../src/core/onboard/init-nudge.ts';
import type { BrainEngine } from '../src/core/engine.ts';
/** Per-probe result: a count, or an Error to make that arm reject. */
interface ProbeCounts {
stale?: number | Error;
entities?: number | Error;
linked?: number | Error;
timeline?: number | Error;
takes?: number | Error;
pages?: number | Error;
}
/**
* Stub engine shaped like { executeRaw: async (sql) => [...] }. Routes each
* of runInitNudge's 6 COUNT queries by a distinctive SQL fragment. Order
* matters: the linked/timeline queries also contain "type IN ('person'",
* so they are matched first.
*/
function stubEngine(counts: ProbeCounts): BrainEngine {
const route = (sql: string): number | Error => {
if (sql.includes('content_chunks')) return counts.stale ?? 0;
if (sql.includes('FROM takes')) return counts.takes ?? 0;
if (sql.includes('FROM links')) return counts.linked ?? 0;
if (sql.includes('timeline_entries')) return counts.timeline ?? 0;
if (sql.includes('p.type = ANY(')) return counts.entities ?? 0;
// 6th probe: SELECT COUNT(*) FROM pages WHERE deleted_at IS NULL
return counts.pages ?? 0;
};
return {
// #4772: the entity counts resolve the active pack first (no overrides: gbrain-base).
getConfig: async () => null,
executeRaw: async (sql: string) => {
if (sql.includes('FROM config c')) return [];
const r = route(sql);
if (r instanceof Error) throw r;
return [{ count: r }];
},
} as unknown as BrainEngine;
}
/**
* Run the nudge with stderr forced to look like a TTY and its writes
* captured. Restores both in finally so no other test sees the patch.
*/
async function runNudgeCaptured(engine: BrainEngine): Promise<string> {
// Agent contract v1 (F7): the nudge is a notice on every surface — stderr
// lines on a terminal, an [AGENT] block on stdout otherwise — so capture both.
const origIsTTY = process.stderr.isTTY;
const origWrite = process.stderr.write;
const origOut = process.stdout.write;
let out = '';
const sink = ((chunk: unknown) => { out += String(chunk); return true; }) as typeof process.stderr.write;
try {
(process.stderr as unknown as { isTTY: boolean }).isTTY = true;
process.stderr.write = sink;
process.stdout.write = sink as typeof process.stdout.write;
await runInitNudge(engine);
} finally {
process.stderr.write = origWrite;
process.stdout.write = origOut;
(process.stderr as unknown as { isTTY: boolean | undefined }).isTTY = origIsTTY;
}
return out;
}
describe('runInitNudge — empty-brain suppression', () => {
test('empty brain (pages 0, takes 0) prints NOTHING', async () => {
const out = await runNudgeCaptured(
stubEngine({ stale: 0, entities: 0, linked: 0, timeline: 0, takes: 0, pages: 0 }),
);
expect(out).toBe('');
});
});
describe('runInitNudge — pages probe failure is fail-open', () => {
test('pages probe REJECTS with takes 0 → nudge still fires with "0 takes"', async () => {
// The -1 sentinel means "count unknown" — treat as non-empty so the
// pre-existing behavior (nudge on 0 takes) is preserved.
const out = await runNudgeCaptured(
stubEngine({
stale: 0,
entities: 0,
linked: 0,
timeline: 0,
takes: 0,
pages: new Error('pages probe failed'),
}),
);
expect(out).toContain('Brain has opportunities');
expect(out).toContain('0 takes');
});
});
describe('runInitNudge — partial-checks notice', () => {
test('non-empty healthy brain with one rejected arm → "Init checks incomplete"', async () => {
// pages > 0 (non-empty), takes > 0 (no opportunity part), entities 0
// (coverage arms vacuous), stale 0 — but the linked probe rejects, so
// partial=true with zero parts → the incomplete-checks line.
const out = await runNudgeCaptured(
stubEngine({
stale: 0,
entities: 0,
linked: new Error('linked probe failed'),
timeline: 0,
takes: 5,
pages: 10,
}),
);
expect(out).toContain('Init checks incomplete');
expect(out).toContain('(5/6)');
expect(out).toContain('gbrain onboard --check');
expect(out).not.toContain('Brain has opportunities');
});
});
describe('runInitNudge — non-empty brain opportunities', () => {
test('non-empty brain with takes 0 → "Brain has opportunities: 0 takes"', async () => {
const out = await runNudgeCaptured(
stubEngine({ stale: 0, entities: 0, linked: 0, timeline: 0, takes: 0, pages: 10 }),
);
expect(out).toContain('Brain has opportunities: 0 takes');
expect(out).toContain("Run 'gbrain onboard --check' to see the plan");
// All 6 probes succeeded — no partial-checks suffix.
expect(out).not.toContain('checks complete');
});
});
describe('runInitNudge — agents get the nudge too (F7)', () => {
test('a non-interactive caller gets an [AGENT] coaching block naming the command', async () => {
const out = await withEnv({ GBRAIN_NON_INTERACTIVE: '1', GBRAIN_INTERACTIVE: undefined }, () => runNudgeCaptured(
stubEngine({ stale: 0, entities: 0, linked: 0, timeline: 0, takes: 0, pages: 10 }),
));
expect(out).toContain('[AGENT]');
expect(out).toContain('[onboard_opportunities]');
expect(out).toContain('gbrain onboard --check');
});
});
describe('shared collector (collectOnboardOpportunities)', () => {
test('init output is byte-identical to the pre-collector nudge', async () => {
const full = await withEnv({ GBRAIN_NON_INTERACTIVE: '1', GBRAIN_INTERACTIVE: undefined }, () => runNudgeCaptured(
stubEngine({ stale: 3, entities: 10, linked: 5, timeline: 2, takes: 0, pages: 20 })));
expect(full).toBe("[AGENT]\nwhy: [onboard_opportunities] Brain has opportunities: 3 stale chunks, link coverage 50%, timeline coverage 20%, 0 takes. Run 'gbrain onboard --check' to see the plan.\nactor: agent\nnext: run: gbrain onboard --check\n[/AGENT]\n");
const partial = await withEnv({ GBRAIN_NON_INTERACTIVE: '1', GBRAIN_INTERACTIVE: undefined }, () => runNudgeCaptured(
stubEngine({ stale: 0, entities: 4, linked: new Error('linked probe failed'), timeline: 4, takes: 2, pages: 9 })));
expect(partial).toBe("[AGENT]\nwhy: [onboard_opportunities] Brain has opportunities: link coverage 0%. Run 'gbrain onboard --check' to see the plan. (5/6 checks complete; run gbrain onboard --check for full recommendations)\nactor: agent\nnext: run: gbrain onboard --check\n[/AGENT]\n");
});
test('sequential (background refresh) and parallel (init) runs return the same counts; a failed probe is null, never a gap', async () => {
const { collectOnboardOpportunities, onboardGaps } = await import('../src/core/onboard/mcp-onboarding.ts');
const engine = stubEngine({ stale: 3, entities: 10, linked: new Error('linked probe failed'), timeline: 2, takes: 0, pages: 20 });
let yields = 0;
const parallel = await collectOnboardOpportunities(engine, new AbortController().signal);
const sequential = await collectOnboardOpportunities(engine, new AbortController().signal, async () => { yields++; });
expect(sequential).toEqual(parallel);
expect(yields).toBe(6);
expect(parallel).toMatchObject({ staleChunks: 3, entities: 10, linkedEntities: null, linkCoverage: null, timelineCoverage: 0.2, takes: 0, pages: 20, partial: true, checksRan: 5, checksAttempted: 6 });
expect(onboardGaps(parallel)).toEqual({ stale_chunks: true, link_coverage: false, timeline_coverage: true, no_takes: true });
});
test('an aborted sequential run stops issuing counts', async () => {
const { collectOnboardOpportunities } = await import('../src/core/onboard/mcp-onboarding.ts');
const controller = new AbortController();
controller.abort();
const counts = await collectOnboardOpportunities(stubEngine({ stale: 1, pages: 2 }), controller.signal, async () => {});
expect(counts.checksRan).toBe(0);
expect(counts.partial).toBe(true);
});
});