Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Thin-client `gbrain serve`: a stdio MCP server that relays every request to
* the remote brain with this install's stored OAuth credential (#8543).
*
* Nothing here opens an engine or runs an operation handler, and no page text
* is stored on this machine. The host decides every call: `tools/list` is the
* host's own list for this client's token (narrowed, never widened, by
* `--surface` / `--advertise`), and `tools/call` returns the host's
* `CallToolResult` byte-identical, `isError` envelopes and pending write
* receipts included. Each relayed call reaches the host as an ordinary remote
* OAuth caller (`remote: true`); this process never builds an
* OperationContext, so nothing in it can act as the trusted local CLI.
*
* Bridge-built answers (a transport failure, a refusal that never left this
* machine, a bridge fault) are v1 envelopes from remote-bridge-errors.ts.
* stdout carries JSON-RPC only; the bridge's own lines go to stderr as
* `[gbrain-bridge]`. The lifecycle (signals, bounded EOF drain, MCP_STDIO=1,
* parent watchdog) is local serve's, from stdio-lifecycle.ts.
*/
import { randomUUID } from 'node:crypto';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
import { CallToolRequestSchema, ListToolsRequestSchema, type CallToolResult, type Tool } from '@modelcontextprotocol/sdk/types.js';
import type { RenderContext } from '../core/agent-output.ts';
import { configDir, type GBrainConfig } from '../core/config.ts';
import { forwardRemoteToolCall, listRemoteToolDefs, RemoteMcpError, type RemoteToolDefs } from '../core/mcp-client.ts';
import { OPERATION_MANIFEST } from '../core/operation-manifest.generated.ts';
import type { Operation, OperationMeta } from '../core/ops/contract.ts';
import { isPersistenceIpcMutation } from '../core/persistence/ipc.ts';
import { VERSION } from '../version.ts';
import { hiddenToolHint } from './hidden-tool-hint.ts';
import { installInstructionsResolver, MCP_SERVER_DESCRIPTION, resolveMcpInstructions } from './instructions.ts';
import { BRIDGE_LOG_PREFIX, bridgeCallFailure, bridgeInternalFailure, bridgeListFailure, bridgeRefusal, endpointLabel, writeBridgeTrace, type BridgeErrorContext } from './remote-bridge-errors.ts';
import { exitAfterStdoutDrains, installStdioShutdownTriggers, mcpStdioTransport, probeWatchdogAvailable, readLiveParentPid, resolveEofDrainMs, type StdioLifecycleDeps } from './stdio-lifecycle.ts';
import { clampSurface, createStdioSurfaceState, isMcpSurface, resolveStdioSurface, sessionWidenAllowed, stdioToolListing, surfaceWiderThan, SURFACE_SOURCE_LABEL, type McpSurface } from './surface.ts';
import { stripUrlSecrets } from '../core/url-redact.ts';
/** The client name the host sees. Not the thin client's, so the host serves the lean rows and windowed pages any remote agent gets. */
export const BRIDGE_CLIENT_NAME = 'gbrain-stdio-bridge';
/** Per-call timeout (the CLI's think default); the SDK's own 60 s would cut think off. `gbrain --timeout=Ns serve` overrides it. */
export const BRIDGE_DEFAULT_TIMEOUT_MS = 180_000;
/** The first gbrain whose hosts enforce a request-level `_meta.on_behalf_of` and report it as `_meta.access.audience`. */
export const AUDIENCE_MIN_HOST_VERSION = '0.60.543.0';
export interface RemoteBridgeOptions {
surface?: McpSurface | null;
advertise?: McpSurface | null;
sourceGuard?: boolean;
timeoutMs?: number;
/** Test seams; production uses the process's stdio and the real remote calls. */
transport?: () => Transport;
lifecycle?: Partial<StdioLifecycleDeps>;
mcpStdio?: boolean;
eofDrainMs?: number;
installFatalHandlers?: boolean;
list?: typeof listRemoteToolDefs;
forward?: typeof forwardRemoteToolCall;
}
/** Whether a host's initialize `serverInfo` names a gbrain at least `min` (four-part versions). */
export function hostAtLeast(server: { name?: string; version?: string } | undefined, min: string): boolean {
if (server?.name !== 'gbrain' || typeof server.version !== 'string') return false;
const have = server.version.split('.').map(Number);
const need = min.split('.').map(Number);
if (have.some(n => !Number.isInteger(n))) return false;
for (let i = 0; i < need.length; i++) {
if ((have[i] ?? 0) !== need[i]) return (have[i] ?? 0) > need[i];
}
return true;
}
const isPlainObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
/** Start the bridge on this process's stdio. Resolves once the transport is connected; the lifecycle exits the process. */
export async function startRemoteStdioBridge(cfg: GBrainConfig, opts: RemoteBridgeOptions = {}): Promise<void> {
const deps: StdioLifecycleDeps = {
stdin: process.stdin, signals: process, exit: exitAfterStdoutDrains(), log: (msg: string) => console.error(msg),
getParentPid: readLiveParentPid, setInterval: (fn, ms) => setInterval(fn, ms), clearInterval: (h) => clearInterval(h as ReturnType<typeof setInterval>),
probeWatchdog: probeWatchdogAvailable, ...opts.lifecycle,
};
const log = (line: string) => deps.log(stripUrlSecrets(line));
const home = configDir();
const fatal = (stage: string, error: unknown) => {
const trace = writeBridgeTrace(home, error, { stage });
log(`${BRIDGE_LOG_PREFIX} code=internal_error version=${VERSION} stage=${stage} diagnostic=${trace.id}${trace.path ? ` trace=${trace.path}` : ''}`);
deps.exit(1);
};
if (opts.installFatalHandlers !== false) {
process.on('uncaughtException', (e) => fatal('uncaught_exception', e));
process.on('unhandledRejection', (e) => fatal('unhandled_rejection', e));
}
try {
await runBridge(cfg, opts, deps, log, home);
} catch (error) {
fatal('startup', error);
}
}
async function runBridge(cfg: GBrainConfig, opts: RemoteBridgeOptions, deps: StdioLifecycleDeps, log: (line: string) => void, home: string): Promise<void> {
const remote = cfg.remote_mcp;
const mcpUrl = remote?.mcp_url ?? '';
const timeoutMs = opts.timeoutMs ?? BRIDGE_DEFAULT_TIMEOUT_MS;
const list = opts.list ?? listRemoteToolDefs;
const forward = opts.forward ?? forwardRemoteToolCall;
const byName = new Map<string, OperationMeta>(OPERATION_MANIFEST.map(op => [op.name, op]));
const resolved = resolveStdioSurface(opts.surface ?? null, cfg);
if (resolved.invalidEnv !== undefined) {
log(`${BRIDGE_LOG_PREFIX} surface_env_invalid: ignoring GBRAIN_SURFACE="${resolved.invalidEnv}" (use verbs | starter | full); serving '${resolved.surface}' (source: ${SURFACE_SOURCE_LABEL[resolved.source]})`);
}
let server: Server | null = null;
const notify = () => { Promise.resolve(server?.sendToolListChanged()).catch(() => { /* best-effort */ }); };
const session = createStdioSurfaceState(OPERATION_MANIFEST, {
surface: clampSurface(resolved.surface), source: resolved.source, readOnly: false,
onWiden: ({ from, to, added }) => { log(`${BRIDGE_LOG_PREFIX} surface_widened from=${from} to=${to} op=request_tools added=${added.length}`); notify(); },
});
session.widenAllowed = await sessionWidenAllowed(null, cfg);
const advertise = opts.advertise ?? null;
const listing = stdioToolListing(async () => advertise, session, { sendToolListChanged: async () => notify() });
const listingNarrowed = () => session.allowedOps !== undefined || (advertise !== null && surfaceWiderThan(session.surface, advertise));
const hostNames = new Set<string>();
const revealedDefs = new Map<string, Tool>();
const warnedUnknown = new Set<string>();
const render: RenderContext = {
transport: 'stdio', surface: session.surface,
isCallable: (n) => hostNames.has(n) && (!session.allowedOps || session.allowedOps.has(n)),
preapproved: () => false,
};
const errCtx: BridgeErrorContext = { render, mcpUrl, clientId: remote?.oauth_client_id, timeoutMs };
log(`${BRIDGE_LOG_PREFIX} relaying stdio to ${endpointLabel(mcpUrl)} surface=${session.surface} (source: ${SURFACE_SOURCE_LABEL[resolved.source]})${advertise ? ` advertise=${advertise}` : ''}`);
if (opts.sourceGuard) {
log(`${BRIDGE_LOG_PREFIX} --source-guard: write routing follows this client's source grant on the brain host; the bridge enforces nothing locally`);
}
/** The host's tools for this token that this session may call, before the advertise listing. */
const callableTools = (defs: RemoteToolDefs): Tool[] => {
const all = [...defs.tools, ...[...revealedDefs.values()].filter(r => !defs.tools.some(t => t.name === r.name))];
hostNames.clear();
for (const t of all) hostNames.add(t.name);
const hostTools = all.filter(t => !byName.get(t.name)?.localOnly && !byName.get(t.name)?.cliOnly);
if (!listingNarrowed()) return hostTools;
const unknown = hostTools.filter(t => !byName.has(t.name) && !warnedUnknown.has(t.name)).map(t => t.name);
if (unknown.length) {
for (const n of unknown) warnedUnknown.add(n);
log(`${BRIDGE_LOG_PREFIX} not listing ${unknown.length} host tool(s) this gbrain does not know under a narrowed surface: ${unknown.join(', ')}`);
}
return hostTools.filter(t => byName.has(t.name) && (!session.allowedOps || session.allowedOps.has(t.name)));
};
const listedTools = async (defs: RemoteToolDefs): Promise<Tool[]> => {
const callable = callableTools(defs);
if (!listingNarrowed()) return callable;
const names = new Set((await listing.listed(callable.map(t => byName.get(t.name)!))).map(op => op.name));
return callable.filter(t => names.has(t.name));
};
server = new Server({ name: 'gbrain', version: VERSION, description: MCP_SERVER_DESCRIPTION },
{ capabilities: { tools: { listChanged: true } }, instructions: resolveMcpInstructions(cfg, process.env) });
installInstructionsResolver(server, async () => {
const relay = `This MCP server is a gbrain stdio bridge: it relays every call to the remote brain at ${endpointLabel(mcpUrl)}, which decides what each call may read or write.`;
try {
const defs = await list(cfg, { clientName: BRIDGE_CLIENT_NAME, timeoutMs: Math.min(timeoutMs, 15_000) });
return `${defs.instructions ?? resolveMcpInstructions(cfg, process.env)}\n\n${relay}`;
} catch {
return `${resolveMcpInstructions(cfg, process.env)}\n\n${relay}`;
}
});
let inFlight = 0;
const writes = new Map<number, { tool: string; requestId?: string }>();
let nextCall = 0;
const track = async <T>(work: () => Promise<T>): Promise<T> => {
inFlight++;
try { return await work(); } finally { inFlight--; }
};
server.setRequestHandler(ListToolsRequestSchema, async () => track(async () => {
try {
return { tools: await listedTools(await list(cfg, { clientName: BRIDGE_CLIENT_NAME, timeoutMs })) };
} catch (e) {
if (!(e instanceof RemoteMcpError)) throw e;
const { error, line } = bridgeListFailure(e, errCtx);
log(line);
throw error;
}
}));
/** `request_tools {surface}` is this session's own widen (never forwarded, so nothing is written on the host). */
const widenSession = async (args: Record<string, unknown>): Promise<CallToolResult> => {
const requested = args.surface;
if (!isMcpSurface(requested)) {
return bridgeRefusal({ code: 'invalid_params', message: 'request_tools surface must be one of: verbs, starter, full.', why: 'The bridge widens its own session surface and knows only these three.',
suggestion: 'Call request_tools {"surface":"starter"} or {"surface":"full"}.' }, render) as CallToolResult;
}
const persistent = `For a lasting change, set GBRAIN_SURFACE=${requested} in the env of this harness's MCP server entry for gbrain (or edit its --surface) and start a new session.`;
session.widenAllowed = await sessionWidenAllowed(null, cfg);
if (!session.widenAllowed) {
return bridgeRefusal({ code: 'permission_denied', message: 'Session widening is off for this bridge (mcp.allow_session_widen is false), so request_tools cannot add tools to it.',
why: 'The owner of this machine turned stdio session widening off.', suggestion: persistent,
fix: { argv: ['gbrain', 'serve', '--surface', requested], consent: [], actor: 'user', requires_exclusive: false, why: `The bridge surface is a start flag of this harness entry. ${persistent}` } }, render) as CallToolResult;
}
const target = clampSurface(requested);
let change: Record<string, unknown>;
if (!surfaceWiderThan(target, session.surface)) {
change = { persisted: false, scope: 'session', surface: session.surface, widened: false,
note: target !== requested ? `GBRAIN_MCP_FORCE_SURFACE caps this bridge at '${target}', so this session stays at '${session.surface}'.` : `This session already serves '${session.surface}', which includes everything in '${requested}'.` };
} else {
const widened = session.widen(target);
render.surface = session.surface;
const added = new Set(widened.added);
const tools = callableTools(await list(cfg, { clientName: BRIDGE_CLIENT_NAME, timeoutMs })).filter(t => added.has(t.name));
change = { persisted: false, scope: 'session', surface: target, previous: widened.from, tools,
note: `This session now serves '${target}' (tools/list_changed was sent). Call the new tools by name now; their schemas are above. Only tools the brain host grants this client are added. ${persistent}` };
}
if (args.tools === undefined) return { content: [{ type: 'text', text: JSON.stringify(change, null, 2) }] };
const described = await relay('request_tools', { tools: args.tools }, undefined, undefined);
return withBody(described, body => ({ ...body, surface_change: change }));
};
/** Rewrite a relayed request_tools answer for this session: its catalog note, and which described tools this session can call now. */
const sessionRequestTools = (result: CallToolResult): CallToolResult => withBody(result, body => {
const out = { ...body };
if (Array.isArray(body.catalog)) {
out.note = 'Call request_tools {tools: ["name", ...]} for full schemas, or {surface: "starter"|"full"} to add those tools to this session (nothing is written).';
if (session.allowedOps && !session.widenAllowed) {
const allowed = session.allowedOps;
out.catalog = (body.catalog as Array<{ area: string; tools: Array<{ name: string }> }>).map(g => ({ ...g, tools: g.tools.filter(t => allowed.has(t.name)) })).filter(g => g.tools.length);
out.total_tools = (out.catalog as Array<{ tools: unknown[] }>).reduce((n, g) => n + g.tools.length, 0);
}
}
if (Array.isArray(body.tools)) {
const fresh = (body.tools as Tool[]).filter(t => typeof t?.name === 'string' && isPlainObject(t.inputSchema) && !hostNames.has(t.name) && !revealedDefs.has(t.name));
for (const t of fresh) revealedDefs.set(t.name, t);
if (fresh.length && !listingNarrowed()) notify();
}
if (Array.isArray(body.tools) && body.tools.length && listingNarrowed()) {
const names = (body.tools as Array<{ name?: unknown }>).map(t => t.name).filter((n): n is string => typeof n === 'string');
const reachable = names.filter(n => !session.allowedOps || session.allowedOps.has(n));
const outside = names.filter(n => !reachable.includes(n));
listing.reveal(reachable);
out.listed = outside.length === 0;
out.note = outside.length === 0
? 'These tools are now in your tool list (tools/list_changed was sent); call them directly.'
: `${reachable.length ? `${reachable.map(n => `\`${n}\``).join(', ')} are now in your tool list (tools/list_changed was sent). ` : ''}${outside.map(n => `\`${n}\``).join(', ')} are outside this session's '${session.surface}' surface, so they are not listed and cannot be called yet: call request_tools {"surface":"full"} to add them to this session, then call them by name.`;
}
return out;
});
/** Forward one call and return the host's answer, or the bridge's envelope for a transport failure. */
const relay = async (name: string, args: Record<string, unknown>, meta: Record<string, unknown> | undefined, signal: AbortSignal | undefined): Promise<CallToolResult> => {
const op = byName.get(name);
const audience = meta?.on_behalf_of !== undefined;
const sent = isPersistenceIpcMutation(name) && args.request_id === undefined && args.dry_run !== true ? { ...args, request_id: randomUUID() } : args;
const id = nextCall++;
if (!op || op.mutating) writes.set(id, { tool: name, ...(typeof sent.request_id === 'string' ? { requestId: sent.request_id } : {}) });
let result: CallToolResult;
try {
result = await forward(cfg, name, sent, {
clientName: BRIDGE_CLIENT_NAME, timeoutMs, ...(signal ? { signal } : {}), ...(meta ? { meta } : {}),
...(audience ? { admit: (host) => hostAtLeast(host, AUDIENCE_MIN_HOST_VERSION) ? null : audienceUnsupported(host?.version) } : {}),
});
} catch (e) {
if (!(e instanceof RemoteMcpError)) throw e;
return bridgeCallFailure(e, name, op, errCtx) as CallToolResult;
} finally {
writes.delete(id);
}
// A received answer is authoritative: a fault while reading it relays it unchanged.
try {
if (audience && op && !op.mutating && !result.isError && !Array.isArray((result._meta as { access?: { audience?: unknown } } | undefined)?.access?.audience)) {
return audienceUnsupported(undefined);
}
return name === 'request_tools' && !result.isError ? sessionRequestTools(result) : result;
} catch (error) {
const trace = writeBridgeTrace(home, error, { stage: 'read_result', tool: name });
log(`${BRIDGE_LOG_PREFIX} code=internal_error stage=read_result tool=${name} diagnostic=${trace.id}; relayed the host's answer unchanged`);
return result;
}
};
const audienceUnsupported = (hostVersion: string | undefined): CallToolResult => bridgeRefusal({
code: 'host_upgrade_required',
message: `This call names an audience (_meta.on_behalf_of), but the brain host${hostVersion ? ` (gbrain ${hostVersion})` : ''} cannot be shown to enforce one, so the bridge did not relay it.`,
why: `A host older than gbrain ${AUDIENCE_MIN_HOST_VERSION} ignores a request-level audience and would answer with the credential's whole view; the bridge never relays an audience-narrowed call it cannot verify.`,
suggestion: 'Upgrade gbrain on the brain host (gbrain upgrade there), or ask its operator to; until then, call without the audience only if every reader of the answer may see this credential\'s whole view.',
fix: { argv: ['gbrain', 'upgrade'], consent: [], actor: 'host_admin', requires_exclusive: false, why: 'The audience is enforced by the brain host; only an upgrade there adds it.' },
}, render, { client_version: VERSION, ...(hostVersion ? { host_version: hostVersion } : {}), min_host_version: AUDIENCE_MIN_HOST_VERSION }) as CallToolResult;
server.setRequestHandler(CallToolRequestSchema, async (request, extra) => track(async () => {
const { name, arguments: rawArgs, _meta: meta } = request.params;
const args = (rawArgs ?? {}) as Record<string, unknown>;
const op = byName.get(name);
try {
if (op?.localOnly || op?.cliOnly) {
return bridgeRefusal({ code: 'unknown_tool', message: `${name} is not a tool this connection can call.`, why: `${name} runs only on the brain host itself, so no remote connection reaches it.`,
suggestion: 'Call request_tools for the tools this connection can call.' }, render) as CallToolResult;
}
if (session.allowedOps && !session.allowedOps.has(name)) {
const hint = hiddenToolHint(op as Operation | undefined, { transport: 'stdio', remote: true, surface: session.surface, allowedOps: session.allowedOps, readOnly: false }, session.widenAllowed);
return bridgeRefusal({ code: 'unknown_tool', message: `${name} is not in this session's '${session.surface}' tool surface.`,
why: hint ? 'The bridge was started with a narrower --surface (or GBRAIN_SURFACE) than the brain host grants.' : `${name} is not a tool this connection can call.`,
suggestion: hint?.suggestion ?? 'Call request_tools for the tools this connection can call.', ...(hint ? { fix: hint.fix } : {}) }, render) as CallToolResult;
}
if (meta !== undefined && !isPlainObject(meta)) {
return bridgeRefusal({ code: 'invalid_params', message: 'Request-level _meta must be a JSON object, so the bridge did not relay this call.',
why: 'An audience or session id rides in _meta beside arguments; a call is never relayed with its narrowing dropped.',
suggestion: 'Send _meta as an object beside arguments, for example {"name": "query", "arguments": {...}, "_meta": {"on_behalf_of": ["alice-example"], "session_id": "s-1"}}; never put on_behalf_of inside arguments.' }, render) as CallToolResult;
}
if (name === 'request_tools' && args.surface !== undefined) return await widenSession(args);
return await relay(name, args, meta as Record<string, unknown> | undefined, extra.signal);
} catch (error) {
if (error instanceof RemoteMcpError) return bridgeCallFailure(error, name, op, errCtx) as CallToolResult;
const trace = writeBridgeTrace(home, error, { stage: 'call', tool: name });
log(`${BRIDGE_LOG_PREFIX} code=internal_error stage=call tool=${name} diagnostic=${trace.id}${trace.path ? ` trace=${trace.path}` : ''}`);
return bridgeInternalFailure(name, 'call', trace, render) as CallToolResult;
}
}));
let shuttingDown = false;
let exitCode = 0;
const mcpStdio = opts.mcpStdio ?? (process.env.MCP_STDIO === '1');
// Under MCP_STDIO=1 stdin EOF is not a disconnect, and with no engine nothing else holds the event loop open.
const keepAlive = mcpStdio ? setInterval(() => {}, 1 << 30) : undefined;
const triggers = installStdioShutdownTriggers(deps, {
beginShutdown: (reason) => {
if (shuttingDown) return;
shuttingDown = true;
triggers.stopWatchdog();
if (keepAlive) clearInterval(keepAlive);
log(`${BRIDGE_LOG_PREFIX} exit (${reason})`);
const deadline = setTimeout(() => deps.exit(exitCode), 2_000);
deadline.unref?.();
void Promise.resolve(server?.close()).catch(() => { /* best-effort */ }).finally(() => { clearTimeout(deadline); deps.exit(exitCode); });
},
isShuttingDown: () => shuttingDown,
pendingRpcs: () => inFlight,
// A forwarded write may take the whole call timeout; the drain waits that long before it gives up on a receipt.
eofDrainMs: opts.eofDrainMs ?? resolveEofDrainMs(timeoutMs),
mcpStdio,
logPrefix: BRIDGE_LOG_PREFIX,
onDrainExpired: () => {
for (const w of writes.values()) {
exitCode = 1;
log(`${BRIDGE_LOG_PREFIX} code=write_outcome_unknown tool=${w.tool} submission_status=unknown${w.requestId ? ` request_id=${w.requestId} fix="gbrain write-request -- ${w.requestId}"` : ' fix="ask the brain host owner whether it took effect before resending"'}`);
}
},
});
server.onclose = () => triggers.drainThenShutdown('transport-close');
await server.connect(opts.transport ? opts.transport() : mcpStdioTransport());
}
/** Apply `edit` to a result's JSON body (content[0]); any other shape passes through unchanged. */
function withBody(result: CallToolResult, edit: (body: Record<string, unknown>) => Record<string, unknown>): CallToolResult {
const first = result.content?.[0];
if (!first || first.type !== 'text') return result;
let body: unknown;
try { body = JSON.parse(first.text); } catch { return result; }
if (!isPlainObject(body)) return result;
return { ...result, content: [{ ...first, text: JSON.stringify(edit(body), null, 2) }, ...result.content.slice(1)] };
}