Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.31.1 (Issue #734, CDX-4): unit tests for the callRemoteTool hardening
* pass — the internal helpers that ensure every thrown value reaches the
* dispatcher as a typed RemoteMcpError.
*
* Pre-v0.31.1 contract was unsound: callRemoteTool's outermost block did NOT
* normalize all errors; plain Error, AbortError, JSON parse, and undici
* network errors could bubble untyped. The dispatcher's "exhaustive switch on
* RemoteMcpError.reason" was a false promise.
*
* v0.31.1 funnel: every catch in callRemoteTool routes through
* `toRemoteMcpError(e, mcpUrl)`. These tests pin the funnel's behavior so
* the dispatcher's exhaustive switch (in cli.ts:runThinClientRouted) holds.
*/
import { describe, test, expect } from 'bun:test';
import {
toRemoteMcpError,
extractToolErrorCode,
extractToolErrorDetail,
buildAbortController,
buildMcpRequestOptions,
RemoteMcpError,
type CallRemoteToolOptions,
} from '../src/core/mcp-client.ts';
import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
const MCP_URL = 'https://brain-host.example/mcp';
const PENDING_WRITE = { request_id: 'd7599b95-65c2-4d54-aa4e-cb5745af90cf', state: 'queued' as const, retry_after_ms: 1000 };
describe('toRemoteMcpError', () => {
test('passes through existing RemoteMcpError unchanged', () => {
const original = new RemoteMcpError('auth', 'bad creds', { mcp_url: MCP_URL });
const out = toRemoteMcpError(original, MCP_URL);
expect(out).toBe(original);
expect(out.reason).toBe('auth');
});
test('a received write receipt survives a simultaneous transport deadline', () => {
const controller = new AbortController();
controller.abort(new DOMException('deadline', 'TimeoutError'));
const original = new RemoteMcpError('tool_error', 'accepted', { write_request: PENDING_WRITE, write_error: 'write_pending' });
expect(toRemoteMcpError(original, MCP_URL, controller.signal)).toBe(original);
});
test('plain Error becomes network/unreachable', () => {
const err = new Error('ECONNREFUSED 127.0.0.1:3131');
const out = toRemoteMcpError(err, MCP_URL);
expect(out).toBeInstanceOf(RemoteMcpError);
expect(out.reason).toBe('network');
expect(out.detail?.kind).toBe('unreachable');
expect(out.detail?.mcp_url).toBe(MCP_URL);
expect(out.message).toContain('ECONNREFUSED');
});
test('AbortError (by .name) becomes network/aborted', () => {
const err = new Error('operation aborted');
err.name = 'AbortError';
const out = toRemoteMcpError(err, MCP_URL);
expect(out.reason).toBe('network');
expect(out.detail?.kind).toBe('aborted');
});
test('abort text alone does not classify cancellation', () => {
const err = new Error('request was aborted by the user');
const out = toRemoteMcpError(err, MCP_URL);
expect(out.reason).toBe('network');
expect(out.detail?.kind).toBe('unreachable');
});
test('the call signal identifies cancellation even when the SDK wraps its error', () => {
const controller = new AbortController();
controller.abort(new Error('caller stopped'));
const out = toRemoteMcpError(new Error('SDK request failed'), MCP_URL, controller.signal);
expect(out.detail?.kind).toBe('aborted');
});
test('a timeout signal overrides an already-normalized probe failure', () => {
const controller = new AbortController();
controller.abort(new DOMException('deadline', 'TimeoutError'));
const out = toRemoteMcpError(new RemoteMcpError('network', 'probe failed'), MCP_URL, controller.signal);
expect(out.detail?.kind).toBe('timeout');
});
test('SDK RequestTimeout becomes network/timeout while the caller signal is still live', () => {
const controller = new AbortController();
const out = toRemoteMcpError(new McpError(ErrorCode.RequestTimeout, 'Request timed out', { timeout: 60_000 }), MCP_URL, controller.signal);
expect(controller.signal.aborted).toBe(false);
expect(out.reason).toBe('network');
expect(out.detail?.kind).toBe('timeout');
});
test('non-Error throwable (string) becomes network/unreachable', () => {
const out = toRemoteMcpError('something blew up', MCP_URL);
expect(out).toBeInstanceOf(RemoteMcpError);
expect(out.reason).toBe('network');
expect(out.detail?.kind).toBe('unreachable');
expect(out.message).toContain('something blew up');
});
test('non-Error throwable (object) becomes network/unreachable with String() fallback', () => {
const out = toRemoteMcpError({ weird: 'shape' }, MCP_URL);
expect(out.reason).toBe('network');
expect(out.detail?.kind).toBe('unreachable');
});
test('non-Error throwable (null) becomes network/unreachable', () => {
const out = toRemoteMcpError(null, MCP_URL);
expect(out.reason).toBe('network');
expect(out.detail?.kind).toBe('unreachable');
});
test('mcp_url is always populated in detail', () => {
expect(toRemoteMcpError(new Error('x'), MCP_URL).detail?.mcp_url).toBe(MCP_URL);
expect(toRemoteMcpError('x', MCP_URL).detail?.mcp_url).toBe(MCP_URL);
expect(toRemoteMcpError(null, MCP_URL).detail?.mcp_url).toBe(MCP_URL);
});
test('the dispatcher contract: every output has a recognized reason', () => {
const validReasons = ['config', 'discovery', 'auth', 'auth_after_refresh', 'network', 'tool_error', 'parse'];
const inputs = [
new Error('x'),
'string-error',
null,
undefined,
42,
{ weird: true },
new RemoteMcpError('parse', 'mock', { mcp_url: MCP_URL }),
];
for (const input of inputs) {
const out = toRemoteMcpError(input, MCP_URL);
expect(validReasons).toContain(out.reason);
}
});
});
describe('extractToolErrorCode', () => {
test('parses the operation error string without replacing it with a guessed code', () => {
const msg = JSON.stringify({ error: 'permission_denied', message: 'access denied to client abc401def' });
expect(extractToolErrorCode(msg)).toBe('permission_denied');
});
test('parses JSON envelope with error.code', () => {
const msg = JSON.stringify({ error: { code: 'missing_scope', message: 'admin required' } });
expect(extractToolErrorCode(msg)).toBe('missing_scope');
});
test('parses JSON envelope with top-level code', () => {
const msg = JSON.stringify({ code: 'rate_limit_exceeded', message: 'too fast' });
expect(extractToolErrorCode(msg)).toBe('rate_limit_exceeded');
});
test('falls back to substring detection for missing_scope-shaped messages', () => {
// Regex is `scope.+(insufficient|required)` — requires "scope" BEFORE
// the keyword. Inputs designed to hit each alternative branch.
expect(extractToolErrorCode('error: missing scope admin')).toBe('missing_scope');
expect(extractToolErrorCode('access denied: admin required')).toBe('missing_scope');
expect(extractToolErrorCode('forbidden: admin required')).toBe('missing_scope');
expect(extractToolErrorCode('scope is insufficient for this op')).toBe('missing_scope');
expect(extractToolErrorCode('scope required: admin')).toBe('missing_scope');
});
test('returns undefined for unstructured messages', () => {
expect(extractToolErrorCode('something went wrong')).toBeUndefined();
expect(extractToolErrorCode('')).toBeUndefined();
expect(extractToolErrorCode('database timed out')).toBeUndefined();
});
test('JSON envelope without code field returns undefined', () => {
const msg = JSON.stringify({ error: { message: 'no code here' } });
expect(extractToolErrorCode(msg)).toBeUndefined();
});
test('non-string code in JSON envelope returns undefined (defensive)', () => {
const msg = JSON.stringify({ error: { code: 42, message: 'wrong type' } });
expect(extractToolErrorCode(msg)).toBeUndefined();
});
test('malformed JSON falls through to substring detection', () => {
// "missing_scope" appears literally in the broken JSON; substring path catches it.
const msg = '{not valid json missing_scope';
expect(extractToolErrorCode(msg)).toBe('missing_scope');
});
});
describe('extractToolErrorDetail', () => {
test('preserves a typed pending receipt and its frozen error code', () => {
expect(extractToolErrorDetail(JSON.stringify({ error: 'unavailable', write_error: 'write_pending', write_request: PENDING_WRITE })))
.toEqual({ code: 'unavailable', write_error: 'write_pending', write_request: PENDING_WRITE });
});
test('rejects malformed receipt metadata without losing the original error code', () => {
expect(extractToolErrorDetail(JSON.stringify({ error: 'unavailable', write_error: 42,
write_request: { ...PENDING_WRITE, state: 'succeeded' } }))).toEqual({ code: 'unavailable' });
});
test('does not expose unknown internal journal fields', () => {
const parsed = extractToolErrorDetail(JSON.stringify({ error: 'unavailable', write_request: {
...PENDING_WRITE, claim_token: 'private', payload: 'private',
} }));
expect(parsed.write_request).toEqual(PENDING_WRITE);
});
test('preserves the optional health contract while stripping private nested metadata', () => {
const diagnostic = { age_ms: 120000, observed_at: '2026-09-23T00:00:00.000Z',
assessment: 'stalled', reason: 'cause_unknown', next_action: 'inspect_owner' } as const;
const parsed = extractToolErrorDetail(JSON.stringify({ error: 'unavailable', write_request: {
...PENDING_WRITE, diagnostic: { ...diagnostic, predecessor_id: 'PRIVATE_PREDECESSOR', raw_error: 'PRIVATE_ERROR' },
} }));
expect(parsed.write_request).toEqual({ ...PENDING_WRITE, diagnostic });
expect(JSON.stringify(parsed)).not.toContain('PRIVATE_');
expect(extractToolErrorDetail(JSON.stringify({ error: 'unavailable', write_request: {
...PENDING_WRITE, diagnostic: { ...diagnostic, age_ms: -1 },
} }))).toEqual({ code: 'unavailable' });
});
test('retains backward compatibility with plain text tool errors', () => {
expect(extractToolErrorDetail('missing scope write')).toEqual({ code: 'missing_scope' });
expect(extractToolErrorDetail('failed')).toEqual({});
});
});
describe('buildAbortController', () => {
test('no opts → signal never fires', async () => {
const { signal, cleanup } = buildAbortController({});
expect(signal.aborted).toBe(false);
await new Promise(r => setTimeout(r, 50));
expect(signal.aborted).toBe(false);
cleanup();
});
test('timeoutMs fires on schedule', async () => {
const { signal, cleanup } = buildAbortController({ timeoutMs: 30 });
expect(signal.aborted).toBe(false);
await new Promise(r => setTimeout(r, 80));
expect(signal.aborted).toBe(true);
expect(signal.reason).toBeInstanceOf(Error);
expect((signal.reason as Error).message).toContain('timeout');
cleanup();
});
test('external signal already-aborted propagates immediately', () => {
const ext = new AbortController();
ext.abort(new Error('SIGINT'));
const { signal, cleanup } = buildAbortController({ signal: ext.signal });
expect(signal.aborted).toBe(true);
cleanup();
});
test('external signal aborted later propagates to inner signal', async () => {
const ext = new AbortController();
const { signal, cleanup } = buildAbortController({ signal: ext.signal });
expect(signal.aborted).toBe(false);
ext.abort(new Error('user-cancel'));
expect(signal.aborted).toBe(true);
cleanup();
});
test('timeout + external signal compose: whichever fires first wins', async () => {
// External fires before timeout.
const ext = new AbortController();
const { signal, cleanup } = buildAbortController({ timeoutMs: 1000, signal: ext.signal });
setTimeout(() => ext.abort(new Error('manual')), 20);
await new Promise(r => setTimeout(r, 60));
expect(signal.aborted).toBe(true);
cleanup();
});
test('cleanup clears the timeout timer', async () => {
// After cleanup, the timer must NOT fire (would otherwise leak via
// unhandled abort on a controller no caller cares about).
const { signal, cleanup } = buildAbortController({ timeoutMs: 30 });
cleanup();
await new Promise(r => setTimeout(r, 80));
expect(signal.aborted).toBe(false);
});
test('cleanup is idempotent (safe to call multiple times)', () => {
const { cleanup } = buildAbortController({ timeoutMs: 100 });
cleanup();
expect(() => cleanup()).not.toThrow();
});
test('cleanup removes external signal listener (no leak after callRemoteTool returns)', async () => {
// The external signal should NOT keep the inner controller alive after
// cleanup(). After cleanup, aborting the external must NOT mutate inner.
const ext = new AbortController();
const { signal, cleanup } = buildAbortController({ signal: ext.signal });
cleanup();
ext.abort(new Error('after-cleanup'));
// Inner signal stays whatever it was at cleanup time. Since neither timeout
// nor pre-cleanup external abort fired, it must still be NOT aborted.
expect(signal.aborted).toBe(false);
});
});
describe('buildMcpRequestOptions', () => {
test('forwards the caller timeout into the MCP SDK request deadline', () => {
const controller = new AbortController();
expect(buildMcpRequestOptions({ timeoutMs: 200_000 }, controller.signal)).toEqual({ signal: controller.signal, timeout: 200_000 });
});
test('leaves the SDK default untouched when no timeout was requested', () => {
const controller = new AbortController();
expect(buildMcpRequestOptions({}, controller.signal)).toEqual({ signal: controller.signal });
});
});
describe('RemoteMcpError class shape', () => {
test('is an instance of Error', () => {
const e = new RemoteMcpError('network', 'msg');
expect(e).toBeInstanceOf(Error);
expect(e).toBeInstanceOf(RemoteMcpError);
});
test('exposes reason + detail as readonly fields', () => {
const e = new RemoteMcpError('tool_error', 'msg', { code: 'missing_scope', mcp_url: MCP_URL });
expect(e.reason).toBe('tool_error');
expect(e.detail?.code).toBe('missing_scope');
expect(e.detail?.mcp_url).toBe(MCP_URL);
});
test('has name="RemoteMcpError" for instanceof-free identification', () => {
const e = new RemoteMcpError('parse', 'msg');
expect(e.name).toBe('RemoteMcpError');
});
test('detail is optional', () => {
const e = new RemoteMcpError('config', 'msg');
expect(e.detail).toBeUndefined();
});
});
describe('CallRemoteToolOptions type contract', () => {
test('both fields are optional', () => {
const empty: CallRemoteToolOptions = {};
expect(empty.timeoutMs).toBeUndefined();
expect(empty.signal).toBeUndefined();
});
test('timeoutMs accepts a number', () => {
const opts: CallRemoteToolOptions = { timeoutMs: 30000 };
expect(opts.timeoutMs).toBe(30000);
});
test('signal accepts an AbortSignal', () => {
const ctrl = new AbortController();
const opts: CallRemoteToolOptions = { signal: ctrl.signal };
expect(opts.signal).toBe(ctrl.signal);
});
});