Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Outbound HTTP MCP client for thin-client mode (multi-topology v1, Tier B).
*
* Wraps the official @modelcontextprotocol/sdk Client + StreamableHTTPClientTransport
* with OAuth `client_credentials` minting + token caching + 401 retry. Used by:
* - `gbrain remote ping` — submits autopilot-cycle, polls get_job
* - `gbrain remote doctor` — calls run_doctor MCP op
*
* Token caching strategy: an in-process Map in front of a 0600 file under the
* gbrain home (remote-token-cache.ts), both keyed by a hash of the issuer, MCP
* URL, client id and secret. Each CLI command is its own process, so the file
* is what lets a per-prompt caller reuse one token instead of minting one per
* command and spending the host's /token budget (#7360).
*
* HTTP 401 handling: drop the cached token, mint fresh once, retry the call.
* Application errors and other HTTP statuses are terminal. If the refreshed
* attempt is also rejected with HTTP 401, surface auth_after_refresh.
*/
import { createHash, randomUUID } from 'node:crypto';
import { isPersistenceIpcMutation } from './persistence/ipc.ts';
import { replayWhilePending } from './persistence/write-wait.ts';
import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
import type { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
import { anySignal } from './abort-check.ts';
import type { GBrainConfig } from './config.ts';
import { discoverOAuth, mintClientCredentialsToken } from './remote-mcp-probe.ts';
import { clearTokenCacheFile, dropCachedToken, readCachedToken, tokenCacheKey, writeCachedToken, type CachedToken } from './remote-token-cache.ts';
import { isTerminalWriteState, isWriteErrorCode, isWriteReceipt, isWriteRequestId, publicWriteReceipt, type WriteReceipt } from './persistence/types.ts';
import { GBRAIN_CLIENT_HEADER, GBRAIN_THIN_CLIENT_NAME } from '../mcp/result-rows.ts';
import { VERSION } from '../version.ts';
import { RemoteMcpError, extractResponseMeta, type RemoteMcpErrorDetail } from './remote-mcp-error.ts';
import { FRAME_RESERVE_BYTES } from './egress-budget.ts';
import { OperationError, opError } from './ops/contract.ts';
// The error class and the envelope-meta readers live in remote-mcp-error.ts so
// a local CLI command can name them without loading this module's MCP SDK graph.
export { RemoteMcpError, extractResponseMeta, ignoredRemoteParams } from './remote-mcp-error.ts';
export type { RemoteMcpErrorReason, RemoteMcpErrorDetail } from './remote-mcp-error.ts';
const tokenCache = new Map<string, CachedToken>();
/**
* Test-only escape hatch. Tests that mock the OAuth fixture across multiple
* runs need to invalidate the cache between runs. Production callers should
* never need this — the 401 path handles staleness automatically.
* `keepDisk` simulates a new CLI process: the in-process map is gone, the file stays.
*/
export function _clearMcpClientTokenCache(opts: { keepDisk?: boolean } = {}): void {
tokenCache.clear();
if (!opts.keepDisk) clearTokenCacheFile();
}
function dropAccessToken(config: GBrainConfig): void {
const remote = requireRemoteMcp(config);
const key = tokenCacheKey(remote, resolveSecret(remote));
tokenCache.delete(key);
dropCachedToken(key);
}
/**
* B5 (#5949): a 429 on the /token mint is the host's mint budget, not a
* connectivity fault: code `rate_limited`, a provider-side wait, and the
* read-only check to run once the wait is over.
*/
function rateLimitedMintDetail(retryAfterS: number | undefined): RemoteMcpErrorDetail {
const wait = retryAfterS !== undefined ? `${retryAfterS}s` : 'a few minutes';
return {
code: 'rate_limited',
why: `The brain host's OAuth /token mint budget is spent (HTTP 429); it clears by itself in ${wait}.`,
suggestion: `Wait ${wait}, then re-run the same command. If this repeats, the host operator can raise GBRAIN_OAUTH_TOKEN_RATE_LIMIT_MAX.`,
fix: {
argv: ['gbrain', 'remote', 'doctor', '--json'], consent: [], actor: 'provider',
why: `Retry after ${wait}; remote doctor confirms the token mint works again.`, requires_exclusive: false,
},
};
}
type HttpClientSdk = typeof import('@modelcontextprotocol/sdk/client/index.js')
& typeof import('@modelcontextprotocol/sdk/client/streamableHttp.js');
let httpClientSdk: HttpClientSdk | undefined;
/**
* The SDK's client + Streamable HTTP transport, loaded by the first remote
* call (buildClient). Only thin-client calls use them, so a local CLI command
* never pays for their import graph.
*/
async function loadHttpClientSdk(): Promise<HttpClientSdk> {
httpClientSdk ??= {
...(await import('@modelcontextprotocol/sdk/client/index.js')),
...(await import('@modelcontextprotocol/sdk/client/streamableHttp.js')),
};
return httpClientSdk;
}
/**
* A second HTTP 401 after a fresh token. GBRA-582 item 9d: when the host's refusal body names access_member_disabled
* (GBRA-218), the client is fine and its bound member cannot read, so the error says that instead of "revoked". The OAuth
* host's SDK bearer check puts the code at the start of error_description; the bearer-token transport sends a code key.
*/
function authAfterRefresh(e: StreamableHTTPError, mcpUrl: string, fallback: string): RemoteMcpError {
return /"(?:code|error_description)"\s*:\s*"access_member_disabled\b/.test(e.message)
? new RemoteMcpError('auth_after_refresh', 'The brain host refused this client: its credential is bound to a member who is disabled, removed or missing (access_member_disabled). Ask the brain host\'s operator to enable the member or bind this client to an enabled one.',
{ mcp_url: mcpUrl, status: 401, code: 'access_member_disabled' })
: new RemoteMcpError('auth_after_refresh', fallback, { mcp_url: mcpUrl, status: 401 });
}
/** A transport error: only possible once loadHttpClientSdk has loaded the transport that throws it. */
function isStreamableHttpError(e: unknown): e is StreamableHTTPError {
return httpClientSdk !== undefined && e instanceof httpClientSdk.StreamableHTTPError;
}
/**
* v0.31.1: convert any thrown value into a RemoteMcpError. Used by the
* outermost catch in `callRemoteTool` so the dispatcher's exhaustive switch
* is sound — no plain `Error` (undici, AbortError, JSON parse) escapes.
*
* @internal Exported for test access (test/mcp-client-hardening.test.ts).
* Not part of the public API — production code should consume this only via
* the callRemoteTool funnel.
*/
export function toRemoteMcpError(e: unknown, mcpUrl: string, signal?: AbortSignal): RemoteMcpError {
// A received receipt is stronger evidence than a deadline that fired while
// unwinding the call. Losing it invites a second mutation after acceptance.
if (e instanceof RemoteMcpError && e.detail?.write_request) return e;
if (signal?.aborted) {
const kind = signal.reason instanceof Error && signal.reason.name === 'TimeoutError'
? 'timeout' : 'aborted';
return new RemoteMcpError(
'network',
`Request to ${mcpUrl} ${kind === 'timeout' ? 'timed out' : 'was aborted'}`,
{ mcp_url: mcpUrl, kind },
);
}
if (e instanceof RemoteMcpError) return e;
// The SDK's own request timer can fire while our composed signal is still
// live. A slow operation on a reachable server is a timeout, not unreachable.
if (e instanceof McpError && e.code === ErrorCode.RequestTimeout) {
return new RemoteMcpError('network', `Request to ${mcpUrl} timed out`, { mcp_url: mcpUrl, kind: 'timeout' });
}
if (e instanceof Error) {
if (e.name === 'AbortError' || e.name === 'TimeoutError') {
return new RemoteMcpError(
'network',
`Request to ${mcpUrl} ${e.name === 'TimeoutError' ? 'timed out' : 'was aborted'}`,
{ mcp_url: mcpUrl, kind: e.name === 'TimeoutError' ? 'timeout' : 'aborted' },
);
}
// undici/fetch network errors (DNS, connection refused, TLS) end up here.
return new RemoteMcpError(
'network',
`Network error talking to ${mcpUrl}: ${e.message}`,
{
mcp_url: mcpUrl,
kind: 'unreachable',
...(isStreamableHttpError(e) && e.code !== undefined && e.code > 0
? { status: e.code } : {}),
},
);
}
return new RemoteMcpError(
'network',
`Unknown error talking to ${mcpUrl}: ${String(e)}`,
{ mcp_url: mcpUrl, kind: 'unreachable' },
);
}
/**
* v0.31.1: parse a tool_error content envelope and extract a structured
* `code` (e.g. 'missing_scope') if the server provided one. Tries JSON-parsed
* payload first, then falls back to substring detection on the message.
*
* @internal Exported for test access (test/mcp-client-hardening.test.ts).
*/
export function extractToolErrorCode(message: string): string | undefined {
// Try to parse a JSON payload first — gbrain server-side tool errors
// sometimes come through as `{"error":{"code":"...","message":"..."}}`.
try {
const parsed = JSON.parse(message);
if (parsed && typeof parsed === 'object') {
const code = typeof parsed.error === 'string'
? parsed.error : parsed.error?.code ?? parsed.code;
if (typeof code === 'string') return code;
}
} catch { /* not json; fall through */ }
if (/missing[_\s-]?scope|scope.+(insufficient|required)|forbidden|access.+denied/i.test(message)) {
return 'missing_scope';
}
return undefined;
}
/** Keep only validated public receipt fields from a tool's JSON error body. */
function isBatchErrorBody(text: string): boolean {
try { const body = JSON.parse(text) as { items?: unknown; status?: unknown }; return Array.isArray(body?.items) && body.status === 'error'; } catch { return false; }
}
export function extractToolErrorDetail(message: string): RemoteMcpErrorDetail {
const code = extractToolErrorCode(message);
const detail: RemoteMcpErrorDetail = code ? { code } : {};
try {
const body: unknown = JSON.parse(message);
if (body === null || typeof body !== 'object' || Array.isArray(body)) return detail;
const envelope = body as Record<string, unknown>;
if (typeof envelope.message === 'string') detail.message = envelope.message;
if (typeof envelope.suggestion === 'string') detail.suggestion = envelope.suggestion;
if (envelope.protocol_version === 1) detail.protocol_version = 1;
if (typeof envelope.detail === 'string') detail.server_detail = envelope.detail;
if (typeof envelope.docs === 'string') detail.docs = envelope.docs;
if (typeof envelope.code === 'string' && envelope.code !== code) detail.canonical_code = envelope.code;
if (typeof envelope.reason === 'string') detail.reason = envelope.reason;
if (typeof envelope.why === 'string') detail.why = envelope.why;
if (envelope.fix && typeof envelope.fix === 'object' && !Array.isArray(envelope.fix)) detail.fix = envelope.fix as Record<string, unknown>;
if (Array.isArray(envelope.notices)) detail.notices = envelope.notices.filter(n => n && typeof n === 'object') as Array<Record<string, unknown>>;
if (envelope.contract_version === 1) detail.contract_version = 1;
if (isWriteReceipt(envelope.write_request)) detail.write_request = publicWriteReceipt(envelope.write_request);
if (isWriteErrorCode(envelope.write_error)) detail.write_error = envelope.write_error;
} catch { /* Older servers can return plain text; preserve existing code extraction. */ }
return detail;
}
/** PR B: a server answers a write deferred behind a refresh as a `status: "pending"` success; the CLI treats it as the pending write it is. */
function deferredPendingReceipt(res: unknown): WriteReceipt | null {
const first = (res as { content?: Array<{ text?: unknown }> } | null)?.content?.[0]?.text;
if (typeof first !== 'string' || !/^\s*\{\s*"status"\s*:\s*"pending"/.test(first.slice(0, 64))) return null;
try {
const body = JSON.parse(first) as { receipt?: unknown };
return isWriteReceipt(body.receipt) && !isTerminalWriteState(body.receipt.state) ? publicWriteReceipt(body.receipt) : null;
} catch { return null; }
}
function requireRemoteMcp(config: GBrainConfig | null): NonNullable<GBrainConfig['remote_mcp']> {
if (!config?.remote_mcp) {
throw new RemoteMcpError(
'config',
'No remote_mcp config. Run `gbrain init --mcp-only` first.',
);
}
return config.remote_mcp;
}
function resolveSecret(remote: NonNullable<GBrainConfig['remote_mcp']>): string {
const secret = process.env.GBRAIN_REMOTE_CLIENT_SECRET ?? remote.oauth_client_secret;
if (!secret) {
throw new RemoteMcpError(
'config',
'No client_secret available. Set GBRAIN_REMOTE_CLIENT_SECRET or rerun `gbrain init --mcp-only`.',
);
}
return secret;
}
/**
* Mint or reuse a cached access_token for the given config. Throws
* RemoteMcpError on discovery failure or auth rejection.
*/
async function getAccessToken(config: GBrainConfig, force = false, signal?: AbortSignal): Promise<string> {
signal?.throwIfAborted();
const remote = requireRemoteMcp(config);
const secret = resolveSecret(remote);
const key = tokenCacheKey(remote, secret);
if (!force) {
const cached = tokenCache.get(key) ?? readCachedToken(key);
if (cached && cached.expires_at_ms > Date.now()) {
tokenCache.set(key, cached);
return cached.access_token;
}
}
const disco = await discoverOAuth(remote.issuer_url, { signal });
signal?.throwIfAborted();
if (!disco.ok) {
throw new RemoteMcpError(
disco.reason === 'http' || disco.reason === 'parse' ? 'discovery' : 'network',
`OAuth discovery failed: ${disco.message}`,
{ ...(disco.status ? { status: disco.status } : {}), ...(disco.kind ? { kind: disco.kind } : {}), mcp_url: remote.mcp_url,
...(disco.status_only ? { ...extractToolErrorDetail(JSON.stringify(disco.status_only)), retry_after_s: disco.retry_after_s } : {}) },
);
}
const tokenRes = await mintClientCredentialsToken(disco.metadata.token_endpoint, remote.oauth_client_id, secret, { signal });
signal?.throwIfAborted();
if (!tokenRes.ok) {
// Discovery already succeeded, so a /token failure is never 'discovery'.
throw new RemoteMcpError(
tokenRes.reason === 'http' || tokenRes.reason === 'parse' ? 'token' : tokenRes.reason,
`OAuth /token failed: ${tokenRes.message}`,
{
...(tokenRes.status ? { status: tokenRes.status } : {}), ...(tokenRes.kind ? { kind: tokenRes.kind } : {}),
...(tokenRes.retry_after_s !== undefined ? { retry_after_s: tokenRes.retry_after_s } : {}), mcp_url: remote.mcp_url,
...(tokenRes.reason === 'rate_limited' ? rateLimitedMintDetail(tokenRes.retry_after_s) : {}),
...(tokenRes.status_only ? extractToolErrorDetail(JSON.stringify(tokenRes.status_only)) : {}),
},
);
}
const ttlSec = tokenRes.token.expires_in ?? 3600;
const expires_at_ms = Date.now() + Math.max(0, ttlSec * 1000 - 30_000);
const token: CachedToken = { access_token: tokenRes.token.access_token, expires_at_ms };
tokenCache.set(key, token);
writeCachedToken(key, token);
return token.access_token;
}
/**
* Build a connected Client with the given bearer. Caller is responsible for
* `await client.close()` after use. Each tool call gets its own short-lived
* Client because StreamableHTTPClientTransport doesn't expose a clean way to
* swap headers on an existing connection — re-mint + reconnect on 401 is
* cheaper than reusing.
*
* The SDK replaces requestInit.signal with its own transport signal. Compose
* them in fetch so cancellation covers HTTP bodies as well as SDK requests.
*/
async function buildClient(mcpUrl: string, accessToken: string, signal?: AbortSignal, clientName: string = GBRAIN_THIN_CLIENT_NAME): Promise<Client> {
const { Client, StreamableHTTPClientTransport } = await loadHttpClientSdk();
const transport = new StreamableHTTPClientTransport(new URL(mcpUrl), {
requestInit: {
headers: {
'Authorization': `Bearer ${accessToken}`,
// Hosts serve full search/query rows to gbrain's own CLI (renderers,
// --explain). A row-shape hint only, never an authority claim.
[GBRAIN_CLIENT_HEADER]: `${clientName}/${VERSION}`,
},
},
fetch: (input, init) => fetch(input, {
...init,
signal: signal ? anySignal(signal, init?.signal) : init?.signal,
}),
});
const client = new Client(
{ name: clientName, version: '1' },
{ capabilities: {} },
);
try {
signal?.throwIfAborted();
await client.connect(transport, { signal });
return client;
} catch (error) {
try { await client.close(); } catch { /* best-effort */ }
// Also close when connect failed before attaching the transport.
try { await transport.close(); } catch { /* best-effort */ }
throw error;
}
}
/**
* Options for `callRemoteTool`. When absent, discovery/token requests retain
* their own caps and MCP requests inherit the SDK's timeout. A `timeoutMs`
* also becomes the SDK request deadline (see buildMcpRequestOptions).
*/
export interface CallRemoteToolOptions {
/** Hard wall-clock cap for the whole call (token mint + tool call). Aborts on expiry. */
timeoutMs?: number;
/** External AbortSignal (e.g. SIGINT handler). Composed with the timeout. */
signal?: AbortSignal;
/**
* #5232: keep a mutation's commit wait beyond the server's own bounded
* wait by replaying the identical request (same request_id) while it is
* pending. `timeoutMs` still bounds each exchange.
*/
writeWaitMs?: number;
/** GBRA-498: request-level `_meta` sent with the tool call (the CLI's `--room` goes as `_meta.room`, never as an argument). */
meta?: Record<string, unknown>;
}
/**
* The SDK request options for one tool call. Passing only `signal` leaves the
* SDK's independent 60s default deadline in force, so a caller's longer
* timeout would still die at 60s; forward it.
*
* @internal Exported for test access (test/mcp-client-hardening.test.ts).
*/
export function buildMcpRequestOptions(opts: CallRemoteToolOptions, signal: AbortSignal): { signal: AbortSignal; timeout?: number } {
return { signal, ...(opts.timeoutMs !== undefined && opts.timeoutMs > 0 ? { timeout: opts.timeoutMs } : {}) };
}
/**
* Compose an external signal with a timeout into a single AbortController.
* Returns the controller (so callers can pass `controller.signal` to
* downstream fetch) plus a `cleanup` to stop the timer + drop listeners.
*/
/** @internal Exported for test access (test/mcp-client-hardening.test.ts). */
export function buildAbortController(opts: CallRemoteToolOptions): { signal: AbortSignal; cleanup: () => void } {
const controller = new AbortController();
const cleanups: Array<() => void> = [];
if (opts.timeoutMs !== undefined && opts.timeoutMs > 0) {
const timer = setTimeout(() => {
controller.abort(new DOMException(`timeout after ${opts.timeoutMs}ms`, 'TimeoutError'));
}, opts.timeoutMs);
cleanups.push(() => clearTimeout(timer));
}
if (opts.signal) {
if (opts.signal.aborted) {
controller.abort(opts.signal.reason);
} else {
const onAbort = () => controller.abort(opts.signal!.reason);
opts.signal.addEventListener('abort', onAbort);
cleanups.push(() => opts.signal!.removeEventListener('abort', onAbort));
}
}
return { signal: controller.signal, cleanup: () => cleanups.forEach(fn => { try { fn(); } catch { /* best-effort */ } }) };
}
/**
* Call an MCP tool on the remote server. Handles auth refresh on 401 once.
* Returns the parsed `result` payload from the tool response. Mutation calls
* retain a generated request_id on args for refresh and caller retries.
*
* Throws RemoteMcpError on:
* - missing remote_mcp config
* - OAuth discovery / token failures
* - 401 after refresh attempt (auth_after_refresh)
* - tool-call errors (tool_error)
* - network errors
*/
export async function callRemoteTool(
config: GBrainConfig,
toolName: string,
args: Record<string, unknown> = {},
opts: CallRemoteToolOptions = {},
): Promise<unknown> {
const remote = requireRemoteMcp(config);
// Retain on the caller's object so transport refresh and caller retries use
// the same durable identity. Explicit malformed IDs still reach validation.
if (isPersistenceIpcMutation(toolName) && args.request_id === undefined && args.dry_run !== true) args.request_id = randomUUID();
if (opts.writeWaitMs !== undefined && isPersistenceIpcMutation(toolName) && args.dry_run !== true) {
const { writeWaitMs, ...exchange } = opts;
return replayWhilePending(() => callRemoteTool(config, toolName, args, exchange), writeWaitMs);
}
const requestId = isPersistenceIpcMutation(toolName) && isWriteRequestId(args.request_id) ? args.request_id : undefined;
let submitted = false;
// v0.31.1 (CDX-4): wrap the WHOLE call in normalize-on-error so the
// exhaustive switch on RemoteMcpError.reason at the dispatcher is sound.
// No plain Error (undici, AbortError, JSON parse) escapes.
const { signal, cleanup } = buildAbortController(opts);
try {
// Step 1: mint (or reuse cached) token. If THIS fails — bad credentials,
// unreachable issuer, etc. — surface immediately. Retry-on-401 is for
// the mid-session token-rotation case, NOT for initial-credentials-wrong.
const initialToken = await getAccessToken(config, false, signal);
// Step 2: try the tool call. On an HTTP 401 here, drop the cache
// and retry ONCE with a freshly-minted token (handles host-side rotation
// mid-session). If the retry also fails auth, surface auth_after_refresh.
const tryCall = async (token: string): Promise<unknown> => {
const client = await buildClient(remote.mcp_url, token, signal);
try {
signal.throwIfAborted();
submitted = true;
const res = await client.callTool({ name: toolName, arguments: args, ...(opts.meta ? { _meta: opts.meta } : {}) }, undefined, buildMcpRequestOptions(opts, signal));
if (res.isError) {
// Agent contract v1: the envelope is content[0] alone. A notice
// block from a newer server never joins the body.
const first = Array.isArray(res.content) ? (res.content[0] as { text?: unknown } | undefined) : undefined;
const message = typeof first?.text === 'string' ? first.text : 'unknown tool error';
// GST-1387: a remember batch with a failed item is an error whose body keeps every item's receipt; the caller renders it.
if (isBatchErrorBody(message)) return res;
// v0.31.1: extract structured error code (e.g. 'missing_scope') so
// the dispatcher can produce a pinpoint hint instead of a generic
// "tool error" message.
throw new RemoteMcpError(
'tool_error',
`Remote tool ${toolName} failed: ${message}`,
{ mcp_url: remote.mcp_url, ...extractToolErrorDetail(message) },
);
}
const pending = deferredPendingReceipt(res);
if (pending) {
throw new RemoteMcpError('tool_error', `Remote tool ${toolName}: request ${pending.request_id} was accepted and publishes after the worktree refresh.`,
{ mcp_url: remote.mcp_url, code: 'write_pending', write_error: 'write_pending', write_request: pending, request_id: pending.request_id });
}
return res;
} finally {
try { await client.close(); } catch { /* best-effort */ }
}
};
try {
return await tryCall(initialToken);
} catch (e) {
// A response received before cleanup is authoritative even if closing
// the transport crosses the deadline. Preserve its receipt first.
if (e instanceof RemoteMcpError && e.detail?.write_request) throw e;
// Application errors can contain arbitrary text (including client IDs
// with "401"). Only a rejected HTTP request authorizes a replay.
signal.throwIfAborted();
if (!isStreamableHttpError(e) || e.code !== 401) throw e;
submitted = false; // This attempt was explicitly refused, not accepted.
// Drop cached token and retry once with a fresh mint.
dropAccessToken(config);
let freshToken: string;
try {
freshToken = await getAccessToken(config, true, signal);
} catch (mintErr) {
if (mintErr instanceof RemoteMcpError && mintErr.reason === 'auth') {
throw new RemoteMcpError(
'auth_after_refresh',
`Auth failed after token refresh. Verify oauth_client_id and secret are still valid; the host operator may need to re-run \`gbrain auth register-client\`.`,
{ mcp_url: remote.mcp_url, ...(mintErr.detail?.status ? { status: mintErr.detail.status } : {}) },
);
}
throw mintErr;
}
try {
return await tryCall(freshToken);
} catch (e2) {
if (e2 instanceof RemoteMcpError && e2.detail?.write_request) throw e2;
signal.throwIfAborted();
if (isStreamableHttpError(e2) && e2.code === 401) {
submitted = false;
dropAccessToken(config);
throw authAfterRefresh(e2, remote.mcp_url,
`Auth failed after token refresh. Verify oauth_client_id and secret are still valid; the host operator may need to re-run \`gbrain auth register-client\`.`);
}
throw e2;
}
}
} catch (e) {
// CDX-4: this is the funnel. ANYTHING that escapes the inner block becomes
// a typed RemoteMcpError. The dispatcher's exhaustive switch can rely on
// this contract.
const error = toRemoteMcpError(e, remote.mcp_url, signal);
if (!requestId) throw error;
throw new RemoteMcpError(error.reason, error.message, {
...error.detail, request_id: requestId,
...(!error.detail?.write_request && error.reason !== 'tool_error'
? { submission_status: submitted ? 'unknown' as const : 'not_sent' as const } : {}),
...(toolName === 'remember' || toolName === 'forget' ? { protocol_version: 1 as const } : {}),
});
} finally {
cleanup();
}
}
/** One tool a remote serve lists for this token: its name and the parameter names its input schema declares. */
export interface RemoteToolListing { name: string; params: string[] }
/** A remote serve's whole tools/list answer for this token, with what its initialize said about itself. */
export interface RemoteToolDefs {
tools: Tool[];
/** The host's initialize instructions, when it sent any. */
instructions?: string;
/** The host's initialize serverInfo. */
server?: { name?: string; version?: string };
}
/** Which client the host sees: the thin client's own name by default (its header asks for full rows). */
export interface RemoteClientOptions extends CallRemoteToolOptions { clientName?: string }
/**
* #6696 B2: the tools a remote serve lists for this client's token (tools/list
* already filters by the token's scope and surface). Lets the thin client send
* a parameter only to a serve that advertises it. Same token handling as
* `callRemoteTool`: a cached token, one refresh on an HTTP 401.
*/
export async function listRemoteTools(config: GBrainConfig, opts: CallRemoteToolOptions = {}): Promise<RemoteToolListing[]> {
const { tools } = await listRemoteToolDefs(config, opts);
return tools.map((t) => ({ name: t.name, params: Object.keys((t.inputSchema as { properties?: Record<string, unknown> } | undefined)?.properties ?? {}) }));
}
/** The full tool definitions behind `listRemoteTools` (the stdio bridge lists them as-is). */
export async function listRemoteToolDefs(config: GBrainConfig, opts: RemoteClientOptions = {}): Promise<RemoteToolDefs> {
const remote = requireRemoteMcp(config);
const { signal, cleanup } = buildAbortController(opts);
const list = async (token: string): Promise<RemoteToolDefs> => {
const client = await buildClient(remote.mcp_url, token, signal, opts.clientName);
try {
const { tools } = await client.listTools(undefined, buildMcpRequestOptions(opts, signal));
const instructions = client.getInstructions();
const server = client.getServerVersion();
return { tools, ...(instructions ? { instructions } : {}), ...(server ? { server: { name: server.name, version: server.version } } : {}) };
} finally {
try { await client.close(); } catch { /* best-effort */ }
}
};
try {
try {
return await list(await getAccessToken(config, false, signal));
} catch (e) {
signal.throwIfAborted();
if (!isStreamableHttpError(e) || e.code !== 401) throw e;
dropAccessToken(config);
return await list(await getAccessToken(config, true, signal));
}
} catch (e) {
throw toRemoteMcpError(e, remote.mcp_url, signal);
} finally {
cleanup();
}
}
/** Options for `forwardRemoteToolCall`. */
export interface ForwardRemoteToolOptions extends RemoteClientOptions {
/**
* Read after connecting, before anything is sent: a returned result answers
* the call instead and nothing reaches the host (the bridge refuses an
* audience a host cannot be shown to enforce).
*/
admit?: (server: { name?: string; version?: string } | undefined) => CallToolResult | null;
}
/**
* The stdio bridge's call path: send one tool call to the remote serve and
* return its `CallToolResult` exactly as the host answered, `isError`
* envelopes and pending write receipts included (`callRemoteTool` turns those
* into thrown errors). Same token handling as `callRemoteTool`: a cached
* token, and one re-mint and resend only after an explicit HTTP 401, which
* refused the request; nothing else is ever replayed. A persistence mutation
* gets one `request_id` before the first send, kept across that resend.
* Only a transport failure throws: a RemoteMcpError carrying `request_id`
* (when one was sent) and `submission_status` (`unknown` once the request
* left, `not_sent` before).
*/
export async function forwardRemoteToolCall(
config: GBrainConfig,
toolName: string,
args: Record<string, unknown> = {},
opts: ForwardRemoteToolOptions = {},
): Promise<CallToolResult> {
const remote = requireRemoteMcp(config);
const sent = isPersistenceIpcMutation(toolName) && args.request_id === undefined && args.dry_run !== true ? { ...args, request_id: randomUUID() } : args;
const requestId = isPersistenceIpcMutation(toolName) && isWriteRequestId(sent.request_id) ? sent.request_id : undefined;
let submitted = false;
const { signal, cleanup } = buildAbortController(opts);
const send = async (token: string): Promise<CallToolResult> => {
const client = await buildClient(remote.mcp_url, token, signal, opts.clientName);
try {
const refused = opts.admit?.(client.getServerVersion());
if (refused) return refused;
signal.throwIfAborted();
submitted = true;
return await client.callTool({ name: toolName, arguments: sent, ...(opts.meta ? { _meta: opts.meta } : {}) }, undefined, buildMcpRequestOptions(opts, signal)) as CallToolResult;
} finally {
try { await client.close(); } catch { /* best-effort */ }
}
};
try {
try {
return await send(await getAccessToken(config, false, signal));
} catch (e) {
signal.throwIfAborted();
if (!isStreamableHttpError(e) || e.code !== 401) throw e;
submitted = false; // The host refused this attempt; it was not accepted.
dropAccessToken(config);
let fresh: string;
try {
fresh = await getAccessToken(config, true, signal);
} catch (mintErr) {
if (mintErr instanceof RemoteMcpError && mintErr.reason === 'auth') {
throw new RemoteMcpError('auth_after_refresh', 'Auth failed after token refresh.', { mcp_url: remote.mcp_url, ...(mintErr.detail?.status ? { status: mintErr.detail.status } : {}) });
}
throw mintErr;
}
try {
return await send(fresh);
} catch (e2) {
signal.throwIfAborted();
if (!isStreamableHttpError(e2) || e2.code !== 401) throw e2;
submitted = false;
dropAccessToken(config);
throw authAfterRefresh(e2, remote.mcp_url, 'Auth failed after token refresh.');
}
}
} catch (e) {
const error = toRemoteMcpError(e, remote.mcp_url, signal);
throw new RemoteMcpError(error.reason, error.message, {
...error.detail, ...(requestId ? { request_id: requestId } : {}),
submission_status: submitted ? 'unknown' : 'not_sent',
});
} finally {
cleanup();
}
}
/**
* Extract the structured result from a successful tool-call response. The MCP
* spec says tool results are returned as `content: Array<{type, text|...}>`.
* gbrain ops set the JSON-encoded result as `text` of the first content item.
* This helper parses + types it for the caller.
*/
export function unpackToolResult<T = unknown>(res: unknown): T {
const content = (res as { content?: unknown[] } | undefined)?.content;
if (!Array.isArray(content) || content.length === 0) {
throw new RemoteMcpError('parse', 'Remote tool returned no content');
}
// Deliberately content[0]-only (D8 skew guard): new servers append a
// model-facing diagnosis block as content[1] on empty retrievals; the
// structured body contract stays in block 0 and this parser must never
// trip on the extra block. Pinned by test.
const first = content[0] as { type?: string; text?: string };
if (first.type !== 'text' || typeof first.text !== 'string') {
throw new RemoteMcpError('parse', 'Remote tool returned unexpected content shape');
}
try {
return JSON.parse(first.text) as T;
} catch (e) {
throw new RemoteMcpError('parse', `Remote tool result was not valid JSON: ${(e as Error).message}`);
}
}
/**
* Agent contract v1 notices on a SUCCESS result: `_meta.gbrain_notices`
* (rendered) when present, else the prefixed extra text blocks after
* content[0] (`[gbrain notice <code> kind=<kind>]` first line), for hosts
* that drop `_meta`. Old servers return none.
*/
export function extractNotices(res: unknown): Array<Record<string, unknown>> {
const meta = extractResponseMeta(res)?.gbrain_notices;
if (Array.isArray(meta)) return meta.filter(n => n && typeof n === 'object') as Array<Record<string, unknown>>;
const content = (res as { content?: unknown[] } | undefined)?.content;
const out: Array<Record<string, unknown>> = [];
for (const block of Array.isArray(content) ? content.slice(1) : []) {
const text = (block as { text?: unknown })?.text;
if (typeof text !== 'string' || !text.startsWith('[gbrain notice ')) continue;
const [head, ...rest] = text.split('\n');
const m = /^\[gbrain notice (\S+) kind=(\S+)\]$/.exec(head);
if (!m) continue;
const notice: Record<string, unknown> = { code: m[1], kind: m[2] };
for (const line of rest) {
const kv = /^(why|fix|next|user_message): (.*)$/.exec(line);
if (kv) notice[kv[1]] = kv[2];
}
out.push(notice);
}
return out;
}
/**
* Wave B upload sessions (spec 6.2): the bytes of the JSON-RPC `tools/call`
* request that carries `args` to `tool`, measured the way egress-budget.ts
* `encodedFrameBytes` measures a result frame: the whole frame stringified
* (every string escaped: a control character costs 6 bytes, a quote or
* backslash 2), UTF-8 encoded, plus the framing reserve.
*/
export function toolCallFrameBytes(tool: string, args: Record<string, unknown>): number {
return Buffer.byteLength(JSON.stringify({ jsonrpc: '2.0', id: 0, method: 'tools/call', params: { name: tool, arguments: args } }), 'utf8') + FRAME_RESERVE_BYTES;
}
/** A part's sha256 is always 64 hex characters, so the cut measures the frame with a stand-in of the same length. */
const PART_SHA256_STAND_IN = '0'.repeat(64);
const isHighSurrogate = (unit: number) => unit >= 0xd800 && unit <= 0xdbff;
const isLowSurrogate = (unit: number) => unit >= 0xdc00 && unit <= 0xdfff;
/**
* The end (a UTF-16 index) of the longest prefix of `text` whose
* `upload_page_part` request frame (`toolCallFrameBytes`) is at most
* `maxFrameBytes`. A binary search over code-point boundaries on the exact
* stringified length: never splits a surrogate pair. Throws when not even one
* code point fits the frame.
*/
export function cutUploadPart(text: string, frame: { upload_id: string; part: number }, maxFrameBytes: number): number {
const fits = (end: number) => toolCallFrameBytes('upload_page_part',
{ upload_id: frame.upload_id, part: frame.part, text: text.slice(0, end), part_sha256: PART_SHA256_STAND_IN }) <= maxFrameBytes;
const boundary = (i: number) => i > 0 && i < text.length && isHighSurrogate(text.charCodeAt(i - 1)) && isLowSurrogate(text.charCodeAt(i)) ? i - 1 : i;
// Every UTF-16 unit costs at least one frame byte, so no longer prefix can fit.
let hi = boundary(Math.min(text.length, Math.max(0, maxFrameBytes)));
if (fits(hi)) return hi;
let lo = 0;
while (hi - lo > 1) {
let mid = boundary(lo + Math.floor((hi - lo) / 2));
if (mid === lo) mid = lo + 2;
if (mid >= hi) break;
if (fits(mid)) lo = mid;
else hi = mid;
}
if (lo === 0) {
throw opError('payload_too_large', `An upload part frame of at most ${maxFrameBytes} bytes cannot carry even one character.`,
'The brain host advertised a part frame smaller than the request envelope, so nothing was uploaded. Report it with gbrain remote doctor; the host operator raises its request cap.',
{ fix: { argv: ['gbrain', 'remote', 'doctor', '--json'], consent: [], actor: 'agent', requires_exclusive: false,
why: 'Shows the brain host and its connection limits, read-only.' } });
}
return lo;
}
/** One tool call of an upload: the parsed tool result, or a thrown error. */
export type UploadToolCall = (tool: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
/** A body to upload: its UTF-8 size and sha256, and its text from a byte offset (a code-point boundary) on. */
export interface UploadBody {
bytes: number;
sha256: string;
text(fromByte: number): AsyncIterable<string>;
}
export interface UploadPageOptions {
/** A failure that may have lost only the reply (a dropped connection): the driver asks get_page_upload where the session stands and resumes there. */
transient?: (error: unknown) => boolean;
/** Attempts after a transient failure, per call. Default 3. */
retries?: number;
/** commit_page_upload's wait_ms. */
wait_ms?: number;
/** begin_page_upload's reply when the caller already began the session (with this body's total_bytes and sha256). */
begun?: Record<string, unknown>;
}
/** A body held as one string. */
export function stringUploadBody(text: string): UploadBody {
const bytes = Buffer.from(text, 'utf8');
return {
bytes: bytes.length,
sha256: createHash('sha256').update(bytes).digest('hex'),
async *text(fromByte: number) { yield bytes.subarray(fromByte).toString('utf8'); },
};
}
/**
* Upload `body` through an upload session and commit it: begin, the parts in
* order (each cut to the session's `part_max_frame_bytes` by
* `cutUploadPart`), commit. After a transient failure it reads
* get_page_upload and continues at `next_part`; any other failure aborts the
* session (releasing its reservation) and rethrows, except a sign that another
* client holds the same session (`idempotency_conflict`), which it leaves. Returns the commit's
* put_page-shaped receipt.
*/
export async function uploadPageBody(call: UploadToolCall, begin: Record<string, unknown>, body: UploadBody, opts: UploadPageOptions = {}): Promise<Record<string, unknown>> {
const transient = opts.transient ?? (() => false);
const retries = opts.retries ?? 3;
const retry = async (fn: () => Promise<Record<string, unknown>>): Promise<Record<string, unknown>> => {
for (let attempt = 0; ; attempt++) {
try { return await fn(); } catch (error) { if (attempt >= retries || !transient(error)) throw error; }
}
};
const session = opts.begun ?? await retry(() => call('begin_page_upload', { ...begin, total_bytes: body.bytes, sha256: body.sha256 }));
const uploadId = String(session.upload_id);
const maxFrame = Number(session.part_max_frame_bytes);
let part = Number(session.next_part);
let received = Number(session.received_bytes);
const moved = (expected: number, state: Record<string, unknown>) => opError('idempotency_conflict',
`Upload ${uploadId} holds ${String(state.received_bytes)} bytes at part ${String(state.next_part)}; this client expected ${expected} bytes.`,
'Another client is writing this upload session (the same request_id), so this one stopped and committed nothing. Run the command again without --request-id to start a new upload.');
try {
const chunks = body.text(received)[Symbol.asyncIterator]();
let buffer = '';
let eof = false;
for (;;) {
while (!eof && buffer.length <= maxFrame) {
const next = await chunks.next();
if (next.done) eof = true;
else buffer += next.value;
}
if (buffer.length === 0) break;
const end = cutUploadPart(buffer, { upload_id: uploadId, part }, maxFrame);
const text = buffer.slice(0, end);
const expected = received + Buffer.byteLength(text, 'utf8');
const args = { upload_id: uploadId, part, text, part_sha256: createHash('sha256').update(text, 'utf8').digest('hex') };
let ack: Record<string, unknown> | undefined;
for (let attempt = 0; !ack; attempt++) {
try { ack = await call('upload_page_part', args); } catch (error) {
if (attempt >= retries || !transient(error)) throw error;
const state = await retry(() => call('get_page_upload', { upload_id: uploadId }));
if (Number(state.next_part) > part) ack = state;
else if (Number(state.next_part) !== part || Number(state.received_bytes) !== received) throw moved(received, state);
}
}
if (Number(ack.received_bytes) !== expected || Number(ack.next_part) <= part) throw moved(expected, ack);
part = Number(ack.next_part);
received = expected;
buffer = buffer.slice(end);
}
if (received !== body.bytes) {
throw opError('source_changed', `The body read back ${received} bytes, not the ${body.bytes} it declared.`,
'The input changed while it was uploading, so nothing was committed. Run the command again on the finished file.');
}
} catch (error) {
const code = error instanceof OperationError ? error.code : error instanceof RemoteMcpError ? error.detail?.code : undefined;
if (!transient(error) && code !== 'idempotency_conflict') await call('abort_page_upload', { upload_id: uploadId }).catch(() => undefined);
throw error;
}
return retry(() => call('commit_page_upload', { upload_id: uploadId, ...(opts.wait_ms !== undefined ? { wait_ms: opts.wait_ms } : {}) }));
}