Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
42.1 KB
Raw Blame
/**
 * 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 } : {}) }));
}