Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.34 W3 — MCP exposure of code-intel ops.
*
* Pre-v0.34 code-callers / code-callees / code-def / code-refs lived in
* CLI_ONLY at cli.ts:30. Agents calling gbrain via MCP couldn't reach
* them and fell through to text search.
*
* This E2E pins:
* - All four ops appear in the operations registry with scope:'read'.
* - Tool descriptions match the constants in operations-descriptions.ts
* so the LLM tool-selection prompt sees the right wording (D10 fix).
* - Each op routes to the right engine method / library function and
* returns the documented envelope shape.
* - Source scoping honors ctx.sourceId and the per-call source_id /
* all_sources params.
*
* PGLite in-memory.
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
import { operations, operationsByName } from '../../src/core/operations.ts';
import {
CODE_CALLERS_DESCRIPTION,
CODE_CALLEES_DESCRIPTION,
CODE_DEF_DESCRIPTION,
CODE_REFS_DESCRIPTION,
} from '../../src/core/operations-descriptions.ts';
import { resetPgliteState } from '../helpers/reset-pglite.ts';
import type { GBrainConfig } from '../../src/core/config.ts';
import type { Logger } from '../../src/core/operations.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);
});
describe('v0.34 W3 — code-intel MCP ops registered', () => {
test('code_callers exists with scope:read and v0.34 description', () => {
expect(operationsByName.code_callers).toBeDefined();
expect(operationsByName.code_callers!.scope).toBe('read');
expect(operationsByName.code_callers!.description).toStartWith(CODE_CALLERS_DESCRIPTION);
});
test('code_callees exists with scope:read and v0.34 description', () => {
expect(operationsByName.code_callees).toBeDefined();
expect(operationsByName.code_callees!.scope).toBe('read');
expect(operationsByName.code_callees!.description).toStartWith(CODE_CALLEES_DESCRIPTION);
});
test('code_def exists with scope:read and v0.34 description', () => {
expect(operationsByName.code_def).toBeDefined();
expect(operationsByName.code_def!.scope).toBe('read');
expect(operationsByName.code_def!.description).toStartWith(CODE_DEF_DESCRIPTION);
});
test('code_refs exists with scope:read and v0.34 description', () => {
expect(operationsByName.code_refs).toBeDefined();
expect(operationsByName.code_refs!.scope).toBe('read');
expect(operationsByName.code_refs!.description).toStartWith(CODE_REFS_DESCRIPTION);
});
test('all four code_* ops have a symbol param marked required', () => {
for (const opName of ['code_callers', 'code_callees', 'code_def', 'code_refs']) {
const op = operationsByName[opName];
expect(op).toBeDefined();
expect(op!.params.symbol).toBeDefined();
expect(op!.params.symbol!.required).toBe(true);
}
});
});
describe('v0.34 W3 — code_callers / code_callees route to the engine', () => {
test('code_callers finds direct callers', async () => {
await seedTwoFileGraph(engine);
const ctx = makeCtx(engine, 'source-a');
const op = operationsByName.code_callers!;
const result = (await op.handler(ctx, { symbol: 'parseMarkdown' })) as {
symbol: string;
count: number;
callers: Array<{ from_symbol_qualified: string; to_symbol_qualified: string }>;
};
expect(result.symbol).toBe('parseMarkdown');
expect(result.count).toBeGreaterThanOrEqual(1);
const fromNames = result.callers.map((c) => c.from_symbol_qualified);
expect(fromNames).toContain('callerInA');
});
test('code_callees finds direct callees', async () => {
await seedTwoFileGraph(engine);
const ctx = makeCtx(engine, 'source-a');
const op = operationsByName.code_callees!;
const result = (await op.handler(ctx, { symbol: 'callerInA' })) as {
symbol: string;
count: number;
callees: Array<{ from_symbol_qualified: string; to_symbol_qualified: string }>;
};
expect(result.symbol).toBe('callerInA');
expect(result.count).toBeGreaterThanOrEqual(1);
const toNames = result.callees.map((c) => c.to_symbol_qualified);
expect(toNames).toContain('parseMarkdown');
});
// #4670: the op promises "bare or qualified name". Nested chunks (C# namespace
// + class, TS class methods, ...) carry a QUALIFIED from_symbol_qualified, so
// the bare method name used to return count 0 while the qualified form and
// code_callers on the bare callee both worked.
test('code_callees honors the documented bare-name contract for a qualified chunk (#4670)', async () => {
await seedQualifiedMethodGraph(engine);
const ctx = makeCtx(engine, 'source-a');
const op = operationsByName.code_callees!;
const bare = (await op.handler(ctx, { symbol: 'SubmitAsync' })) as {
count: number;
callees: Array<{ from_symbol_qualified: string; to_symbol_qualified: string }>;
};
expect(bare.count).toBe(1);
expect(bare.callees[0]!.from_symbol_qualified).toBe('MyApp.Services.OrderService.SubmitAsync');
expect(bare.callees[0]!.to_symbol_qualified).toBe('ValidateRequest');
// Qualified input is unchanged.
const qualified = (await op.handler(ctx, { symbol: 'MyApp.Services.OrderService.SubmitAsync' })) as { count: number };
expect(qualified.count).toBe(1);
// No substring leakage.
const partial = (await op.handler(ctx, { symbol: 'Async' })) as { count: number };
expect(partial.count).toBe(0);
});
});
describe('v0.34 W3 — code_callers source scoping', () => {
test('honors ctx.sourceId by default', async () => {
await seedCrossSourceGraph(engine);
const ctx = makeCtx(engine, 'source-a');
const op = operationsByName.code_callers!;
const result = (await op.handler(ctx, { symbol: 'parseMarkdown' })) as {
callers: Array<{ source_id: string | null }>;
};
// Should only see callers from source-a; source-b's caller MUST NOT leak
for (const c of result.callers) {
expect(c.source_id === 'source-a' || c.source_id === null).toBe(true);
}
});
test('all_sources=true forces cross-source', async () => {
await seedCrossSourceGraph(engine);
const ctx = makeCtx(engine, 'source-a');
const op = operationsByName.code_callers!;
const result = (await op.handler(ctx, { symbol: 'parseMarkdown', all_sources: true })) as {
callers: Array<{ source_id: string | null }>;
};
const sources = new Set(result.callers.map((c) => c.source_id));
// Both sources represented when all_sources is set
expect(sources.has('source-a')).toBe(true);
expect(sources.has('source-b')).toBe(true);
});
test("source_id='__all__' is equivalent to all_sources=true", async () => {
await seedCrossSourceGraph(engine);
const ctx = makeCtx(engine, 'source-a');
const op = operationsByName.code_callers!;
const result = (await op.handler(ctx, { symbol: 'parseMarkdown', source_id: '__all__' })) as {
callers: Array<{ source_id: string | null }>;
};
const sources = new Set(result.callers.map((c) => c.source_id));
expect(sources.has('source-a')).toBe(true);
expect(sources.has('source-b')).toBe(true);
});
});
describe('#4011 — graph ops re-route to the code-bearing federated source', () => {
test('remote code_callers is temporarily suspended before federated rerouting', async () => {
// Vault+code brain: the caller's scalar scope ('default') holds no code;
// the graph lives entirely in 'code-src'. Pre-#4011 the traversal stayed
// on 'default' and readiness honestly reported not_built — masking a
// fully built graph that code_def / code_refs could already see.
await registerSource(engine, 'default');
await registerSource(engine, 'code-src');
const defPage = await insertCodePage(engine, 'code-src', 'src/foo.ts');
const callerPage = await insertCodePage(engine, 'code-src', 'src/caller.ts');
await insertChunk(engine, defPage, 0, 'parseMarkdown', 'function');
const callerChunk = await insertChunk(engine, callerPage, 0, 'callerInCode', 'function');
await insertUnresolvedEdge(engine, callerChunk, 'callerInCode', 'parseMarkdown', 'code-src');
const ctx = {
...makeCtx(engine, 'default'),
remote: true,
localFederatedSourceIds: ['default', 'code-src'],
};
await expect(operationsByName.code_callers!.handler(ctx, { symbol: 'parseMarkdown' })).rejects.toMatchObject({
code: 'permission_denied', message: expect.stringContaining('temporarily unavailable'),
});
});
});
describe('v0.34 W3 — code_def finds definition sites', () => {
test('returns a definition for a seeded function symbol', async () => {
await seedDefSite(engine);
const ctx = makeCtx(engine, 'source-a');
const op = operationsByName.code_def!;
const result = (await op.handler(ctx, { symbol: 'parseMarkdown' })) as {
symbol: string;
count: number;
defs: Array<{ slug: string; symbol_type: string | null }>;
};
expect(result.symbol).toBe('parseMarkdown');
expect(result.count).toBe(1);
expect(result.defs[0]!.symbol_type).toBe('function');
});
});
describe('#1780 Gap 1 — readiness envelope on code_* ops', () => {
test('code_callers carries status:ready when callers are found', async () => {
await seedTwoFileGraph(engine);
const ctx = makeCtx(engine, 'source-a');
const result = (await operationsByName.code_callers!.handler(ctx, { symbol: 'parseMarkdown' })) as {
count: number; status: string; ready: boolean;
};
expect(result.count).toBeGreaterThanOrEqual(1);
expect(result.status).toBe('ready');
expect(result.ready).toBe(true);
});
test('code_callers → indexing when code exists but edges unresolved + no callers', async () => {
// callerInA has no callers; seeded chunks have edges_backfilled_at = NULL.
await seedTwoFileGraph(engine);
const ctx = makeCtx(engine, 'source-a');
const result = (await operationsByName.code_callers!.handler(ctx, { symbol: 'callerInA' })) as {
count: number; status: string; ready: boolean;
};
expect(result.count).toBe(0);
expect(result.status).toBe('indexing');
expect(result.ready).toBe(false);
});
test('code_def → not_built on an empty brain', async () => {
const ctx = makeCtx(engine, 'source-a');
const result = (await operationsByName.code_def!.handler(ctx, { symbol: 'anything' })) as {
count: number; status: string; ready: boolean;
};
expect(result.count).toBe(0);
expect(result.status).toBe('not_built');
expect(result.ready).toBe(false);
});
test('code_def → ready when a definition exists (brain-wide)', async () => {
await seedDefSite(engine);
const ctx = makeCtx(engine, 'source-a');
const result = (await operationsByName.code_def!.handler(ctx, { symbol: 'parseMarkdown' })) as {
count: number; status: string; ready: boolean;
};
expect(result.count).toBe(1);
expect(result.status).toBe('ready');
expect(result.ready).toBe(true);
});
test('code_refs → not_built on an empty brain', async () => {
const ctx = makeCtx(engine, 'source-a');
const result = (await operationsByName.code_refs!.handler(ctx, { symbol: 'anything' })) as {
count: number; status: string; ready: boolean;
};
expect(result.status).toBe('not_built');
expect(result.ready).toBe(false);
});
});
// ─────────────────────────────────────────────────────────────────
// Fixtures
// ─────────────────────────────────────────────────────────────────
async function seedTwoFileGraph(engine: PGLiteEngine): Promise<void> {
await registerSource(engine, 'source-a');
const pageA = await insertCodePage(engine, 'source-a', 'src/foo.ts');
const pageA2 = await insertCodePage(engine, 'source-a', 'src/caller.ts');
await insertChunk(engine, pageA, 0, 'parseMarkdown', 'function');
const callerChunk = await insertChunk(engine, pageA2, 0, 'callerInA', 'function');
await insertUnresolvedEdge(engine, callerChunk, 'callerInA', 'parseMarkdown', 'source-a');
}
// #4670: one C#-shaped chunk whose identity is namespace-qualified while its
// only call edge is emitted bare (edge-extractor keeps the trailing identifier).
async function seedQualifiedMethodGraph(engine: PGLiteEngine): Promise<void> {
await registerSource(engine, 'source-a');
const page = await insertCodePage(engine, 'source-a', 'src/Services/OrderService.cs');
const rows = await engine.executeRaw<{ id: number }>(
`INSERT INTO content_chunks (page_id, chunk_index, chunk_text, chunk_source, language, symbol_name, symbol_name_qualified, symbol_type)
VALUES ($1, 0, 'public async Task SubmitAsync() { ValidateRequest(); }', 'compiled_truth', 'c_sharp', 'SubmitAsync', 'MyApp.Services.OrderService.SubmitAsync', 'method')
RETURNING id`,
[page],
);
await insertUnresolvedEdge(engine, rows[0]!.id, 'MyApp.Services.OrderService.SubmitAsync', 'ValidateRequest', 'source-a');
await engine.executeRaw('UPDATE pages SET text_projection_revision=knowledge_revision WHERE id=$1', [page]);
}
async function seedCrossSourceGraph(engine: PGLiteEngine): Promise<void> {
await registerSource(engine, 'source-a');
await registerSource(engine, 'source-b');
// Source A: callerInA → parseMarkdown
const pageA = await insertCodePage(engine, 'source-a', 'src/foo.ts');
const pageA2 = await insertCodePage(engine, 'source-a', 'src/caller.ts');
await insertChunk(engine, pageA, 0, 'parseMarkdown', 'function');
const callerA = await insertChunk(engine, pageA2, 0, 'callerInA', 'function');
await insertUnresolvedEdge(engine, callerA, 'callerInA', 'parseMarkdown', 'source-a');
// Source B: callerInB → parseMarkdown (same symbol name, different source)
const pageB = await insertCodePage(engine, 'source-b', 'src/foo.ts');
const pageB2 = await insertCodePage(engine, 'source-b', 'src/caller.ts');
await insertChunk(engine, pageB, 0, 'parseMarkdown', 'function');
const callerB = await insertChunk(engine, pageB2, 0, 'callerInB', 'function');
await insertUnresolvedEdge(engine, callerB, 'callerInB', 'parseMarkdown', 'source-b');
}
async function seedDefSite(engine: PGLiteEngine): Promise<void> {
await registerSource(engine, 'source-a');
const pageA = await insertCodePage(engine, 'source-a', 'src/foo.ts');
// code-def reads content_chunks.symbol_name (not symbol_name_qualified).
// Set both to be safe.
await engine.executeRaw(
`INSERT INTO content_chunks (page_id, chunk_index, chunk_text, chunk_source, language, symbol_name, symbol_name_qualified, symbol_type, start_line, end_line)
VALUES ($1, 0, 'export function parseMarkdown(s: string) { return s; }', 'compiled_truth', 'typescript', 'parseMarkdown', 'parseMarkdown', 'function', 1, 3)`,
[pageA],
);
await engine.executeRaw('UPDATE pages SET text_projection_revision=knowledge_revision WHERE id=$1', [pageA]);
}
async function registerSource(engine: PGLiteEngine, id: string): Promise<void> {
await engine.executeRaw(
`INSERT INTO sources (id, name, local_path, config, created_at)
VALUES ($1, $1, $2, '{}'::jsonb, NOW())
ON CONFLICT (id) DO NOTHING`,
[id, `/fake/${id}`],
);
}
async function insertCodePage(engine: PGLiteEngine, sourceId: string, slug: string): Promise<number> {
const rows = await engine.executeRaw<{ id: number }>(
`INSERT INTO pages (slug, source_id, title, type, page_kind, compiled_truth, frontmatter, updated_at, created_at)
VALUES ($1, $2, $3, 'code', 'code', '', '{}'::jsonb, NOW(), NOW())
RETURNING id`,
[slug, sourceId, slug],
);
return rows[0]!.id;
}
async function insertChunk(
engine: PGLiteEngine,
pageId: number,
chunkIndex: number,
symbolName: string,
symbolType: string,
): Promise<number> {
const rows = await engine.executeRaw<{ id: number }>(
`INSERT INTO content_chunks (page_id, chunk_index, chunk_text, chunk_source, language, symbol_name, symbol_name_qualified, symbol_type)
VALUES ($1, $2, $3, 'compiled_truth', 'typescript', $4, $4, $5)
RETURNING id`,
[pageId, chunkIndex, `// ${symbolName} body`, symbolName, symbolType],
);
await engine.executeRaw('UPDATE pages SET text_projection_revision=knowledge_revision WHERE id=$1', [pageId]);
return rows[0]!.id;
}
async function insertUnresolvedEdge(
engine: PGLiteEngine,
fromChunkId: number,
fromSymbol: string,
toSymbol: string,
sourceId: string,
): Promise<void> {
await engine.executeRaw(
`INSERT INTO code_edges_symbol (from_chunk_id, from_symbol_qualified, to_symbol_qualified, edge_type, source_id, edge_metadata)
VALUES ($1, $2, $3, 'calls', $4, '{}'::jsonb)`,
[fromChunkId, fromSymbol, toSymbol, sourceId],
);
}
function makeCtx(engine: PGLiteEngine, sourceId: string): any {
const logger: Logger = {
info: () => {},
warn: () => {},
error: () => {},
};
return {
engine,
config: {} as GBrainConfig,
logger,
dryRun: false,
remote: false,
sourceId,
};
}