Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* E2E for the "standalone from nothing" funnel: `gbrain init --pglite` →
* `gbrain serve` (stdio) wired into a coding agent as an MCP subprocess.
*
* This is the canonical local path the docs encourage for Claude Code / Codex
* users with no remote brain:
*
* claude mcp add gbrain -- gbrain serve
* codex mcp add gbrain -- gbrain serve
*
* The `connect`/bearer E2E proves the REMOTE (HTTP) funnel. Nothing proved the
* LOCAL stdio funnel end-to-end: that a freshly-init'd PGLite brain, served
* over stdio, actually answers real MCP `tools/call`s through the official MCP
* SDK client (the same handshake Claude Code / Codex perform). The
* serve-stdio-lifecycle unit test only covers shutdown signalling.
*
* No Postgres / Docker. PGLite, hermetic temp HOME. Drives the real
* StdioClientTransport, so the MCP SDK spawns `gbrain serve` for us, runs the
* `initialize` handshake, and round-trips `tools/list` + `tools/call`.
*
* The second session (v0.45.7) covers `gbrain serve --surface verbs`: the
* frozen 7-verb MEMORY_VERBS surface over the same real stdio transport —
* exact tool list, the two ambient-recall verbs (context_pack + delta),
* fail-closed dispatch on hidden ops, and the delta session cursor advancing
* across two wakes.
*
* Lane: unit. Run: `bun test test/serve-stdio-roundtrip.test.ts`. Moved from test/e2e/
* by the 2026-09 lane-move pilot (PGLite-only, no DATABASE_URL); see
* docs/test-audit/2026-09-29/implementation/lane-pilot.md.
*/
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { spawnSync } from 'child_process';
import { keylessBrainEnv } from './helpers/provider-env.ts';
import { cliDiagnostic, toolDiagnostic } from './helpers/fixture-diagnostics.ts';
import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { VERB_NAMES } from '../src/core/verbs.ts';
import { contractFor } from './helpers/instructions-parity.ts';
function execFixture(args: string[], env: Record<string, string>): void {
const result = spawnSync('bun', ['--no-env-file', ...args], { cwd: process.cwd(), env, encoding: 'utf8' });
if (result.status !== 0) throw new Error(cliDiagnostic(args[2] ?? 'stdio fixture', {
exitCode: result.status ?? -1, stdout: result.stdout ?? '', stderr: result.stderr ?? '',
}));
}
// Distinctive token so keyword search can't accidentally match anything else.
const MARKER = 'qantani-marker-9f3z';
const FEDERATED_MARKER = 'umbriel-federated-marker-71c4';
/** The result body: content[0] (agent contract v1 — notice blocks ride after it). */
function textOf(result: unknown): string {
const content = (result as { content?: Array<{ type?: string; text?: string }> })?.content;
if (!Array.isArray(content)) return '';
return typeof content[0]?.text === 'string' ? content[0].text : '';
}
function resultSourceIds(text: string): string[] {
const result = JSON.parse(text) as Array<{ source_id?: unknown }>;
return result.flatMap((row) => (typeof row.source_id === 'string' ? [row.source_id] : []));
}
describe('serve stdio round-trip E2E (local PGLite → real MCP tool calls)', () => {
let home: string;
let client: Client | null = null;
let transport: StdioClientTransport | null = null;
let connected = false;
beforeAll(async () => {
home = mkdtempSync(join(tmpdir(), 'gbrain-stdio-e2e-'));
// Hermetic PGLite: strip any ambient Postgres URL so `init --pglite` and the
// served brain actually use PGLite even when the shell/CI has DATABASE_URL
// set (otherwise the subprocess comes up on Postgres → `engine: pglite`
// assertion fails).
// Build a concrete Record<string,string> (StdioClientTransport.env rejects
// undefined values), dropping the ambient DB URLs so the subprocess is PGLite.
const env = keylessBrainEnv(process.env, home, {
DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined, GBRAIN_REMOTE_CLIENT_SECRET: undefined,
});
delete env.GBRAIN_SOURCE;
// 1. Init a local PGLite brain (the "from nothing" step).
execFixture(['run', 'src/cli.ts', 'init', '--pglite', '--no-embedding', '--non-interactive'], env);
// 2. Seed one page so page_count > 0 and search has something to find.
// --no-embed keeps it hermetic (no embedding provider configured); the
// keyword path still finds the distinctive marker.
const notes = join(home, 'notes');
mkdirSync(notes, { recursive: true });
writeFileSync(
join(notes, 'marker.md'),
`---\ntitle: ${MARKER} note\n---\n\n# ${MARKER}\n\nThis page exists to prove ${MARKER} is retrievable over stdio MCP.\n`,
);
execFixture(['run', 'src/cli.ts', 'import', notes, '--no-embed'], env);
// Seed a second source that participates in unqualified federated reads.
// Import through the CLI so this uses the ordinary source registration
// and page-routing path.
const federatedNotes = join(home, 'federated-notes');
mkdirSync(federatedNotes, { recursive: true });
writeFileSync(
join(federatedNotes, 'marker.md'),
`---\ntitle: ${FEDERATED_MARKER} note\n---\n\n# ${FEDERATED_MARKER}\n\nThis page exists only in the federated source.\n`,
);
execFixture(['run', 'src/cli.ts', 'sources', 'add', 'federated-source', '--path', federatedNotes, '--federated', '--force'], env);
execFixture(['run', 'src/cli.ts', 'import', federatedNotes, '--no-embed', '--source-id', 'federated-source'], env);
// 3. Let the MCP SDK spawn `gbrain serve` (stdio) and run the initialize
// handshake with the opt-in idle timeout enabled. This pins the
// production wrapper shape that previously let the timeout's activity
// listener consume initialize before the SDK transport attached.
transport = new StdioClientTransport({
command: 'bun',
args: ['--no-env-file', 'run', 'src/cli.ts', 'serve', '--stdio-idle-timeout', '14400'],
cwd: process.cwd(),
env, // includes PATH (to find `bun`) + GBRAIN_HOME
});
client = new Client({ name: 'gbrain-stdio-e2e', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport);
connected = true;
}, 60_000);
afterAll(async () => {
if (client) { try { await client.close(); } catch { /* best-effort */ } }
if (transport) { try { await transport.close(); } catch { /* best-effort */ } }
if (home) { try { rmSync(home, { recursive: true, force: true }); } catch { /* best-effort */ } }
});
test('initialize handshake + tools/list exposes the core retrieval tools', async () => {
expect(connected).toBe(true);
const { tools } = await client!.listTools();
const names = new Set(tools.map((t) => t.name));
// F1: the contract for exactly this connection's tools/list (+ readiness tail).
expect(client!.getInstructions()).toStartWith(contractFor(names));
// The core MCP tools the connect LEARN_INSTRUCTION promises always work.
// `capture` earned its MCP slot in the CLI-to-MCP gap-closure wave: the
// LEARN_INSTRUCTION names it, so tools/list parity requires it advertised
// (regression guard against re-demoting it to a CLI-only wrapper).
for (const core of ['search', 'query', 'get_page', 'put_page', 'get_brain_identity', 'think', 'find_experts']) {
expect(names.has(core)).toBe(true);
}
expect(names.has('capture')).toBe(true); // MCP-advertised since the gap-closure wave
}, 30_000);
test('tools/call get_brain_identity returns version + engine + a populated counter', async () => {
expect(connected).toBe(true);
const res = await client!.callTool({ name: 'get_brain_identity', arguments: {} });
const text = textOf(res);
const id = JSON.parse(text) as { version: string; engine: string; page_count: number };
expect(typeof id.version).toBe('string');
expect(id.engine).toBe('pglite');
expect(id.page_count).toBeGreaterThanOrEqual(1); // the seeded page
}, 30_000);
test('tools/call search surfaces the seeded page (keyword path, no embeddings)', async () => {
expect(connected).toBe(true);
const res = await client!.callTool({ name: 'search', arguments: { query: MARKER, limit: 5 } });
const text = textOf(res);
// The result payload (slug / title / snippet) must mention the marker.
expect(text).toContain(MARKER);
}, 30_000);
test('query treats an explicit __all__ like an omitted source in federated stdio', async () => {
expect(connected).toBe(true);
const args = { query: FEDERATED_MARKER, expand: false, limit: 5 };
const omitted = textOf(await client!.callTool({ name: 'query', arguments: args }));
const explicitAll = textOf(await client!.callTool({
name: 'query',
arguments: { ...args, source_id: '__all__' },
}));
const explicitDefault = textOf(await client!.callTool({
name: 'query',
arguments: { ...args, source_id: 'default' },
}));
expect(omitted).toContain(FEDERATED_MARKER);
expect(explicitAll).toContain(FEDERATED_MARKER);
expect(explicitDefault).not.toContain(FEDERATED_MARKER);
expect(resultSourceIds(omitted)).toContain('federated-source');
expect(resultSourceIds(explicitAll)).toContain('federated-source');
expect(resultSourceIds(explicitDefault)).not.toContain('federated-source');
}, 30_000);
});
// Distinct marker for the verbs-surface session (own temp brain, own token).
const VERBS_MARKER = 'veridian-verbs-7q2x';
describe('serve --surface verbs stdio E2E (the 7 frozen memory verbs over a real MCP session)', () => {
let home: string;
let client: Client | null = null;
let transport: StdioClientTransport | null = null;
let connected = false;
beforeAll(async () => {
home = mkdtempSync(join(tmpdir(), 'gbrain-stdio-verbs-e2e-'));
// Same hermetic-PGLite env dance as the full-surface session above.
const env = keylessBrainEnv(process.env, home, {
DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined, GBRAIN_REMOTE_CLIENT_SECRET: undefined,
});
// Quiescent brain: the startup sweep could touch pages BETWEEN the two
// delta wakes and legitimately re-surface them (a changed page is SUPPOSED
// to re-appear), turning the cursor-advance assertion flaky. Kill switch
// keeps the only writers the test's own tool calls.
env.GBRAIN_SWEEP = '0';
// 1. Init a local PGLite brain.
execFixture(['run', 'src/cli.ts', 'init', '--pglite', '--no-embedding', '--non-interactive'], env);
// 2. Seed two pages BEFORE serve spawns so the first delta wake has pages
// to deliver (the cursor-advance assertion needs a non-empty delivery).
const notes = join(home, 'notes');
mkdirSync(notes, { recursive: true });
writeFileSync(
join(notes, 'pack-a.md'),
`---\ntitle: ${VERBS_MARKER} alpha\n---\n\n# ${VERBS_MARKER} alpha\n\nSeed page A for the verbs-surface delta cursor.\n`,
);
writeFileSync(
join(notes, 'pack-b.md'),
`---\ntitle: ${VERBS_MARKER} beta\n---\n\n# ${VERBS_MARKER} beta\n\nSeed page B for the verbs-surface delta cursor.\n`,
);
execFixture(['run', 'src/cli.ts', 'import', notes, '--no-embed'], env);
// 3. Spawn the QUICKSTART surface — exactly the 7 protocol verbs.
transport = new StdioClientTransport({
command: 'bun',
args: ['--no-env-file', 'run', 'src/cli.ts', 'serve', '--surface', 'verbs'],
cwd: process.cwd(),
env,
});
client = new Client({ name: 'gbrain-stdio-verbs-e2e', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport);
connected = true;
}, 60_000);
afterAll(async () => {
if (client) { try { await client.close(); } catch { /* best-effort */ } }
if (transport) { try { await transport.close(); } catch { /* best-effort */ } }
if (home) { try { rmSync(home, { recursive: true, force: true }); } catch { /* best-effort */ } }
});
test('tools/list advertises EXACTLY the 7 frozen verbs — nothing more, nothing less', async () => {
expect(connected).toBe(true);
const { tools } = await client!.listTools();
const names = tools.map((t) => t.name).sort();
expect(names).toEqual([...VERB_NAMES].sort());
}, 30_000);
test('tools/call context_pack on an unknown entity → schema-valid empty pack, protocol_version 1', async () => {
expect(connected).toBe(true);
const res = await client!.callTool({ name: 'context_pack', arguments: { entities: 'nonexistent-entity' } });
expect((res as { isError?: boolean }).isError, toolDiagnostic("verbs roundtrip", res)).not.toBe(true);
const pack = JSON.parse(textOf(res)) as {
protocol_version: number;
entities: string[];
cards: unknown[];
open_threads: unknown[];
facts: unknown[];
text: string;
};
expect(pack.protocol_version).toBe(1);
// The handler echoes the CAPPED entity list even when nothing resolves.
expect(pack.entities).toEqual(['nonexistent-entity']);
expect(Array.isArray(pack.cards)).toBe(true);
expect(pack.cards.length).toBe(0); // unknown entity → no card, no error
expect(Array.isArray(pack.open_threads)).toBe(true);
expect(Array.isArray(pack.facts)).toBe(true);
expect(typeof pack.text).toBe('string');
}, 30_000);
test('tools/call delta with an explicit epoch cursor → protocol_version 1 + has_more + next_cursor', async () => {
expect(connected).toBe(true);
const res = await client!.callTool({ name: 'delta', arguments: { since: '1970-01-01T00:00:00Z' } });
expect((res as { isError?: boolean }).isError, toolDiagnostic("verbs roundtrip", res)).not.toBe(true);
const d = JSON.parse(textOf(res)) as {
protocol_version: number;
since: string;
pages: Array<{ slug: string; title: string; updated_at: string }>;
facts: unknown[];
threads: unknown[];
has_more: boolean;
next_cursor: { since: string; slug: string };
};
expect(d.protocol_version).toBe(1);
// `since` is NORMALIZED to ISO before it reaches rendering (red-team F4).
expect(d.since).toBe('1970-01-01T00:00:00.000Z');
expect(typeof d.has_more).toBe('boolean');
expect(typeof d.next_cursor.since).toBe('string');
expect(typeof d.next_cursor.slug).toBe('string');
// From the epoch, both seeded pages are "changed since".
const titles = d.pages.map((p) => p.title).join('\n');
expect(titles).toContain(`${VERBS_MARKER} alpha`);
expect(titles).toContain(`${VERBS_MARKER} beta`);
}, 30_000);
test('hidden op stays fail-closed: tools/call list_pages returns the unknown_tool envelope', async () => {
expect(connected).toBe(true);
// list_pages exists in the full catalog but is NOT a verb — surface
// enforcement must reject it at dispatch (codex c2), with the same
// envelope as a truly unknown op so the surface doesn't leak names.
const res = await client!.callTool({ name: 'list_pages', arguments: {} });
expect((res as { isError?: boolean }).isError).toBe(true);
const err = JSON.parse(textOf(res)) as { error: string; message: string };
expect(err.error).toBe('unknown_tool');
expect(err.message).toContain('list_pages');
}, 30_000);
test('remember → delta ×2 with one session_id: the cursor advances (no page re-delivery)', async () => {
expect(connected).toBe(true);
const SESSION = 'verbs-e2e-session-1';
// Write through the protocol write verb — proves the verbs surface carries
// writes over stdio and gives the first wake a fact to deliver.
const remembered = await client!.callTool({
name: 'remember',
arguments: {
fact: `${VERBS_MARKER} chose PGLite for the verbs-surface e2e`,
provenance: 'e2e: serve-stdio-roundtrip',
},
});
expect((remembered as { isError?: boolean }).isError, toolDiagnostic("remember roundtrip", remembered)).not.toBe(true);
const rem = JSON.parse(textOf(remembered)) as { id: string; status: string; protocol_version: number };
expect(rem.protocol_version).toBe(1);
expect(['inserted', 'duplicate', 'superseded']).toContain(rem.status);
expect(typeof rem.id).toBe('string');
// delta never advances a cursor past now() - 2 s (commit-visibility lag), so
// let the seeded pages age past it; otherwise wake 2 re-delivers them once.
await new Promise((r) => setTimeout(r, 2_100));
// Wake 1: explicit epoch cursor + session_id — delivers every seeded page
// and establishes the per-session keyset cursor server-side.
const first = await client!.callTool({
name: 'delta',
arguments: { since: '1970-01-01T00:00:00Z', session_id: SESSION },
});
const d1 = JSON.parse(textOf(first)) as {
protocol_version: number;
pages: Array<{ slug: string }>;
facts: Array<{ fact: string }>;
has_more: boolean;
};
expect(d1.protocol_version).toBe(1);
expect(d1.pages.length).toBeGreaterThanOrEqual(2); // the seeded pages
expect(d1.has_more).toBe(false); // tiny brain: everything fits in one wake
// The remembered fact (world visibility) rides the facts arm.
expect(d1.facts.some((f) => f.fact.includes(VERBS_MARKER))).toBe(true);
// Wake 2: session_id ONLY — the stored cursor must exclude everything
// wake 1 delivered (keyset advance over the real transport, red-team F2:
// a delivered page never re-appears unless it changes).
const second = await client!.callTool({ name: 'delta', arguments: { session_id: SESSION } });
const d2 = JSON.parse(textOf(second)) as { protocol_version: number; pages: Array<{ slug: string }> };
expect(d2.protocol_version).toBe(1);
const delivered = new Set(d1.pages.map((p) => p.slug));
for (const pg of d2.pages) expect(delivered.has(pg.slug)).toBe(false);
expect(d2.pages.length).toBe(0); // nothing changed between wakes
}, 30_000);
});