Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.4 KB
Raw Blame
/**
 * #8543: the stdio bridge's failure envelopes, driven in-process over an
 * in-memory MCP pair with the remote list/forward calls injected. Every
 * transport failure becomes the v1 agent envelope with a fix that never
 * widens the client, every line and envelope is free of URL secrets, and an
 * unexpected fault leaves the bridge serving.
 */
import { afterAll, describe, expect, test } from 'bun:test';
import { existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
import { EventEmitter } from 'node:events';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
import { CallToolResultSchema, McpError, type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
import { RemoteMcpError, type ForwardRemoteToolOptions, type RemoteToolDefs } from '../src/core/mcp-client.ts';
import type { GBrainConfig } from '../src/core/config.ts';
import { startRemoteStdioBridge, type RemoteBridgeOptions } from '../src/mcp/remote-bridge.ts';
import { withEnv } from './helpers/with-env.ts';

const USERINFO = ['user', 's3cret'].join(':');
const SECRET_URL = `https://${USERINFO}@host.example/mcp?token=abc123#frag`;
const cfg = { engine: 'postgres', remote_mcp: { issuer_url: `https://${USERINFO}@host.example`, mcp_url: SECRET_URL,
  oauth_client_id: 'gbrain_cl_example', oauth_client_secret: 'client-secret-example' } } as unknown as GBrainConfig;
const HOST = { name: 'gbrain', version: '9.0.0.0' };
const TOOLS: RemoteToolDefs = { server: HOST, tools: ['get_page', 'put_page', 'query', 'whoami', 'request_tools', 'submit_job'].map(name => ({ name, inputSchema: { type: 'object' as const } })) };
const homes: string[] = [];

afterAll(() => { for (const h of homes) rmSync(h, { recursive: true, force: true }); });

type Forward = (c: GBrainConfig, name: string, args: Record<string, unknown>, o: ForwardRemoteToolOptions & { meta?: Record<string, unknown> }) => Promise<CallToolResult>;

async function startBridge(over: { forward?: Forward; list?: () => Promise<RemoteToolDefs>; transport?: RemoteBridgeOptions['transport']; advertise?: RemoteBridgeOptions['advertise']; eofDrainMs?: number } = {}) {
  const home = mkdtempSync(join(tmpdir(), 'gbrain-bridge-unit-'));
  homes.push(home);
  const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
  const logs: string[] = [];
  const exits: number[] = [];
  const stdin = Object.assign(new EventEmitter(), { isTTY: over.eofDrainMs === undefined });
  await withEnv({ GBRAIN_HOME: home, GBRAIN_SURFACE: undefined }, () => startRemoteStdioBridge(cfg, {
    installFatalHandlers: false, mcpStdio: false, eofDrainMs: over.eofDrainMs ?? 0, ...(over.advertise ? { advertise: over.advertise } : {}),
    transport: over.transport ?? (() => serverSide),
    lifecycle: { stdin: stdin as never, signals: new EventEmitter() as never, log: (m: string) => { logs.push(m); }, exit: (c?: number) => { exits.push(c ?? 0); },
      getParentPid: () => 1, probeWatchdog: () => false },
    list: (async () => (over.list ? over.list() : TOOLS)) as never,
    forward: (over.forward ?? (async () => ({ content: [{ type: 'text', text: '{"ok":true}' }] }))) as never,
  }));
  const client = new Client({ name: 'bridge-unit', version: '1' }, { capabilities: {} });
  if (!over.transport) await client.connect(clientSide);
  return { client, logs, exits, home, stdin, close: () => client.close().catch(() => {}) };
}

const body = (r: unknown) => JSON.parse(((r as CallToolResult).content[0] as { text: string }).text);
const noSecrets = (s: string) => { expect(s).not.toContain('s3cret'); expect(s).not.toContain('abc123'); expect(s).not.toContain('client-secret-example'); expect(s).not.toContain('#frag'); };

const CASES: Array<[string, RemoteMcpError, string]> = [
  ['config', new RemoteMcpError('config', `bad config for ${SECRET_URL}`), 'config_error'],
  ['discovery', new RemoteMcpError('discovery', `no metadata at ${SECRET_URL}`, { mcp_url: SECRET_URL }), 'unavailable'],
  ['token', new RemoteMcpError('token', 'token endpoint 500', { mcp_url: SECRET_URL }), 'unavailable'],
  ['rate_limited', new RemoteMcpError('rate_limited', 'slow down', { mcp_url: SECRET_URL }), 'rate_limited'],
  ['auth', new RemoteMcpError('auth', 'bad creds', { mcp_url: SECRET_URL }), 'invalid_client'],
  ['auth_after_refresh', new RemoteMcpError('auth_after_refresh', 'still 401', { mcp_url: SECRET_URL }), 'invalid_client'],
  ['auth_after_refresh, member disabled', new RemoteMcpError('auth_after_refresh', 'member disabled', { mcp_url: SECRET_URL, status: 401, code: 'access_member_disabled' }), 'access_member_disabled'],
  ['network timeout', new RemoteMcpError('network', `timed out ${SECRET_URL}`, { mcp_url: SECRET_URL, kind: 'timeout' }), 'timeout'],
  ['network aborted', new RemoteMcpError('network', 'aborted', { mcp_url: SECRET_URL, kind: 'aborted' }), 'cancelled'],
  ['network unreachable', new RemoteMcpError('network', `ECONNREFUSED ${SECRET_URL}`, { mcp_url: SECRET_URL, kind: 'unreachable' }), 'unavailable'],
  ['parse', new RemoteMcpError('parse', 'bad json', { mcp_url: SECRET_URL }), 'internal_error'],
  ['tool_error', new RemoteMcpError('tool_error', 'odd', { mcp_url: SECRET_URL }), 'internal_error'],
];

describe('bridge call failures', () => {
  for (const [label, error, code] of CASES) {
    test(`${label} on a read → ${code}, secret-free, and no fix widens the client`, async () => {
      const b = await startBridge({ forward: async () => { throw error; } });
      try {
        const r = await b.client.callTool({ name: 'get_page', arguments: { slug: 'notes/x' } });
        expect(r.isError).toBe(true);
        const env = body(r);
        expect(env.code).toBe(code);
        expect(env.stage).toBe('call');
        noSecrets(JSON.stringify(r));
        noSecrets(b.logs.join('\n'));
        expect(JSON.stringify(env)).not.toMatch(/--scopes|rescope|register-client[^"]*admin/);
      } finally { await b.close(); }
    });
  }
});

describe('bridge list failures', () => {
  for (const [label, error, code] of CASES) {
    test(`${label} on tools/list → JSON-RPC error with the ${code} envelope and no side effects`, async () => {
      let calls = 0;
      const b = await startBridge({ list: async () => { calls++; throw error; } });
      try {
        let caught: unknown;
        try { await b.client.listTools(); } catch (e) { caught = e; }
        expect(caught).toBeInstanceOf(McpError);
        const data = (caught as McpError).data as Record<string, unknown>;
        expect(data.code).toBe(code);
        expect(data.side_effects).toBe('none');
        expect(typeof data.stage).toBe('string');
        noSecrets(JSON.stringify(data) + (caught as Error).message);
        expect(b.logs.some(l => l.includes(`code=${code}`) || l.includes(code))).toBe(true);
        noSecrets(b.logs.join('\n'));
        expect(calls).toBeGreaterThan(0);
      } finally { await b.close(); }
    });
  }
});

describe('write identity', () => {
  test('an accepted mutation whose answer was lost keeps its request_id and says the outcome is unknown', async () => {
    let sentId: unknown;
    const b = await startBridge({ forward: async (_c, _n, args) => {
      sentId = args.request_id;
      throw new RemoteMcpError('network', 'socket hang up', { mcp_url: SECRET_URL, kind: 'unreachable', request_id: args.request_id as string, submission_status: 'unknown' });
    } });
    try {
      const env = body(await b.client.callTool({ name: 'put_page', arguments: { slug: 'notes/x', content: 'x' } }));
      expect(env.code).toBe('write_outcome_unknown');
      expect(env.submission_status).toBe('unknown');
      expect(env.request_id).toBe(sentId);
      expect(env.retryable).toBe(false);
      expect(JSON.stringify(env)).toContain('get_write_request');
      expect(env.fix.argv).toEqual(['gbrain', 'write-request', '--', sentId]);
    } finally { await b.close(); }
  });

  test('a mutation that was never sent is safe to resend', async () => {
    const b = await startBridge({ forward: async (_c, _n, args) => {
      throw new RemoteMcpError('network', 'ECONNREFUSED', { mcp_url: SECRET_URL, kind: 'unreachable', request_id: args.request_id as string, submission_status: 'not_sent' });
    } });
    try {
      const env = body(await b.client.callTool({ name: 'put_page', arguments: { slug: 'notes/x', content: 'x' } }));
      expect(env.code).toBe('unavailable');
      expect(env.submission_status).toBe('not_sent');
    } finally { await b.close(); }
  });

  test('a job submission whose answer was lost points at list_jobs, not a write receipt', async () => {
    const b = await startBridge({ forward: async () => {
      throw new RemoteMcpError('network', 'reset', { mcp_url: SECRET_URL, kind: 'unreachable', submission_status: 'unknown' });
    } });
    try {
      const env = body(await b.client.callTool({ name: 'submit_job', arguments: { name: 'sync' } }));
      expect(env.code).toBe('write_outcome_unknown');
      expect(JSON.stringify(env)).toContain('list_jobs');
      expect(JSON.stringify(env)).not.toContain('get_write_request');
    } finally { await b.close(); }
  });
});

describe('unexpected faults', () => {
  test('a thrown non-remote error becomes internal_error with a 0600 trace, and the next call still works', async () => {
    let n = 0;
    const b = await startBridge({ forward: async () => {
      if (n++ === 0) throw new Error(`kaboom at ${SECRET_URL}`);
      return { content: [{ type: 'text', text: '{"ok":true}' }] };
    } });
    try {
      const first = await b.client.callTool({ name: 'get_page', arguments: { slug: 'notes/x' } });
      expect(first.isError).toBe(true);
      const env = body(first);
      expect(env.code).toBe('internal_error');
      const trace = b.logs.map(l => /trace=(\S+)/.exec(l)?.[1]).find(Boolean);
      expect(trace && existsSync(trace)).toBe(true);
      expect(statSync(trace!).mode & 0o777).toBe(0o600);
      noSecrets(await Bun.file(trace!).text());
      noSecrets(JSON.stringify(first) + b.logs.join('\n'));
      const second = await b.client.callTool({ name: 'get_page', arguments: { slug: 'notes/x' } });
      expect(second.isError ?? false).toBe(false);
      expect(body(second)).toEqual({ ok: true });
    } finally { await b.close(); }
  });

  test('stdin EOF whose drain bound expires with a write in flight logs write_outcome_unknown and exits 1', async () => {
    let started = false;
    const b = await startBridge({ eofDrainMs: 50, forward: async () => { started = true; return await new Promise<CallToolResult>(() => {}); } });
    try {
      void b.client.callTool({ name: 'put_page', arguments: { slug: 'notes/eof-example', content: 'x' } }).catch(() => {});
      for (let i = 0; i < 200 && !started; i++) await Bun.sleep(5);
      b.stdin.emit('end');
      for (let i = 0; i < 400 && !b.exits.length; i++) await Bun.sleep(5);
      const unknown = b.logs.filter(l => l.includes('code=write_outcome_unknown'));
      expect(unknown).toHaveLength(1);
      expect(unknown[0]).toMatch(/tool=put_page submission_status=unknown request_id=[0-9a-f-]{36} fix="gbrain write-request -- [0-9a-f-]{36}"/);
      expect(b.exits[0]).toBe(1);
    } finally { await b.close(); }
  });

  test('a startup failure exits 1 with one secret-free stderr line', async () => {
    const b = await startBridge({ transport: () => { throw new Error(`cannot open ${SECRET_URL}`); } });
    expect(b.exits).toEqual([1]);
    const fatal = b.logs.filter(l => l.includes('code=internal_error'));
    expect(fatal).toHaveLength(1);
    expect(fatal[0]).toContain('stage=startup');
    noSecrets(b.logs.join('\n'));
  });
});

describe('audience', () => {
  test('an audience-bearing call to a host too old to enforce it is refused before it is sent', async () => {
    let sent = 0;
    const b = await startBridge({ forward: async (_c, _n, _a, o) => {
      const refused = o.admit?.({ name: 'gbrain', version: '0.60.500.0' });
      if (refused) return refused;
      sent++;
      return { content: [{ type: 'text', text: '{}' }] };
    } });
    try {
      const env = body(await b.client.callTool({ name: 'query', arguments: { query: 'x' }, _meta: { on_behalf_of: ['alice-example'] } }));
      expect(env.code).toBe('host_upgrade_required');
      expect(env.min_host_version).toBe('0.60.543.0');
      expect(sent).toBe(0);
    } finally { await b.close(); }
  });

  test('a read answer that does not report its audience is withheld', async () => {
    const b = await startBridge({ forward: async (_c, _n, _a, o) => {
      expect(o.meta).toEqual({ on_behalf_of: ['alice-example'], session_id: 's-1' });
      return { content: [{ type: 'text', text: '{"rows":["canary-row-8543"]}' }] };
    } });
    try {
      const r = await b.client.callTool({ name: 'query', arguments: { query: 'x' }, _meta: { on_behalf_of: ['alice-example'], session_id: 's-1' } });
      expect(body(r).code).toBe('host_upgrade_required');
      expect(JSON.stringify(r)).not.toContain('canary-row-8543');
    } finally { await b.close(); }
  });

  test('a read answer that reports its audience is relayed unchanged', async () => {
    const answer: CallToolResult = { content: [{ type: 'text', text: '{"rows":[]}' }], _meta: { access: { audience: ['alice-example'] } } };
    const b = await startBridge({ forward: async () => answer });
    try {
      const r = await b.client.callTool({ name: 'query', arguments: { query: 'x' }, _meta: { on_behalf_of: ['alice-example'] } });
      expect(r).toEqual(answer);
    } finally { await b.close(); }
  });

  test('a non-object _meta is never relayed (the protocol layer drops the frame before any handler)', async () => {
    let sent = 0;
    const b = await startBridge({ forward: async () => { sent++; return { content: [] }; } });
    try {
      let failed = false;
      try { await b.client.request({ method: 'tools/call', params: { name: 'query', arguments: { query: 'x' }, _meta: 'alice-example' as never } }, CallToolResultSchema, { timeout: 1000 }); }
      catch { failed = true; }
      expect(failed).toBe(true);
      expect(sent).toBe(0);
      expect((await b.client.callTool({ name: 'query', arguments: { query: 'x' } })).isError ?? false).toBe(false);
      expect(sent).toBe(1);
    } finally { await b.close(); }
  });
});

describe('request_tools schemas the host describes enter the bridge tool list', () => {
  const hostVerbsOnly: RemoteToolDefs = { server: HOST, tools: ['query', 'request_tools'].map(name => ({ name, inputSchema: { type: 'object' as const } })) };
  const described = { content: [{ type: 'text' as const, text: JSON.stringify({ tools: [{ name: 'get_page', description: 'Read a page', inputSchema: { type: 'object', properties: { slug: { type: 'string' } } } }] }) }] };

  for (const advertise of [undefined, 'verbs'] as const) {
    test(`a tool the host lists only after request_tools is listed next time (advertise=${advertise ?? 'none'})`, async () => {
      const b = await startBridge({ list: async () => hostVerbsOnly, forward: async () => described, ...(advertise ? { advertise } : {}) });
      try {
        expect((await b.client.listTools()).tools.map(x => x.name)).not.toContain('get_page');
        const r = await b.client.callTool({ name: 'request_tools', arguments: { tools: ['get_page'] } });
        expect(r.isError ?? false).toBe(false);
        const after = (await b.client.listTools()).tools;
        expect(after.map(x => x.name)).toContain('get_page');
        expect(after.find(x => x.name === 'get_page')?.inputSchema).toEqual({ type: 'object', properties: { slug: { type: 'string' } } });
      } finally { await b.close(); }
    });
  }
});