Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Agent operator contract v1 version skew (A1 thin client):
* - old client (frozen copy of v0.60.37.0's parser) × new server: the v1
* goldens parse; the legacy `error`, `suggestion` and receipts survive;
* success bodies stay content[0]-only even with notice blocks.
* - new client × old server: an envelope without `code` gets the canonical
* code derived; nothing is invented.
* - new client × new server: code/reason/why/fix/notices/contract_version
* and receipts are preserved on RemoteMcpError and its toJSON().
*/
import { describe, expect, test } from 'bun:test';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { oldReadError, oldUnpack } from './fixtures/agent-contract/frozen-thin-client-v0.60.37.ts';
import { extractNotices, extractToolErrorDetail, RemoteMcpError, unpackToolResult } from '../src/core/mcp-client.ts';
const golden = (name: string) => JSON.parse(readFileSync(join(import.meta.dir, 'fixtures', 'agent-contract', 'v1', name), 'utf8'));
describe('old client × new server (frozen v0.60.37.0 parser)', () => {
test('error results are one block, so the old join-all parse still reads them', () => {
for (const name of ['error-with-fix.json', 'error-with-notices.json', 'legacy-error-value.json']) {
const res = golden(name);
expect(res.content).toHaveLength(1);
const d = oldReadError(res);
expect(typeof d.code).toBe('string');
expect(typeof d.suggestion).toBe('string');
}
expect(oldReadError(golden('legacy-error-value.json')).code).toBe('unknown_operation');
});
test('receipt-bearing errors keep write_request + write_error for the old client', () => {
const d = oldReadError(golden('receipt-error.json'));
expect(d).toMatchObject({ code: 'write_pending', write_error: 'write_pending' });
expect((d.write_request as { request_id: string }).request_id).toBe('11111111-2222-4333-8444-555555555555');
});
test('success bodies with notice blocks: the old client reads content[0] only', () => {
expect(oldUnpack(golden('bare-array-result.json'))).toEqual([]);
expect(oldUnpack(golden('object-result.json'))).toEqual({ slug: 'notes/alpha-example', title: 'Alpha example' });
});
});
describe('new client', () => {
test('× new server: every v1 field is preserved', () => {
const text = golden('error-with-notices.json').content[0].text;
const d = extractToolErrorDetail(text);
expect(d).toMatchObject({ code: 'unavailable', reason: 'embeddings_disabled', contract_version: 1 });
expect(d.notices?.[0]).toMatchObject({ code: 'backup_coverage', kind: 'safety' });
const json = new RemoteMcpError('tool_error', 'x', d).toJSON() as Record<string, unknown>;
expect(json).toMatchObject({ error: 'unavailable', code: 'unavailable', reason: 'embeddings_disabled', contract_version: 1 });
expect(json.notices).toHaveLength(1);
expect(json.fix).toMatchObject({ command: 'gbrain doctor --json --brain host' });
});
test('× new server: frozen error value and canonical code both survive', () => {
const d = extractToolErrorDetail(golden('legacy-error-value.json').content[0].text);
expect(d).toMatchObject({ code: 'unknown_operation', canonical_code: 'unknown_tool' });
expect(new RemoteMcpError('tool_error', 'x', d).toJSON()).toMatchObject({ error: 'unknown_operation', code: 'unknown_tool' });
});
test('× new server: receipts survive', () => {
const d = extractToolErrorDetail(golden('receipt-error.json').content[0].text);
expect(d.write_request?.request_id).toBe('11111111-2222-4333-8444-555555555555');
expect(d.write_error).toBe('write_pending');
});
test('× old server: code derived from the legacy value; no v1 fields invented', () => {
const d = extractToolErrorDetail(JSON.stringify({ error: 'unknown_operation', message: 'Unknown: x' }));
const json = new RemoteMcpError('tool_error', 'x', d).toJSON() as Record<string, unknown>;
expect(json).toMatchObject({ error: 'unknown_operation', code: 'unknown_tool' });
expect(json).not.toHaveProperty('contract_version');
expect(json).not.toHaveProperty('fix');
});
test('success: body from content[0]; notices from _meta, else from prefixed blocks', () => {
const res = golden('bare-array-result.json');
expect(unpackToolResult<unknown[]>(res)).toEqual([]);
expect(extractNotices(res)[0]).toMatchObject({ code: 'empty_retrieval', kind: 'info' });
const noMeta = { content: res.content };
expect(extractNotices(noMeta)[0]).toMatchObject({ code: 'empty_retrieval', kind: 'info', fix: 'gbrain doctor --json --brain host' });
expect(extractNotices(golden('object-result.json')).length).toBe(0);
});
});